c8802cfc65
- 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>
152 lines
4.1 KiB
Markdown
152 lines
4.1 KiB
Markdown
# 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 여유 공간
|