# CTRL+F AI Gateway 기술 스택
> 최종 검증일: 2026-01-07
## 1. 언어 및 런타임
| 구분 | 기술 | 버전 |
|------|------|------|
| **언어** | Python | 3.12 |
| **베이스 이미지** | python:3.12-slim | Docker 기반 |
| **패키지 관리** | pip | requirements.txt 기반 |
---
## 2. 웹 프레임워크 & 서버
| 구분 | 기술 | 버전 | 용도 |
|------|------|------|------|
| **웹 프레임워크** | FastAPI | >=0.115.0 | 비동기 REST API, WebSocket 지원 |
| **ASGI 서버** | Uvicorn | >=0.32.0 | 프로덕션 서버 ([standard] extras 포함) |
| **데이터 검증** | Pydantic | >=2.9.0 | 요청/응답 스키마 검증 |
| **설정 관리** | pydantic-settings | >=2.6.0 | 환경변수 및 .env 파일 관리 |
---
## 3. AI/ML 핵심 기술
| 구분 | 기술 | 상세 |
|------|------|------|
| **LLM (메인)** | LGAI-EXAONE/EXAONE-3.5-7.8B-Instruct | LG AI EXAONE 모델 (vLLM 서빙) |
| **LLM (선택)** | OpenAI gpt-4o-mini | 관리자 대시보드에서 선택 가능 |
| **RAG 시스템** | RAGFlow | 문서 파싱, 청킹, 검색 파이프라인 |
| **벡터 DB** | Milvus (pymilvus >=2.5.0) | 벡터 유사도 검색 |
### 임베딩 모델
| 모델 | 차원 | 용도 |
|------|------|------|
| BAAI/bge-m3 | 1024 | vLLM 서버 기본 임베딩 |
| OpenAI text-embedding-3-large | 3072 | OpenAI 임베딩 (선택) |
| jhgan/ko-sroberta-multitask | 768 | 한국어 SRoBERTa (A/B 테스트용) |
---
## 4. 데이터 처리 라이브러리
| 구분 | 기술 | 버전 | 용도 |
|------|------|------|------|
| **PDF 처리** | PyMuPDF | >=1.24.0 | PDF 문서 파싱 |
| **Word 처리** | python-docx | >=1.1.0 | DOCX 문서 파싱 |
| **OLE 파일** | olefile | >=0.47 | 레거시 Office 파일 지원 |
| **데이터 분석** | pandas | >=2.0.0 | 데이터프레임 처리 |
| **Excel 처리** | openpyxl | >=3.1.0 | XLSX 파일 읽기/쓰기 |
| **수치 연산** | NumPy | >=1.26.0 | 벡터/행렬 연산 |
| **ML 유틸** | scikit-learn | >=1.3.0 | 머신러닝 유틸리티 |
| **퍼지 매칭** | RapidFuzz | >=3.0.0 | 금지질문 퍼지 매칭 |
---
## 5. TTS (Text-to-Speech)
| 구분 | 기술 | 설치 | 용도 |
|------|------|------|------|
| **기본 TTS** | gTTS | >=2.5.0 (requirements.txt 포함) | Google TTS (무료, 한국어 지원) |
| **AWS TTS** | boto3 | **선택적 설치** | AWS Polly (프리미엄) |
| **GCP TTS** | google-cloud-texttospeech | **선택적 설치** | Google Cloud TTS (Wavenet) |
| **Mock TTS** | 자체 구현 | - | 테스트용 무음 파일 생성 |
> **주의**: boto3, google-cloud-texttospeech는 requirements.txt에 포함되지 않음 (선택적 설치)
---
## 6. HTTP 통신 & 비동기
| 구분 | 기술 | 버전 | 용도 |
|------|------|------|------|
| **HTTP 클라이언트** | httpx | >=0.27.0 | 비동기 HTTP 요청 |
| **비동기 I/O** | anyio | >=4.6.0 | 비동기 작업 관리 |
| **멀티파트** | python-multipart | >=0.0.9 | 파일 업로드 처리 |
---
## 7. 이미지 처리
| 구분 | 기술 | 버전 | 용도 |
|------|------|------|------|
| **이미지 처리** | Pillow | >=10.0.0 | 영상 썸네일, 씬 이미지 처리 |
---
## 8. 테스트 프레임워크
| 구분 | 기술 | 버전 | 용도 |
|------|------|------|------|
| **테스트 프레임워크** | pytest | >=8.3.0 | 단위/통합 테스트 |
| **비동기 테스트** | pytest-asyncio | >=0.24.0 | async 테스트 지원 |
| **anyio 테스트** | pytest-anyio | >=0.0.0 | anyio 통합 테스트 |
---
## 9. 인프라 & DevOps
| 구분 | 기술 | 상세 |
|------|------|------|
| **컨테이너화** | Docker | python:3.12-slim 베이스 이미지 |
| **오케스트레이션** | Docker Compose | mock/real 프로필 지원 |
| **CI/CD** | GitHub Actions | Self-hosted Runner 배포 |
| **헬스체크** | httpx 기반 | 30초 간격 자동 체크 |
---
## 10. 로깅 & 모니터링 (ELK Stack)
| 구분 | 기술 | 버전 | 용도 |
|------|------|------|------|
| **검색 엔진** | Elasticsearch | 8.11.3 | 로그 저장 및 검색 |
| **시각화** | Kibana | 8.11.3 | 로그 대시보드 |
| **로그 포맷** | JSON 1-line | 자체 구현 | ELK 친화적 구조화 로깅 |
| **텔레메트리** | TelemetryPublisher | 자체 구현 | 비동기 이벤트 배치 전송 |
---
## 11. 환경설정 & 보안
| 구분 | 기술 | 용도 |
|------|------|------|
| **환경변수** | python-dotenv >=1.0.0 | .env 파일 로드 |
| **보안** | 비루트 유저 실행 | Docker 컨테이너 보안 |
| **인증** | X-Internal-Token | 내부 API 인증 |
---
## 12. 외부 서비스 연동
| 서비스 | 기술 | 역할 |
|--------|------|------|
| **ctrlf-back** | Spring Boot (Java) | 백엔드 API, 사용자 인증, 비즈니스 로직 |
| **ctrlf-ragflow** | RAGFlow | RAG 문서 파싱 및 검색 |
| **ctrlf-front** | React | 프론트엔드 UI |
---
## 13. API 엔드포인트
### 공개 API
| 경로 | 메서드 | 기능 |
|------|--------|------|
| `/health` | GET | Liveness 헬스체크 |
| `/health/ready` | GET | Readiness 헬스체크 |
| `/ai/chat/messages` | POST | AI 채팅 응답 생성 |
| `/ai/chat/stream` | POST | 스트리밍 채팅 (NDJSON) |
| `/ai/quiz/generate` | POST | 퀴즈 자동 생성 |
| `/ai/faq/generate` | POST | FAQ 초안 생성 (단건) |
| `/ai/faq/generate/batch` | POST | FAQ 초안 배치 생성 |
| `/ai/gap/policy-edu/suggestions` | POST | RAG Gap 보완 제안 |
### WebSocket
| 경로 | 기능 |
|------|------|
| `/ws/videos/{video_id}/render-progress` | 영상 렌더링 실시간 진행률 |
### Internal API (Backend -> AI)
| 경로 | 메서드 | 기능 |
|------|--------|------|
| `/internal/ai/source-sets/{sourceSetId}/start` | POST | SourceSet 처리 시작 |
| `/internal/ai/rag-documents/ingest` | POST | RAG 문서 ingest 요청 |
| `/internal/ai/render-jobs` | POST | 영상 렌더 잡 생성 |
| `/internal/ai/feedback` | POST | 피드백 수신 |
### Deprecated (410 Gone)
| 경로 | 상태 |
|------|------|
| `/internal/rag/index` | 제거됨 |
| `/internal/rag/delete` | 제거됨 |
---
## 14. 아키텍처 특징
| 특징 | 설명 |
|------|------|
| **RAG** | Retrieval-Augmented Generation (문서 검색 + LLM 응답 생성) |
| **PII 마스킹** | INPUT/OUTPUT/LOG 3단계 개인정보 마스킹 |
| **의도 분류** | Rule-based + LLM Router 하이브리드 |
| **Fallback 전략** | RAG/Backend/LLM 실패 시 graceful degradation |
| **비동기 처리** | 전체 파이프라인 async/await 기반 |
| **텔레메트리** | Fire-and-forget 방식 비동기 이벤트 전송 |
---
## 15. requirements.txt 전체 목록 (22개 라이브러리)
fastapi>=0.115.0 uvicorn[standard]>=0.32.0 python-multipart>=0.0.9 pydantic>=2.9.0 pydantic-settings>=2.6.0 httpx>=0.27.0 python-dotenv>=1.0.0 pytest>=8.3.0 pytest-anyio>=0.0.0 pytest-asyncio>=0.24.0 anyio>=4.6.0 PyMuPDF>=1.24.0 python-docx>=1.1.0 olefile>=0.47 gTTS>=2.5.0 Pillow>=10.0.0 pymilvus>=2.5.0 pandas>=2.0.0 openpyxl>=3.1.0 rapidfuzz>=3.0.0 numpy>=1.26.0 scikit-learn>=1.3.0