Gradio Server: 맞춤 프론트엔드를 Gradio 백엔드와 통합하기

Gradio Server: 맞춤 프론트엔드를 Gradio 백엔드와 통합하기

Hugging Face는 gradio.Server를 도입했습니다. 이 도구를 사용하면 개발자가 React, Svelte 또는 순수 HTML/JS와 같은 프레임워크를 이용해 완전히 맞춤형 프론트엔드를 구축하면서 Gradio의 백엔드 인프라를 활용할 수 있습니다. 이를 통해 Gradio의 표준 컴포넌트가 제공하는 UI 기능을 넘어서는 복잡한 웹 애플리케이션을 만들 수 있으며, Gradio의 큐 시스템, 동시성 관리, 그리고 Hugging Face Spaces ZeroGPU와의 통합을 포기하지 않아도 됩니다.

gradio.Server 기술 아키텍처

gradio.Server는 FastAPI를 확장하여 FastAPI 애플리케이션의 전체 기능—맞춤 라우트, 미들웨어, 유연한 응답 타입—을 제공하면서 Gradio의 API 엔진을 통합합니다. 이 하이브리드 접근 방식 덕분에 개발자는 정적 HTML을 제공하는 @app.get("/")와 같은 표준 FastAPI 라우트를 Gradio 전용 API 엔드포인트와 함께 공존시킬 수 있습니다.

@app.api()의 역할

표준 FastAPI 라우트(예: @app.post())와 달리 @app.api() 데코레이터는 함수를 Gradio의 큐 엔진에 감싸서 다음과 같은 중요한 기술적 이점을 제공합니다:

  • 동시성 제어: 요청이 직렬화되어 여러 사용자가 동시에 GPU 자원을 경쟁하지 않게 하여 애플리케이션 충돌이나 출력 손상을 방지합니다.
  • ZeroGPU 통합: @spaces.GPU와 함께 사용할 경우 GPU 할당이 Hugging Face Spaces에서 자동으로 처리됩니다.
  • 클라이언트 호환성: @app.api()로 정의된 엔드포인트는 gradio_client와 기본적으로 호환되어 다른 애플리케이션이나 스크립트가 백엔드를 프로그래밍 방식으로 호출할 수 있습니다.

구현 예시: Text Behind Image

이 기능을 시연하기 위해 Hugging Face는 배경을 제거하고 전경 피사체와 배경 사이에 스타일화된 텍스트를 배치할 수 있는 편집기 "Text Behind Image"를 개발했습니다.

백엔드 구현

백엔드는 약 50줄의 Python 코드로 구현되었습니다. 이미지 분할을 위해 BiRefNet 모델을 사용해 투명 마스크를 생성합니다. remove_background 함수는 @app.api()로 데코레이트되어 Gradio 엔진에 의해 큐에 넣어지고 관리되며, 표준 FastAPI 라우트는 index.html 프론트엔드를 제공합니다.

프론트엔드 구현

프론트엔드는 자체 포함된 순수 HTML/CSS/JS 애플리케이션으로 다음을 특징으로 합니다:

  • 계층형 렌더링: CSS z-index를 이용해 배경, 텍스트, 전경의 세 레이어 캔버스를 관리합니다.
  • 풍부한 제어 패널: 3D 돌출, 원근 변환, 폰트 관리 등을 포함한 20개 이상의 텍스트 스타일링 파라미터를 제공합니다.
  • Gradio JS 클라이언트: 프론트엔드는 Gradio JS Client를 사용해 백엔드와 통신합니다. 이 클라이언트를 사용함으로써 fetch() 같은 원시 호출 대신 Gradio의 큐에 접근할 수 있어 동시성이 관리되고 GPU 요청이 충돌하지 않게 됩니다.

비교: 표준 Gradio vs. gradio.Server

gradio.Server는 디자인 자유도와 인프라 안정성 사이의 트레이드오프를 없애줍니다.

Feature Before gradio.Server After gradio.Server
UI Flexibility Gradio 생태계를 떠나는 맞춤 UI 필요 맞춤 UI를 Gradio 백엔드 엔진과 결합 가능
Static Content Gradio 앱에서 정적 HTML을 제공하는 기본 방법 없음 @app.get("/")를 통해 모든 정적 콘텐츠 제공 가능
API Access gradio_client가 컴포넌트 기반 앱에만 제한 @app.api() 엔드포인트는 완전한 클라이언트 호환
Infrastructure Gradio 인프라와 디자인 자유 중 하나 선택 두 가지를 동시에 제공

향후 확장

맞춤 프론트엔드 외에도 gradio.Server는 다음과 같은 지원을 추가합니다:

  • MCP Tool Registration: @app.mcp.tool()을 사용한 도구 통합.
  • SSE Streaming: Server-Sent Events를 통한 실시간 업데이트 활성화.
  • Batch Processing: 대규모 요청에 대한 향상된 처리.
  • Multi-page Applications: 여러 페이지에 걸친 공유 상태 관리 패턴.

Sources