85 lines
3.9 KiB
Markdown
85 lines
3.9 KiB
Markdown
# 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
|