Update web search entity doc with LLM harness best practices

- Add hybrid routing with uncertainty-based LLM escalation
- Detail context pruning and OOS guardrail strategies
- Include intent discovery loop and forced confirmation policy
- Add monitoring metrics aligned with 2024-2025 research
- Reference ACL/arXiv papers on intent detection and OOS handling

Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

troubleshooting/251023_admin_rb8001_웹검색_엔티티_정확도_개선.md

@@ -12,27 +12,70 @@
 - 대표/이름 질의가 엔티티 미확정 상태에서 실행되어 잘못된 대상에 대한 답변 반복.
 
 ## 해결 설계/적용
-1) 그래프 파이프 강화  
-   - resolve(코리퍼런스) → link(엔티티링크/신뢰도) → CQR(재작성) → search → rerank → summarize → format.  
-   - AsyncSqliteSaver(체크포인터) + thread_id/checkpoint_ns 지정, 실패 시 폴백 로깅.
 
-2) 폴백 경로 동등 정책  
-   - /search 경로에서도 대명사 해소 스코어링(한글/기업접미사 가중, 파일·상수 패널티) 적용.  
-   - 저신뢰(<2) 또는 미해결 시 즉시 재질문(clarify) 반환.
+### 1) 불확실성 기반 하이브리드 라우팅 (LLM 하니스 최신 동향)
 
-3) Clarify UX  
-   - Slack 버튼으로 후보(최대 3) 제시 → 선택 즉시 재검색/응답.
+**원칙**: 경량 NER → 불확실성 평가 → 저신뢰만 LLM 승격 → 고신뢰 즉시 실행
 
-4) 라우팅 보강  
-   - “(기업|회사).*(이름|대표|대표이사)” 등도 웹검색 파이프로 라우팅.
+**구현**:
+- **1차 경량 NER**: 최근 N턴(10~15분) 대화에서 한글/기업 접미사(주식회사, Inc, Corp, Ltd, Labs) 패턴 추출
+- **불확실성 앙상블 스코어링**:
+  - a) NER 매칭 스코어 (TF-IDF, 편집거리 기반)
+  - b) 시간 감쇠 가중 (최근 턴: 1.0, 5분 이상: 0.5, 파일명/전대문자 상수: 0.0)
+  - c) 후보 개수·분산도 (단일 후보 고신뢰 vs 복수 후보 저신뢰)
+- **동적 임계치**: 고신뢰(>2.0) 즉시 검색, 중신뢰(1.0~2.0) LLM 승격, 저신뢰(<1.0) clarify 우선
+- **비용/지연 최적화**: LLM 승격율 <30% 목표, 지연 중앙값 <500ms 유지
 
-5) 의도-회귀(곱씹기) 단계  
-   - 실행 전 “요청-대상-행위” 삼단 체크리스트로 의도 재확인(예: [요청] 이 기업 대표? [대상] 지에프솔루션? [행위] 웹검색/대표확인).  
-   - 엔티티 확정(clarify/CQR) 없이는 실행 금지. 질문이 모호하면 반드시 clarify 우선.
+**학술 근거**: ACL 2024 EMNLP Industry Track - "Intent Detection in the Age of LLMs"는 SetFit 등 경량 분류기와 LLM을 불확실성 기반으로 라우팅하여 LLM 단독 대비 정확도 유지하며 지연/비용을 절반으로 절감한 사례 보고.
 
