Agent Zeroの埋め込みモデルを変更する：メモリの再インデックスとロールバック

Agent Zeroの埋め込みモデルを変更するには、Model Preset内のembeddingスロットを編集してSaveをクリックします。そして、その編集でプロバイダーまたはモデル名が変わると、次回アクセス時にメモリが再インデックスされます。FAISSインデックスは1つのモデルの出力幅に合わせてサイズが決まり、ディスク上の既存ベクトルは古いモデルによって書き込まれているためです。 Agent Zero自身のインストールガイドは、その結果を「embedding_llmを変更するとA0のすべてのメモリが再インデックスされます」と1行で述べていますが、手順も所要時間も復旧方法も示していません。このページでは、その空白をソースから埋めます。自動再構築が実際に行うこと、静かに発火しない2つの経路、古いメモリが引き続き戻ることを確認する方法、そして戻す方法です。Kunavoは埋め込みモデルを提供していないため、そのスロットは別途購入します。Kunavoが価格を提示できるのはmainスロットとutilityスロットです。

まず、区別しておくべきバージョン番号が2つあります。フレームワークのバージョンはv2.12で、プロジェクト自身のリリース記事によると、2026年9月9日に公開されました。READMEで最も目立つ番号はA0 Launcher v1.7ですが、これはagent0ai/a0-launcherにある別のデスクトップ用インストーラーのバージョンです。この番号をフレームワークのものとして扱うと、メジャーバージョンの系列が丸ごと異なってしまいます。また、v2.xでは、モデルのフィールドは単一のグローバル設定ではなく、プリセットに属しています。モデルプリセットのガイドには「すべてのセットアップには、メイン、ユーティリティ、埋め込みの各モデルが含まれる」と記載されており、新しいチャットで使用するプリセットは Settings → Agent → Models で選択します。なお、インストールガイドには現在も、Provider と Model Name のフィールドを含む「Embedding Model Settings」セクションが記載されています。そのため、この形式で書かれた手順が必ずしも古いとは限りません。ただし、入力した値はプリセット内のスロットに設定されるため、以下で説明する設定の反映に関する注意が重要になります。

チャットモデルの切り替えと異なる理由

チャットモデルの変更は次のリクエストで有効になり、ディスク上で移動するものはありません。埋め込みモデルの変更はストレージを無効化します。Agent Zeroは、実行中のモデルが返す値（faiss.IndexFlatIP(len(embedder.embed_query("example"))) in plugins/_memory/helpers/memory.py）からFAISSインデックスのサイズを決めるため、幅は設定値ではなくモデルの属性です。出荷時のデフォルトであるsentence-transformers/all-MiniLM-L6-v2は、そのモデルカードによればテキストを384次元空間に変換します。OpenAIのembeddingsガイドでは、text-embedding-3-smallは1536、text-embedding-3-largeは3072です。切り替えによって生じる形状の変化はこれです。

実際に購入する再構築回数を決めるスコープ上の事実は2つあります。第一に、これはグローバル編集ではなくプリセット編集です。model-presetsガイドは、スコープが「プリセットの選択だけを保存し、プリセットを編集するとそれを使用するすべてのスコープが更新される」と述べています。そのため、1回の編集が意図した範囲を超えて伝播する場合があり、プリセット間の切り替えによって埋め込みモデルも変わる可能性があります。キュレーション済みのEfficiencyおよびPowerプリセットには独自のembeddingブロックがなく、ガイドは既存の非デフォルトプリセットが省略された高度な値をDefaultから継承する場合があると述べているだけです。思い込まず、プリセットの概要を確認してください。第二に、project_memory_isolation: trueはメモリプラグイン設定における出荷時のデフォルトです。そのため、複数プロジェクトのインスタンスでは独立したストアが複数存在し、それぞれが次回の使用時に個別に再構築されます。数週間使われていなかったプロジェクトは、誰かが開いた日に再構築のコストを負担します。

ステップ1：バックアップを取り、離れるものを書き留める

