multilingual-translation/README.md

Multilingual Translation API

최대 204개 언어를 지원하는 다국어 번역 REST API 서비스입니다. 상업적 사용이 가능한 M2M100 모델(105개 언어)을 기본으로 제공하며, 비상업적 용도로 NLLB-200 모델(204개 언어)을 선택할 수 있습니다.

주요 기능

• 최대 204개 언어 지원 - 모든 언어 간 양방향 번역 가능 (Any-to-Any Translation)
• 듀얼 모델 시스템
  • M2M100 (기본): 105개 언어, Apache 2.0 라이선스, 상업적 사용 가능 ✅
  • NLLB-200 (옵션): 204개 언어, CC-BY-NC 4.0 라이선스, 비상업적 용도만 가능
• 고성능 번역 - 최신 신경망 기계 번역 모델
• FastAPI 기반 - 고성능 비동기 REST API
• Docker 지원 - 간편한 배포 및 확장
• 자동 API 문서화 - Swagger UI 제공
• GPU 자동 감지 - CUDA 사용 가능 시 자동으로 GPU 활용

지원 언어

M2M100 모델 (105개 언어, 기본)

상업적 사용 가능 ✅ Apache 2.0 License

주요 언어: English, 中文 (Chinese), Español (Spanish), العربية (Arabic), हिन्दी (Hindi), বাংলা (Bengali), Português (Portuguese), Русский (Russian), 日本語 (Japanese), Deutsch (German), Français (French), 한국어 (Korean), Italiano (Italian), Türkçe (Turkish)

동남아시아: Bahasa Melayu (Malay), Bahasa Indonesia (Indonesian), ไทย (Thai), Tiếng Việt (Vietnamese), Tagalog, မြန်မာဘာသာ (Burmese), ភាសាខ្មែរ (Khmer), ລາວ (Lao)

남아시아: اردو (Urdu), தமிழ் (Tamil), తెలుగు (Telugu), मराठी (Marathi), ગુજરાતી (Gujarati), ಕನ್ನಡ (Kannada), മലയാളം (Malayalam), ਪੰਜਾਬੀ (Punjabi), नेपाली (Nepali), සිංහල (Sinhala)

유럽: Polski (Polish), Nederlands (Dutch), Українська (Ukrainian), Română (Romanian), Svenska (Swedish), Dansk (Danish), Suomi (Finnish), Norsk (Norwegian), Čeština (Czech), Slovenčina (Slovak), Magyar (Hungarian), Български (Bulgarian), Српski (Serbian), Hrvatski (Croatian), Slovenščina (Slovenian), Eesti (Estonian), Latviešu (Latvian), Lietuvių (Lithuanian), Ελληνικά (Greek), עברית (Hebrew), فارسی (Persian), Català (Catalan), Euskara (Basque), Galego (Galician), Cymraeg (Welsh), Gaeilge (Irish), Gàidhlig (Scottish Gaelic), Íslenska (Icelandic), Malti (Maltese)

아프리카: Kiswahili (Swahili), አማርኛ (Amharic), Hausa, Igbo, Yorùbá (Yoruba), isiZulu (Zulu), isiXhosa (Xhosa), Afrikaans, Malagasy, Luganda, Lingála (Lingala), chiShona (Shona), Soomaali (Somali), Sesotho, Chichewa

기타: Azərbaycan (Azerbaijani), ქართული (Georgian), Қазақша (Kazakh), Oʻzbekcha (Uzbek), Монгол (Mongolian), Shqip (Albanian), Հայերեն (Armenian), Беларуская (Belarusian), Bosanski (Bosnian), Esperanto, Frysk (Frisian), ʻŌlelo Hawaiʻi (Hawaiian), Hmong, Kreyòl ayisyen (Haitian Creole), Kurdî (Kurdish), Кыргызча (Kyrgyz), Latina (Latin), Lëtzebuergesch (Luxembourgish), Te Reo Māori (Maori), Македонски (Macedonian), پښتو (Pashto), Тоҷикӣ (Tajik), Türkmençe (Turkmen), ئۇيغۇرچە (Uyghur), ייִדיש (Yiddish)

NLLB-200 모델 (204개 언어, 옵션)

비상업적 용도만 가능 ⚠️ CC-BY-NC 4.0 License

M2M100의 105개 언어에 더해 다음 99개 추가 언어 지원:

