Agent Zero Model Presets 完全指南：主模型、工具模型与嵌入模型的命名预设管理

Agent Zero Model Presets 完全指南：主模型、工具模型与嵌入模型的命名预设管理

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

Model Presets（模型预设）是 Agent Zero 中"可命名、可复用"的模型组合方案：每一套预设同时包含主模型（Main）、工具模型（Utility）与嵌入模型（Embedding）三个槽位。本文基于 docs/guides/model-presets.md 与_model_config插件的源码实现，完整讲解预设的选择、编辑、添加、全局/项目/Agent 作用域配置，以及预设与 Agent Profile、Project、Skill 等控件的协作关系。读完本文，你将掌握如何用 "fast / cheap / local / balanced / maximum power" 这类语义化标签随时切换整套模型配置，而无需逐个重建参数。

什么是 Model Presets

Model Presets 是 Agent Zero 模型配置的核心抽象。每一套预设固定包含三个模型槽位：

从源码结构看，这三个槽位与运行时配置节chat_model、utility_model、embedding_model一一对应，映射关系定义在 plugins/_model_config/helpers/model_config.py 的PRESET_SLOT_CONFIG_SECTIONS中：

PRESET_SLOT_CONFIG_SECTIONS = { "chat": "chat_model", "utility": "utility_model", "embedding": "embedding_model", }

预设存在的意义在于：当你需要在 "fast"（快速）、"cheap"（省钱）、"local"（本地）、"balanced"（均衡）、"maximum power"（最强性能）等方案之间切换某个聊天时，只需点选一次，不必每次重新填写 provider、模型名、上下文窗口、速率限制等全部参数。

预设的存储形态

• 预设定义是全局的，持久化在用户目录usr/plugins/_model_config/presets.yaml（对应源码PRESETS_FILE = "presets.yaml"与_get_presets_path()的实现，见 plugins/_model_config/helpers/model_config.py）。
• 每个作用域（global、project、agent-profile、chat）的config.json中只保存一个预设名，例如：

{"model_preset": "Balance"}

• 项目级选择存放在/a0/usr/projects/<project>/.a0proj/plugins/_model_config/config.json；Agent Profile 级、全局级同理，都只存名字。
• API Key 永远不会写入预设 YAML，它始终走环境变量 / 设置的密钥流程。预设编辑器里填写的密钥会单独保存（详见下文"编辑预设"）。

Default 预设的特殊地位

Default预设始终存在、永远排在最前、不能被重命名或删除。你可以修改它的模型，但不能删除。这一约束在 plugins/_model_config/helpers/model_config.py 的validate_presets()中强制执行：校验时若找不到名为Default的预设，直接抛出ValueError("The Default preset cannot be deleted or renamed.")，并且校验通过后会把Default强制插回列表首位。此外，Default的每个槽位都必须有真实的模型标识（provider + name），否则校验失败。

选择一个预设

预设菜单位于聊天状态栏左侧的第一个下拉框。关闭态下，它显示预设名 + 主模型的短名称（不带 provider 前缀），例如截图中的 "Max Power" 会显示anthropic/claude-opus-4-6的短名，而不是openrouter/anthropic/claude-opus-4-6全路径。

操作步骤：

1. 打开一个聊天。
2. 点击当前预设名称。
3. 选择你想要的预设。

选择后，该预设只影响当前聊天。如果选择Use scoped preset（使用作用域预设），聊天将回到其项目与 Agent Profile 默认选择的预设；若不存在更具体的配置，Agent Zero 使用全局预设。

从实现角度看，"仅影响当前聊天"是通过聊天上下文中的chat_model_override实现的（源码见 plugins/_model_config/api/model_override.py）：set_preset动作把{"preset_name": "Max Power"}写入当前聊天的chat_model_override并持久化；而clear动作清除该字段，使聊天回退到作用域预设。运行时解析顺序是：聊天级 override → 项目/Agent Profile 作用域 → 全局预设 → Default（见get_effective_config()与get_configured_preset_name()，plugins/_model_config/helpers/model_config.py）。任何作用域引用了一个已被删除的预设名时，会安全地回退到Default。

初始预设：Default、Efficiency 与 Power

当启动时不存在任何已保存的预设集合，Agent Zero 会下载精选的Default、Efficiency、Power三套预设。下载逻辑位于 plugins/_model_config/extensions/python/startup_migration/_20_bootstrap_model_presets.py：

