Agent Zero Model Presets 完全指南主模型、工具模型与嵌入模型的命名预设管理【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zeroModel 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 PresetsModel Presets 是 Agent Zero 模型配置的核心抽象。每一套预设固定包含三个模型槽位槽位字段作用主模型chat承担主要对话与推理任务的主模型也是预设选择器下拉框关闭态显示的短名称来源工具模型utility负责摘要、后台轻量任务等内部工作的较小辅助模型嵌入模型embedding为记忆memory与知识检索knowledge retrieval创建向量的模型从源码结构看这三个槽位与运行时配置节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.jsonAgent 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全路径。操作步骤打开一个聊天。点击当前预设名称。选择你想要的预设。选择后该预设只影响当前聊天。如果选择Use scoped preset使用作用域预设聊天将回到其项目与 Agent Profile 默认选择的预设若不存在更具体的配置Agent Zero 使用全局预设。从实现角度看仅影响当前聊天是通过聊天上下文中的chat_model_override实现的源码见 plugins/_model_config/api/model_override.pyset_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 ModelCreates vectors for memory and knowledge retrieval为每个模型 provider 填写共享 API Key打开 API Key 设置页新增或删除预设Default除外保存预设列表。把预设理解为贴在模型配置上的一张标签最贴切编辑器里看到的是一整套配置但底层保存的预设文件只含纯净的模型定义不含任何 UI 元数据与密钥。_clean_preset_for_file()会剥离所有下划线开头的 UI 字段并移除api_keyplugins/_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 PowerBalancedFast CheapLocal PrivateGPT-5 MiniClaude OpusKimi Budget有人按用途命名有人按最常用的模型命名两者都可以——关键是扫一眼就能定位。命名约束方面validate_presets()强制预设名不能为空、大小写不敏感地全局唯一、Default不可改名删除。一套简单的起始组合如果不知道从何下手先创建这三套预设用途Best艰难任务质量优先于成本或速度Balanced日常聊天、写代码、写作、研究Cheap简单任务、快速草稿、摘要、测试它们可以随时重命名后续再按需演化出更多组合。为新聊天选择默认预设在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 Profileagent profile或两者的组合project profile。这些作用域只保存预设名标准的{model_preset: Balance}JSON 形态编辑某个预设会更新所有引用它的作用域。若引用的预设被删除对应作用域安全回退到Default。作用域解析优先级从源码get_config()/plugins.get_plugin_config()的作用域链推断组合作用域projectprofile最具体其次是单独的项目或 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再替换且迁移是幂等的可安全重复执行。迁移完成后运行时只存在预设这一层模型配置不再有独立的持久化模型配置层。预设如何与其他控件协同控件它改变什么Model Preset该聊天由哪套主 / 工具 / 嵌入模型驱动Agent ProfileAgent 的角色、语气与提示词行为Project工作区、文件、记忆、密钥与项目指令Skill注入到提示词协议中的特定流程四个维度相互独立、可自由组合。典型场景同一个 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.yamlDefault恒在、恒为首、不可删改非 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考