• 동남아시아: Acehnese, Balinese, Banjar, Buginese, Minangkabau
• 남아시아: Assamese, Awadhi, Bhojpuri, Chhattisgarhi, Magahi, Maithili, Meitei, Odia, Santali
• 아프리카: Akan, Bambara, Bemba, Chokwe, Dyula, Fon, Kikuyu, Kimbundu, Kongo, Luba-Kasai, Luo, Mossi, Nuer, Northern Sotho, Tumbuka, Umbundu, Wolof
• 중동/아랍: Mesopotamian Arabic, Najdi Arabic, Moroccan Arabic, Egyptian Arabic, Tunisian Arabic, South Levantine Arabic, North Levantine Arabic, Dari, Central Kurdish, Sindhi
• 유럽: Asturian, Friulian, Latgalian, Ligurian, Limburgish, Lombard, Norwegian Nynorsk, Norwegian Bokmål, Occitan, Sardinian, Sicilian, Silesian, Venetian
• 중앙아시아: Bashkir, Crimean Tatar, South Azerbaijani, Tatar
• 기타: Dzongkha, Fijian, Guarani, Kabyle, Kabuverdianu, Papiamento, Quechua, Samoan, Sango, Shan, Tamasheq, Tibetan, Tok Pisin
• 그 외 다양한 지역 언어 및 방언

전체 언어 목록 및 언어 코드는 다음 엔드포인트에서 확인:

• M2M100: /api/supported-languages?model=m2m100
• NLLB-200: /api/supported-languages?model=nllb200

빠른 시작

1. Docker로 실행 (권장)

# Docker Compose로 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 서비스 종료
docker-compose down

서버가 실행되면 http://localhost:8001 에서 API에 접근할 수 있습니다.

2. 로컬 환경 설정

주의: PyTorch는 Python 3.13을 지원하지 않으므로 Python 3.11 이하 버전을 사용해야 합니다.

# Python 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

# 환경변수 설정 (선택사항)
cp .env.example .env

# 서버 실행
python run.py

서버가 실행되면 http://localhost:8000 에서 API에 접근할 수 있습니다.

API 사용법

번역 요청

M2M100 모델 (기본, 상업적 사용 가능)

# 말레이어 → 영어
curl -X POST "http://localhost:8001/api/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Selamat pagi, apa khabar?",
    "source_lang": "ms",
    "target_lang": "en"
  }'

# 영어 → 한국어 (model 파라미터 생략 시 m2m100이 기본값)
curl -X POST "http://localhost:8001/api/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, how are you?",
    "source_lang": "en",
    "target_lang": "ko",
    "model": "m2m100"
  }'

응답:

{
  "original_text": "Selamat pagi, apa khabar?",
  "translated_text": "Good morning, how are you?",
  "source_lang": "ms",
  "target_lang": "en",
  "model_used": "facebook/m2m100_418M"
}

NLLB-200 모델 (204개 언어, 비상업적 용도)

# 영어 → 벵골어 (NLLB-200 사용)
curl -X POST "http://localhost:8001/api/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Good morning",
    "source_lang": "en",
    "target_lang": "bn",
    "model": "nllb200"
  }'

# 영어 → Bemba (NLLB-200 전용 언어)
curl -X POST "http://localhost:8001/api/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to our service",
    "source_lang": "en",
    "target_lang": "bem",
    "model": "nllb200"
  }'

응답:

{
  "original_text": "Good morning",
  "translated_text": "শুভ সকাল",
  "source_lang": "en",
  "target_lang": "bn",
  "model_used": "facebook/nllb-200-distilled-600M"
}

지원 언어 확인

# M2M100 지원 언어 (105개)
curl http://localhost:8001/api/supported-languages?model=m2m100

# NLLB-200 지원 언어 (204개)
curl http://localhost:8001/api/supported-languages?model=nllb200

응답:

{
  "model": {
    "name": "M2M100",
    "languages": 105,
    "license": "Apache 2.0",
    "commercial_use": true,
    "model_id": "facebook/m2m100_418M"
  },
  "languages": [
    {
      "code": "af",
      "name": "Afrikaans",
      "native_name": "Afrikaans"
    },
    {
      "code": "en",
      "name": "English",
      "native_name": "English"
    },
    {
      "code": "ko",
      "name": "Korean",
      "native_name": "한국어"
    },
    ...
  ],
  "total_languages": 105,
  "note": "All language pairs are supported (any-to-any translation)"
}

헬스체크

curl http://localhost:8001/health

응답:

{
  "status": "healthy",
  "message": "Translation service is running",
  "models_loaded": true
}