• 若usr/plugins/_model_config/presets.yaml已存在，启动时直接返回，不做任何网络请求（if os.path.exists(presets_path): return "existing"）。
• 否则发起一次有边界的请求（超时 5 秒、文件上限 256 KB，即FETCH_TIMEOUT_SECONDS = 5、MAX_PRESETS_BYTES = 256 * 1024），拉取社区维护的agent0ai/a0-presets仓库中的model_presets.yaml，做整包校验、剥离密钥字段后本地落盘。
• 若 GitHub 不可用、解析失败或校验失败，则改用插件内置的离线回退文件 plugins/_model_config/mode_presets_fallback.yaml 走同一套校验路径保存，保证离线也能完成初始化。
• 已存在的已保存预设会短路整个检查流程，永远不会被覆盖或替换。

回退文件中的三套预设结构如下（节选关键字段）：

- name: Default chat: provider: openrouter name: openai/gpt-5.6-terra ctx_length: 200000 ctx_history: 0.7 vision: true max_embeds: 10 utility: provider: openrouter name: google/gemini-3.1-flash-lite ctx_length: 128000 ctx_input: 0.7 embedding: provider: huggingface name: sentence-transformers/all-MiniLM-L6-v2 - name: Efficiency chat: provider: openrouter name: z-ai/glm-5.2 ctx_length: 128000 vision: false utility: provider: openrouter name: deepseek/deepseek-v4-flash - name: Power chat: provider: openrouter name: openai/gpt-5.6-sol ctx_length: 200000 vision: true utility: provider: openrouter name: openai/gpt-5.6-luna

注意观察Efficiency与Power只声明了部分字段——这正是"预设是部分配置"的设计：非 Default 预设可以省略高级字段或某个模型槽位，省略的值从 Default 继承（详见下文"预设解析与继承"）。

说明：以上模型名以当前仓库内置的 mode_presets_fallback.yaml 为准，实际联网下载的初始预设可能随上游仓库更新而变化；ctx_history/ctx_input表示上下文比例，rl_requests/rl_input/rl_output为速率限制参数，缺省为 0 表示不限。

编辑预设

从预设菜单中点击Edit presets进入编辑器。编辑器界面（plugins/_model_config/webui/main.html 与 plugins/_model_config/webui/preset-overview.html）把每个预设呈现为一套完整配置，支持：

• 重命名预设（Default除外）；
• 选择主模型（Main Model）；
• 选择工具模型（Utility Model，界面文案为 "Faster helper model for summaries and background work"）；
• 选择嵌入模型（Embedding Model，"Creates vectors for memory and knowledge retrieval"）；
• 为每个模型 provider 填写共享 API Key；
• 打开 API Key 设置页；
• 新增或删除预设（Default除外）；
• 保存预设列表。

把预设理解为"贴在模型配置上的一张标签"最贴切：编辑器里看到的是一整套配置，但底层保存的预设文件只含纯净的模型定义，不含任何 UI 元数据与密钥。_clean_preset_for_file()会剥离所有下划线开头的 UI 字段并移除api_key（plugins/_model_config/helpers/model_config.py）。

编辑器底部还提供Restore bundled presets（恢复内置预设）按钮：对应 API 的reset动作（plugins/_model_config/api/model_presets.py），会删除用户自定义预设、回退到内置集合，并把所有引用已删除预设的作用域与聊天引用重写回Default。

预设解析与继承规则

编辑器内部呈现的是"每套预设一个完整配置"，但底层遵循"部分预设 + 继承"模型：

• 非 Default 预设可以省略高级字段或整个槽位，省略的值从Default继承；
• 相反，provider 专属的kwargs在预设中被显式替换或清空，避免不同 provider 之间的参数泄漏（MODEL_SLOT_PRESET_REPLACE_FIELDS = {"kwargs"}，见 plugins/_model_config/helpers/model_config.py）；
• 空槽位占位不会误覆盖上下文 / 速率限制等已调优参数（_should_apply_preset_slot()要求槽位必须有模型标识才生效，plugins/_model_config/helpers/model_config.py）。

重命名 / 删除时的引用修复

