B컷전문 | 개발과 인생의 이야기

Gradio 앱을 외부 클라우드가 아닌 로컬 환경이나 사내 서버에 배포하고자 할 때 Docker 기반 배포가 유용합니다. 본 글에서는 Gradio 앱을 Docker로 컨테이너화하는 전 과정을 실습 중심으로 설명합니다.

 

Hugging Face Spaces는 편리하지만 다음과 같은 한계를 가질 수 있습니다:

• GPU 사용 제한
• 앱 초기화 지연
• 프라이빗 환경에 적합하지 않음
• 외부 네트워크 제약

실제 프로젝트에서는 Gradio 앱을 Docker로 컨테이너화하여 자체 서버에 배포하는 방식이 요구됩니다.

---

Docker 기반 배포의 장점

• OS나 라이브러리 환경에 무관한 실행
• 사내망 또는 오프라인 환경에서도 앱 구동 가능
• CI/CD 연동 용이
• Kubernetes 등과 결합하여 확장 가능

Gradio는 매우 가볍기 때문에, Docker 기반 마이크로서비스 구성에 적합합니다.

---

1. 기본 프로젝트 구조

gradio-docker-app/
├── app.py
├── requirements.txt
└── Dockerfile

app.py 예제

import gradio as gr

def echo(text):
    return text

app = gr.Interface(fn=echo, inputs="text", outputs="text")
app.launch(server_name="0.0.0.0", server_port=7860)

server_name="0.0.0.0" 설정은 Docker 컨테이너 외부에서 접속 가능하도록 필수 설정입니다.

---

requirements.txt

gradio

Gradio 외에 추가 라이브러리가 있다면 여기에 모두 포함시킵니다.

---

Dockerfile

FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py ./

CMD ["python", "app.py"]

• python:3.10-slim 이미지는 가볍고 안정적
• COPY 명령으로 소스 코드 파일들을 컨테이너에 복사
• CMD로 Gradio 앱 실행

---

2. Docker 이미지 빌드 및 실행

빌드

docker build -t gradio-app .

실행

docker run -p 7860:7860 gradio-app

• -p 7860:7860은 컨테이너의 포트와 호스트 포트를 연결
• 실행 후 브라우저에서 http://localhost:7860 접속

필요 시 포트 번호를 환경 변수로 설정하거나 다른 포트로 매핑 가능

---

3. 고급 활용 – 파일 시스템, 모델 경로 마운트

Gradio 앱이 내부 모델이나 사용자 업로드 파일에 접근해야 하는 경우, 호스트 경로를 컨테이너에 마운트할 수 있습니다.

docker run -p 7860:7860 -v $(pwd)/models:/app/models gradio-app

• 호스트의 models/ 디렉토리를 컨테이너 내부 /app/models 경로에 연결

---

4. 프로덕션 환경 고려사항

항목 설명

리버스 프록시	Nginx, Traefik 등과 연동해 도메인 설정 및 HTTPS 적용
로그 처리	stdout → 로그 파일 연동 또는 Loki/Grafana 연계
자동 재시작	Docker Compose 또는 systemd로 관리
GPU 활용	--gpus all 옵션을 활용해 CUDA 연동 가능 (nvidia-docker 필요)
보안	CORS 설정, 포트 접근 제한, 내부 인증 로직 추가 필요

---

예제: Docker Compose 설정 (여러 Gradio 앱 운영 시)

version: '3.8'
services:
  gradio-app:
    build: .
    ports:
      - "7860:7860"
    volumes:
      - ./models:/app/models

docker-compose up --build

---

마무리

Gradio는 매우 가볍고 독립적인 구조를 가지므로, Docker 기반의 자체 배포에 매우 적합합니다.

• 모델 파일만 경량화하면 로컬에서도 고성능 실행 가능
• 기업 내부망, 클러스터 환경에서도 손쉽게 확장 가능
• FastAPI, 데이터베이스, Kafka 등과의 조합도 용이

Gradio는 단순한 데모 도구가 아닌 AI 서비스의 인터페이스 구성 요소로 발전할 수 있으며, Docker 배포는 그 핵심 기반입니다.

---

다음 화에서는 Gradio 프로젝트를 구성할 때 파일과 코드가 늘어날수록 어떻게 디렉토리를 분리하고 유지보수를 고려한 구조로 확장할 수 있는지 설명합니다.

👉 Gradio 실전 시리즈 11화 – Gradio 프로젝트 구조 설계와 유지보수 전략