サイドカー統合仕様書 (Sidecar Integration Specification)

1. サイドカーの役割と設計思想

本システムにおける llama-server は、外部プロセスとして動作する「推論エンジン」です。Rust コアにライブラリとして組み込むのではなく、サイドカー（別プロセス）として分離することで、以下の設計上の利点を得ています。

• 安定性の隔離: 万が一推論エンジンがメモリ不足などでクラッシュしても、メインの GUI や MCP サーバー、データベースは影響を受けず、安全に再起動を行えます。
• 更新の柔軟性: モデルバイナリやランタイムを Rust コードの再コンパイルなしでアップデート可能です。

2. プロセス管理

2.1 ライフサイクル制御

Tauri の Command API を使用して管理されます。

• 自動起動: アプリ起動時に --embedding モードでバックグラウンド実行されます。
• 孤立防止: メインプロセスが異常終了した場合でも、プロセスグループ管理によりサイドカーがゾンビプロセスとして残らないよう設計されています。

2.2 起動引数の詳細

現状、以下のパラメータで最適化されています。

• --pooling mean: Embedding 精度の向上のための設定。
• --embedding: 入力テキストから特徴ベクトルを抽出する機能を有効化します。

3. Hermetic Build (自己完結型ビルド)

Windows 環境における DLL 地獄を防ぐため、以下の設計を徹底しています。

• DLL 自動配置: ビルドおよびリリース時に、vec0.dll (sqlite-vec) などの依存ライブラリを実行ファイルと同階層に自動的にコピーします。
• パス解決: アプリ実行時に LdgLibrary 等の仕組みを介さず、カレントディレクトリから優先的に DLL をロードするよう build.rs で制御しています。

4. トラブルシューティング

• ポート 8080 の競合: 他のアプリがポート 8080 を使用している場合、サイドカーの起動に失敗します。このステータスは UI 上のインジケーターで確認可能です。
• モデル未検出: resources フォルダ内に適切な GGUF モデルが存在しない場合、ログにエラーが出力され、検索機能が無効化されます。