變更 Agent Zero 的 embedding 模型，表示要編輯 Model Preset 內的 embedding 欄位並按一下 Save；當該編輯變更 provider 或模型名稱時，下次存取會重新建立記憶索引，因為 FAISS 索引是依單一模型的輸出寬度建立，而磁碟上既有的向量是由舊模型寫入的。 Agent Zero 自己的安裝指南用一行文字說明後果——「變更embedding_llm將重新建立 A0 的所有記憶索引」——但未提供程序、耗時或回復方式。本頁根據原始碼補足這項缺口：自動重建實際執行的內容、它會靜默不觸發的兩條路徑、如何確認舊記憶仍會被找回，以及如何回復。Kunavo 不提供 embedding 模型，因此該欄位需向其他地方購買；Kunavo 可以定價的是主要欄位和工具欄位。
首先要分清兩個版本號。框架目前是 v2.12，依專案自己的發行文章所述，發布於 2026 年 9 月 9 日。README 中最醒目的數字是 A0 Launcher v1.7，它是 agent0ai/a0-launcher 中的獨立桌面安裝程式——將這個版本號當成框架的版本號，會整整差一個主要版本系列。而在 v2.x 中，模型欄位屬於預設組態，而不是平面的全域設定：model-presets 指南表示「每個設定都包含主要模型、輔助模型及嵌入模型」，而 Settings → Agent → Models 是選擇新聊天使用哪個預設組態的位置。請注意，安裝指南仍記載一個「Embedding Model Settings」區段，其中有 Provider 和 Model Name 欄位，因此以這種方式撰寫的操作說明不一定已過時；但您輸入的值會落在預設組態的欄位上，這正是下方關於變更傳播的警告之所以重要的原因。
為什麼這不像切換聊天模型
聊天模型的變更會在下一個請求時生效，磁碟上不需要搬移任何內容。embedding 的變更則會使儲存失效。Agent Zero 依目前模型回傳的內容建立 FAISS 索引大小——位於plugins/_memory/helpers/memory.py中的 faiss.IndexFlatIP(len(embedder.embed_query("example")))——因此寬度是模型的屬性，而不是設定值。隨附的預設值 sentence-transformers/all-MiniLM-L6-v2 會將文字映射至 384 維空間，詳見其模型卡。OpenAI 的embeddings 指南將 text-embedding-3-small 設為 1536，將 text-embedding-3-large 設為 3072。這就是切換模型所造成的形狀變更。
兩項範圍事實決定您實際購買多少次重建。第一，這是 preset 編輯，而不是全域編輯：model-presets 指南表示範圍「只儲存 preset 選擇；編輯 preset 會更新所有使用該 preset 的範圍」，因此一次編輯可能傳播到比您預期更廣的範圍——而在 preset 之間切換也可能變更 embedding 模型。隨附的 Efficiency 和 Power 精選 preset 沒有自己的 embedding 區塊，而指南只說現有的非預設 preset 可能會從 Default 繼承省略的進階值，因此請閱讀 preset 摘要，不要自行假設。第二，project_memory_isolation: true 是memory plugin 設定中的隨附預設值，因此多專案執行個體會持有數個獨立儲存區，而每個儲存區都會在下次使用時自行重建——數週未使用的專案會在有人開啟它的當天支付重建成本。
步驟 1：備份，並記下您要離開的設定
Agent Zero 的使用指南已經明確列出此情況：備份會保護「您的聊天、專案、知識、記憶、設定、技能及工作區檔案」，並將「大量記憶清理」列為事前應備份的事項。請從 Settings → Backup & Restore 建立備份，或使用Launcher的 Backup of /a0/usr。請注意指南自己的提醒：密 secrets「不一定總會包含在備份封存檔中」，因此請另外保存憑證。
接著記錄您要從哪個模型遷移。不要自行假設——精選 preset 集合會在首次啟動時從公開儲存庫下載，並且可能在您安裝後變更。
# 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：進行變更
安裝指南所記載的流程分為三步：在 Web UI 中開啟 Settings，為每個角色選擇 provider 並輸入模型名稱，然後按一下 Save。以下四件事是該流程未告訴您的內容，全部取自main的原始碼：
| 陷阱 | 實際發生的情況 |
|---|---|
| 在預設欄位填入 API base URL | 會被忽略。Provider huggingface 搭配以 sentence-transformers/ 開頭的名稱時，會短路進入本機 wrapper，不會接觸 LiteLLM，並將參數限制為僅限本機的允許清單。若要連至託管端點，必須離開這條本機路徑——改用不同的 provider，或使用不含 sentence-transformers/ 前綴的模型名稱。兩者都是中繼資料檔案會儲存的欄位，因此兩者都會觸發重建。 |
| 先輸入端點，再切換 provider | 會遺失。provider 下拉選單攜帶 @change="model.api_base = ''; model.kwargs = {}; …"，因此變更它會清除 API base URL 和所有其他參數。請先切換 provider，再填寫 Advanced。 |
| 假設 OpenAI 相容的聊天閘道可以運作 | 該欄位呼叫的是 LiteLLM 的 embedding() 函式，而不是 chat wrapper。端點必須實作 POST /v1/embeddings。Provider other 會重新映射至 LiteLLM 的 openai provider，而其金鑰會以 API_KEY_OTHER 的形式寫入 .env。 |
使用 localhost 作為本機模型伺服器 | 在 Docker 內，這代表 Agent Zero 容器。安裝指南會引導您使用 http://host.docker.internal:<port> 或 bridge gateway 位址。 |
重建會做什麼——以及它不會觸發的兩條路徑
按下 Save 時，model_config_set.py會比較先前與新的 embedding provider、名稱以及 kwargs；只要有任何差異，就會以延遲背景工作形式啟動 embedding_model_changed；它觸發的擴充功能只會做一件事：重新載入記憶。下次存取時會重新執行 Memory.initialize()，它會檢查索引旁的 embedding.json。該檔案恰好包含兩個欄位——model_provider 和 model_name。若不相符，程式會使用 get_all_docs 從舊索引取出每份文件，在新寬度下建立全新索引，並以相同 ID 重新插入相同文件。這條路徑可以正常運作，並會保留您的記憶。
| 您變更的內容 | 中繼資料檔案會注意到嗎？ | 結果 |
|---|---|---|
| Provider 或模型名稱 | 會——兩者都會儲存 | 讀出文件，並以新寬度重新插入。這是預期的路徑。 |
僅額外參數，例如使用 dimensions 縮短 OpenAI 向量 | 不會——kwargs 不會儲存 | 記憶重新載入，接著載入未變更的舊索引。寬度不相符會在回憶時顯現，而不是在儲存時顯現。 |
| 僅 API base URL，將相同模型名稱指向不同端點 | 不會——儲存路徑也不會比較它 | 甚至不會排程重新載入；舊索引會繼續使用。如果該端點以不同寬度回應，回憶時會引發 FAISS assertion。 |
| 手動編輯、截短或從外部還原索引檔案 | 會先由另一項雜湊檢查失敗 | 舊索引永遠不會被載入，因此其中的文件也不會被讀出，並會寫入全新的空索引；同時主控台會印出以「index will be rebuilt」結尾的雜湊不相符警告——完全沒有提及被捨棄的文件。遺失或無法讀取的雜湊檔案會被視為有效。 |
第二列和第三列就是issue #759「Errors after changed default Embedding Model」背後的接縫；該 issue 於 2025 年 10 月 13 日開啟並已關閉，其追蹤記錄顯示 memory recall 進行相似度搜尋時出現 assert d == self.d；截至 2026 年 9 月 21 日，該接縫在main中仍然可見。另一個已關閉的 issue #1396 回報 Ollama 的 /api/embed 發生 400，其作者追查原因為過時索引，並提供刪除 index.faiss 和 index.pkl 的處理方式。該處理方式會摧毀儲存區；請將其視為重設，絕不要視為修復或回復。兩個 issue 都沒有得到維護者留言——#1396 在九十天後由過時 issue bot 關閉——因此兩項診斷都是回報者自己的判斷，兩項解決方式也都尚未驗證。
步驟 3：驗證舊記憶是否能找回，而不是只驗證呼叫成功
這項變更造成的失敗很安靜，因此「新模型有回應」是錯誤的驗收測試。開啟記憶儀表板，並依照記憶指南的說明，在四個區域——main、fragments、solutions 和 skills——全部進行篩選，搜尋您知道在變更前就存在的內容。每個專案都要執行一次，因為每個專案都有自己的儲存區。接著觀察相似度閾值：隨附的 memory_recall_similarity_threshold 是 0.7，它是每個 plugin 的預設值，而不是任何模型的屬性；新的 embedding 模型會重新分配相似度分數。即使完全沒有引發錯誤，回憶效果也可能降低，這就是為什麼閾值控制是驗證的一部分，而不是枝微末節。
本頁無法告訴您一件事：Web UI 在重建執行期間是否會顯示任何進度或完成訊號。它會以延遲背景工作執行，目前未確認存在可查看的介面。請假設沒有確認訊號，並手動驗證。
回復，以及重建的成本
沒有供應商記載的回復程序。現有的是備份機制加上上述中繼資料檔案行為，以下途徑是根據兩者組合而成，而非專案發布的程序。還原變更前的備份；或將欄位設回完全相同的先前 provider 和模型名稱，讓中繼資料檔案比較從另一方向判定不相符並進行重建。在同一個容器中，tmp/下的 embedding 快取依 provider 和模型命名空間隔離，因此回到先前使用過的模型時，未變更文字的快取向量可能可以重用；但 tmp/ 不在文件記載的備份範圍內，因此重新建立容器時會遺失。若新 provider 在重建中途發生錯誤，程式會如何處理並未測試，也未在此說明；請從備份進行驗證，不要依賴這種情況。
關於費用：Kunavo 不提供 embedding 模型，因此以下所有金額都會由您使用自己的帳戶直接支付給 OpenAI，採用截至 2026 年 9 月 21 日查核的公布費率。請自行估算工作量——在記憶儀表板中計算儲存的文件數，乘以平均長度，再除以每個 token 約四個字元。這個除數是慣例，不是測量結果。
| 重建目標 | 公布費率，直接向 OpenAI 計費 | 重新建立 3M tokens 的 embedding | 重新建立 30M tokens 的 embedding |
|---|---|---|---|
text-embedding-3-small（1536 維） | 每 1M tokens $0.02，直接向 OpenAI 計費 | $0.06 | $0.60 |
text-embedding-3-large（3072 維） | 每 1M tokens $0.13，直接向 OpenAI 計費 | $0.39 | $3.90 |
text-embedding-ada-002 | 每 1M tokens $0.10，直接向 OpenAI 計費——比 3-small 貴，因此今天不是合理的目標 | $0.30 | $3.00 |
| 隨附的 CPU 本機模型 | 沒有按 token 計費；改為使用您自己機器的 CPU 時間 | 機器時間 | 機器時間 |
這是在所述假設下的 token 算術，不是測量所得的重建成本，也不是上限。同樣，它是每個儲存區的成本：啟用專案隔離時，請乘以實際會再次開啟的專案數，並記住，回復會以相同費率進行第二次重建。
Kunavo 可以提供的兩個欄位
明確說明界線：這裡不提供 embedding 欄位，而實作聊天線路格式的閘道也不是 embeddings 端點。剩下的是主要欄位和工具欄位，它們是一般的聊天模型。依即時目錄費率，Claude Sonnet 4.6列出每百萬個輸入 token 的 $2.10 和每百萬個輸出 token 的 $10.50，而Claude Haiku 4.5列出 $0.70 和 $3.50。
假設一個月在 Claude Sonnet 4.6 主要欄位使用 8M 個輸入 token 和 0.4M 個輸出 token，並在 Claude Haiku 4.5 工具欄位使用 2M 個輸入 token 和 0.2M 個輸出 token；embedding 欄位不在此提供，因此排除在外。目錄估算：$23.10。這些是假設的用量，不是測量所得的工作負載，也不是帳單上限——Agent Zero 尚未針對 Kunavo 的端點進行執行期測試，上述設定是從專案原始碼和文件讀取而來，而非實際執行。目錄金額是計費下限：當上游回報其費用時，帳單金額取目錄成本與上游成本乘以適用加價率兩者中的較高者。最低儲值金額為預付額度 $10，這是資金最低要求，而不是訂閱——請參閱計費詳細資料。
如果您仍在選擇框架，Agent Zero 與 OpenClaw 的比較會比較執行模型和三欄位配置。至於端點格式本身，OpenAI 相容參考資料和快速入門涵蓋聊天欄位，而建立 Kunavo 帳戶可為其儲值。若要更廣泛地處理檢索工作，RAG 實作說明生成供應商與另行購買的檢索步驟之間相同的區分。
常見問題
如何在 Agent Zero 中變更 embedding 模型？
Agent Zero 安裝指南所記載的流程分為三步：在 Web UI 中開啟 Settings 頁面，為每個角色選擇 LLM 的供應商（Main Model、Utility Model、Embedding Model），並輸入模型名稱，然後按一下 Save。在 v2.x 中，這項編輯會套用到 Model Preset 的欄位，而不是扁平的全域設定，因為每個 preset 都包含主要、工具及 embedding 模型；model-presets 指南也警告，編輯 preset 會更新所有使用該 preset 的範圍。有一項安裝頁面未提及的注意事項：變更 provider 下拉選單會清除該欄位的 API base URL 及所有其他參數，因此切換 provider 後再輸入自訂端點，絕不要反過來。
變更 Agent Zero 的 embedding 模型會刪除我的記憶嗎？
依照文件記載的路徑，不會。Agent Zero 會在索引旁寫入一個小型中繼資料檔案 embedding.json，其中保存 embedding provider 和模型名稱。當這些資訊不再符合已設定的模型時，memory.py 會使用 get_all_docs 從舊的 FAISS 索引讀出每份文件，依目前向量長度建立新索引，並以相同 ID 重新插入相同文件。記憶會重新建立 embedding，不會被丟棄。針對損壞索引，issue #1396 中記載的破壞性處理方式是刪除 index.faiss 和 index.pkl；這會清除記憶，而不是執行遷移，也不是回復。
Agent Zero 的記憶重新建立索引需要多久？
專案沒有發布相關數據，在其他地方也找不到。v2.12 發行說明中最接近的數字——回報的儲存中位時間從 1,171 ms 降至 52 ms——屬於 preset 編輯，原因是 embedding 比較不再執行多餘讀取。它測量的是儲存 preset，而不是重新建立索引；請勿用它來編列預算。重建成本取決於儲存中的文件數量，以及目標模型回應的速度，因此請根據自己的執行個體估算：在記憶儀表板中計算儲存的文件數，並記住，在隨附預設值啟用專案隔離時，每個專案會在下次開啟當天各自支付重建成本，而不是一次全部重建。
為什麼我變更 embedding 模型後會收到 FAISS assertion 錯誤？
這是維度不相符：儲存的索引具有一種寬度，而目前模型回傳另一種寬度。Agent Zero 儲存庫中一個已關閉的 issue「Errors after changed default Embedding Model」（#759，於 2025 年 10 月 13 日開啟）記錄了完全相同的情況——在記憶回憶擴充功能進行相似度搜尋時，向量儲存區引發 assert d == self.d AssertionError。閱讀 main 上的原始碼可知，產生此錯誤的機制位於兩項檢查之間的接縫：儲存路徑會在觸發重新載入事件前，比較 provider、name 和 kwargs，而磁碟上的中繼資料檔案只記錄 provider 和 name。因此，僅變更 kwargs 會觸發重新載入，接著載入未變更的舊索引；僅變更 API base 則完全不會進行比較，因此不會排程任何操作，舊索引會繼續使用。截至 2026 年 9 月 21 日，該 issue 中未看到維護者留言，解決方式也尚未驗證；main 中仍可看到這個接縫。
可以將 Agent Zero 的 embedding 欄位指向 Kunavo 嗎？
不可以。Kunavo 不提供 embedding 模型——/v1/embeddings 路由實作了線路格式，但沒有啟用的模型提供該端點，因此呼叫會失敗；Kunavo 自己的機器可讀文件也表示不要將其推薦用於 embeddings。這裡比通常更重要的一點是，Agent Zero 的 embedding 欄位不會經過 chat wrapper：models.py 會為此匯入 LiteLLM 的 embedding() 函式，這是不同的 API 介面，因此 OpenAI 相容的聊天閘道不會自動成為 embeddings 閘道。請直接向提供該服務的供應商購買此欄位，或繼續使用本機 CPU 模型。在 Agent Zero preset 中，Kunavo 所負責的是主要欄位和工具欄位。
如何在 Agent Zero 中回復 embedding 模型變更？
Agent Zero 沒有發布這項操作的回復程序——文件只提供一行警告，說明變更會重新建立記憶索引，另有一般性的 Backup and Restore 機制，除此之外沒有其他說明。根據這兩者可採用的方式是：還原您在變更前建立的備份，或將欄位設回完全相同的先前 provider 和模型名稱，讓中繼資料檔案比較再次從另一方向判定不相符並進行重建。在同一個容器中，tmp/ 下的本機 embedding 快取依 provider 和模型命名空間隔離，因此回到先前使用過的模型時，未變更文字的快取向量可能可以重用；但 tmp/ 不在文件記載的備份範圍內，因此重新建立容器時這些內容會消失。絕不要透過刪除索引檔案來回復。
於 2026 年 9 月 21 日，已對照 agent0ai/agent-zero main——memory.py、model_config_set.py、models.py、memory 外掛預設值與文件樹——以及 v2.12 發布文章、a0-presets 集合、兩個連結的 issue 和 OpenAI 公開定價完成查核。本頁沒有執行任何內容：機制相關說法均已由來源驗證，並非執行期測試；Kunavo 沒有 Agent Zero 的執行紀錄。Kunavo 的 token 費率來自即時目錄。