重命名或删除预设后，所有引用该预设的作用域配置、以及所有已持久化或已加载聊天的chat_model_override都会被自动重写（_rename_preset_references()，plugins/_model_config/api/model_presets.py）。代码特别处理了"聊天是懒加载的"这一事实：除了更新内存中的AgentContext，还会扫描usr/chats/*/chat.json中未打开的聊天，避免下次加载时静默退回 Default。

添加一个预设

在编辑器点击Add，为它命名、选择模型，然后点击Save即可。新增时默认得到名为 "Preset N" 的空条目，填写模型后保存（见 model-presets-add.png 截图 所示状态）。

好的预设名应当让眼睛在几秒内找到目标，官方建议参考这些命名风格：

• Max Power
• Balanced
• Fast Cheap
• Local Private
• GPT-5 Mini
• Claude Opus
• Kimi Budget

有人按用途命名，有人按最常用的模型命名，两者都可以——关键是"扫一眼就能定位"。命名约束方面，validate_presets()强制：预设名不能为空、大小写不敏感地全局唯一、Default不可改名删除。

一套简单的起始组合

如果不知道从何下手，先创建这三套：

它们可以随时重命名，后续再按需演化出更多组合。

为新聊天选择默认预设

在Settings → Agent → Models中，可以选择新聊天使用的全局预设。摘要区会展示该预设的主 / 工具 / 嵌入三个模型。修改它也会立即把该预设应用到当前打开的聊天。

点击Per-project / agent会打开完整的 Model Configuration 插件（即 plugins/_model_config 插件本体，plugin.yaml声明了per_project_config: true、per_agent_config: true）。其中的作用域选择器（scope selector）允许你为以下作用域指定不同的默认预设：

• 某个项目（project）；
• 某个Agent Profile（agent profile）；
• 或两者的组合（project + profile）。

这些作用域只保存预设名（标准的{"model_preset": "Balance"}JSON 形态）；编辑某个预设会更新所有引用它的作用域。若引用的预设被删除，对应作用域安全回退到Default。

作用域解析优先级（从源码get_config()/plugins.get_plugin_config()的作用域链推断）：组合作用域（project+profile）最具体，其次是单独的项目或 Agent Profile，再次是全局，最后是Default。前端preset-overview.html是 Settings 与插件设置页共享的同一套摘要组件，因此两处看到的预设列表与摘要完全一致。

旧版配置的自动迁移

如果你是从旧版本升级而来，启动迁移脚本 plugins/_model_config/extensions/python/startup_migration/_10_migrate_model_config.py 会自动完成：

• 把旧的全局完整模型配置（chat_model_provider、util_model_name、embed_model_*等LEGACY_FIELDS）转换为Default预设；
• 保留已存在的全局预设；
• 把分散的项目级完整配置与旧项目预设提升为独立命名的全局预设；
• 把所有作用域配置文件重写为"仅含预设名"的 JSON；
• 原文件先备份为.pre-unified-presets.bak再替换，且迁移是幂等的，可安全重复执行。

迁移完成后，运行时只存在"预设"这一层模型配置，不再有独立的持久化模型配置层。

预设如何与其他控件协同

四个维度相互独立、可自由组合。典型场景：同一个 "Researcher" Agent Profile，回答简单问题时挂一个更便宜的预设，做困难调查时换一个更强的预设——角色的行为不变，只有背后的模型组合在变。

运行时层面，预设最终会转化为真实的模型配置。build_chat_model()/build_utility_model()/build_embedding_model()（plugins/_model_config/helpers/model_config.py）读取当前生效配置，通过build_model_config()构造ModelConfig（含 provider、name、api_key、api_base、ctx_length、vision、速率限制与 kwargs），再交给 models.py 的get_chat_model()/get_embedding_model()实例化。切换预设后若嵌入模型发生变化，插件会通过embedding_model_changed扩展钩子通知相关子系统刷新向量库（见_notify_embedding_changed()与save_project_llm_settings()中的call_extensions_async("embedding_model_changed")）。

小结

• 预设 = 三个模型槽位（主 / 工具 / 嵌入）+ 一个名字，全局存储于usr/plugins/_model_config/presets.yaml；
• Default恒在、恒为首、不可删改；非 Default 预设省略的字段从 Default 继承，provider 专属 kwargs 不跨预设泄漏；
• 各作用域只存预设名，聊天可用chat_model_override临时换预设，删除/重命名会自动修复所有引用；
• 首次启动自动初始化 Default / Efficiency / Power，离线时回退到 mode_presets_fallback.yaml；
• 迁移脚本把旧版完整配置无缝升级为统一预设模型，全程幂等、带备份。

想深入源码，建议从 plugins/_model_config/helpers/model_config.py（预设校验 / 解析 / 继承核心）、plugins/_model_config/api/model_presets.py（编辑与引用修复）与 plugins/_model_config/api/model_override.py（聊天级覆盖）三个文件读起，配套测试可参考 tests/test_model_config_project_presets.py、tests/test_model_config_api_keys.py 与 tests/test_model_config_ui.py。

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero