본문으로 건너뛰기

[PaddleOCR] PaddleOCR-VL 배포 문서 개선 — Docker 이미지 및 디바이스 호환성 가이드 추가

PR 링크: PaddlePaddle/PaddleOCR#16808 상태: Merged | 변경: +365 / -95

들어가며

ML 모델의 추론 서빙 환경을 구축하는 과정은 종종 모델 개발보다 더 큰 허들이 됩니다. 의존성 충돌, GPU 드라이버 호환성, 오프라인 환경 제약 등 수많은 변수가 존재하기 때문입니다. 이번 PR은 PaddleOCR-VL의 배포 경험을 대폭 개선합니다. Docker 이미지 기반의 원클릭 배포 환경을 제공하고, 디바이스 호환성 매트릭스를 추가하며, Docker Compose를 활용한 프로덕션 서빙 가이드까지 포함합니다.

핵심 코드 분석

1. Docker Compose 기반 서빙 아키텍처

새로 추가된 deploy/paddleocr_vl_docker/compose.yaml은 두 컨테이너로 구성된 마이크로서비스 아키텍처를 정의합니다.

After:

services:
  paddleocr-vl-api:
    image: ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-offline
    ports:
      - 8080:8080
    depends_on:
      paddleocr-genai-vllm-server:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]

  paddleocr-genai-vllm-server:
    image: ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-offline
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]
      start_period: 300s

OCR 파이프라인 API 서버와 VLM 추론 서버를 분리하여, VLM 서버가 health check를 통과한 후에만 API 서버가 시작되도록 했습니다. start_period: 300s는 대형 모델 로딩에 필요한 워밍업 시간을 보장합니다.

2. 멀티스테이지 Dockerfile과 오프라인 빌드

After (pipeline.Dockerfile 발췌):

ARG BUILD_FOR_OFFLINE=false
RUN if [ "${BUILD_FOR_OFFLINE}" = 'true' ]; then \
        mkdir -p "${HOME}/.paddlex/official_models" \
        && cd "${HOME}/.paddlex/official_models" \
        && wget https://...UVDoc_infer.tar \
            https://...PP-DocLayoutV2_infer.tar \
            https://...PaddleOCR-VL_infer.tar \
        && tar -xf UVDoc_infer.tar && mv UVDoc_infer UVDoc \
        # ... 모델 파일 사전 다운로드
    fi

BUILD_FOR_OFFLINE ARG를 통해 조건부로 모델 가중치를 이미지에 번들링합니다. 인터넷이 차단된 환경에서도 docker load만으로 전체 추론 파이프라인을 구동할 수 있게 됩니다.

3. 디바이스 호환성 매트릭스 개선

Before:

| Inference Method | GPU Compute Capability |
| PaddlePaddle     | >= 8.5                 |
| vLLM             | >= 8                   |

After:

| Inference Method | Supports x64 CPU | Supported GPU Compute | Supported CUDA |
| PaddlePaddle     | ✅               | >= 7                   | 11.8, 12.6, 12.8 |
| vLLM             | 🚧               | >= 8                   | 12.8              |
| SGLang           | 🚧               | 8 <= CC < 12           | 12.8              |

CPU 지원 여부와 CUDA 버전별 호환성을 명시하여, 사용자가 자신의 하드웨어에 맞는 추론 방식을 빠르게 선택할 수 있게 했습니다. PaddlePaddle의 GPU Compute Capability 요구사항도 8.5에서 7로 낮아져 T4, V100 등 구형 GPU도 공식 지원합니다.

왜 이게 좋은가

  1. 진입 장벽 대폭 감소: docker run --gpus all 한 줄로 전체 OCR-VL 파이프라인을 실행할 수 있어, Python 환경 설정 없이도 즉시 테스트가 가능합니다.
  2. 오프라인 환경 지원: 보안이 엄격한 기업 환경에서 모델 서빙을 위해 외부 네트워크 접근 없이 배포할 수 있습니다.
  3. 프로덕션 레디: Health check, depends_on 조건, GPU 리소스 예약 등 프로덕션 배포에 필요한 요소를 Docker Compose에 포함하여 운영 안정성을 확보했습니다.

정리

이 PR은 PaddleOCR-VL의 배포 경험을 근본적으로 개선합니다. Docker 이미지, Compose 파일, 오프라인 빌드 옵션, 디바이스 호환성 매트릭스를 통해 다양한 환경에서의 배포를 원활하게 합니다. ML 모델 서빙의 "last mile" 문제를 해결하는 좋은 사례입니다.

참고 자료

이 글은 AI(Claude)의 도움을 받아 작성되었으며, 실제 PR의 코드 변경 사항을 기반으로 분석한 내용입니다.

댓글

관련 포스트

PR Analysis 의 다른글