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 사용 (가장 쉬운 방법)

# 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 직접 사용

# 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이 설치되어 있어야 합니다.

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

pip install -r requirements.txt

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

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. 실행

개발 모드

python main.py

프로덕션 모드

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

GPU 사용

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

요청 예시:

# 로컬에서 테스트
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"
  }'

응답 예시:

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

2. 헬스 체크

GET /health

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

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

응답:

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

3. 지원 언어 목록

GET /languages

# 로컬
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를 사용하여 번역 속도를 크게 향상시킬 수 있습니다:

DEVICE=cuda python main.py

모델 캐싱

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

문제 해결

메모리 부족

mBART 모델은 크기가 크므로 충분한 메모리가 필요합니다:

• CPU: 최소 8GB RAM 권장
• GPU: 최소 8GB VRAM 권장

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

CUDA 오류

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

DEVICE=cpu python main.py

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

라이선스

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