docs: 트러블슈팅 문서 간소화 (195줄→약140줄)

- 중복 내용 제거 (Few-shot LLM 개선 방향 통합)
- 구현 상세 섹션 간소화 (파일명:줄번호 형식)
- XML 예시 코드 블록 제거 (파일명:줄번호로 참조)
- 문서 작성 원칙 준수 (100줄 이하 목표)
This commit is contained in:
Claude-51124 2026-01-03 12:34:48 +09:00
parent 00d5b489b4
commit 13be81e1fa

View File

@ -66,18 +66,15 @@
## 개선 방향
### 1. Multi-centroid 방식 도입
- 각 intent별 5-10개 실제 예시 문장으로 K-means centroid 생성
- `seed_calendar_event_samples.py` 방식으로 모든 intent 확장
- intent_prototypes DB에 version=2로 저장
- 각 intent별 K-means centroid 생성 (`seed_multi_centroid_prototypes.py`)
- intent_prototypes DB에 version=3으로 저장
### 2. Few-shot LLM 프롬프트 개선
- Top-3 임베딩 후보를 활용한 Few-shot 예시 추가
- Gemini 프롬프트 설계 원칙(`313_Gemini_프롬프트_설계_원칙.md`) 적용
- XML 구조화된 프롬프트로 예시 블록 제공
- Top-3 임베딩 후보 활용, XML 구조화 프롬프트
- 참고: `313_Gemini_프롬프트_설계_원칙.md`
### 3. 하이브리드 3단계 최적화
- FastPath(명확 패턴) → multi-centroid embedding(Top-3) → Few-shot LLM
- multi-centroid 정확도 개선 후 병행 비교 재검토
- FastPath → multi-centroid embedding → Few-shot LLM
---
@ -129,60 +126,15 @@
## 구현 상세
### 스크립트 사용법
**스크립트**: `scripts/seed_multi_centroid_prototypes.py --apply --max-k=3`
**Multi-centroid 재생성**:
```bash
docker exec rb8001 python3 scripts/seed_multi_centroid_prototypes.py --apply
```
**코드 변경**:
- `intent_store.py:70-118`: `load_multi_prototypes_db()` 추가, version 높은 것 우선 로드
- `semantic_classifier.py:41-86`: multi-centroid 최대 유사도 계산
**파라미터**:
- `--apply`: DB에 실제로 저장 (없으면 dry-run)
- `--max-k`: intent당 최대 centroid 수 (기본값: 3)
**버전**: version=3 (multi-centroid), version=2 (단일), version=1 (legacy)
**주의사항**:
- `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>
```
**Few-shot LLM**: `intent_parser.py:26-91`에서 Top-3 후보 활용 예시 추가 필요
---