## **LLM Gateway 프로젝트 제품 요구사항 문서 (PRD)**

### 1\. 문서 개요

본 문서는 사내 다양한 서비스에서 발생하는 LLM(거대 언어 모델) 및 관련 AI 모델(OCR, STT 등) 수요를 중앙에서 효율적으로 처리하고 관리하기 위한 **LLM Gateway** 프로젝트의 요구사항을 정의합니다.

  * **프로젝트명:** LLM Gateway
  * **작성일:** 2025년 8월 8일
  * **담당자/팀:** 한치영 - AI 팀장


### 2\. 프로젝트 배경 및 목표

#### 2.1. 배경 및 문제 정의

  * **리소스 중복:** 유사한 기능이 팀별로 중복 운영
  * **일관성 부재:** 모델 API 규격, 인증 방식, 성능 기준이 다르고, 코드 재활용이 어려움
  * **확장성 한계:** 트래픽 증가 시 유연한 수평 확장에 대한 통일된 전략이 부재
  * **외부 LLM 사용량 측정:** 외부 LLM API를 사용하는 경우 사용량 측정을 위한 목(통일된 진입점)이 필요

#### 2.2. 프로젝트 목표

LLM Gateway는 이러한 문제들을 해결하고자 아래와 같은 목표를 가짐

  * **API 통합 및 표준화:** 사내 모든 LLM 및 AI 모델 접근을 위한 단일 End-point를 제공하여 API 규격을 표준화
  * **전처리 파이프라인 제공:** OCR, STT 등 자주 사용되는 전처리 기능을 파이프라인으로 제공하여 개발 생산성을 향상
  * **효율적인 자원 관리:** Docker 기반의 통합 인프라와 Ollama 런타임을 통해 모델 서버를 효율적으로 운영하고, 수평 확장이 용이한 구조를 마련
  * **중앙 집중 관리 및 모니터링:** API 사용량, 응답 시간, 오류 등을 중앙에서 모니터링하여 안정적인 운영을 지원


### 3\. 기능 요구사항

| 기능 ID | 기능명 | 상세 설명 | 우선순위 |
| :--- | :--- | :--- | :--- |
| **F-001** | **Gateway API 서버** | FastAPI 기반으로 모든 요청을 수신하고 적절한 서비스로 라우팅. 인증, 로깅, 요청/응답 형식 변환을 처리 | **높음** |
| **F-002** | **LLM 추론 요청 처리** | Ollama로 구동되는 LLM에 대한 추론(Chat/Completion) 요청을 처리합니다. 향후 로드 밸런싱을 통해 여러 LLM 인스턴스로 요청을 분산 | **높음** |
| **F-003** | **비동기 OCR 처리** | 이미지 파일을 입력받아 PaddleOCR 서버에 비동기 처리를 요청하고, 처리 결과를 Redis에 저장. 사용자에게는 Job ID를 즉시 반환 | **높음** |
| **F-004** | **비동기 STT 처리** | 음성 파일을 입력받아 STT 모델(위스퍼) 서버에 비동기 처리를 요청 | **낮음** |
| **F-005** | **비동기 작업 결과 조회** | Job ID를 통해 Redis에 저장된 OCR, STT 등의 작업 상태(대기, 처리 중, 완료, 실패) 및 최종 결과를 조회하는 API를 제공 | **높음** |
| **F-006** | **모듈 추가 확장성** | 향후 새로운 AI 모델(번역, 문서 요약 등)이 추가될 때, 최소한의 설정으로 Gateway에 쉽게 통합할 수 있는 구조 | **중간** |
| **F-007** | **공문 분석** | 국내외 수발신 공문에 대한 데이터 추출  | **높음** |
| **F-008** | **문서 요약** | 문서에 대한 단문 요약  | **낮음** |


