LLM Gateway API

프로젝트 개요

이 프로젝트는 ocr_gateway_test와 연동하여 OCR 모델을 테스트하는 데 사용되는 API 게이트웨이입니다.

설치 및 실행 방법

이 프로젝트는 Docker Compose를 사용하여 각 서비스를 컨테이너 환경에서 실행합니다. 로컬에 Python 가상 환경(venv)을 구성할 필요가 없습니다.

Docker 설치: 시스템에 Docker와 Docker Compose가 설치되어 있어야 합니다.
환경 변수 설정: 프로젝트 루트의 .env 파일을 각 환경에 맞게 설정합니다.
서비스 실행: 아래 명령어를 사용하여 모든 서비스를 백그라운드에서 실행합니다.
```
docker compose up -d
```
서비스 로그 확인: 아래 명령어로 서비스 로그를 확인할 수 있습니다.
```
docker compose logs -f
```
서비스 종료: 실행 중인 서비스를 중지하려면 아래 명령어를 사용합니다.
```
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 구조 예시입니다. (실제 응답은 다를 수 있습니다.)

{
  "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": {
      "제목": "문서의 제목",
      "한글제목": "번역된 한국어 제목",
      "본문": "문서의 영문 본문",
      "한글본문": "번역된 한국어 본문",
      "날짜": "문서에 명시된 날짜",
      "보낸사람": "발신인 정보",
      "받는사람": "수신인 정보",
      "연관공문": "참조 또는 연관된 문서",
      "문서유형": "문서의 분류 (예: 보고서, 계약서)"
    }
  }
}