Initial commit: mBART Translation API with Docker support
- 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>
This commit is contained in:
jungwoo choi
274
README.md
Normal file
274
README.md
Normal file
@ -0,0 +1,274 @@
|
||||
# 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)을 사용합니다.
|
||||
Reference in New Issue
Block a user