Any Custom Frontend with Gradio's Backend

🖼️ 인포그래픽

Any Custom Frontend with Gradio's Backend 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

그라디오 서버는 리액트·스벨트·순수 HTML 같은 사용자 정의 프런트엔드를 유지하면서도 그라디오의 요청 대기열, 동시성 제어, 스트리밍, 클라이언트 호환성 및 허깅페이스 스페이스 실행 환경을 활용하게 해준다.

📌 핵심 요약

그라디오 서버는 패스트API를 확장해 사용자 정의 경로와 응답을 지원하면서 그라디오의 API 실행 엔진을 함께 제공한다.
예제 애플리케이션은 사진의 배경을 제거한 뒤 배경과 전경 사이에 꾸민 글자를 배치하고, 결과를 브라우저에서 PNG로 내보낸다.
배경 제거 함수는 그라디오 API로 공개되며, 요청 대기열과 동시성 제어를 통해 여러 요청이 GPU에서 충돌하는 문제를 방지한다.
프런트엔드는 그라디오 자바스크립트 클라이언트로 API를 호출하고, 글자 렌더링과 계층 합성 및 내보내기는 모두 브라우저에서 처리한다.
개발자는 그라디오 기본 UI와 완전한 사용자 정의 UI 중 하나를 선택하면서도 스페이스 호스팅과 API 인프라를 공통으로 활용할 수 있다.

🧩 주요 포인트

그라디오 서버는 패스트API를 확장해 사용자 정의 경로와 응답을 지원하면서 그라디오의 API 실행 엔진을 함께 제공한다.
예제 애플리케이션은 사진의 배경을 제거한 뒤 배경과 전경 사이에 꾸민 글자를 배치하고, 결과를 브라우저에서 PNG로 내보낸다.
배경 제거 함수는 그라디오 API로 공개되며, 요청 대기열과 동시성 제어를 통해 여러 요청이 GPU에서 충돌하는 문제를 방지한다.
프런트엔드는 그라디오 자바스크립트 클라이언트로 API를 호출하고, 글자 렌더링과 계층 합성 및 내보내기는 모두 브라우저에서 처리한다.
개발자는 그라디오 기본 UI와 완전한 사용자 정의 UI 중 하나를 선택하면서도 스페이스 호스팅과 API 인프라를 공통으로 활용할 수 있다.

🧠 상세 정리

1. 사용자 정의 프런트엔드와 그라디오 백엔드의 결합

기존의 그라디오 HTML 기능을 이용하면 사용자 정의 HTML·CSS·자바스크립트로 풍부한 화면을 만들 수 있지만, 리액트나 스벨트처럼 별도의 프런트엔드 체계를 온전히 사용하려는 경우에는 한계가 있었다. 그렇다고 그라디오를 떠나면 요청 대기열, API 인프라, 동시성 관리, 스페이스의 제로GPU 지원 같은 기능도 직접 대체해야 한다. 그라디오 서버는 이 선택의 충돌을 해결하기 위해 패스트API 기반의 자유로운 웹 애플리케이션과 그라디오의 백엔드 실행 엔진을 결합한다. 따라서 화면 구성은 원하는 기술로 전담하고, 계산이 필요한 API는 그라디오의 관리 기능을 거쳐 실행하는 구조를 만들 수 있다.

2. 배경 뒤에 글자를 넣는 편집기의 요구사항

글에서 구현한 사례는 사진을 올리면 기계학습 모델이 배경을 제거하고, 사용자가 전경 피사체와 원래 배경 사이에 꾸민 글자를 배치하는 이미지 편집기다. 이를 위해 배경, 글자, 투명 전경을 순서대로 합성하는 드래그 앤드 드롭 캔버스가 필요하다. 글꼴 크기와 굵기, 자간, 색상, 투명도뿐 아니라 외곽선, 그림자, 입체 돌출, 회전, 기울기 및 원근 변환까지 다루는 상세 제어판도 요구된다. 배경 제거는 서버의 모델이 담당하지만 최종 PNG 내보내기는 클라이언트에서 처리해야 하므로, 일반적인 그라디오 구성요소만으로 표현하기 어려운 완전한 웹 애플리케이션에 해당한다.

3. 그라디오 서버로 구성한 배경 제거 백엔드

백엔드는 약 50줄의 파이썬 코드로 구성되며, 시작 단계에서 BiRefNet 이미지 분할 모델을 불러와 GPU로 이동한다. 입력 이미지는 1024×1024 크기로 조정하고 정규화한 뒤 모델에 전달하며, 예측 결과를 원래 이미지 크기의 투명도 마스크로 변환해 알파 채널에 넣는다. 배경 제거 API는 업로드된 파일을 RGB 이미지로 읽고 분할 함수를 실행한 다음, 투명 배경을 가진 PNG 파일을 저장해 파일 데이터로 반환한다. 루트 경로는 별도의 HTML 파일을 읽어 웹페이지로 제공하며, 모델 실행에는 스페이스의 GPU 할당 장식자를 적용한다. 이처럼 동일한 서버 안에서 사용자 정의 웹 경로와 그라디오가 관리하는 모델 API가 함께 동작한다.

