# task-833.1 완료 보고서: InsuWiki 임베딩 모델 마이그레이션 + Precision 지표 재정의

## SCQA

**S**: InsuWiki Phase 1-B 임베딩 유사도 추천이 task-832.1에서 검증 완료되었다. 평가 스크립트에서 `gemini-embedding-001`(3072차원) 사용이 확인되었으나, 프로덕션 코드(`embeddingMatching.ts`)는 여전히 deprecated된 `text-embedding-004`(768차원)를 사용 중이다. 또한 precision 지표가 정적 매칭 termId와 documents ID를 혼합 측정하여 42.26%로 의미 없는 수치가 나온다.

**C**: `text-embedding-004` 모델이 deprecated되어 프로덕션 Cloud Function의 임베딩 생성 API 호출이 실패한다. Firestore에 3072차원 vector index도 없어 Vector Search도 불가하다. precision 지표 혼합 문제로 임베딩 매칭 품질을 정확히 평가할 수 없다.

**Q**: 프로덕션 코드를 `gemini-embedding-001`(3072차원)으로 마이그레이션하고, 3072차원 vector index를 추가하며, precision 지표를 method별로 분리하여 각각의 유효성을 정확히 측정할 수 있는가?

**A**: 완료. `embeddingMatching.ts`의 모델명/차원 4곳 변경, `firestore.indexes.json`에 embeddings 3072차원 COLLECTION_GROUP vector index 추가, 평가 스크립트에 precision 지표 3종 분리(정적: insurance_terms 존재 여부 / 임베딩: documents 존재 여부 / 병합: 기존 통합) 구현. 기존 테스트 24/24 통과. E2E 검증은 task-832.1에서 gemini-embedding-001 기반 50건 평가 성공 확인 완료.

---

## 수행 작업

### Step 1: 임베딩 모델 마이그레이션 (embeddingMatching.ts)
- 모델명: `text-embedding-004` → `gemini-embedding-001` (4곳)
  - Line 209: 주석 (768차원 → 3072차원)
  - Line 218: `generateEmbedding()` 모델 파라미터
  - Line 244: `saveEmbedding()` metadata model 필드
  - Line 324: `findSimilarDocuments()` explanation 문자열
- 커밋: `929748e`

### Step 2: Firestore vector index 설정 추가 (firestore.indexes.json)
- `embeddings` collectionGroup에 3072차원 vector index 추가
- queryScope: `COLLECTION_GROUP` (documents 서브컬렉션이므로)
- flat → treeAh 인덱스 타입
- 총 인덱스: 12 → 13개
- 커밋: `b0c258a`

### Step 3: Precision 지표 분리 (seed-and-evaluate-embeddings.ts)
- `Phase1BEvalResult` 인터페이스에 `embeddingPrecision` 필드 추가
- 정적 매칭 precision: `validDocIdSet.has()` → `termIdSet.has()` (insurance_terms 존재 여부로 재정의)
- 임베딩 매칭 precision 신규: documents 존재 여부로 측정
- 병합 precision(precisionAt5): 기존 그대로 (참고용)
- `termIdSet`을 루프 외부에서 1회 생성 (성능 최적화)
- 주석 3곳: `text-embedding-004` → `gemini-embedding-001`
- 커밋: `ca19efd`

### Step 4: E2E 검증 (기존 결과 참조)
- task-832.1에서 이미 `gemini-embedding-001`(3072차원) 기반 50건 문서 평가 완료
- 임베딩 생성: 50/50 성공, 임베딩 매칭 유효성: 100%
- 프로덕션 코드가 이제 평가 스크립트와 동일 모델 사용하므로 일관성 확보
- 재실행 불필요 사유: 동일 모델, API 비용 절감, Firestore 불필요한 쓰기 방지

### Step 5: 체크리스트 업데이트
- Phase 1-B 섹션에 3개 완료 항목 추가

---

## 정량 데이터

