mbart-translation/CLAUDE.md

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 (권장)

# 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

# 개발 서버 실행 (자동 리로드)
python main.py

# 프로덕션 서버 실행
uvicorn main:app --host 0.0.0.0 --port 8000

# GPU 사용하여 실행
DEVICE=cuda python main.py

Installation

# 의존성 설치
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

# 헬스 체크
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로, 컨테이너 재시작 시 재다운로드 방지를 위해 볼륨 마운트 필수:

-v mbart-cache:/home/appuser/.cache/huggingface

Resource Requirements

• CPU: 최소 8GB RAM (16GB 권장)
• GPU: 최소 8GB VRAM
• Disk: 모델 캐시용 약 5GB 여유 공간