-6) 시간 감쇠·윈도우 제한  
-   - 메모리/최근 대화 검색은 최신 N개·최근 T분(예: 10~15분) 윈도우로 제한하고, 오래된 기억은 감쇠 가중(0.5× 이하) 적용.  
-   - 파일명/전대문자 상수 토큰은 기본 제외 목록으로 처리.
+### 2) 맥락 축소 프롬프트 + OOS 가드레일
+
+**그래프 파이프 강화**:
+- resolve(코리퍼런스) → link(엔티티링크/신뢰도) → CQR(재작성) → search → rerank → summarize → format
+- AsyncSqliteSaver(체크포인터) + thread_id/checkpoint_ns 지정, 실패 시 폴백 로깅
+
+**맥락 축소 전략**:
+- LLM 프롬프트에 **한글 기업명 후보 하위집합만 주입** (파일명/상수 블랙리스트 제외)
+- 최근 10~15분 윈도우로 제한, 오래된 턴은 감쇠 가중(0.5× 이하)
+- 다자 대화 시 발화자 역할·화행 정보 포함하여 라벨 공간 축소
+
+**OOS 가드레일 (폴백 경로 동등 정책)**:
+- /search 경로에서도 대명사 해소 스코어링(한글/기업접미사 가중, 파일·상수 패널티) 적용
+- 저신뢰(<2) 또는 미해결 시 즉시 재질문(clarify) 반환
+- **OOS 판단 앙상블**: a) NER 불확실성, b) LLM 거절/근거 점수, c) 로짓 기반 에너지 점수
+- OOS 시 우회: Slack clarify 버튼 → FAQ 검색 → 상담원 연결
+
+**학술 근거**:
+- arXiv 2024 - "Intent Recognition in Multi-party Conversations"는 동적 프롬프트 축소로 라벨 공간을 줄여 성능과 비용 개선 보고
+- arXiv 2024 - "Efficient Out-of-Scope Detection via Uncertainty-Driven LLM Routing"는 불확실성 기반 OOS 라우팅의 효율성 강조
+
+### 3) Clarify UX 및 의도 발견 루프
+
+**Clarify UX**:
+- Slack 버튼으로 후보(최대 3) 제시 → 선택 즉시 재검색/응답
+- 버튼 라벨: "[기업명] (최근 언급: [턴수]턴 전, 신뢰도: [스코어])"
+
+**의도-회귀(곱씹기) 단계**:
+- 실행 전 "요청-대상-행위" 삼단 체크리스트로 의도 재확인
+  - 예: [요청] 이 기업 대표? [대상] 지에프솔루션? [행위] 웹검색/대표확인
+- 엔티티 확정(clarify/CQR) 없이는 실행 금지, 질문 모호 시 clarify 우선
+
+**의도 발견 루프** (신규 엔티티 패턴 자동 발견):
+- 주기적(매주) OOS·clarify 실패 로그를 LLM으로 군집화·요약
+- 신규 의도 후보(예: 약어 기업명, 신조어) 제안 → 운영자 승인 → 라벨셋 반영
+- 반복 실패 패턴을 블랙리스트에서 화이트리스트로 전환 (점진적 학습)
+
+**학술 근거**: arXiv 2024 - "IntentGPT: Few-shot Intent Discovery with Large Language Models"는 LLM 기반 의도 군집화·명명의 효율성 보고, 개방세계(open-world) 시나리오 대응에 유리.
+
+### 4) 라우팅 보강
+
+- "(기업|회사).*(이름|대표|대표이사)" 등도 웹검색 파이프로 라우팅
+- 함수 호출(tool calling) 패턴: 분류 결과를 구조화된 JSON으로 반환, 백엔드 액션 연결
+
+### 5) 시간 감쇠·윈도우 제한
+
+- 메모리/최근 대화 검색은 최신 N개·최근 T분(10~15분) 윈도우로 제한
+- 오래된 기억은 감쇠 가중(0.5× 이하), 파일명/전대문자 상수 토큰은 기본 제외
 
 ## 정확도/표현
 - 확신도 낮은 경우: “재질문/보류(출처 부족)”로 응답.  
@@ -44,12 +87,77 @@
 - 반성적 리라이트: 응답 말미에 “가정/근거/시간/확신도”를 메타로 요약하여 과장 금지, 불확실 영역은 분리 표기.
 
 ## 검증/모니터링
