更改 Agent Zero 的嵌入模型，意味着编辑 Model Preset 内的嵌入槽并点击 Save；当该编辑更改 provider 或 model name 时，下次访问会重新为内存建立索引，因为 FAISS 索引的大小取决于单个模型的输出宽度，而磁盘上已有的向量是由旧模型写入的。Agent Zero 自己的安装指南用一行话说明了这一后果——“Changing the embedding_llm will re-index all of A0's memory”——但没有提供流程、持续时间或返回方式。本页面根据源码补足这一空白：自动重建实际会做什么、它悄然不触发的两条路径、如何验证旧内存仍能被召回，以及如何返回。Kunavo 不提供嵌入模型，因此该槽位需要从其他地方购买；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 字段，因此按这种方式编写的操作说明不一定已经过时——但你输入的值最终会落在预设槽位上，这正是下面的传播警告重要的原因。
为什么这不同于切换聊天模型
聊天模型更改会在下一次请求时生效，磁盘上无需移动任何内容。嵌入更改会使存储失效。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。这就是切换会造成的形状变化。
两个范围事实决定了你实际上要购买多少次重建。第一，这是预设编辑，而不是全局编辑：model-presets 指南称范围“store only the preset choice; editing a preset updates every scope that uses it”，因此一次编辑的传播范围可能比你预期更大——在预设之间切换也可能更改嵌入模型。精选的 Efficiency 和 Power 预设自身没有嵌入块，而指南只说现有的非默认预设may从 Default 继承省略的高级值，因此请阅读预设摘要，不要自行假定。第二，project_memory_isolation: true是memory 插件配置中的发布默认值，因此多项目实例会持有多个独立存储，每个存储都会在下次使用时自行重建——一个数周未被触碰的项目，会在有人打开它的当天承担重建成本。
第 1 步：备份，并记下你要离开的设置
Agent Zero 的使用指南已经明确提到这一情况：备份可以保护“你的聊天、项目、知识、内存、设置、技能和工作区文件”，并将“bulk memory cleanup”列为应提前备份的事项。请从 Settings → Backup & Restore 创建备份，或使用Launcher的 Backup of /a0/usr。请注意指南自己的提醒：机密“may not always be included in backup archives”，因此应另外保存凭据。
然后记录你要迁出的模型。不要自行假定——精选预设集合在首次启动时从公共仓库下载，并且可能在你的安装日期之后发生变化。
# 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 并填写 model name，然后点击 Save。该流程没有告诉你的四件事，全部来自main中的源码：
| 陷阱 | 实际发生的情况 |
|---|---|
| 在默认槽位填写 API base URL | 它会被忽略。Provider huggingface与以sentence-transformers/开头的名称会短路进入本地包装器，该包装器不会接触 LiteLLM，只会将参数筛选为本地专用允许列表。要访问托管端点，必须离开这条本地路径——改用其他 provider，或使用不带sentence-transformers/前缀的模型名称。这两者都是 meta 文件会存储的字段，因此任一项都会触发重建。 |
| 先输入端点，再切换 provider | 会丢失。provider 下拉框携带@change="model.api_base = ''; model.kwargs = {}; …"，因此切换 provider 会清除 API base URL 和所有附加参数。请先切换 provider，再填写 Advanced。 |
| 假设兼容 OpenAI 的聊天网关可以正常工作 | 该槽位调用的是 LiteLLM 的embedding()函数，而不是聊天包装器。端点必须实现POST /v1/embeddings。Provider other会重新映射为 LiteLLM 的openai provider，其密钥会以API_KEY_OTHER的形式写入.env。 |
使用localhost连接本地模型服务器 | 在 Docker 内，这指的是 Agent Zero 容器。安装指南建议使用http://host.docker.internal:<port>或桥接网关地址。 |
重建会做什么——以及它不会触发的两条路径
点击 Save 时，model_config_set.py会比较之前和新的嵌入 provider、name 以及 kwargs，任何差异都会以延迟后台任务的形式启动embedding_model_changed；它触发的扩展只做一件事：重新加载内存。下次访问时会再次运行Memory.initialize()，该操作会检查索引旁边的embedding.json。该文件恰好包含两个字段——model_provider和model_name。如果不匹配，代码会使用get_all_docs从旧索引中取出所有文档，在新的宽度下建立新索引，并以相同的 ID 重新插入相同的文档。这条路径有效，并且会保留你的内存。
| 你更改的内容 | meta 文件能发现吗？ | 结果 |
|---|---|---|
| Provider 或 model name | 能——二者都会被存储 | 在新的宽度下读出并重新插入文档。预期路径。 |
仅更改附加参数，例如使用dimensions缩短 OpenAI 向量 | 不能——kwargs 不会被存储 | 内存重新加载，然后原样加载旧索引。宽度不匹配会在召回时出现，而不是在保存时出现。 |
| 仅更改 API base URL，在相同模型名称下指向不同端点 | 不能——保存路径也不会比较它 | 甚至不会安排重新加载；旧索引会继续使用。如果该端点返回不同宽度，召回时会抛出 FAISS 断言。 |
| 手动编辑、截断或从外部恢复的索引文件 | 会先失败于单独的哈希检查 | 旧索引不会被加载，因此其中的文档不会被读出；随后会写入一个新的空索引，同时控制台打印以“index will be rebuilt”结尾的哈希不匹配警告——其中没有任何关于被丢弃文档的信息。缺失或无法读取的哈希文件会被视为有效。 |
第二行和第三行正是问题 #759背后的衔接点。该问题“Errors after changed default Embedding Model”于 2025 年 10 月 13 日创建并已关闭，其回溯显示在内存回忆执行相似度搜索期间出现assert d == self.d；截至 2026 年 9 月 21 日，该衔接点在main中仍然可见。另一个已关闭的问题#1396报告了 Ollama 的/api/embed返回 400，其作者将原因追溯到陈旧索引，并给出了删除index.faiss和index.pkl的解决方法。该方法会破坏存储；应将其视为重置，绝不能视为修复或回滚。两个问题都没有得到维护者评论——#1396 在九十天后由陈旧问题机器人关闭——因此两项诊断都是报告者自己的判断，两项解决方案也都未经验证。
第 3 步：验证旧召回，而不是验证调用成功
该更改产生的失败是悄无声息的，因此“新模型返回了结果”不是正确的验收测试。打开内存控制面板，并按照内存指南的说明，在四个区域——main、fragments、solutions和skills——中进行筛选，搜索一个你知道早于此次更改的内容。每个项目都要做一次，因为每个项目都有自己的存储。然后观察相似度阈值：发布的memory_recall_similarity_threshold为0.7，这是每个插件的默认值，而不是任何模型的属性；新的嵌入模型会重新分布相似度分数。召回质量可能下降，却不会引发任何错误，这就是为什么阈值控制是验证的一部分，而不是细节。
有一件事本页面无法告诉你：重建运行期间 Web UI 是否会显示任何进度或完成信号。它作为延迟后台任务执行，并且尚未确认存在可供查看的界面。请假定不会有确认信号，并手动验证。
回滚，以及重建的成本
没有供应商记录的回滚流程。现有的是备份机制加上上文所述的 meta 文件行为，下面的做法是根据这两者组合出来的，并非项目发布的流程。恢复更改前的备份；或者将槽位恢复为完全相同的旧 provider 和 model name，这会使 meta 文件比较从相反方向失败并触发重建。在同一个容器中，tmp/下的嵌入缓存按 provider 和 model 分区，因此回到以前使用过的模型时，可以复用未改变文本的缓存向量——但tmp/位于文档所述备份之外，因此重新创建容器会丢失这些内容。如果新 provider 在重建过程中途出错，代码会做什么尚未测试，本页也未说明；请从备份恢复，不要依赖这一点。
说到费用：Kunavo 不提供嵌入模型，因此下面的所有金额都由你使用自己的账户直接支付给 OpenAI，价格为截至 2026 年 9 月 21 日核查的已公布费率。请自行估算任务规模——在内存控制面板中统计存储文档数量，乘以文档平均长度，再除以大约每个 token 四个字符。这个除数是约定值，不是测量值。
| 重建目标 | 已公布费率，由 OpenAI 直接计费 | 重新嵌入 3M 个 token | 重新嵌入 30M 个 token |
|---|---|---|---|
text-embedding-3-small（1536 维） | 每 1M 个 token $0.02，由 OpenAI 直接计费 | $0.06 | $0.60 |
text-embedding-3-large（3072 维） | 每 1M 个 token $0.13，由 OpenAI 直接计费 | $0.39 | $3.90 |
text-embedding-ada-002 | 每 1M 个 token $0.10，由 OpenAI 直接计费——比 3-small 更贵，因此今天不是合理的目标 | $0.30 | $3.00 |
| 发布的 CPU 本地模型 | 不按 token 收费；改为消耗你自己机器上的 CPU 时间 | 机器时间 | 机器时间 |
这是基于所述假设的 token 算术，不是实测重建结果，也不是上限。同样，它是按存储计算的：启用项目隔离后，将费用乘以实际会再次打开的项目数量，并记住，回滚意味着按相同费率进行第二次重建。
Kunavo 可以提供的两个槽位
明确来说：这里不提供嵌入槽位，而实现聊天线路格式的网关也不是嵌入端点。剩下的是主槽位和实用槽位，它们都是普通聊天模型。按当前目录费率，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；这里不提供嵌入槽位，已将其排除。目录估算：$23.10。这些是假设的用量，不是实测工作负载，也不是账单上限——Agent Zero 尚未针对 Kunavo 端点进行运行时测试，上述设置来自项目源码和文档的阅读，而非实际执行。目录金额是计费下限：上游报告费用后，账单取目录成本与上游成本乘以适用加价之间的较大值。预付余额的最低充值金额是$10，它是资金最低额度而不是订阅——请参阅计费详情。
如果你仍在选择框架，Agent Zero 与 OpenClaw 对比介绍了执行模型和三槽位布局。关于端点形态本身，OpenAI 兼容参考和快速入门涵盖聊天槽位，而创建 Kunavo 账户用于为其充值。对于更广义的检索工作，RAG 实现介绍了生成 provider 与单独购买的检索步骤之间的相同拆分。
常见问题
如何更改 Agent Zero 中的嵌入模型？
Agent Zero 安装指南记载的流程分为三步：在 Web UI 中打开 Settings 页面，为每个角色（Main Model、Utility Model、Embedding Model）的 LLM 选择提供商并填写模型名称，然后点击 Save。在 v2.x 中，这项修改作用于 Model Preset 的槽位，而不是单一的全局设置，因为每个预设都包含一个主模型、一个辅助模型和一个嵌入模型；模型预设指南提醒，编辑预设会更新使用该预设的每个作用域。安装页面没有提到一个注意事项：更改提供商下拉选项会清除该槽位的 API 基础 URL 和所有附加参数，因此必须在切换提供商之后输入自定义端点，绝不要在切换之前输入。
更改 Agent Zero 嵌入模型会删除我的记忆吗？
按文档所述路径操作不会。Agent Zero 会在索引旁写入一个小型元数据文件 embedding.json，保存嵌入提供商和模型名称。当这些信息不再与配置的模型匹配时，memory.py 会通过 get_all_docs 从旧的 FAISS 索引读取所有文档，根据实时向量长度创建一个新索引，并以相同的 ID 重新插入相同的文档。记忆会被重新嵌入，而不会被丢弃。具有破坏性的是 issue #1396 中针对损坏索引记载的变通办法——删除 index.faiss 和 index.pkl——这会清空记忆，而不是迁移，也不是回滚。
Agent Zero 记忆重建索引需要多长时间？
项目未公布相关数字，其他地方也未找到。v2.12 发布说明中最接近的数字——据报告，中位保存时间从 1,171 毫秒降至 52 毫秒——属于预设编辑场景，当时嵌入比较停止了冗余读取。它衡量的是保存预设，而不是重建索引；不要据此制定预算。重建成本取决于存储中包含的文档数量以及目标模型的响应速度，因此应根据你自己的实例进行估算：在内存控制面板中统计已存储的文档数量，并记住，在已启用项目隔离且使用发布默认设置的情况下，每个项目会在下次打开当天分别承担自己的重建成本，而不是一次性全部发生。
更改嵌入模型后，为什么会出现 FAISS 断言错误？
这是维度不匹配：已存储的索引具有一种宽度，而实时模型返回的是另一种宽度。Agent Zero 仓库中一个已关闭的问题“Errors after changed default Embedding Model”（#759，2025 年 10 月 13 日创建）准确记录了这种情况——内存回忆扩展执行相似度搜索时，向量存储中抛出了 assert d == self.d AssertionError。阅读 main 分支源码后可以看出，产生该问题的机制位于两项检查之间的衔接处：保存路径会在触发重新加载事件之前比较 provider、name 和 kwargs，而磁盘上的 meta 文件只记录 provider 和 name。因此，仅更改 kwargs 会触发重新加载，随后却原样加载旧索引；仅更改 API base 则完全不会参与比较，所以不会安排任何操作，旧索引会继续使用。截至 2026 年 9 月 21 日，该问题中未看到维护者评论，解决方案也未经验证；main 分支中仍可看到这一衔接问题。
可以将 Agent Zero 的嵌入槽指向 Kunavo 吗？
不可以。Kunavo 不提供嵌入模型——/v1/embeddings 路由实现了线路格式，但没有启用的模型提供该端点，因此调用会失败；Kunavo 自己的机器可读文档也明确表示不应将其推荐用于嵌入。这里这一点比通常更重要，因为 Agent Zero 的嵌入槽不会经过聊天包装器：models.py 为其导入的是 LiteLLM 的 embedding() 函数，这是另一套 API 表面，因此兼容 OpenAI 的聊天网关不会自动成为嵌入网关。请直接向提供该服务的供应商购买这一槽位，或继续使用本地 CPU 模型。Kunavo 在 Agent Zero 预设中的角色是主槽位和实用槽位。
如何在 Agent Zero 中回滚嵌入模型更改？
Agent Zero 没有公布回滚流程——文档只提供了一行警告，说明更改会重新为内存建立索引，以及一个通用的 Backup and Restore 机制，二者之间没有其他说明。根据这两部分可以组合出的做法是：恢复你在更改前创建的备份，或者将槽位恢复为完全相同的旧 provider 和 model name，使 meta 文件比较再次从相反方向失败并触发重建。在同一个容器中，tmp/ 下的本地嵌入缓存按 provider 和 model 分区，因此回到以前使用过的模型时，可以复用未改变文本的缓存向量——但 tmp/ 不在文档所述的备份范围内，所以重新创建容器时这部分保存内容会消失。绝不要通过删除索引文件来回滚。
于 2026 年 9 月 21 日根据 agent0ai/agent-zero main进行核查——包括 memory.py、model_config_set.py、models.py、memory 插件默认值和文档树——以及 v2.12 发布文章、a0-presets 集合、两个关联问题和 OpenAI 已公布的定价。本页面没有任何内容经过执行：机制相关说法已通过源码核验，但未经运行时测试，Kunavo 也没有 Agent Zero 的运行记录。Kunavo token 费率来自实时目录。