From 00d5b489b4854843c3638f865bcde6e176d691ff Mon Sep 17 00:00:00 2001
From: Claude-51124 <claude@51124.local>
Date: Sat, 3 Jan 2026 12:33:42 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20multi-centroid=20=EA=B5=AC=ED=98=84=20?=
 =?UTF-8?q?=EC=83=81=EC=84=B8=20=EB=B0=8F=20=EC=9A=B4=EC=98=81=20=EA=B0=80?=
 =?UTF-8?q?=EC=9D=B4=EB=93=9C=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- seed_multi_centroid_prototypes.py 사용법 및 파라미터 설명
- 코드 변경 요약 (intent_store.py, semantic_classifier.py)
- 버전 관리 전략 (version=3 multi-centroid)
- Few-shot LLM 프롬프트 개선 구체적 방법 및 예시 구조
---
 ...�_의도_분류_성능_비교_테스트.md | 59 +++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/journey/troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md b/journey/troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md
index d783b74..6c558d7 100644
--- a/journey/troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md
+++ b/journey/troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md
@@ -127,6 +127,65 @@
 
 ---
 
+## 구현 상세
+
+### 스크립트 사용법
+
+**Multi-centroid 재생성**:
+```bash
+docker exec rb8001 python3 scripts/seed_multi_centroid_prototypes.py --apply
+```
+
+**파라미터**:
+- `--apply`: DB에 실제로 저장 (없으면 dry-run)
+- `--max-k`: intent당 최대 centroid 수 (기본값: 3)
+
+**주의사항**:
+- `intent_prototypes` 테이블의 `(intent_id, version, source)` UNIQUE 제약으로 기존 version=3은 덮어씀
+- 샘플 데이터 추가 시 `intent_eval_samples.json`, `intent_eval_challenge.json` 수정 후 재실행
+
+### 코드 변경 요약
+
+**`intent_store.py`**:
+- `load_multi_prototypes_db()`: version이 높은 것 우선, 같은 version 내 모든 centroid 로드
+- `load_prototypes_db()`: 하위 호환성 유지 (첫 번째 centroid만 반환)
+
+**`semantic_classifier.py`**:
+- `_intent_multi_vecs`: 여러 centroid 저장 (Dict[str, List[List[float]]])
+- `top_k()`: multi-centroid 존재 시 최대 유사도 계산, 없으면 단일 centroid 사용
+
+**버전 관리**:
+- version=3: multi-centroid (source="multi_centroid_{idx}")
+- version=2: 단일 centroid (calendar_event 등)
+- version=1: description 기반 (legacy)
+
+### Few-shot LLM 프롬프트 개선 계획
+
+**현재 상태**: `intent_parser.py`에서 CoT 지원하나 Few-shot 예시 미적용
+
+**개선 방향**:
+1. Top-3 임베딩 후보를 활용한 Few-shot 예시 구성
+2. Gemini 프롬프트 설계 원칙(`313_Gemini_프롬프트_설계_원칙.md`) 적용
+3. XML 구조화: `<examples>` 블록에 각 후보별 실제 문장 예시 제공
+
+**구현 위치**: `rb8001/app/services/llm/intent_parser.py:26-91`
+
+**예시 구조**:
+```xml
+<examples>
+후보 intent: email_summary
+- "어제 받은 메일 두 줄로 정리"
+- "오늘 받은 메일들 핵심 포인트 알려줘"
+- "메일함 정리해서 핵심만 알려줘"
+
+후보 intent: email_read
+- "최근 받은 메일 확인해 줘"
+- "어제 밤에 온 메일 열어봐"
+</examples>
+```
+
+---
+
 ## 참고
 
 - 계획 문서: `journey/plans/archive/251017_intent_analysis_improvement_plan.md`