# mBART Translation API

mBART 모델을 사용한 다국어 번역 REST API 서비스입니다.

## 기능

- mBART-50 모델을 사용한 다국어 번역
- RESTful API 인터페이스
- 18개 이상의 언어 지원 (한국어, 영어, 일본어, 중국어 등)
- GPU/CPU 지원
- 자동 API 문서화 (Swagger UI)

## 지원 언어

- 한국어 (ko)
- 영어 (en)
- 일본어 (ja)
- 중국어 (zh)
- 스페인어 (es)
- 프랑스어 (fr)
- 독일어 (de)
- 러시아어 (ru)
- 아랍어 (ar)
- 힌디어 (hi)
- 베트남어 (vi)
- 태국어 (th)
- 인도네시아어 (id)
- 터키어 (tr)
- 포르투갈어 (pt)
- 이탈리아어 (it)
- 네덜란드어 (nl)
- 폴란드어 (pl)

## 빠른 시작 (Docker 권장)

### Docker Compose 사용 (가장 쉬운 방법)

```bash
# 1. 서비스 시작
docker-compose up -d

# 2. 로그 확인
docker-compose logs -f

# 3. 서비스 중지
docker-compose down
```

서비스가 시작되면 http://localhost:8000 에서 API를 사용할 수 있습니다.

### 외부 접속

외부에서 접속하려면 서버의 IP 주소를 사용하세요:
- 로컬: http://localhost:8000
- 외부: http://172.30.1.2:8000 (서버 IP 주소로 변경)

### Docker 직접 사용

```bash
# 1. 이미지 빌드
docker build -t mbart-translation-api .

# 2. 컨테이너 실행
docker run -d \
  --name mbart-api \
  -p 8000:8000 \
  -e DEVICE=cpu \
  -v mbart-cache:/home/appuser/.cache/huggingface \
  mbart-translation-api

# 3. 로그 확인
docker logs -f mbart-api

# 4. 컨테이너 중지
docker stop mbart-api
docker rm mbart-api
```

### GPU 지원 (NVIDIA GPU)

GPU를 사용하려면 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)이 설치되어 있어야 합니다.

```bash
docker run -d \
  --name mbart-api-gpu \
  --gpus all \
  -p 8000:8000 \
  -e DEVICE=cuda \
  -v mbart-cache:/home/appuser/.cache/huggingface \
  mbart-translation-api
```

또는 docker-compose.yml에서 GPU 서비스 주석을 해제하세요.

## 로컬 설치 및 실행

### 1. 의존성 설치

```bash
pip install -r requirements.txt
```

### 2. 환경 변수 설정 (선택사항)

```bash
cp .env.example .env
```

`.env` 파일을 편집하여 설정을 변경할 수 있습니다:

```
HOST=0.0.0.0
PORT=8000
MODEL_NAME=facebook/mbart-large-50-many-to-many-mmt
MAX_LENGTH=512
DEVICE=cpu  # GPU 사용 시 cuda로 변경
```

### 3. 실행

#### 개발 모드

```bash
python main.py
```

#### 프로덕션 모드

```bash
uvicorn main:app --host 0.0.0.0 --port 8000
```

#### GPU 사용

```bash
DEVICE=cuda python main.py
```

## API 사용법

### API 문서

서버 실행 후 다음 URL에서 자동 생성된 API 문서를 확인할 수 있습니다:
- Swagger UI: http://localhost:8000/docs (또는 http://172.30.1.2:8000/docs)
- ReDoc: http://localhost:8000/redoc (또는 http://172.30.1.2:8000/redoc)

### 엔드포인트

#### 1. 번역 API

**POST** `/translate`

요청 예시:

```bash
# 로컬에서 테스트
curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "안녕하세요, 반갑습니다.",
    "source_lang": "ko",
    "target_lang": "en"
  }'

# 외부에서 접속
curl -X POST "http://172.30.1.2:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "안녕하세요, 반갑습니다.",
    "source_lang": "ko",
    "target_lang": "en"
  }'
```

응답 예시:

```json
{
  "translated_text": "Hello, nice to meet you.",
  "source_lang": "ko",
  "target_lang": "en",
  "original_text": "안녕하세요, 반갑습니다."
}
```

#### 2. 헬스 체크

**GET** `/health`

```bash
# 로컬
curl http://localhost:8000/health

# 외부
curl http://172.30.1.2:8000/health
```

응답:

```json
{
  "status": "healthy",
  "model_loaded": true,
  "device": "cpu"
}
```

#### 3. 지원 언어 목록

**GET** `/languages`

```bash
# 로컬
curl http://localhost:8000/languages

# 외부
curl http://172.30.1.2:8000/languages
```

## 프로젝트 구조

```
.
├── main.py              # FastAPI 애플리케이션 메인 파일
├── translator.py        # mBART 번역 서비스 클래스
├── models.py            # Pydantic 데이터 모델
├── config.py            # 설정 파일
├── requirements.txt     # Python 의존성
├── Dockerfile           # Docker 이미지 빌드 설정
├── docker-compose.yml   # Docker Compose 설정
├── .dockerignore        # Docker 빌드 제외 파일
├── .env.example         # 환경 변수 예시
├── .gitignore          # Git 무시 파일
├── README.md           # 프로젝트 문서
└── CLAUDE.md           # 코드베이스 가이드
```

## 성능 최적화

### GPU 사용

CUDA가 설치된 환경에서는 GPU를 사용하여 번역 속도를 크게 향상시킬 수 있습니다:

```bash
DEVICE=cuda python main.py
```

### 모델 캐싱

첫 실행 시 모델이 다운로드되며, 이후 실행에서는 캐시된 모델을 사용합니다.

## 문제 해결

### 메모리 부족

mBART 모델은 크기가 크므로 충분한 메모리가 필요합니다:
- CPU: 최소 8GB RAM 권장
- GPU: 최소 8GB VRAM 권장

메모리가 부족한 경우 `MAX_LENGTH` 값을 줄이거나 더 작은 모델을 사용하세요.

### CUDA 오류

GPU 사용 시 CUDA 관련 오류가 발생하면:

```bash
DEVICE=cpu python main.py
```

CPU 모드로 전환하여 실행하세요.

## 라이선스

이 프로젝트는 mBART 모델 (Facebook AI)을 사용합니다.