多言語embeddingモデル対応 (BGE-M3)

[Kewton]

概要

日本語ナレッジ検索の精度向上のため、BGE-M3 embeddingモデルへの対応を行う。

背景

現在のデフォルトモデル nomic-embed-text は英語最適化で、日本語クエリ→英日混在ドキュメントのクロスリンガル検索精度が低い。

性能比較検証にて「iPadでの表示崩れと対応方針」で関連性の低いドキュメントが上位に来る問題が確認された。

モデル比較（ベンチマーク）

モデル	英語検索 (MTEB-R)	多言語 (MIRACL)	日本語 (MIRACL-ja)
nomic-embed-text (現在)	-	-	弱い
snowflake-arctic-embed2	0.556 (1位)	0.649	弱い (-6.9%転移)
BGE-M3	0.488	0.678 (1位)	0.926 (最強)

BGE-M3は日本語を含む多言語検索でトップ性能。Ollamaで qllama/bge-m3:q8_0 として利用可能（動作確認済み）。

タスク

T1: known_dimension にBGE-M3を追加

• ファイル: src/embedding/ollama.rs 行71-78
• 内容: "qllama/bge-m3:q8_0" => Some(1024) を追加
• コスト: 1行追加
• test_dimension_known_models テストにBGE-M3のアサーションを追加

T1.5: モデル変更時のキャッシュ無効化対応（必須）

• 根本原因: has_current_embedding() が section_path と file_hash のみでキャッシュ判定し、model 列を条件に含めていない
• 必須要件:
  1. has_current_embedding(path, file_hash, model) に変更し、モデル変更時に必ず再生成されるようにする
  2. 旧モデルのembeddingレコードは embedding生成時（embed / index --with-embedding / update --with-embedding の全経路）に自動削除する
  3. 上記挙動をユニットテスト/統合テストで確認する
• 受け入れ基準:
  • モデル変更後にembedを再実行すると、全セクションが新モデルで再生成される
  • 旧モデルのembeddingレコードがDBから削除される
  • embedding生成の全経路（embed, index --with-embedding, update --with-embedding）でモデル変更時に再生成・旧モデル削除が一貫して行われる
  • テストで上記挙動が検証されている

T2: 設定ファイルでのモデル変更動作確認

• commandindex.toml に [embedding] model = "qllama/bge-m3:q8_0" を設定
• commandindexdev embed --path . でembedding生成が正常に完了することを確認
• セマンティック検索が動作することを確認

T2.5: 次元不一致時の警告メッセージ実装

• search_similar() の返り値にメタ情報（スキップ数、総レコード数）を持たせる
  • 既存テスト影響: EmbeddingStore のユニットテスト、tests/e2e_semantic_hybrid.rs の更新が必要
  • 代替案: メタ情報を別構造体に切り出す設計も検討可
• 全CLI経路（search --semantic、hybrid search、suggest fallback）で一貫して警告を扱う
• 大部分がスキップされた場合に警告メッセージを出力する
  • 例: Warning: 95% of embeddings were skipped due to dimension mismatch. Consider re-running 'commandindex embed' after model change.

T3: セマンティック検索の精度比較テスト（手動評価）

• 同一クエリで nomic-embed-text と BGE-M3 の検索結果を比較
• 種別: 手元の実モデルで行う手動評価（CIテストではない。Ollama依存のためCI再現性が低い）
• 前提条件: Ollama上に qllama/bge-m3:q8_0 を事前pullしておくこと（ollama pull qllama/bge-m3:q8_0）
• 合否基準: top-5以内に期待ドキュメントが含まれること
• テストクエリ:
  • 日本語: 「iPadでの表示崩れと対応方針」（期待: Issue #299設計ポリシー）
  • 日本語: 「auto-yesの誤検知をどう解決したか」（期待: Issue #161設計ポリシー）
  • 英語: 「fullscreen terminal iPad landscape」（期待: useFullscreen.ts）
  • 英語: 「security review XSS protection」（期待: セキュリティレビュー文書）

T4: embedding再構築手順の整備

• README.mdに「Embedding」セクションを新設し、以下を追記:
  • 対応モデル一覧（nomic-embed-text, bge-m3等）
  • 前提条件: Ollamaモデルの事前pull（ollama pull qllama/bge-m3:q8_0、634MB）
  • モデル変更手順:

    commandindexdev clean
    commandindexdev index --path .
    commandindexdev embed --path .

  • T1.5の自動クリーンアップ機能により、embed 再実行のみでも対応可能な旨を記載
  • モデル変更時は再生成に時間がかかる旨の注意書き

モデル情報

• Ollama: qllama/bge-m3:q8_0
• パラメータ: 567M
• 次元数: 1024
• コンテキスト長: 8192
• 量子化: Q8_0
• サイズ: 634MB
• ライセンス: MIT

依存関係

• Rust crate: 新規追加なし
• 外部依存: Ollama上に qllama/bge-m3:q8_0 モデルの事前pullが必要（634MB）

今後の検討事項

• デフォルトモデルをBGE-M3に変更するかの検討
• bge-m3系モデル名バリエーション（qllama/bge-m3, bge-m3等）への対応
• 日本語テキストのMAX_TEXT_LENGTH（8192文字）とBGE-M3コンテキスト長（8192トークン）の整合性確認
• 大規模リポジトリでの1024次元化によるパフォーマンス影響評価（33%ストレージ増加）