BentoML 실무 스터디 가이드

데이터 엔지니어 · AI 엔지니어를 위한 핵심 요약

model-serving packaging deployment MLOps 2026.03

1. BentoML란?

BentoML은 머신러닝 모델을 프로덕션 환경에 서빙하기 위한 오픈소스 플랫폼입니다. 모델 패키징, 서빙, 배포의 전 과정을 표준화하고 자동화하여 MLOps 워크플로우를 단순화합니다.

📦 표준화된 패키징

모든 프레임워크(PyTorch, TensorFlow, Scikit-learn 등)의 모델을 Bento라는 단일 컨테이너 형식으로 패키징합니다. 코드, 모델, 의존성을 하나로 묶어 재현성을 보장합니다.

⚡ 고성능 서빙

비동기 지원, 배치 처리, 자동 스케일링이 내장된 프로덕션급 서빙 API를 제공합니다. 단일 엔드포인트로 REST, gRPC를 동시에 지원합니다.

🚀 원클릭 배포

빌드된 Bento를 Kubernetes, AWS SageMaker, Azure ML, Docker 등 다양한 플랫폼에 손쉽게 배포할 수 있습니다. Vendor lock-in을 피할 수 있습니다.

2. 왜 써야 하는가?

기존 모델 서빙 솔루션과의 비교를 통해 BentoML의 장점을 확인해보세요.

도구 패키징 서빙 성능 배포 유연성 학습곡선
BentoML ✅ 표준화된 Bento 형식 ✅ 비동기/배치 내장 ✅ 모든 플랫폼 지원 ✅ 중간
Flask/FastAPI 직접 구축 ❌ 수동 구성 필요 ⚠️ 직접 구현 필요 ✅ 유연하지만 복잡 ❌ 높음
TensorFlow Serving ✅ TF 모델만 ✅ 최적화됨 ⚠️ TF 생태계 제한 ⚠️ 중간
클라우드 서빙 (SageMaker 등) ⚠️ Vendor별 형식 ✅ 관리형 서비스 ❌ Vendor lock-in ✅ 낮음

핵심 가치: BentoML은 "모델을 코드처럼 다루자"는 철학을 실현합니다. Git으로 버전 관리, CI/CD 파이프라인 통합, 팀 간 공유가 용이한 모델 아티팩트를 생성합니다.

3. 핵심 개념

BentoML의 아키텍처는 다음과 같은 구성 요소로 이루어집니다.

+-----------------------------------------------------------------------+ | [ Your ML Model Code ] | | | | | v | | +----------------------+ | | | BentoML Service | (Python Class 정의) | | | - @bentoml.api | | | | - 로직 구현 | | | +----------------------+ | | | | | v | | +------------------------------+ | | | Bento Build | | | | - 모델 아티팟트 저장 | | | | - 의존성 패키징 (Conda) | | | | - Dockerfile 자동 생성 | | | +------------------------------+ | | | | | v | | +-----------------------------------+ | | | Bento (결과물) | | | | - 표준화된 디렉토리 구조 | | | | - 실행 가능한 컨테이너 이미지 | | | +-----------------------------------+ | | | | | +-----------------------------------+ | | | 다양한 배포 대상 | | | | - Docker Container | | | | - Kubernetes | | | | - AWS SageMaker / Lambda | | | | - Azure ML / Container Instances| | | | - Google Cloud Run / AI Platform| | | +-----------------------------------+ | +-----------------------------------------------------------------------+

주요 용어

4. 퀵스타트

5분 안에 첫 BentoML 서비스를 만들어보세요.

Step 1: 설치

# pip를 통해 설치
pip install bentoml

# 버전 확인
bentoml --version

Step 2: 간단한 서비스 정의 (service.py)

import bentoml
from bentoml.io import JSON, Text
import numpy as np

# 모델 로드 (예: Scikit-learn 모델)
# 실제로는 bentoml.models.get() 또는 외부 모델 로드
# 여기서는 더미 모델로 예시

