データベース・ハイブリッド検索仕様書 (Database & Hybrid Search Specification)

1. データベース設計思想

本システムでは、SQLite を単なるメタデータストレージとしてだけでなく、「ベクトル検索エンジン」および「全文検索エンジン（FTS5）」としても活用しています。これにより、意味的な類推（Vector）と厳密なキーワード一致（BM25）を両立させた、堅牢なハイブリッド検索エンジンを実現しています。

1.1 ハイブリッド検索の採用理由

データが少ない初期段階では LSA（Latent Semantic Analysis）による学習が不十分で、語彙の関連性を正しく導き出せない「コールドスタート」問題が発生します。これに対処するため、統計的な重み付けを行う BM25 スコアリング 可能な全文検索（FTS5）を併用しています。

• Vector (LSA): 「意味」が似ているものを探す。データ量が増えるほど賢くなる。
• FTS5 (BM25): 「文字」が合っているものを探す。1件目のデータから正確に動作する。
• 指標: Max(Vector Similarity, BM25 Score) に基づくランキング。

2. エンティティ関係定義 (ERD)

erDiagram
    documents ||--o{ items : "Contains (1:N)"
    items ||--|| vec_items : "Vector Index (1:1)"
    items ||--|| items_lsa : "LSA Metadata (1:1)"
    items ||--|| items_fts : "Full-text Index (1:1)"

    documents {
        integer id PK "文書ID"
        text path "出典・パス (Unique)"
        text mime "MIMEタイプ"
        datetime created_at "作成日"
        datetime updated_at "更新日"
    }
    items {
        integer id PK "チャンクID"
        integer document_id FK "documents.id 参照"
        integer chunk_index "チャンク順番"
        text content "テキスト本体"
        datetime created_at "作成日"
        datetime updated_at "更新日"
    }
    vec_items {
        integer id PK "items.id と紐付け"
        blob embedding "50次元ベクトルデータ(f32)"
    }
    items_fts {
        integer rowid PK "items.id と紐付け"
        text content "全文検索用インデックス"
    }

3. ハイブリッド検索アルゴリズム

3.1 search_text のロジック

検索クエリが入力されると、システムは以下の 2系統の検索 を並列または逐次実行して結果をマージします。

1. セマンティック検索 (Vector):
   • クエリを LSA Engine で 50 次元のベクトルに射影。
   • vec_items から L2 距離が近い順に取得し、1.0 - (distance / 2.0) で類似度を算出。
2. 統計キーワード検索 (FTS5/BM25):
   • クエリを trigram トークナイザー（3文字単位）で分解。
   • SQLite FTS5 の bm25() 関数を用いて、文書内の重要度を算出。
   • BM25 スコアを (1.0 - tanh(score/10)) 等で 0-1 の類似度に変換。

最終スコア: 各 ID ごとに 2 つのスコアのうち高い方（Max）を採用し、降順でランキングします。

4. テーブル詳細

4.1 items (チャンク管理)

文書を分割したテキストを保持。すべての検索インデックスのソースとなります。

4.2 vec_items (ベクトル演算用仮想テーブル)

sqlite-vec による仮想テーブル。LSA エンジンが生成した特徴量を保持します。

4.3 items_fts (全文検索用仮想テーブル)

SQLite FTS5 拡張による仮想テーブル。tokenize='trigram' を指定することで、日本語のわかち書きに依存しない強力な部分一致・統計検索をサポートします。

4.4 items_lsa (LSAメタデータ)

LSA の学習・推論に使用する中間データ（特徴量 blob）を保持します。

4.5 internal_metadata (内部管理テーブル)

システムバージョン（0.3.0）等を保持し、スキーマの互換性を管理します。