Task.md

# QP Search System

반도체 제조 공정문서(QP) 검색을 위한 멀티모달 RAG 파이프라인. LangGraph 기반 StateGraph로 구현되며, 복잡도 기반 전략 분기 → 멀티쿼리 생성 → 텍스트/비전 병렬 검색 → 동적 가중치 융합 → Answerability 평가 → 조건부 재처리의 파이프라인을 따른다.

## 인프라

| 역할 | 주소 | 비고 |
|------|------|------|
| Search API (텍스트) | `10.150.6.47:4275/search/text` | collection: `page` |
| Search API (이미지/ColQwen3.5) | `10.150.6.47:4275/search/text/colqwen35` | collection: `colqwen35` |
| Search API (이미지/Tomoro) | `10.150.6.47:4275/search/text/tomoro` | collection: `tomoro` |
| 단어사전 API | `10.150.6.47:4276/search` | 도메인 약어/용어 검색 |
| Qwen3-VL-235B | `10.150.6.160:8000` | 멀티모달 LLM |

검색 API 공통 파라미터: `query` (string), `top_k` (int). 필터 필드(선택): `apply_region`, `apply_product`, `document_type`, `dept_name` — `filters` 객체로 전달, AND 조건.


> 모든 서버는 Air-gapped 폐쇄망 환경이며 외부 인터넷 접근 불가.

## 핵심 파일

- `qp_rag_pipeline.py` — LangGraph StateGraph 메인 파이프라인 (797줄)
- Jupyter 검증 노트북 (31셀) — 파이프라인 단계별 테스트용

## 도메인 컨텍스트

반도체 공정 약어는 쿼리 이해에 핵심적이다: DSP, DSG, EPI, LAP, CMP, STI. 이 약어들이 포함된 쿼리를 처리할 때 단어사전 API(`4276/search`)를 반드시 먼저 호출할 것.

## 아키텍처 규칙

### 파이프라인 흐름
쿼리 입력 → 쿼리 분석 → 쿼리 생성 → 검색(텍스트/비전 병렬) → 결과 융합 및 평가 → (재처리 or 출력)

### 1. 쿼리 분석
- 복잡도(High/Medium/Low)와 쿼리 유형(Text/Vision/Hybrid)을 분류
- 복잡도에 따라 쿼리 생성 전략이 달라짐
- 쿼리 유형에 따라 융합 가중치 `alpha` 결정: Text=0.8, Vision=0.4, Hybrid=0.6

### 2. 쿼리 생성
- 복잡도별 전략: High → 원본+확장+재해석+Text-HyDE / Medium → 원본+확장+재해석 / Low → 원본+경량 재해석
- 약어 포함 쿼리는 단어사전 API(`4276`)로 약어 풀어쓰기 후 리라이트
- 생성된 `query_set`과 `alpha`를 검색 모듈에 전달

### 3. 검색
- Track 1 (텍스트): BGE-M3 하이브리드 → Top-50 → Cross-Encoder 리랭킹 → Top-30
- Track 2 (비전): VLM 기반 VRAG → Top-30 (리랭킹 생략)
- 두 트랙은 병렬 실행

### 4. 결과 융합 및 평가
- 동적 가중치 선형 결합: `S_final = alpha * S_text + (1 - alpha) * S_vision`
- 융합 결과 상위 10개 이미지에 대해 VLM으로 Answerability Score 산출
- `S_avg < threshold` 이고 `retry_count < 1`이면 재처리 발동
- 재처리: Top-K 이미지 VLM 분석 → Vision-HyDE 쿼리 생성 → 쿼리 생성 모듈로 회귀
- 재처리는 최대 1회로 제한 — reducer 결과 누적 버그 주의, 각 iteration마다 초기화할 것

### 모듈 간 데이터 흐름
- 쿼리 분석 → 쿼리 생성: `complexity`, `query_type`, `alpha`
- 쿼리 생성 → 검색: `query_set`, `alpha`
- 검색 → 융합/평가: `text_results`, `vision_results`, `alpha`
- 융합/평가 → 쿼리 생성 (재처리): `enhanced_query`, `alpha`, `retry_count + 1`
- 융합/평가 → 출력: `fused_results`, `S_avg`, `retrieval_retried`

## 코드 스타일

- Python 3.10+, type hint 필수
- async/await 패턴 사용 (FastAPI 연동)
- 로깅은 `loguru` 사용, print 금지
- 한글 주석 허용, docstring도 한글로 작성

## 테스트 & 검증
- Milvus 쿼리 결과는 `relevance_score >= 0.7` 기준으로 필터링