4. 일반 패스트API 경로 대신 그라디오 API를 쓰는 이유

배경 제거 기능을 일반적인 패스트API의 POST 경로로 구현하는 것 자체는 가능하지만, 여러 사용자가 동시에 요청하면 동일한 GPU 자원을 놓고 연산이 충돌할 수 있다. 그라디오 API 장식자는 함수를 요청 대기열 엔진으로 감싸 직렬화와 동시성 제어를 수행하고, 제로GPU 스페이스에서는 GPU 할당 과정도 관련 장식자와 함께 처리한다. 이 때문에 동시에 들어온 요청이 서로 간섭해 애플리케이션이 중단되거나 잘못된 결과를 반환할 위험을 줄일 수 있다. 또한 해당 API는 그라디오 클라이언트와 호환되므로, 다른 애플리케이션이나 파이썬 스크립트에서도 스페이스에 연결해 배경 제거 기능을 호출할 수 있다.

5. 순수 HTML·CSS·자바스크립트 프런트엔드

예제의 프런트엔드는 빌드 도구나 번들러 없이 작성된 약 1300줄의 독립적인 HTML 애플리케이션이다. CSS 계층 순서를 이용해 배경 이미지, 글자, 투명 PNG 전경을 세 층으로 쌓고, 포인터 이벤트로 글자의 위치를 끌어서 조정한다. 제어판은 25개 이상의 글꼴과 크기·굵기·간격·색상·투명도·배경 채우기·외곽선·그림자·입체 깊이·회전·기울기·원근 변환 등을 제공한다. 서버 통신에는 원시 HTTP 요청 대신 그라디오 자바스크립트 클라이언트를 사용해 배경 제거 API를 호출하므로 요청이 그라디오 대기열을 통과한다. 글자 렌더링, 이미지 계층 합성, 캔버스를 이용한 PNG 내보내기는 서버가 아니라 브라우저에서 수행된다.

6. 확장된 활용 범위와 후속 주제

그라디오 서버가 도입되면서 사용자 정의 화면을 만들기 위해 그라디오의 백엔드 기능까지 포기해야 했던 제약이 사라졌다. 루트 경로를 비롯한 표준 패스트API 경로로 HTML이나 다른 응답을 제공하면서, 그라디오 API로 공개한 함수는 대기열과 클라이언트 호환성을 그대로 확보할 수 있다. 기본 화면이 적합한 프로젝트에서는 블록, 인터페이스 또는 채팅 인터페이스를 사용하고, 완전한 디자인 자유가 필요하면 별도 프런트엔드를 연결하는 식으로 선택할 수 있다. 어느 방식을 택하더라도 스페이스 호스팅, API 대기열, 그라디오 클라이언트 및 허깅페이스 생태계를 활용할 수 있다는 것이 핵심이다. 글은 향후 MCP 도구 등록, 서버 전송 이벤트 스트리밍, 일괄 처리, 공유 상태를 가진 다중 페이지 애플리케이션 구성 방식을 후속 주제로 예고한다.

🧾 핵심 주장 / 시사점

연산 집약적인 모델 처리는 관리되는 서버 API에 두고, 상호작용과 합성 및 파일 내보내기는 브라우저에 배치하면 백엔드 부하와 화면 구현의 복잡성을 분리할 수 있다.
그라디오 자바스크립트 클라이언트를 사용하는 것은 단순한 호출 편의 이상의 의미가 있으며, 사용자 정의 프런트엔드도 서버의 요청 대기열과 동시성 제어 흐름에 참여하게 만든다.
그라디오 서버는 기본 UI를 대체하도록 강제하는 기능이 아니라, 프로젝트마다 그라디오 UI와 독립 프런트엔드 사이에서 선택할 수 있도록 백엔드 활용 범위를 확장한 방식이다.

✅ 액션 아이템

그라디오 서버의 FastAPI 확장 경로를 통해 React·Svelte·HTML 사용자 정의 프런트엔드를 설계하고 API 실행은 동일한 그라디오 엔진으로 일원화한다.
배경 제거 등 GPU 연산 밀집 함수는 그라디오 API의 요청 대기열·동시성 제어 구간으로 감싸고, 동시 처리 규칙을 먼저 정의한다.
텍스트 렌더링·계층 합성·PNG 내보내기는 브라우저에서 수행하고, 서버는 API 공개와 스페이스 호스팅 운용에 집중해 책임을 분리한다.