192 lines
9.3 KiB
Markdown
192 lines
9.3 KiB
Markdown
# 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": {
|
|
"제목": "문서의 제목",
|
|
"한글제목": "번역된 한국어 제목",
|
|
"본문": "문서의 영문 본문",
|
|
"한글본문": "번역된 한국어 본문",
|
|
"날짜": "문서에 명시된 날짜",
|
|
"보낸사람": "발신인 정보",
|
|
"받는사람": "수신인 정보",
|
|
"연관공문": "참조 또는 연관된 문서",
|
|
"문서유형": "문서의 분류 (예: 보고서, 계약서)"
|
|
}
|
|
}
|
|
}
|
|
```
|