# LLM 게이트웨이 ## 프로젝트 개요 이 프로젝트는 스캔된 PDF 문서에서 텍스트와 구조를 자동으로 추출하고, 대규모 언어 모델(LLM)을 활용하여 내용을 분석하고 요약한 뒤, 최종 결과를 JSON 형식으로 제공하는 문서 분석 시스템입니다. 시스템은 OCR, LLM 추론, 음성 변환 등 각 기능을 독립적인 API로 구성하여 모듈성과 확장성을 높였습니다. 사용자는 FastAPI로 구현된 API 엔드포인트를 통해 서비스를 이용하여, 문서를 업로드하고 결과를 확인할 수 있습니다. ## 주요 기능 - **PDF 및 이미지 처리**: PDF, 이미지 등 다양한 형식의 문서에서 텍스트와 좌표 정보를 추출합니다. - **다중 모델 지원**: Ollama를 통해 Gemma, Qwen 등 다양한 로컬 LLM 모델을 지원하며, 외부 상용 LLM API 연동도 가능합니다. - **비동기 처리**: 대용량 문서나 복잡한 분석 작업을 비동기적으로 처리하여 사용자 응답 시간을 단축합니다. - **구조화된 데이터 추출**: 사용자 정의 JSON 스키마에 따라 문서에서 필요한 정보를 정확히 추출합니다. - **음성-텍스트 변환 (STT)**: 음성 파일을 텍스트로 변환하는 STT 기능을 API 게이트웨이를 통해 중계합니다. - **모니터링**: Loki, Prometheus, Grafana를 활용하여 시스템 로그와 성능 지표를 실시간으로 모니터링합니다. ## 설치 및 실행 방법 이 프로젝트는 Docker Compose를 사용하여 각 서비스를 컨테이너 환경에서 실행합니다. 1. **Docker 설치**: 시스템에 Docker와 Docker Compose가 설치되어 있어야 합니다. 2. **환경 변수 설정**: 프로젝트 루트의 `.env` 파일을 각 환경에 맞게 설정합니다. (예: `.env.8888`, `.env.ollama`) 3. **서비스 실행**: 필요에 따라 아래 명령어를 사용하여 서비스를 실행합니다. - **LLM 게이트웨이 API (포트: 8888)** ```bash docker-compose -f docker-compose_8888.yml up -d ``` - **Streamlit UI (포트: 8889)** ```bash docker-compose -f docker-compose_8889.yml up -d ``` - **Ollama 모델 서버** (예: Gemma 모델 실행) ```bash ./start_ollama_gemma.sh ``` - **모니터링 시스템** ```bash docker-compose -f docker-compose_monitoring.yml up -d ``` 4. **서비스 종료**: 실행 중인 서비스를 중지하려면 아래 명령어를 사용합니다. ```bash docker-compose -f <사용된-compose-파일.yml> down ``` ## 프로젝트 구조 ``` . ├── Dockerfile # 메인 서비스용 Dockerfile ├── README.md # 프로젝트 설명서 ├── docker-compose_8888.yml # LLM 게이트웨이 API 서비스용 docker-compose ├── docker-compose_8889.yml # LLM 게이트웨이 Streamlit UI용 docker-compose ├── docker-compose_monitoring.yml # 모니터링(Loki, Prometheus, Grafana) 구성 ├── docker-compose_ollama.yml # Ollama 모델 서버용 docker-compose ├── docs # 아키텍처 결정 기록(ADR) 및 문서 ├── log_config.yaml # 로그 설정 파일 ├── pyproject.toml # Python 프로젝트 및 의존성 관리 파일 ├── requirements.txt # 의존성 목록 ├── swagger-ui # Swagger UI 프론트엔드 모듈 └── workspace # LLM 게이트웨이 메인 서비스 코드 ├── api.py # FastAPI 애플리케이션 진입점 ├── config # 설정 관련 모듈 ├── interface # 사용자 인터페이스 (Streamlit 등) ├── routers # FastAPI 라우터 (API 엔드포인트 정의) ├── services # 비즈니스 로직 처리 서비스 ├── static # 정적 파일 (예제, 템플릿 등) └── utils # 공용 유틸리티 모듈 ``` ## API 엔드포인트 ### 상태 확인 및 가이드 | 경로 | 메서드 | 설명 | | -------------------- | ------ | ------------------------------------ | | `/health/*` | GET | 서버 상태 확인 | | `/info` | GET | 사용 가능한 내부/외부 모델 목록 조회 | | `/schema_file_guide` | GET | 스키마 파일 작성 가이드 HTML 제공 | | `/general_guide` | GET | 범용 추론 가이드 HTML 제공 | | `/extract_guide` | GET | 문서 추출 가이드 HTML 제공 | ### 파일 다운로드 | 경로 | 메서드 | 설명 | | -------------------- | ------ | --------------------------------------- | | `/default_prompt` | GET | 기본 프롬프트 템플릿 파일 다운로드 | | `/structured_prompt` | GET | 구조화 추출용 프롬프트 템플릿 다운로드 | | `/structured_schema` | GET | 구조화 추출용 JSON 스키마 예시 다운로드 | ### 범용 추론 (General) | 경로 | 메서드 | 설명 | | -------------------------------- | ------ | -------------------------------- | | `/general/inner` | POST | 내부 LLM 기반 범용 추론 (비동기) | | `/general/outer` | POST | 외부 LLM 기반 범용 추론 (비동기) | | `/general/progress/{request_id}` | GET | 범용 추론 작업 상태 및 결과 조회 | ### 문서 정보 추출 (Extract) | 경로 | 메서드 | 설명 | | -------------------------------- | ------ | ------------------------------------- | | `/extract/inner` | POST | 내부 LLM 기반 문서 정보 추출 (비동기) | | `/extract/outer` | POST | 외부 LLM 기반 문서 정보 추출 (비동기) | | `/extract/progress/{request_id}` | GET | 문서 추출 작업 상태 및 결과 조회 | ### 텍스트 요약 (Summary) | 경로 | 메서드 | 설명 | | ------------------------- | ------ | ----------------------------------------------- | | `/summary` | POST | 모든 모델을 사용하여 텍스트 요약 (동기) | | `/ollama_summary` | POST | Ollama 모델을 사용하여 텍스트 요약 (동기) | | `/task_summary` | POST | 모든 모델을 사용한 비동기 텍스트 요약 작업 생성 | | `/task_summary/{task_id}` | GET | 비동기 요약 작업 상태 및 결과 조회 | ### 음성-텍스트 변환 (STT) | 경로 | 메서드 | 설명 | | ------------------------ | ------ | ---------------------------------------- | | `/audio` | POST | 음성 파일을 STT API로 전달하여 변환 요청 | | `/progress/{request_id}` | GET | STT 작업 진행 상태 조회 | | `/result/{request_id}` | GET | STT 작업 결과 조회 | | `/languages` | GET | STT 지원 언어 목록 조회 | ### 텍스트 추출 (OCR) | 경로 | 메서드 | 설명 | | ---------------------------- | ------ | -------------------------------- | | `/ocr` | POST | 문서 파일 OCR 작업 요청 (비동기) | | `/ocr/progress/{request_id}` | GET | OCR 작업 진행 상태 조회 | | `/ocr/result/{request_id}` | GET | OCR 작업 결과 조회 | ### 테스트용 | 경로 | 메서드 | 설명 | | ---------------------- | ------ | ------------------------------- | | `/dummy/extract/outer` | POST | 실제 추론 없이 더미 응답을 반환 | ## 결과 JSON 구조 예시 문서 추출 API (`/extract/*`) 호출 시 반환되는 최종 결과의 JSON 구조입니다. ```json { "request_id": "요청 식별자", "progress_logs": [ {"status": "작업 접수", "timestamp": "2025-07-21T10:00:00Z"}, {"status": "OCR 작업 시작", "timestamp": "2025-07-21T10:00:05Z"}, {"status": "텍스트 추출 중", "timestamp": "2025-07-21T10:00:06Z"} ], "final_result": { "filename": "example.pdf", "model": { "ocr_model": "tesseract", "llm_model": "gemma:7b" }, "time": { "duration_sec": 25.5, "started_at": 1721556000.0, "ended_at": 1721556025.5 }, "fields": { "추출된 텍스트": [[x1, y1], [x2, y2], [x3, y3], [x4, y4]] }, "parsed": "OCR 모델로 추출한 원본 텍스트입니다.", "generated": "LLM이 요약 및 번역한 텍스트입니다.", "processed": { "제목": "문서의 제목", "한글제목": "번역된 한국어 제목", "본문": "문서의 영문 본문", "한글본문": "번역된 한국어 본문", "날짜": "문서에 명시된 날짜", "보낸사람": "발신인 정보", "받는사람": "수신인 정보", "연관공문": "참조 또는 연관된 문서", "문서유형": "문서의 분류 (예: 보고서, 계약서)" } } } ```