# 의도 런타임(하이브리드) 설계: 임베딩 + 베이지안 + 동적학습 + LLM 재분석 + A/B/밴딧

작성일: 2025-10-23  
작성자: happybell80  
대상 서비스: rb8001 (51124)

---

## 1) 개요
- 목표: 룰/키워드 중심 의도 파악의 한계를 넘어, 의미 기반·불확실성 관리·지속 학습을 갖춘 “의도 런타임”으로 전환.
- 접근: FastPath(규칙/NB) + 임베딩 Top‑K 후보축소 + LLM JSON 재분석 + Beta(α,β) 기반 동적 임계치/경로 최적화.
- 기대: Unknown↓, 잘못된 실행<1%, LLM 호출≤30% 유지, 지연 관리(중앙값 < 800ms).

## 2) 아키텍처(Phase 1)
- FastPath: 기존 `DecisionEngine`(정규식 + Naive Bayes). conf≥0.9 시 즉시 결정.
- 임베딩 후보축소: intent 설명/예시 벡터와 코사인 유사도 Top‑K + 마진 기반 신뢰도.
- LLM 재분석: Top‑K만 JSON 스키마(`{intent, slots, confidence, clarify}`)로 결정, conf<τ는 clarify.
- 캘리브레이션: 유사도·마진 기반 conf를 온도/Isotonic 등으로 보정(과신 방지).

구현 파일(스캐폴드)
- `rb8001/app/brain/intent_graph.py` — FastPath→Semantic→LLM 파이프(ENV: `INTENT_ENGINE=graph`)
- `rb8001/app/brain/semantic_classifier.py` — intent_registry 기반 제로샷 후보축소
- `rb8001/app/llm/intent_parser.py` — LLM 함수호출(JSON) 파서
- `rb8001/app/brain/intent_registry.yaml` — intent 설명/슬롯 레지스트리

## 3) 임베딩 설계
- 모델: 한국어 강건 다국어 SBERT/miniLM 계열(테스트 후 선정). 서비스는 HTTP 임베딩 사이드카 사용.
- 프로토타입: intent별 centroid(설명+예시 임베딩 평균). DB 버전관리 → 성공 샘플 EMA 반영(온라인), outlier 감쇠.
- 신뢰도: cos(top1)·마진(top1–top2) 합성 → 캘리브레이션으로 정규화.

## 4) 베이지안·동적 학습
- 의도/경로별 성공률 Beta(α,β) 추적: 성공 α+=1, 실패 β+=1 → θ~Beta(α,β).
- 경로 선택: Thompson Sampling으로 FastPath/LLM/clarify 임계치 τ 동적 최적화.
- 로그 스키마(요지): intent_decision_log(user_id, message, candidates, chosen, confs, path, success, clarify, latency, ts), prototype_version(intent, centroid_hash, updated_at).

## 5) LLM 재분석 가드레일

### 5.1 기본 구조
- 입력: Top‑K 후보명/설명 + 최근 컨텍스트 최소화 주입.
- 출력: JSON 한 줄. OOS/불확실은 clarify true, 슬롯 미충족 시 되묻기 우선.

### 5.2 Chain-of-Thought (CoT) 적용 방안 (2025-11-18 추가)

**목적**: 복잡한 질문이나 확신도 낮은 경우 LLM이 단계별 추론을 통해 더 정확한 의도 분류를 수행하도록 개선.

**구현 방안**:
1. **IntentParserLLM 프롬프트 수정**: 
   - 현재: "JSON만 출력하세요"
   - 변경: "단계별로 추론한 후 JSON 출력하세요"
   - 추론 단계:
     - 1단계: 메시지에서 핵심 키워드/엔티티 추출
     - 2단계: 의도 후보 검토 및 컨텍스트 분석 (직전 대화, 슬롯 정보 등)
     - 3단계: 최종 의도 결정 및 신뢰도 평가

2. **조건부 CoT 활성화**:
   - 환경변수: `INTENT_USE_COT=true` (기본값: false)
   - 활성화 조건:
     - FastPath/Semantic에서 확신도 낮은 경우 (conf < 0.7)
     - 복잡한 질문 (키워드 3개 이상, 대명사 포함 등)
     - 컨텍스트 의존적 질문 ("이 기업", "그 회사" 등)
   - 비활성화 조건:
     - FastPath/Semantic에서 확신도 높은 경우 (conf ≥ 0.9) → CoT 생략하여 비용/지연 최소화

