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