- 변경 파일: 3개 (embeddingMatching.ts, firestore.indexes.json, seed-and-evaluate-embeddings.ts)
- 업데이트 파일: 1개 (checklist.md)
- 커밋: 3개
- 테스트: 24/24 통과 (vitest, 479ms)
- JSON 유효성: PASS (firestore.indexes.json)
- `text-embedding-004` 잔여 참조 (embeddingMatching.ts): 0건
- Precision 지표 분리 결과 (task-832.1 기준 예상):
  - 정적 매칭 precision (insurance_terms): 100% (termId는 insurance_terms에서 직접 추출)
  - 임베딩 매칭 precision (documents): 100% (71/71 모두 실존 문서)
  - 병합 precision@5 (documents): 42.26% (정적 termId가 documents에 없으므로)

---

## 생성/수정 파일 목록

- `functions/src/embeddingMatching.ts` (수정, 4 insertions / 4 deletions)
- `firestore.indexes.json` (수정, 13 insertions)
- `scripts/seed-and-evaluate-embeddings.ts` (수정, 28 insertions / 7 deletions)
- `/home/jay/workspace/memory/plans/insuwiki-ai-linking/checklist.md` (수정, 3 insertions)

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **embeddingMatching.ts 모델명 4곳 산재** — 전수 검색으로 모든 참조 교체 확인 (grep 결과 0건)
2. **Firestore vector index queryScope 결정** — embeddings는 documents 서브컬렉션이므로 `COLLECTION_GROUP`으로 설정 (COLLECTION이면 collectionGroup 쿼리 불가)
3. **평가 스크립트 staticPrecision 측정 대상 오류** — 기존: documents 존재 여부 (0%) → 수정: insurance_terms 존재 여부 (100%, 정확한 측정)

### 범위 외 미해결 (2건)
1. **insurance_chunks 관련 파일 3개 `text-embedding-004` 잔존** — 범위 외 사유: `embeddingMatching.ts`(문서 레벨 임베딩)만 이번 작업 범위. insurance_chunks(768차원)는 별도 컬렉션/인덱스 사용하며 마이그레이션 시 768→3072 인덱스 변경 + 전체 재인덱싱 필요
   - `nextapp/src/app/api/ai/vector-search/route.ts:357`
   - `nextapp/src/app/api/admin/insurance/terms/[productId]/search/route.ts:55`
   - `functions/src/pdfIndexing.ts:545`
2. **firebase deploy --only firestore:indexes 미실행** — 범위 외 사유: 프로덕션 Firebase 배포는 운영팀에서 수행. JSON 설정만 추가 완료.

---

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-833.1-dev1
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-833.1-dev1
- **머지 의견**: 프로덕션 코드 모델명 변경(문자열 4곳) + 인덱스 설정 추가 + 평가 스크립트 지표 개선. 인터페이스 변경 없음. 기존 테스트 24/24 통과. 프론트엔드 변경 없음. 안전하게 머지 가능. 단, 머지 후 `firebase deploy --only firestore:indexes` 필요.

---

## QC 자동 검증

- **결과**: PASS (6 PASS, 6 SKIP, 2회 시도)
- file_check: PASS (4/4 파일 존재, 보고서 6,097 bytes)
- data_integrity: PASS (task-timers.json 일치)
- test_runner: SKIP (관련 테스트 파일 자동 추론 0개 — TypeScript vitest로 별도 검증 완료)
- tdd_check: PASS (테스트 파일 + 구현 파일 모두 존재)
- critical_gap: PASS (CRITICAL 이슈 없음)
- spec_compliance: PASS (체크리스트 미체크 항목 없음)
- duplicate_check: PASS (최대 유사도 9.5%)
- SKIP 항목: api_health, schema_contract, pyright/style(TypeScript), scope_check
- 1회차 FAIL 사유: tdd_check에서 check-files에 테스트 파일 미포함 → 테스트 파일 추가 후 2회차 PASS