# Pro 埋め込みモデル仕様（ONNX / tract・ort）

エディション概要は **01_system_overview.md**、アーキテクチャは **02_architecture_design.md** を参照。本文書は Pro 版の埋め込みまわりの技術仕様のみを扱う。

## 1. 目的

- Community は LSA（50 次元）。Pro は **ニューラル埋め込み**（768 次元）で検索精度を向上させる。
- 同一プロセス・純 Rust（tract または ort）で動作し、配布をシンプルに保つ。

## 2. 採用方針

### 2.1 埋め込みモデル

- **候補**: **sonoisa/sentence-bert-base-ja**（例: `sentence-bert-base-ja-mean-tokens-v2`）
- **理由**: 日本語特化でビジネス・学術文書に強い。paraphrase-multilingual より日本語のフォーマルな語彙に適している。
- **仕様**: 出力 **768 次元**。モデルサイズ約 440MB のため、**量子化（FP16/INT8）** を検討する。

### 2.2 量子化

- 公式の量子化済み sonoisa は公開されていないため、**自前で量子化**する。
- PyTorch / Hugging Face から ONNX にエクスポートし、**ONNX 形式で量子化**したモデルを配布またはビルド時に用意する。

### 2.3 実行系（Rust）

- **推奨**: **tract**
  - **純 Rust**。C++ 依存がなく、`cargo build` で完結する。
  - 同一プロセスで動作し、別プロセス起動は不要。
  - ONNX を読み込み可能。Rust との親和性が高い。
- **代替**: **ort**（ONNX Runtime の Rust バインディング）
  - ONNX Runtime の最適化をそのまま使えるが、ネイティブ lib の取得・リンクが必要。
  - 必要に応じて検討。

## 3. 技術メモ

### 3.1 他方式との比較

| 方式 | 特徴 |
|------|------|
| **LSA**（現行） | 軽量・CPU のみ・学習データ不要。次元数は 50 などで調整可能。 |
| **LDA** | トピックモデル。検索の「意味の近さ」には LSA ほど直結しない。次元を増やしてもスパースになりがち。 |
| **ICA** | 独立性の最大化が目的で、意味検索には不向き。 |
| **Elasticsearch** | ベクトルは外部の埋め込みモデルで作成。GPU は一般的に使わず、多くは CPU 推論。 |

### 3.2 モデル・次元・サイズ（参考）

| モデル | 次元数 | パラメータ数 | ファイルサイズ（目安） |
|--------|--------|--------------|------------------------|
| paraphrase-multilingual-MiniLM-L12-v2 | 384 | 約 118M | 約 470 MB |
| sonoisa/sentence-bert-base-ja | 768 | 約 110M | 約 440 MB |

### 3.3 ONNX

- **ONNX (Open Neural Network Exchange)**: フレームワーク非依存のモデル形式。PyTorch 等で学習したモデルを ONNX にエクスポートし、ONNX Runtime や **tract** などで実行できる。
- 量子化や配布がしやすく、Rust からは tract / ort で利用する。

## 4. 組み込み済み（Pro 版）

- **モデル配置**: プロジェクト内 **`embedding_model/`** に `model_quantized.onnx` と `vocab.txt` をコピーして置く。README は `embedding_model/README.md` を参照。
- **パス解決**: (1) 環境変数 `TELOS_EMBEDDING_MODEL_DIR`（上書き用）、(2) 配布ビルド時は `resource_dir/embedding_model`（同梱リソース）、(3) 開発時は exe からの相対 `../../embedding_model`。いずれも `model_quantized.onnx` の存在で有効とみなす。
- **同梱**: `tauri.conf.json` の `bundle.resources` に上記2ファイルを登録。Pro ビルド前にファイルを置いておくとインストーラに含まれる。
- **次元**: Pro 版は 768 次元。DB の vec_items は起動時に 768 次元で初期化される。
- **検索・追加**: Pro ビルドでは埋め込みモデルでベクトルを計算し、HNSW と vec_items に保存する。
- **既知の事象**: 量子化 ONNX を tract で読み込むと `into_optimized()` で Cast ノード失敗することがある。その場合は最適化スキップ（`TELOS_EMBEDDING_NO_OPTIMIZE=1` 等）で起動し、FTS のみでも検索可能。ort 利用時は出力 shape が `[1, 768]` の場合はそのまま採用（mean_pool 不要）。

動作確認・KPI は **08_embedding_tract_goals_and_kpi.md**・**09_embedding_tract_implementation_and_tests.md**・**11_pro_vectorization_and_ann.md** を参照。
