# Pro ベクトル化・ANN — 動作確認と既知の制約

データベース・検索の仕様は **03_database_specification.md**、埋め込みの技術仕様は **07_embedding_tract.md** を参照。本文書は **動作確認チェックリスト** と **既知の制約・改修メモ** のみ。

## 1. 動作確認チェックリスト（モデルロード成功時）

| # | 確認項目 | 合格基準 |
|---|----------|----------|
| T1 | 1 件追加で vec_items に 768 次元が入る | `add_item_text` 後、`SELECT COUNT(*), vec_to_json(embedding) FROM vec_items` で 1 行・768 要素 |
| T2 | 起動時 HNSW 構築 | Pro 再起動後ログに `[BOOT] Pro HNSW: ... index built.` |
| T3 | 検索でベクトルヒット | 追加文書に近いクエリで `search_text` がその文書を返し、類似度が付与される |
| T4 | 複数文書で類似度順 | 意味的に近い文書が上位に来る |

## 2. 既知の制約・対処

| 事象 | 対処 |
|------|------|
| tract の `into_optimized()` で Cast 失敗 | `TELOS_EMBEDDING_NO_OPTIMIZE=1` で最適化スキップ。または ort 使用。 |
| モデル未ロード時 | FTS のみで検索可能。ベクトル化・ANN は動作しない。 |
| ONNX 出力が `[1, 768]` | ort 利用時は mean_pool 不要でそのまま採用（実装済み）。 |

## 3. 任意の改修メモ

- **update_item 時の HNSW**: 現状は vec_items のみ更新。HNSW は次回起動または RE-INDEX で再構築。必要なら 1 件更新を検討。
- **スタブ埋め込み**: モデルなしでパイプラインだけ検証する場合は `TELOS_EMBEDDING_STUB=1` 相当のスタブを検討。

KPI 定義は **08_embedding_tract_goals_and_kpi.md**（K16–K19）、検証手順は **09_embedding_tract_implementation_and_tests.md** を参照。
