170 lines
6.7 KiB
Markdown
170 lines
6.7 KiB
Markdown
# LLM Gateway API
|
|
|
|
## 프로젝트 개요
|
|
|
|
이 프로젝트는 `ocr_gateway_test`와 연동하여 OCR 모델을 테스트하는 데 사용되는 API 게이트웨이입니다.
|
|
|
|
## 설치 및 실행 방법
|
|
|
|
이 프로젝트는 Docker Compose를 사용하여 각 서비스를 컨테이너 환경에서 실행합니다. 로컬에 Python 가상 환경(`venv`)을 구성할 필요가 없습니다.
|
|
|
|
1. **Docker 설치**: 시스템에 Docker와 Docker Compose가 설치되어 있어야 합니다.
|
|
|
|
2. **환경 변수 설정**: 프로젝트 루트의 `.env` 파일을 각 환경에 맞게 설정합니다.
|
|
|
|
3. **서비스 실행**: 아래 명령어를 사용하여 모든 서비스를 백그라운드에서 실행합니다.
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
4. **서비스 로그 확인**: 아래 명령어로 서비스 로그를 확인할 수 있습니다.
|
|
|
|
```bash
|
|
docker compose logs -f
|
|
```
|
|
|
|
5. **서비스 종료**: 실행 중인 서비스를 중지하려면 아래 명령어를 사용합니다.
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
/mnt/c/Python/workspace/llm_gateway_test/
|
|
├───.env
|
|
├───.gitattributes
|
|
├───.gitignore
|
|
├───.python-version
|
|
├───api_keys.json
|
|
├───docker-compose.yml
|
|
├───Dockerfile
|
|
├───pyproject.toml
|
|
├───README.md
|
|
├───requirements.lock
|
|
├───uv.lock
|
|
├───logs/
|
|
└───src/
|
|
├───api_keys.json
|
|
├───api.py # FastAPI 애플리케이션 진입점
|
|
├───config/ # 설정 관련 모듈
|
|
│ ├───__init__.py
|
|
│ ├───log_config.yaml
|
|
│ └───setting.py
|
|
├───interface/ # 사용자 인터페이스 (Streamlit 등)
|
|
│ ├───__init__.py
|
|
│ └───streamlit_ui.py
|
|
├───routers/ # FastAPI 라우터 (API 엔드포인트 정의)
|
|
│ ├───__init__.py
|
|
│ ├───api_key_router.py
|
|
│ ├───download_router.py
|
|
│ ├───dummy_router.py
|
|
│ ├───extract_router.py
|
|
│ ├───general_router.py
|
|
│ ├───guide_router.py
|
|
│ ├───llm_summation.py
|
|
│ ├───model_router.py
|
|
│ ├───ocr_router.py
|
|
│ ├───stt_router.py
|
|
│ └───yolo_router.py
|
|
├───services/ # 비즈니스 로직 처리 서비스
|
|
│ ├───__init__.py
|
|
│ ├───api_key_service.py
|
|
│ ├───download_service.py
|
|
│ ├───dummy_service.py
|
|
│ ├───inference_service.py
|
|
│ ├───model_service.py
|
|
│ ├───pipeline_runner.py
|
|
│ ├───prompt.py
|
|
│ └───report.py
|
|
├───static/ # 정적 파일 (가이드 HTML, 예제 등)
|
|
└───utils/ # 공용 유틸리티 모듈
|
|
```
|
|
|
|
## 주요 API 엔드포인트
|
|
|
|
### 상태 확인 및 가이드
|
|
|
|
| 경로 | 메서드 | 설명 |
|
|
| ---------------- | ------ | -------------------------- |
|
|
| `/health/*` | GET | 서버 상태 확인 |
|
|
| `/info` | GET | 사용 가능한 모델 목록 조회 |
|
|
| `/general_guide` | GET | 범용 추론 가이드 HTML 제공 |
|
|
| `/extract_guide` | GET | 문서 추출 가이드 HTML 제공 |
|
|
|
|
### 범용 추론 (General)
|
|
|
|
| 경로 | 메서드 | 설명 |
|
|
| -------------------------------- | ------ | -------------------------------- |
|
|
| `/general/inner` | POST | 내부 LLM 기반 범용 추론 (비동기) |
|
|
| `/general/outer` | POST | 외부 LLM 기반 범용 추론 (비동기) |
|
|
| `/general/progress/{request_id}` | GET | 범용 추론 작업 상태 및 결과 조회 |
|
|
|
|
### 문서 정보 추출 (Extract)
|
|
|
|
| 경로 | 메서드 | 설명 |
|
|
| -------------------------------- | ------ | ------------------------------------- |
|
|
| `/extract/inner` | POST | 내부 LLM 기반 문서 정보 추출 (비동기) |
|
|
| `/extract/outer` | POST | 외부 LLM 기반 문서 정보 추출 (비동기) |
|
|
| `/extract/progress/{request_id}` | GET | 문서 추출 작업 상태 및 결과 조회 |
|
|
|
|
### 텍스트 추출 (OCR)
|
|
|
|
| 경로 | 메서드 | 설명 |
|
|
| ---------------------------- | ------ | -------------------------------- |
|
|
| `/ocr` | POST | 문서 파일 OCR 작업 요청 (비동기) |
|
|
| `/ocr/progress/{request_id}` | GET | OCR 작업 진행 상태 조회 |
|
|
| `/ocr/result/{request_id}` | GET | OCR 작업 결과 조회 |
|
|
|
|
### 음성-텍스트 변환 (STT)
|
|
|
|
| 경로 | 메서드 | 설명 |
|
|
| ------------------------ | ------ | ---------------------------------------- |
|
|
| `/audio` | POST | 음성 파일을 STT API로 전달하여 변환 요청 |
|
|
| `/progress/{request_id}` | GET | STT 작업 진행 상태 조회 |
|
|
| `/result/{request_id}` | GET | STT 작업 결과 조회 |
|
|
|
|
## 결과 JSON 구조 예시
|
|
|
|
문서 추출 API (`/extract/*`) 호출 시 반환되는 최종 결과의 JSON 구조 예시입니다. (실제 응답은 다를 수 있습니다.)
|
|
|
|
```json
|
|
{
|
|
"request_id": "요청 식별자",
|
|
"progress_logs": [
|
|
{"status": "작업 접수", "timestamp": "2025-07-21T10:00:00Z"},
|
|
{"status": "OCR 작업 시작", "timestamp": "2025-07-21T10:00:05Z"},
|
|
{"status": "텍스트 추출 중", "timestamp": "2025-07-21T10:00:06Z"}
|
|
],
|
|
"final_result": {
|
|
"filename": "example.pdf",
|
|
"model": {
|
|
"ocr_model": "tesseract",
|
|
"llm_model": "gemma:7b"
|
|
},
|
|
"time": {
|
|
"duration_sec": 25.5,
|
|
"started_at": 1721556000.0,
|
|
"ended_at": 1721556025.5
|
|
},
|
|
"fields": {
|
|
"추출된 텍스트": [[x1, y1], [x2, y2], [x3, y3], [x4, y4]]
|
|
},
|
|
"parsed": "OCR 모델로 추출한 원본 텍스트입니다.",
|
|
"generated": "LLM이 요약 및 번역한 텍스트입니다.",
|
|
"processed": {
|
|
"제목": "문서의 제목",
|
|
"한글제목": "번역된 한국어 제목",
|
|
"본문": "문서의 영문 본문",
|
|
"한글본문": "번역된 한국어 본문",
|
|
"날짜": "문서에 명시된 날짜",
|
|
"보낸사람": "발신인 정보",
|
|
"받는사람": "수신인 정보",
|
|
"연관공문": "참조 또는 연관된 문서",
|
|
"문서유형": "문서의 분류 (예: 보고서, 계약서)"
|
|
}
|
|
}
|
|
}
|
|
```
|