Agent Zeroの使用ガイドは、このケースをすでに記載しています。バックアップによって「チャット、プロジェクト、知識、メモリ、設定、スキル、ワークスペースファイル」が保護され、事前にバックアップすべきものとして「メモリの一括クリーンアップ」も挙げられています。Settings → Backup & Restoreからバックアップを1つ作成するか、LauncherのBackup機能で/a0/usrをバックアップしてください。ガイド自身も、秘密情報は「バックアップアーカイブに常に含まれるとは限らない」と注意しているため、認証情報は別途保管してください。

次に、移行元のモデルを記録します。推測しないでください。キュレーションされたプリセットコレクションは初回起動時に公開リポジトリからダウンロードされ、インストール日後に変更される可能性があります。

# Read the CURRENT model off your own instance before you touch anything.
# The curated preset set is fetched from GitHub at first start, so the
# default you installed with is not necessarily today's default.
# Container name: take it from your own `docker ps`.

docker exec agent-zero ls -la /a0/usr/memory/default
docker exec agent-zero cat  /a0/usr/memory/default/embedding.json
#   -> {"model_provider": "huggingface",
#       "model_name": "sentence-transformers/all-MiniLM-L6-v2"}

# Projects do not share that directory. With project isolation on (the
# shipped default) each project keeps its own store under its own meta
# directory, and each one rebuilds on its own next use.

ステップ2：変更を行う

インストールガイドに記載された手順は3段階です。Web UIでSettingsを開き、各ロールのプロバイダーを選択してモデル名を入力し、Saveをクリックします。ただし、この手順が説明していない点が4つあります。いずれもmainのソースから読み取れます。

再構築で行われること、行われない2つの経路

Save時にmodel_config_set.pyは、以前と新しい埋め込みプロバイダー、名前およびkwargsを比較し、いずれかに差異があると、embedding_model_changedを遅延バックグラウンドタスクとして開始します。このタスクによって呼び出される拡張機能が行うのは、メモリの再読み込みだけです。次回アクセス時にMemory.initialize()が再実行され、インデックスの隣にあるembedding.jsonを確認します。そのファイルにはmodel_providerとmodel_nameという正確に2つのフィールドだけがあります。不一致の場合、コードはget_all_docsを使って古いインデックスからすべてのドキュメントを取り出し、新しい幅で新しいインデックスを作成し、同じIDで同じドキュメントを再挿入します。この経路は機能し、メモリを保持します。

2行目と3行目は、2025年10月13日に開始され、クローズされたissue #759「Errors after changed default Embedding Model」の背景にある継ぎ目です。このissueのトレースバックには、メモリ想起から類似度検索を行う際のassert d == self.dが示されています。この継ぎ目は、2026年9月21日時点でもmainに残っています。もう1つのクローズ済みissueである#1396では、Ollamaの/api/embedで400が発生したことが報告され、投稿者は原因を古いインデックスと突き止め、index.faissとindex.pklを削除する回避策を示しています。この回避策はストアを破壊するため、修復やロールバックではなく、リセットとして扱ってください。どちらのissueにもメンテナーからのコメントはなく、#1396は90日後に古いissueを処理するボットによってクローズされました。そのため、両方の診断は報告者自身のものであり、両方の解決策は未検証です。

ステップ3：呼び出しの成功ではなく、以前の想起を検証する

この変更によって生じる失敗は静かに起きるため、「新しいモデルが応答した」ことは正しい受け入れテストではありません。メモリダッシュボードを開き、メモリガイドに従って4つの領域すべて — main、fragments、solutions、skills — を対象にフィルターし、変更前から存在することが分かっているものを検索してください。各プロジェクトには固有のストアがあるため、プロジェクトごとに1回実施します。次に類似度しきい値を確認します。出荷時のmemory_recall_similarity_thresholdは0.7であり、これはモデルの性質ではなく、プラグインごとのデフォルト値です。新しい埋め込みモデルは類似度スコアを再分配します。エラーが1つも発生しないまま想起性能が低下する可能性があるため、しきい値の制御は検証の一部であり、細部ではありません。