API 문서

서버 실행 후 다음 URL에서 자동 생성된 API 문서를 확인할 수 있습니다:

• Swagger UI: http://localhost:8001/docs
• ReDoc: http://localhost:8001/redoc

기술 스택

• FastAPI: 고성능 비동기 웹 프레임워크
• Transformers (Hugging Face): 머신러닝 모델 로딩 및 추론
• PyTorch: 딥러닝 프레임워크
• 번역 모델:
  • M2M100 (Facebook): 418M 파라미터, 105개 언어 (기본)
  • NLLB-200 (Facebook): 600M 파라미터, 204개 언어 (옵션)
• Docker & Docker Compose: 컨테이너화 및 배포
• Pydantic: 데이터 검증 및 설정 관리
• Uvicorn: ASGI 서버

프로젝트 구조

site13/
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI 애플리케이션 및 엔드포인트
│   ├── models.py        # Pydantic 데이터 모델
│   ├── translator.py    # 번역 서비스 로직 (M2M100 + NLLB-200)
│   └── config.py        # 설정 관리
├── models/              # 다운로드된 번역 모델 캐시 (자동 생성)
├── requirements.txt     # Python 의존성
├── run.py              # 서버 실행 스크립트
├── Dockerfile          # Docker 이미지 빌드 설정
├── docker-compose.yml  # Docker Compose 설정
├── CLAUDE.md           # 개발자 문서
└── README.md           # 프로젝트 문서

환경 변수

.env 파일에서 다음 설정을 변경할 수 있습니다:

• API_HOST: API 서버 호스트 (기본값: 0.0.0.0)
• API_PORT: API 서버 포트 (기본값: 8000)
• MODEL_CACHE_DIR: 모델 캐시 디렉토리 (기본값: ./models)
• MAX_LENGTH: 최대 번역 길이 (기본값: 512)
• ALLOWED_ORIGINS: CORS 허용 오리진 (기본값: *)

성능 최적화

• 첫 실행 시 선택한 모델을 다운로드합니다:
  • M2M100: ~1.6GB
  • NLLB-200: ~2.5GB
• 모델은 models/ 디렉토리에 캐시되어 재사용됩니다
• GPU가 있는 경우 자동으로 감지하여 사용합니다
• Docker volume을 사용하여 모델을 영구 저장합니다
• 시작 시 번역 모델을 미리 로드하여 첫 요청 응답 시간을 단축합니다

개발

# 개발 모드로 실행 (자동 재시작)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Docker 재빌드
docker-compose down
docker-compose up -d --build

라이선스

모델 라이선스

M2M100 모델 (기본)

• 라이선스: Apache 2.0 License
• 상업적 사용: ✅ 허용됨
• 모델 크기: ~1.6GB
• 언어 수: 105개
• 모델 정보: https://huggingface.co/facebook/m2m100_418M

NLLB-200 모델 (옵션)

• 라이선스: CC-BY-NC 4.0 License
• 상업적 사용: ⚠️ 비상업적 용도만 가능
• 모델 크기: ~2.5GB
• 언어 수: 204개
• 모델 정보: https://huggingface.co/facebook/nllb-200-distilled-600M
• 주의: 연구, 교육, 개인 프로젝트 등 비상업적 목적으로만 사용 가능합니다.

프로젝트 코드

프로젝트 코드는 자유롭게 사용 가능합니다.

제한사항

• 텍스트 길이: 1-5000 자
• 모델 크기: M2M100 ~1.6GB, NLLB-200 ~2.5GB (디스크 공간 필요)
• Python 3.11 이하 버전 필요 (PyTorch 호환성)
• NLLB-200 모델은 비상업적 용도로만 사용 가능

트러블슈팅

포트 충돌 오류

Docker Compose는 포트 8001을 사용합니다. 포트가 이미 사용 중이면 docker-compose.yml에서 포트를 변경하세요:

ports:
  - "9001:8000"  # 9001로 변경

모델 다운로드 실패

인터넷 연결을 확인하고 다시 시도하세요. HuggingFace Hub에 접근할 수 있어야 합니다.

GPU 사용 안 됨

NVIDIA GPU를 사용하려면 Docker에서 nvidia-docker를 설치하고 docker-compose.yml에 GPU 설정을 추가해야 합니다.

기여

이슈 리포트 및 풀 리퀘스트를 환영합니다.

연락처

프로젝트 관련 문의사항이 있으시면 이슈를 생성해 주세요.