# LLM 게이트웨이 아키텍처

## 상태

제안됨

## 콘텍스트

본 프로젝트(`llm_gateway`)는 FastAPI를 기반으로 한 문서 추출 및 LLM 추론 API 시스템으로, PDF 및 이미지 기반의 문서 처리, LLM 기반 응답 생성, 다양한 다운로드 및 가이드 제공 기능을 제공한다.  
이를 효율적으로 구현하기 위해 비동기 처리를 활용하고, 기능별 모듈화 및 서비스 계층을 분리하여 유지보수성과 확장성을 고려한 구조를 설계했다.

## 아키텍처 구성 요소

### (1) API 계층

**FastAPI**

- 클라이언트와 직접 상호작용하는 API 레이어.
- 비동기 요청을 처리하고 파일 업로드, LLM 추론, OCR, 다운로드 등의 엔드포인트를 제공.
- 주요 엔드포인트:
  - `/extract`: 문서 텍스트 추출 및 LLM 응답
  - `/general/inner/outer`: 내부/외부 LLM 추론
  - `/ocr`: PDF/이미지 파일의 OCR 기반 텍스트 추출
  - `/download/*`: 프롬프트 및 스키마 다운로드
  - `/info`: 사용 가능한 모델 정보 제공
  - `/health`: 시스템 상태 확인

### (2) 서비스 계층

**서비스 모듈**

- 라우터에서 호출되는 비즈니스 로직 처리 레이어.
- 주요 서비스:
  - `InferenceService`: 텍스트 추출 및 LLM 호출 처리
  - `DownloadService`: 프롬프트 및 스키마 다운로드 처리
  - `ModelInfoService`: 모델 정보 반환
  - `PipelineRunner`: 추론 파이프라인 실행 로직
  - `DummyService`: 테스트용 API 처리

### (3) 유틸리티 및 처리 계층

**utils 모듈**

- 공통 텍스트 추출(`extract_text_from_file`), LLM 응답 처리, 로깅 및 프롬프트 관리 기능 제공.
- OCR 처리의 경우 업로드된 파일을 `aiofiles`를 통해 임시 디스크에 저장한 후 `extract_text_from_file`을 호출하여 텍스트를 추출한다.
- 주요 모듈:
  - `text_extractor`: 파일 기반 텍스트 추출
  - `text_processor`: OCR 및 후처리
  - `text_generator`: LLM 추론 (Ollama, Gemini, Claude, GPT 등)
  - `logging_utils`, `prompt_cache`: 로깅 및 캐시 관리

### (4) 데이터 계층

**파일 저장소 및 정적 자원**

- 업로드된 파일은 서버 내 `UPLOAD_DIR`에 저장.
- 정적 리소스(`/static/`)를 통해 HTML 가이드, 이미지, JSON 스키마 제공.
- 추론 및 다운로드 요청에 필요한 리소스를 관리하고, 서버 안정성을 위해 디스크 기반 임시 저장소 활용.

## 결정

- FastAPI를 중심으로 기능별 라우터를 독립적으로 구성하고, 서비스 계층과 유틸리티 계층을 분리하여 유지보수성과 확장성을 확보한다.
- `/ocr` 요청 시 파일 업로드는 임시 디스크 저장(aiofiles) 후 `text_extractor` 호출로 처리하며, 이를 Mermaid 흐름도에 반영한다.
- 공통 텍스트 추출 모듈(`text_extractor`)은 `/extract`, `/general`, `/ocr`에서 재사용하도록 `utils` 계층에 위치시킨다.

## 근거

- 비동기 요청 처리 및 모듈화된 구조는 대규모 문서 추출 및 LLM 처리 환경에서 성능과 유지보수성을 동시에 확보한다.
- `aiofiles` 기반 파일 저장은 메모리 상 `UploadFile` 객체를 안정적으로 처리하기 위해 필요하다.
- `utils` 계층 통합으로 공통 로직 재사용성을 높여 코드 중복을 방지하고 유지보수를 용이하게 한다.

## 결과

- 클라이언트는 비동기 요청을 통해 빠르고 안정적인 문서 추출 및 LLM 응답을 받을 수 있다.
- 서비스 계층과 유틸리티 계층 분리를 통해 확장 가능하고 유지보수성이 높은 구조를 확보했다.
- Mermaid 다이어그램을 통해 아키텍처와 흐름을 명확하게 시각화하여 향후 리팩토링 및 개선 작업에 참고할 수 있도록 했다.

## 결정자

AI cell / 김용연 연구원

## 결정 날짜

2025-05-29