# LLM Gateway API 가이드 

## 1. 개요

LLM Gateway는 다양한 AI 모델(Ollama, OpenAI, Google, Anthropic 등)을 통합하여 일관된 인터페이스로 제공하는 API 서버입니다. 문서(PDF, 이미지) 처리, 텍스트 생성, 음성-텍스트 변환(STT), 객체 탐지(YOLO) 등 복잡한 AI 파이프라인을 비동기적으로 처리하고 관리하는 기능을 제공합니다.

주요 기술 스택은 다음과 같습니다:

- **프레임워크**: FastAPI
- **비동기 작업 관리**: Redis
- **파일 저장소**: MinIO
- **내부 LLM 호스팅**: Ollama
- **서비스 오케스트레이션**: Docker Compose

---

## 2. 핵심 아키텍처

### 비동기 처리 모델

대부분의 AI 작업은 시간이 오래 걸리므로, 본 시스템은 비동기 파이프라인을 채택했습니다.

1. **요청 접수**: 사용자가 파일을 포함하여 API를 호출하면, 시스템은 즉시 고유한 `request_id`를 발급하고 백그라운드 작업을 생성합니다.
2. **상태 추적**: `request_id`를 사용하여 `/extract/progress/{request_id}`와 같은 `progress` 엔드포인트에서 작업 상태를 폴링(polling)할 수 있습니다.
3. **결과 저장**: 작업이 완료되면, 최종 결과는 별도의 `result_id`와 매핑되어 Redis에 저장됩니다. `progress` 엔드포인트는 작업 완료 시 `final_result` 필드에 최종 결과를 포함하여 반환합니다.

### 서비스 의존성

- **Redis**: 작업 큐, 상태 로그, 최종 결과, API 키 등을 저장하는 핵심 데이터베이스입니다.
- **MinIO**: 사용자가 업로드한 파일을 임시 저장하고, 각 서비스(OCR, STT 등)가 파일에 접근할 수 있도록 Presigned URL을 생성하는 역할을 합니다.
- **OCR API**: PDF, 이미지 등에서 텍스트를 추출하는 별도의 서비스입니다. `/extract`, `/general` 엔드포인트에서 내부적으로 호출됩니다.
- **STT API**: 음성 파일에서 텍스트를 추출하는 별도의 서비스입니다. `/stt` 엔드포인트가 프록시 역할을 합니다.
- **YOLO API**: 이미지에서 객체를 탐지하는 별도의 서비스입니다. `/yolo` 엔드포인트가 프록시 역할을 합니다.

---


## 3. API 엔드포인트 상세 설명

### Tag: `Extraction`

문서(PDF, 이미지 등)에서 사전 정의된 프롬프트를 기반으로 정보를 추출합니다.

* `POST /extract/inner`: **내부 LLM(Ollama)**을 사용합니다.
* `POST /extract/outer`: **외부 LLM(GPT, Gemini 등)**을 사용합니다.
* `POST /extract/structured`: **내외부 LLM을 사용해 JSON 형식 응답 생성**에 사용합니다.* **요청 (multipart/form-data)**:* `input_file`: 분석할 원본 문서 파일.
  * `prompt_file` (선택): 기본 프롬프트를 대체할 `.txt` 파일.
  * `model` (선택): 사용할 LLM 모델 이름.
  * `schema_file` (structured용/필수): 형식을 지정할 `.json` 파일.
  * **응답 (초기)**: `request_id`를 포함한 JSON 객체.
* `GET /extract/progress/{request_id}`: 정보 추출 작업의 진행 상태와 최종 결과를 조회합니다.

### Tag: `General`

문서 기반의 범용 질의응답을 수행합니다. 사용자가 직접 프롬프트를 제공해야 합니다.

* `POST /general/inner`: **내부 LLM(Ollama)**을 사용합니다.
* `POST /general/outer`: **외부 LLM(GPT, Gemini 등)**을 사용합니다.* **요청 (multipart/form-data)**:* `input_file`: 분석할 원본 문서 파일.
  * `prompt_file`: LLM에 전달할 명령어가 담긴 `.txt` 파일.
  * `schema_file` (선택): 결과 포맷을 강제할 `.json` 스키마 파일.
  * `model` (선택): 사용할 LLM 모델 이름.
  * **응답 (초기)**: `request_id`를 포함한 JSON 객체.
* `GET /general/progress/{request_id}`: 범용 추론 작업의 진행 상태와 최종 결과를 조회합니다.

### Tag: `OCR Gateway`

문서에서 텍스트를 추출하는 OCR API를 프록시합니다.

* `POST /ocr`: 문서를 OCR 서버에 전달하고 `request_id`를 받습니다.
* `GET /ocr/progress/{request_id}`: OCR 작업 상태를 조회합니다.

### Tag: `STT Gateway`

음성 파일을 텍스트로 변환하는 STT API를 프록시합니다.

* `POST /audio`: 단일 음성 파일을 STT 서버로 전달합니다.
* `POST /dialog_processing`: 화자 분리가 포함된 음성 파일을 처리합니다.
* `GET /progress/{request_id}`: STT 작업 상태를 조회합니다.

### Tag: `YOLO Gateway`

이미지 내 객체를 탐지하는 YOLO API를 프록시합니다.

* `POST /detect_view`: 이미지를 YOLO 서버로 전달하고 탐지 결과를 받습니다.
* `GET /detect_view/images/{request_id}`: 탐지 결과가 시각화된 이미지를 조회합니다.
* `GET /detect_view/results/{request_id}`: 탐지 결과 JSON을 조회합니다.

### Tag: `summary`

STT로 전사된 텍스트를 회의록으로 작성합니다.

* `POST /summary`: 등록된 모든 모델을 사용하여 요약을 수행하고 결과를 종합합니다.
* `POST /ollama_summary`: 로컬 모델을 사용하여 요약을 수행하고 결과를 종합합니다.
* `POST /gemini_summary`: gemini flash 모델을 사용하여 요약을 수행하고 결과를 종합합니다.
* `POST /task_summary`: 비동기적으로 모든 모델의 요약을 수행하고 `task_id`를 반환합니다.
* `GET /task_summary/{task_id}`: 비동기 요약 작업의 결과를 조회합니다.

### Tag: `API Key Management`

API 키를 관리합니다.

* `POST /manage/keys`: 새로운 API 키를 생성합니다.
* `GET /manage/keys`: 모든 API 키 목록을 조회합니다.
* `DELETE /manage/keys/{api_key}`: 지정된 API 키를 폐기합니다.

### Tag: `Model Management`

* `GET /info`: `/extract`, `/general` 엔드포인트에서 사용 가능한 내부/외부 모델 목록을 조회합니다.
* `GET /default_prompt`: 기본 프롬프트 파일을 다운로드합니다.
* `GET /structured_prompt`: 구조화 추출용 프롬프트 예시 파일을 다운로드합니다.
* `GET /structured_schema`: 구조화 추출용 스키마 예시 파일을 다운로드합니다.

### Tag: `Guide Book`

* `/schema_file_guide`, `/general_guide`, `/extract_guide`: 각 기능에 대한 HTML 가이드 문서를 제공합니다.