6.1 KiB
6.1 KiB
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 작업은 시간이 오래 걸리므로, 본 시스템은 비동기 파이프라인을 채택했습니다.
- 요청 접수: 사용자가 파일을 포함하여 API를 호출하면,
시스템은 즉시 고유한
request_id를 발급하고 백그라운드 작업을 생성합니다. - 상태 추적:
request_id를 사용하여/extract/progress/{request_id}와 같은progress엔드포인트에서 작업 상태를 폴링(polling)할 수 있습니다. - 결과 저장: 작업이 완료되면, 최종 결과는 별도의
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 가이드 문서를 제공합니다.