このページでは、再構築の実行中にWeb UIが進行状況や完了シグナルを表示するかどうかは分かりません。再構築は遅延バックグラウンドタスクとして実行され、そのための表示場所は確認されていません。確認表示はないものとして、手動で検証してください。

ロールバックと、再構築にかかる費用

ベンダーが文書化したロールバックはありません。存在するのは、上記のバックアップ機構とメタファイルの動作だけです。以下の手順は、プロジェクトが公開したものではなく、その2つから組み立てたものです。変更前のバックアップを復元するか、スロットを以前のプロバイダーとモデル名に正確に戻してください。そうすると、メタファイル比較が逆方向で失敗し、再構築されます。同じコンテナでは、tmp/下の埋め込みキャッシュがプロバイダーとモデルによって名前空間分離されているため、以前使用したモデルに戻すと、変更されていないテキストのキャッシュ済みベクトルを再利用できる場合があります。ただし、tmp/は文書化されたバックアップの対象外であるため、コンテナを再作成すると失われます。新しいプロバイダーが再構築の途中でエラーになった場合のコードの動作はテストされておらず、ここにも記載されていません。それに頼らず、バックアップから検証してください。

費用について：Kunavoは埋め込みモデルを提供していないため、以下の金額はすべて、2026年9月21日に確認した公開料金で、お客様自身のアカウントからOpenAIへ直接支払うものです。保存済みドキュメント数をメモリダッシュボードで数え、平均長を掛け、1トークンあたりおよそ4文字で割って、自分でジョブの規模を見積もってください。この除数は慣例であり、測定値ではありません。

これは記載した前提に基づくトークン計算であり、測定済みの再構築量でも上限でもありません。また、ストアごとの計算です。プロジェクト分離を有効にしている場合、実際に再度開くプロジェクト数を掛け、ロールバックには同じ料金で2回目の再構築が必要になることを忘れないでください。

Kunavoが提供できる2つのスロット

境界を明確にすると、ここでは埋め込みスロットは提供されず、チャットのワイヤ形式を実装するゲートウェイは埋め込みエンドポイントではありません。残るのはメインスロットとユーティリティスロットで、通常のチャットモデルです。現在のカタログ料金では、Claude Sonnet 4.6が入力トークン100万個あたり$2.10、出力トークン100万個あたり$10.50を示し、Claude Haiku 4.5は$0.70と$3.50を示します。

Claude Sonnet 4.6メインスロットで1か月に入力800万トークン、出力40万トークン、Claude Haiku 4.5ユーティリティスロットで入力200万トークン、出力20万トークンを使用すると仮定します。埋め込みスロットはここで提供されず、計算から除外されています。カタログ見積もりは$23.10です。これらは仮定した使用量であり、測定済みのワークロードでも請求額の上限でもありません。Agent ZeroはKunavoのエンドポイントに対して実行時テストされておらず、上記の設定は実行ではなく、プロジェクトのソースとドキュメントを読んで説明したものです。カタログ金額は請求額の下限です。上流サービスが料金を報告すると、請求額はカタログ料金と、適用されるマークアップを掛けた上流料金のうち大きい方になります。最低チャージ額は前払いクレジットの$10で、これはサブスクリプションではなく、資金補充の最低額です。請求の詳細を参照してください。

まだフレームワークを選んでいる場合は、Agent ZeroとOpenClawの比較で実行モデルと3スロット構成を比較しています。エンドポイントの形式については、OpenAI互換リファレンスとクイックスタートでチャットスロットを説明し、Kunavoアカウントの作成で資金を追加できます。検索処理全般については、RAGの実装で、生成プロバイダーと別途購入する検索ステップの同じ分離を説明しています。

よくある質問

2026年9月21日、agent0ai/agent-zero main — memory.py、model_config_set.py、models.py、メモリプラグインのデフォルト値、docsツリー — に加え、v2.12リリース記事、a0-presetsコレクション、リンクされた2つのissue、OpenAIの公開料金を確認しました。このページの内容は何も実行していません。仕組みに関する主張はソースで検証したものであり、実行時テストではありません。また、KunavoにはAgent Zeroの実行記録がありません。Kunavoのトークン料金はライブカタログに基づいています。