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

3.9 KiB Raw Blame History