Initial commit: mBART Translation API with Docker support

- FastAPI 기반 다국어 번역 REST API 서비스
- mBART-50 모델을 사용한 18개 언어 지원
- Docker 및 Docker Compose 설정 포함
- GPU/CPU 지원
- 헬스 체크 및 API 문서 자동 생성
- 외부 접속 지원 (172.30.1.2:8000)

주요 파일:
- main.py: FastAPI 애플리케이션
- translator.py: mBART 번역 서비스
- models.py: Pydantic 데이터 모델
- config.py: 환경 설정
- Dockerfile: 최적화된 Docker 이미지
- docker-compose.yml: 간편한 배포 설정

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,151 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+mBART Translation API - FastAPI 기반의 다국어 번역 REST API 서비스. Facebook의 mBART-50 모델을 사용하여 18개 이상의 언어 간 번역을 제공합니다.
+
+## Commands
+
+### Docker (권장)
+
+```bash
+# Docker Compose로 시작 (가장 쉬움)
+docker-compose up -d
+
+# 로그 확인
+docker-compose logs -f
+
+# 서비스 중지
+docker-compose down
+
+# Docker 직접 사용
+docker build -t mbart-translation-api .
+docker run -d -p 8000:8000 --name mbart-api mbart-translation-api
+
+# GPU 지원
+docker run -d --gpus all -p 8000:8000 -e DEVICE=cuda --name mbart-api-gpu mbart-translation-api
+```
+
+### Local Development
+
+```bash
+# 개발 서버 실행 (자동 리로드)
+python main.py
+
+# 프로덕션 서버 실행
+uvicorn main:app --host 0.0.0.0 --port 8000
+
+# GPU 사용하여 실행
+DEVICE=cuda python main.py
+```
+
+### Installation
+
+```bash
+# 의존성 설치
+pip install -r requirements.txt
+
+# 가상 환경 사용 권장
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# or
+venv\Scripts\activate  # Windows
+pip install -r requirements.txt
+```
+
+### Testing API
+
+```bash
+# 헬스 체크
+curl http://localhost:8000/health
+
+# 번역 테스트 (한국어 -> 영어)
+curl -X POST "http://localhost:8000/translate" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "안녕하세요", "source_lang": "ko", "target_lang": "en"}'
+
+# 지원 언어 목록 조회
+curl http://localhost:8000/languages
+```
+
+## Architecture
+
+### Core Components
+
+1. **main.py** - FastAPI 애플리케이션
+   - `/translate` POST: 번역 요청 처리
+   - `/health` GET: 서비스 상태 확인
+   - `/languages` GET: 지원 언어 목록
+   - `lifespan`: 애플리케이션 시작 시 모델 로드
+
+2. **translator.py** - MBartTranslator 클래스
+   - `load_model()`: mBART 모델과 토크나이저 초기화
+   - `translate()`: 실제 번역 수행
+   - GPU/CPU 자동 감지 및 할당
+   - 모델: facebook/mbart-large-50-many-to-many-mmt
+
+3. **models.py** - Pydantic 데이터 모델
+   - TranslationRequest: 번역 요청 스키마
+   - TranslationResponse: 번역 응답 스키마
+   - HealthResponse, LanguagesResponse
+
+4. **config.py** - 설정 관리
+   - 환경 변수 기반 설정
+   - SUPPORTED_LANGUAGES: 언어 코드 매핑 (예: "ko" -> "ko_KR")
+
+### Request Flow
+
+```
+Client Request → FastAPI Endpoint → Validation (Pydantic)
+                                         ↓
+Response ← Translated Text ← MBartTranslator.translate()
+```
+
+### Model Loading
+
+- 애플리케이션 시작 시 `lifespan` 이벤트에서 모델 로드
+- 첫 실행 시 HuggingFace에서 모델 다운로드 (약 2.4GB)
+- 이후 실행에서는 캐시된 모델 사용 (~/.cache/huggingface/)
+
+### Language Code Mapping
+
+mBART는 특정 언어 코드 형식을 사용합니다:
+- 일반 코드 (ko, en) → mBART 코드 (ko_KR, en_XX)
+- config.py의 SUPPORTED_LANGUAGES에 정의
+- 새 언어 추가 시 이 딕셔너리에 추가 필요
+
+## Key Implementation Details
+
+- **Device Selection**: CUDA 사용 가능 시 자동으로 GPU 사용, 아니면 CPU
+- **Token Length**: MAX_LENGTH(기본 512)로 입력 길이 제한
+- **Error Handling**: 언어 코드 검증, 모델 로드 상태 확인
+- **CORS**: 모든 origin 허용 (프로덕션에서는 제한 필요)
+
+## Configuration
+
+환경 변수로 설정 변경:
+- `HOST`, `PORT`: 서버 바인딩 설정
+- `MODEL_NAME`: 사용할 mBART 모델 (다른 변형 가능)
+- `MAX_LENGTH`: 최대 토큰 길이
+- `DEVICE`: "cuda" 또는 "cpu"
+
+## Docker Details
+
+### Image Structure
+- Base: python:3.11-slim
+- Non-root user (appuser) for security
+- Health check endpoint: /health
+- Model cache volume: /home/appuser/.cache/huggingface
+
+### Volume Management
+모델은 약 2.4GB로, 컨테이너 재시작 시 재다운로드 방지를 위해 볼륨 마운트 필수:
+```bash
+-v mbart-cache:/home/appuser/.cache/huggingface
+```
+
+### Resource Requirements
+- CPU: 최소 8GB RAM (16GB 권장)
+- GPU: 최소 8GB VRAM
+- Disk: 모델 캐시용 약 5GB 여유 공간