@bentoml.service(
    resources={"cpu": "1"},
    traffic={"timeout": 10},
)
class IrisClassifier:
    
    def __init__(self):
        # 모델 초기화 로직
        # self.model = bentoml.sklearn.load_model("iris_model:latest")
        pass
    
    @bentoml.api(input=JSON(), output=JSON())
    def predict(self, input_data: dict):
        """JSON 입력을 받아 예측 결과를 JSON으로 반환"""
        # 실제 예측 로직
        # features = np.array(input_data["features"]).reshape(1, -1)
        # prediction = self.model.predict(features)
        return {"prediction": 1, "confidence": 0.95}
    
    @bentoml.api(input=Text(), output=Text())
    def health(self, name: str = "BentoML") -> str:
        """헬스 체크 엔드포인트"""
        return f"Hello {name}, service is healthy!"

Step 3: 서비스 실행

# 개발 서버 실행
bentoml serve service.py:IrisClassifier --reload

# 또는 Python에서 직접 실행
if __name__ == "__main__":
    import uvicorn
    from service import IrisClassifier
    svc = IrisClassifier()
    uvicorn.run(svc.asgi_app, host="0.0.0.0", port=3000)

서버가 실행되면 http://localhost:3000에서 Swagger UI에 접속하여 API를 테스트할 수 있습니다.

Step 4: Bento 빌드

# bentofile.yaml 생성 (의존성 정의)
# 또는 CLI로 직접 빌드
bentoml build --service service.py:IrisClassifier

# 빌드된 Bento 목록 확인
bentoml list

Step 5: 컨테이너화 및 배포

# Docker 컨테이너 빌드
bentoml containerize iris_classifier:latest

# Docker로 실행
docker run -p 3000:3000 iris_classifier:latest

# Kubernetes에 배포 (YAML 생성)
bentoml generate-kubernetes-resources iris_classifier:latest -o k8s.yaml

5. 핵심 설정 레퍼런스

BentoML 서비스의 주요 설정 옵션입니다.

설정 기본값 설명 예시
resources {} CPU/GPU 리소스 제한 {"cpu": "2", "memory": "4Gi", "gpu": 1}
traffic.timeout 30 요청 타임아웃 (초) {"timeout": 60}
workers_per_resource 1 리소스당 워커 수 0.5 (2리소스당 1워커)
max_batch_size 100 배치 처리 최대 크기 1000
max_latency_ms 10000 배치 최대 지연 시간 5000
cors.enabled False CORS 활성화 True
logging.level "INFO" 로그 레벨 "DEBUG"

설정 방법: @bentoml.service() 데코레이터 인자, bentoml.yml 파일, 환경 변수(BENTOML_ 접두사)로 설정할 수 있습니다.

6. 실무 팁 & 트러블슈팅

✅ 실무 팁

모델 버전 관리

BentoML은 모델 레지스트리를 내장하고 있습니다. bentoml.models.get()로 특정 버전을 로드하거나, 태그를 사용해 프로덕션/스테이징 모델을 구분하세요.

대용량 파일 처리

이미지, 오디오 등 대용량 파일은 Multipart() 입력을 사용하세요. 스트리밍 처리로 메모리 사용을 최적화할 수 있습니다.

모니터링 연동

Prometheus 메트릭이 기본 제공됩니다. /metrics 엔드포인트를 Grafana와 연동하여 지연 시간, 처리량, 에러율을 모니터링하세요.

⚠️ 트러블슈팅

문제 원인 해결책
빌드 시 의존성 충돌 호환되지 않는 패키지 버전 pip check로 확인, conda 환경 사용 또는 버전 고정(requirements.txt)
GPU 메모리 부족 여러 Runner가 GPU 메모리 경쟁 resources={"gpu": 0.5}로 분할하거나, CUDA_VISIBLE_DEVICES로 지정
요청 타임아웃 모델 추론 시간 초과 traffic={"timeout": 120} 증가, 배치 크기 조정, 비동기 처리 검토
Docker 빌드 실패 베이스 이미지 호환성 docker.build_args로 맞춤 베이스 이미지 지정 (예: nvidia/cuda:...)
Cold start 지연 대형 모델 로딩 시간 모델 사전 로딩, 작은 사이즈 모델 사용, 워머 스크립트 추가

주의: 프로덕션 배포 전에는 반드시 부하 테스트를 수행하세요. locust나 k6를 사용하여 서비스의 성능 한계를 파악하는 것이 좋습니다.

7. 참고 자료

학습 경로 추천: 공식 문서의 "Getting Started" → 예제 레포지토리 클론 → 자신의 모델로 Bento 빌드 → Kubernetes에 배포해보기