### 4\. 비기능 요구사항

  * **성능:** 기준 응답 시간이 채팅 인터페이스를 통한 입력보다 3초 이상 길지 않아야 함.
  * **확장성:** 모든 컴포넌트(Gateway, OCR, STT, LLM)는 Docker 컨테이너 기반으로 설계되어 트래픽 증가에 따라 `docker-compose up --scale <service_name>=N` 를 통해 수평 확장
  * **보안:** 내부망 사용을 전제로 하되, 서비스 구분을 위한 API Key 기반의 인증 체계를 도입
  * **모니터링:** API 요청/응답, 처리 시간, 에러율 등 주요 지표를 Prometheus, Grafana 등을 활용해 시각화하고 모니터링

-----

## **LLM Gateway 아키텍처**

하이레벨 아키텍처

```mermaid
graph TD
    User["👩‍💻 사내 서비스:PM 등"]

    subgraph "Gateway Layer"
        Gateway["🚀 LLM Gateway (FastAPI)"]
        Result_Redis
    end

    Ollama

    subgraph "Worker Layer"
        Broker[(Celery Broker)]
        Worker_Redis["💾 Redis (Job Result Store)"]
        Worker_OCR["👷 OCR Celery Worker - PaddleOCR"]
    end
    %% --- Data Flow ---

    %% Synchronous Flow (LLM Chat)
    User --"1.요청"--> Gateway
    Result_Redis -- "2.Job ID 즉시 반환" --> User
    Gateway -- "3.작업 등록" --> Broker
    Broker --> Worker_OCR --> Worker_Redis
    Gateway -- "3-background 작업 결과 반복 확인" --> Worker_Redis
    Gateway -- "4.LLM 추론 요청" --> Ollama
    Ollama -- "5.Json 기반 응답" --> Gateway
    Gateway -- "6.결과 확인 Cache 업데이트" --> Result_Redis
    User -- "7.결과 확인" --> Result_Redis
    
    %% Style Definitions
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px;
    classDef special fill:#E8E8FF,stroke:#663399,stroke-width:2px;
    class Gateway,LB_LLM,Broker,Redis special;
```
-----

시퀀스 기반 이해

```mermaid
sequenceDiagram
    participant User as 👩‍💻 Project Master
    participant Gateway as 🚀 LLM Gateway
    participant Broker as Celery Broker
    participant Worker as 👷 OCR Worker
    participant Worker_Redis as 💾 Redis (Job Store)
    participant Ollama

    User->>+Gateway: 1. 이미지 처리 요청
    Gateway->>-User: 2. Job ID 즉시 반환

    Gateway->>Broker: 3. OCR 작업 등록
    activate Gateway
    Broker->>Worker: OCR 작업 전달
    deactivate Gateway

    activate Worker
    Worker->>Worker: PaddleOCR로 이미지 처리
    Worker->>Worker_Redis: 처리 결과 저장
    deactivate Worker

    loop 3-background. 작업 결과 반복 확인
        Gateway->>Worker_Redis: Job ID로 결과 확인
    end

    Note right of Gateway: OCR 작업 완료 확인 후

    Gateway->>+Ollama: 4. OCR 결과 기반 LLM 추론 요청
    Ollama-->>-Gateway: 5. JSON 형식으로 응답

    Note right of Gateway: 6. 최종 결과를<br/>내부 캐시에 저장 (Result_Redis)

    User->>+Gateway: 7. Job ID로 최종 결과 확인 요청
    Gateway-->>-User: 최종 처리 결과 반환
```


### 아키텍처 설명

1.  **User:** 사내의 다른 서비스나 개발자 등 Gateway의 API를 호출하는 주체
2.  **Gateway Layer:** 모든 요청의 진입점 FastAPI로 구현되어 동기/비동기 요청을 받아 적절한 백엔드 서비스로 분기
3.  **AI Model Layer:**
      * **LLM Serving:** Ollama 런타임을 사용
4.  **Worker Layer:** OCR, STT 등 각 기능을 독립적인 Docker Stack으로 묶습니다.
      * **Celery & Broker(Redis/RabbitMQ):** OCR, STT 같이 시간이 오래 걸리는 작업을 비동기로 처리하기 위한 메시지 큐
      * **Worker:** 실제 작업을 수행하는 프로세스. FastAPI로 랩핑해서 서비스
      * **Redis:** 비동기 작업의 최종 결과를 저장. 클라이언트는 Job ID를 통해 이곳에 저장된 결과를 조회