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>
275 lines
5.4 KiB
Markdown
275 lines
5.4 KiB
Markdown
# 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 사용 (가장 쉬운 방법)
|
|
|
|
```bash
|
|
# 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 직접 사용
|
|
|
|
```bash
|
|
# 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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)이 설치되어 있어야 합니다.
|
|
|
|
```bash
|
|
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. 의존성 설치
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. 환경 변수 설정 (선택사항)
|
|
|
|
```bash
|
|
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. 실행
|
|
|
|
#### 개발 모드
|
|
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
#### 프로덕션 모드
|
|
|
|
```bash
|
|
uvicorn main:app --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
#### GPU 사용
|
|
|
|
```bash
|
|
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`
|
|
|
|
요청 예시:
|
|
|
|
```bash
|
|
# 로컬에서 테스트
|
|
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"
|
|
}'
|
|
```
|
|
|
|
응답 예시:
|
|
|
|
```json
|
|
{
|
|
"translated_text": "Hello, nice to meet you.",
|
|
"source_lang": "ko",
|
|
"target_lang": "en",
|
|
"original_text": "안녕하세요, 반갑습니다."
|
|
}
|
|
```
|
|
|
|
#### 2. 헬스 체크
|
|
|
|
**GET** `/health`
|
|
|
|
```bash
|
|
# 로컬
|
|
curl http://localhost:8000/health
|
|
|
|
# 외부
|
|
curl http://172.30.1.2:8000/health
|
|
```
|
|
|
|
응답:
|
|
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"model_loaded": true,
|
|
"device": "cpu"
|
|
}
|
|
```
|
|
|
|
#### 3. 지원 언어 목록
|
|
|
|
**GET** `/languages`
|
|
|
|
```bash
|
|
# 로컬
|
|
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를 사용하여 번역 속도를 크게 향상시킬 수 있습니다:
|
|
|
|
```bash
|
|
DEVICE=cuda python main.py
|
|
```
|
|
|
|
### 모델 캐싱
|
|
|
|
첫 실행 시 모델이 다운로드되며, 이후 실행에서는 캐시된 모델을 사용합니다.
|
|
|
|
## 문제 해결
|
|
|
|
### 메모리 부족
|
|
|
|
mBART 모델은 크기가 크므로 충분한 메모리가 필요합니다:
|
|
- CPU: 최소 8GB RAM 권장
|
|
- GPU: 최소 8GB VRAM 권장
|
|
|
|
메모리가 부족한 경우 `MAX_LENGTH` 값을 줄이거나 더 작은 모델을 사용하세요.
|
|
|
|
### CUDA 오류
|
|
|
|
GPU 사용 시 CUDA 관련 오류가 발생하면:
|
|
|
|
```bash
|
|
DEVICE=cpu python main.py
|
|
```
|
|
|
|
CPU 모드로 전환하여 실행하세요.
|
|
|
|
## 라이선스
|
|
|
|
이 프로젝트는 mBART 모델 (Facebook AI)을 사용합니다.
|