3. **추론 과정 로깅**:
   - LLM 출력에서 추론 단계는 로깅/디버깅용으로 저장
   - 최종 JSON만 파싱하여 기존 인터페이스 유지
   - Human-in-the-loop 리뷰 큐에서 추론 과정 검증 가능
   - 로그 스키마: `intent_cot_log(user_id, message, reasoning_steps, final_intent, timestamp)`

**예상 효과**:
- 복잡한 질문 정확도 향상 (특히 "이 기업 대표 누구야?" 같은 컨텍스트 의존적 질문)
- 의도 분류 오류 감소 (단계별 검증으로 잘못된 실행 방지)
- 비용/지연 최소화 (조건부 활성화로 불필요한 CoT 호출 방지)

**구현 파일**:
- `rb8001/app/llm/intent_parser.py` — CoT 프롬프트 추가 및 조건부 활성화 로직
- `rb8001/app/core/config.py` — `INTENT_USE_COT` 환경변수 추가

## 6) 실험·배포 전략
- A/B → 밴딧: 10%→30%→50% 점진 롤아웃, 지표(Unknown/Clarify/오실행/지연/비용) 모니터링.
- 임계치/경로/모델 후보는 밴딧 “팔(Arm)”로 관리, Thompson Sampling으로 자동 최적.

## 7) 운영 지표
- 정확도/Unknown/Clarify/오실행(<1%)
- 비용/지연: LLM 호출율≤30%, 중앙 지연<800ms.
- 사용자 피드백/수정률, 슬롯 부족 비율.

## 8) rb8001 적용 계획
- Phase 1 (이번 배포): IntentGraph 플래그 경로 + Clarify UX(버튼 실패 시 숫자 선택 폴백) + 엔티티/패턴 보강.
- Phase 2: Beta(α,β)·임계치/경로 동적화 + 프로토타입 DB버전 관리 + 캘리브레이션 모듈.
- Phase 3: SetFit/경량 분류기 오프라인 재학습 + 개인화 사전(동의어/별칭) 자동 갱신.

활성화/헬스체크
- 활성화: `INTENT_ENGINE=graph`  
- 헬스: `curl -sf http://localhost:8001/health`  
- 로그: `docker logs rb8001 --tail 200 | grep -iE "IntentGraph|web_search|CLARIFY_ENTITY|error|fail"`

## 9) 리스크·완화
- LLM 비용/지연: FastPath/임베딩 우선, conf 게이트/Top‑K 축소로 절감.
- 과신/오실행: 캘리브레이션+clarify 정책, Beta 기반 안전 임계치.
- 데이터 드리프트: 주간 리트레이닝/프로토타입 갱신, 밴딧으로 자동 적응.

## 10) 검증·모니터링
- 테스트: `rb8001/tests/test_intent_entity_skill_comprehensive.py` — 40/40 통과(의도/엔티티/스킬).  
- 리포트: `rb8001/tests/test_results_251023_final.md` — 100% 결과 기록.  
- 모니터: Unknown률/Clarify 비율/오실행/LLM 호출율/평균 지연, 슬랙 이슈는 즉시 로그 근거로 대응.

## 11) 참고(관련 구현 포인터)
- `rb8001/app/router/router.py` — IntentGraph 게이트(ENV), 웹검색 경로
- `rb8001/app/router/message_router.py` — 대명사 해소/엔티티 스코어링
- `rb8001/app/services/workflows/web_search_workflow.py` — LangGraph 검색 워크플로

---

## 12) 3줄 요약
- 하이브리드 의도 파이프라인: FastPath → 임베딩 Top‑K → LLM JSON 재분석(+clarify) + 신뢰도 캘리브레이션.
- 동적 학습/최적화: 로그 기반 프로토타입·동의어 갱신, Beta(α,β)+Thompson Sampling·A/B/밴딧으로 임계치·경로 자동 튜닝.
- rb8001 IntentGraph 스캐폴드 위 단계적 적용 가능, Unknown↓·오실행<1%·LLM 호출≤30% 목표.