-- 테스트(로컬): 엔티티 우선순위·clarify·그래프 경로 안정화 검증.  
-- 로그: `[WebSearch] CAND entity`, `Pronoun resolved`, `Fallback /search`, Clarify 버튼 액션 로그.  
-- 지표: 성공률·clarify 비율·폴백 비율·응답 확신도(ECE/Brier).
+
+### 테스트 (로컬)
+- 엔티티 우선순위·clarify·그래프 경로 안정화 검증
+- 불확실성 스코어링 시뮬레이션 (다양한 턴 간격·파일명 혼입 시나리오)
+
+### 로그
+- `[WebSearch] CAND entity`: 후보 엔티티 목록 및 스코어
+- `Pronoun resolved`: 대명사 해소 결과 (원본 → 확정 엔티티)
+- `Fallback /search`: LangGraph 예외 시 폴백 경로 진입
+- Clarify 버튼 액션 로그: 사용자 선택 엔티티 및 턴 인덱스
+
+### 핵심 지표 (LLM 하니스 운영 모니터링)
+1. **인스코프 성능**:
+   - 웹검색 성공률 (정확한 엔티티로 검색 완료)
+   - Clarify 비율 (전체 요청 대비 재질문 비율)
+   - 폴백 비율 (LangGraph 실패 → /search 경로 진입 비율)
+
+2. **OOS/불확실성 관련**:
+   - OOS 리콜 (실제 엔티티 미확정 중 OOS로 판단한 비율)
+   - LLM 승격율 (경량 NER 저신뢰 → LLM 승격 비율, 목표 <30%)
+   - 에이전트 전환율 (clarify 실패 → FAQ/상담원 연결 비율)
+
+3. **지연/비용**:
+   - 평균 지연 (응답 시간 중앙값, 목표 <500ms)
+   - LLM 토큰 비용 (맥락 축소로 절감 효과 측정)
+
+4. **정확도/신뢰도**:
+   - 응답 확신도 (ECE/Brier Score, 캘리브레이션 품질)
+   - 엔티티 충돌율 (후보 복수 시 잘못된 선택 비율)
+   - 의도 드리프트 (라벨 분포·문체 변화 추적)
+
+### A/B 실험
+- 불확실성 임계치 (1.0 vs 1.5 vs 2.0) 비교
+- 맥락 윈도우 (5분 vs 10분 vs 15분) 성능 측정
+- LLM 프롬프트 템플릿 변경 (라벨 공간 축소 전략)
+
+### 휴먼 인 더 루프
+- Clarify 실패 티켓을 주간 단위 어노테이션
+- 신규 엔티티 패턴 승인 (의도 발견 루프 운영자 검토)
 
 ## 교훈
-- 엔티티 미확정 상태의 실행 금지, 재질문→확정→실행으로 느린 경로라도 안정성 우선.  
-- 오래된 기억/파일 토큰은 강한 패널티, 최신/한글 기업명·기업 접미사 가중으로 현실적 후보를 우선.
+
+### 기본 원칙
+- 엔티티 미확정 상태의 실행 금지, 재질문→확정→실행으로 느린 경로라도 안정성 우선
+- 오래된 기억/파일 토큰은 강한 패널티, 최신/한글 기업명·기업 접미사 가중으로 현실적 후보를 우선
+
+### LLM 하니스 최신 동향 적용 (2024-2025)
+1. **하이브리드 라우팅의 효율성**:
+   - 경량 분류기 + LLM 불확실성 기반 라우팅은 정확도 유지하며 지연/비용을 절반으로 절감
+   - LLM 단독 사용보다 실용적, 동적 임계치로 SLA 충족 가능
+
+2. **맥락 축소와 라벨 공간 관리**:
+   - 프롬프트에 전체 히스토리 주입은 비효율, 윈도우 제한 + 필터링으로 토큰 비용 절감
+   - 라벨 공간 확대 시 OOS 성능 저하 → 하위집합 동적 생성이 핵심
+
+3. **개방세계(Open-World) 대응**:
+   - 사전 정의 라벨만으론 한계, 의도 발견 루프로 신규 패턴을 점진적 학습
+   - LLM 군집화·명명은 빠른 부트스트랩에 유리, 도메인 특화는 미세조정 병행
+
+4. **불확실성 앙상블이 OOS 탐지 핵심**:
+   - 단일 지표(NER 스코어, LLM 신뢰도)보다 앙상블이 강건
+   - OOS 리콜 모니터링 필수, 에이전트 전환율로 실효성 측정
+
+5. **휴먼 인 더 루프의 중요성**:
+   - 자동화된 의도 발견·드리프트 감지도 운영자 검토 없이는 품질 저하
+   - 주기적 어노테이션과 A/B 실험으로 정책 검증 필수
+
+### 참고 문헌
+- ACL 2024 EMNLP Industry Track: "Intent Detection in the Age of LLMs"
+- arXiv 2024: "Efficient Out-of-Scope Detection via Uncertainty-Driven LLM Routing"
+- arXiv 2024: "Intent Recognition in Multi-party Conversations"
+- arXiv 2024: "IntentGPT: Few-shot Intent Discovery with Large Language Models"
 
 ---