> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# BentoML

**머신러닝 모델 패키징 및 서빙 프레임워크**입니다. 학습된 모델을 API 서버로 패키징하고 Docker 이미지로 배포할 수 있습니다.

## 어디에 쓰이나요?

* **모델 API 서빙**: Python으로 학습한 모델을 REST/gRPC API로 배포
* **모델 패키징**: 모델 + 전처리/후처리 코드 + 의존성을 하나의 패키지(Bento)로 묶어서 관리
* **적응형 배치**: 요청을 자동으로 모아서 배치 처리하여 GPU 활용률 향상
* **멀티 모델 파이프라인**: 여러 모델을 하나의 서비스로 구성 (Runner 패턴)

Triton이 사전 변환된 모델(ONNX, TensorRT)을 서빙하는 데 강점이 있다면, BentoML은 **Python 코드로 작성된 모델을 그대로** 서빙할 수 있어 더 유연합니다.

## Docker Compose

BentoML은 모델 서비스를 Bento로 빌드한 후 Docker 이미지로 변환합니다.

### 1. 서비스 코드 작성 (service.py)

```python theme={null}
import bentoml
from bentoml.io import JSON

runner = bentoml.sklearn.get("iris_classifier:latest").to_runner()
svc = bentoml.Service("iris_classifier", runners=[runner])

@svc.api(input=JSON(), output=JSON())
async def predict(input_data):
    result = await runner.predict.async_run(input_data["features"])
    return {"prediction": result.tolist()}
```

### 2. Bento 빌드 및 Docker 이미지 생성

```bash theme={null}
bentoml build
bentoml containerize iris_classifier:latest
```

### 3. Docker Compose로 실행

```yaml docker-compose.yml theme={null}
services:
  bentoml:
    image: iris_classifier:latest
    container_name: bentoml
    restart: unless-stopped
    ports:
      - "3000:3000"
```

## 실행

```bash theme={null}
docker compose up -d
```

## 접속 확인

```bash theme={null}
curl -X POST http://localhost:3000/predict \
  -H "Content-Type: application/json" \
  -d '{"features": [5.1, 3.5, 1.4, 0.2]}'
```

## 기본 정보

| 항목     | 값           |
| ------ | ----------- |
| API 포트 | 3000        |
| API 형식 | REST / gRPC |

## 라이선스

| 구분     | 내용                       |
| ------ | ------------------------ |
| 라이선스   | Apache License 2.0       |
| 개인 사용  | 자유롭게 사용 가능               |
| 상업적 사용 | 자유롭게 사용 가능, 수정/재배포 제한 없음 |

## 참고

* [BentoML 공식 문서](https://docs.bentoml.com/)
* [BentoML GitHub](https://github.com/bentoml/BentoML)

## 설치 점검 목록

* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.

## 문제 해결 가이드

* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: UV 프로젝트 환경" icon="arrow-right" href="/setup/uv-env">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>