Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

多模型配置

介绍使用多个模型提供商的常见模式：按代理分发、提示路由、成本分层、本地优先并以托管服务作为备用、非流式提供商回退、速率限制处理以及流式恢复。

参考材料位于提供程序系统的以下位置：

何时使用多模型配置

多模型配置适用于：

  1. 成本分层：低成本模型处理大批量通道；推理模型处理复杂请求
  2. 能力路由：为含图像的通道使用支持视觉的模型，为研究工作流使用推理模型
  3. 本地优先开发：开发时使用本地 Ollama，生产环境使用托管端点
  4. 团队级隔离：不同团队使用不同的智能体，配备不同的 model_providers 和凭据
  5. 非流式速率限制处理：在可重试的 429 后切换到另一个已配置的提供商配置文件

核心理念：按代理分发

每个 [agents.<alias>] 条目都从一个 [providers.models.<type>.<alias>] 开始。该提供商配置可以通过 fallback_models 声明备用模型，并通过 fallback 声明其他提供商配置。完整模式请参阅路由。

要运行多个模型，请运行多个代理，每个代理绑定到一个模型提供方。每个通道一次只能绑定到一个代理。要将通道迁移到其他代理，请编辑应接管该通道的代理上的 channels 列表；Config::validate() 会确保在启动时正确解析这些引用。

跨提供商可靠性

对于非流式调用，ZeroClaw 可以在提供商配置之间遍历有序的回退图。每个回退配置都保留其自身的端点、凭据、模型、请求头、能力覆盖项和嵌套回退声明。运行时会根据错误分类和配置冷却状态进行重试或转至下一个回退配置。

OpenRouter 仍是一等提供商，并可通过一个端点执行供应商选择。它是可选的外部路由层，并非 ZeroClaw 自有回退机制的必需项。

非流式重试和回退

对于网络故障、503 或超时等瞬态错误，非流式调用会使用有界指数退避进行重试，可在 reliability 下进行全局配置（默认值：重试 2 次，初始退避 500 毫秒）。某个条目耗尽重试次数后，可靠包装器会依次尝试配置文件中的 fallback_models 和备用配置文件。

流式恢复边界

流式调用会选择第一个符合条件、未处于冷却状态且支持所需流式能力的条目。流开始后，它不会转到另一个条目。如果流在可见输出到达不可变消费者之前失败，运行时会通过非流式路径重试整个调用，此路径可能遍历回退图。一旦存在可见输出，运行时会保留部分响应，不会重放请求或切换提供商。有关完整契约，请参阅 提供商路由生命周期。

API 密钥轮换限制

不要依赖 reliability.api_keys 实现凭据故障转移。在可重试的速率限制情况下，可靠封装器会选择并记录备用密钥，但 ModelProvider trait 无法将其应用于已构造的提供程序。重试仍使用原始凭据。Issue #9190 跟踪了此限制。

当需要凭据级故障转移时，请使用各自具有独立凭据的提供商配置文件，或使用外部路由服务。

使用 llmfit 选择本地模型

llmfit 可以在你配置 ZeroClaw 之前，根据你的 CPU、内存、GPU 和可用加速器显存帮你筛选合适的模型。这一步是可选的：如果你已经知道要使用哪个模型，可以直接前往提供商配置或快速开始。

1. 评估推理主机上的适配性

请按照 llmfit 上游的说明安装 llmfit，然后在将要提供模型服务的机器上运行 llmfit recommend。如果您想在本地检查或保存评估结果，请使用 llmfit recommend --json。在不同的客户端机器上运行它无法反映推理主机的容量。

对于你的预期工作负载、量化方式和上下文长度，比较各候选方案。量化会降低存储模型权重所用的精度；它会改变内存占用，并可能影响输出质量。需要为上下文、推理运行时、ZeroClaw 以及其他应用预留内存余量。缺失的硬件信息视为未知。适配评分和速度估计只是估算，并非实测性能，也不能证明其在 ZeroClaw 中能可靠地调用工具。

请将评估保留在本地进行。此工作流不需要账户，也不需要上传硬件配置信息或用户内容。在执行模型下载、运行时启动或配置更改之前，请先审阅并明确确认，包括助手协助设置的情况。

2. 将候选项映射到 ZeroClaw 提供方

请在提供商目录中检查是否有受支持的集成。由 llmfit 发现的运行时并不会自动成为受支持的 ZeroClaw 提供商。请确认所选模型及量化版本在该运行时中可用，并使用运行时中确切的模型标识符；目录中的名称可能与 Ollama 标签或服务器的模型 ID 不同。

对于 Ollama，请参考 Ollama 配置示例。下方的 local-small 配置档案 展示了 providers.models.ollama.local 如何通过 model_provider = "ollama.local" 与 agents.local 建立连接，并同时包含风险与运行时配置档案。请将其中的示例模型替换为您已选定并安装的 Ollama 标签。在 Ollama 提供方上将 num_ctx 设置为您计划测试的上下文长度，并同时检查运行时配置档案中的提示词和历史记录限制。示例模型和限制值仅作为起点，不代表硬件建议，也不是针对您机器验证过的配置方案。

对于 llama.cpp 或其他受支持的本地端点，请遵循自定义提供商设置，并使用该运行时的提供商槽位和端点。请参考服务器自身的文档来配置模型和上下文容量。ZeroClaw 的历史记录预算并不会分配服务器的上下文窗口。

验证所选配置

确认设置后，使用 zeroclaw agent -a local 运行已配置的代理（将 local 替换为你的代理别名）。首先检查它能否回答一个简单的提示。然后让它使用一个允许的工具，例如读取其工作区中一个小型、非敏感的文件并总结内容。请保持已配置的审批和工作区限制不变。

检查运行记录中是否存在实际的工具调用、其执行结果，以及使用该结果的助手后续回复。仅有看似合理的答案或打印出的工具调用标记，不能算作通过的工具测试。下方的 local-small 配置会拒绝以文本形式出现的回退调用；在调查某个模型能正常聊天却无法使用工具的问题时，需要考虑这一设置。

在分享经过测试的配方之前，请记录：

  • 测试日期、ZeroClaw 版本或提交哈希以及构建特性、操作系统和硬件。
  • 运行时版本、精确的模型标识符与量化方式，以及可用时的产物摘要（digest）。无法获取的信息标记为未知。
  • 服务器上下文设置以及相关的 ZeroClaw 提供方、风险和运行时配置档案设置，已移除机密信息。
  • If you share a set of real strings and a glossary, I can run them through the same process and flag the ones that need review.
  • 除 llmfit 的估算值外，是否另有实测的延迟或内存占用数据？

此工作流并未建立经过 ZeroClaw 验证的模型列表。针对某一构建版本、模型、量化方式和上下文设置的证据，并不能验证其他组合。如果它暴露出可复现的集成缺口，请报告该具体缺口，并附上已脱敏的复现步骤和观察到的失败现象。

本地开发与托管替代方案

并排运行本地 Ollama 代理和托管服务商代理；将每个通道路由到你希望其使用的代理。

dev 代理从 CLI 运行（无需绑定通道，使用 zeroclaw agent -a dev 即可）。当 Ollama 宕机时，dev 代理会快速失败并显示错误。生产通道不受影响。

本地小型无文本回退配置

小型本地模型通常需要运行时配置文件，而不是特定于提供方的模式。让 Ollama provider 只专注于连接细节，然后使用 [runtime_profiles.<alias>] 来收紧提示词/工具循环行为。ZeroClaw 为直接安装运行时预设的代码路径提供了内置的 local_small 运行时预设。如果你手动编辑配置，请使用这个等效的块：

[providers.models.ollama.local]
uri   = "http://localhost:11434"
model = "qwen2.5-coder:7b"

[agents.local]
model_provider  = "ollama.local"
risk_profile    = "supervised"
runtime_profile = "local_small"

[risk_profiles.supervised]
level                            = "supervised"
workspace_only                   = true
require_approval_for_medium_risk = true
block_high_risk_commands         = true

[runtime_profiles.local_small]
agentic                 = true
compact_context          = true
prompt_injection_mode    = "compact"
strict_tool_parsing      = true
max_tool_iterations      = 4
max_actions_per_hour     = 10
max_cost_per_day_cents   = 100
shell_timeout_secs       = 30
max_delegation_depth     = 1
delegation_timeout_secs  = 60
agentic_timeout_secs     = 120
max_history_messages     = 20
max_context_tokens       = 8000
parallel_tools           = false
max_system_prompt_chars  = 8000
max_tool_result_chars    = 4000
keep_tool_context_turns  = 1
memory_recall_limit      = 3

此配置文件由现有的基本组件组成：

  • compact_context 通过将 agent-loop 和 channel 轮次中每个工作区引导文件限制为 6000 个字符来保持启动上下文精简，该限制在 max_system_prompt_chars 生效之前应用；当文件超过该上限时，zeroclaw doctor 会发出警告。
  • prompt_injection_mode = "compact" 会将技能元数据保留在行内，并在 read_skill 可用时按需加载完整指令；不具备该加载器的提供方则保留现有的完整注入回退方案。
  • 除非提供方返回原生工具调用，否则 strict_tool_parsing 会将形似 XML/JSON 的回退文本视为助手文本。
  • max_tool_iterations、max_system_prompt_chars 和 max_tool_result_chars 用于限制失控循环以及过大的提示词与工具上下文。max_context_tokens 仍是绝对的主动裁剪预算；如需启用基于模型的相对阈值，请显式设置 context_compact_ratio。所有正的有效阈值都受所选模型配置的上下文容量上限约束；max_context_tokens = 0 仍是禁用主动裁剪的哨兵值。
  • max_actions_per_hour、max_cost_per_day_cents 以及超时/委托字段使本地运行保持与内置预设相同的预算结构。
  • parallel_tools = false 和 keep_tool_context_turns = 1 会使本地运行保持串行，并限制保留的工具上下文。

使用 Ollama 时，这是一个无文本回退配置文件：已授权的工具仍在 risk_profile 中配置，但模型的文本形式工具标记不会被执行。可将其用于聊天优先的本地智能体，或用于返回原生/结构化工具调用的提供商。如果本地模型必须使用 ZeroClaw 的文本回退工具语法，请设置 strict_tool_parsing = false 并保留其他小模型限制。

成本分级：需要时使用重型模型，其他情况使用快速模型

运行两个代理并将通道路由到合适的层级。delegate 工具允许一个代理在对话过程中将任务移交给另一个代理。委派受到限制：调用方的风险配置文件必须设置 delegation_policy mode = "allow"，并且目标必须可从调用方访问（同一配置文件的对等方，或调用方 delegates 列表中的显式条目）。下面的前线代理和重型代理运行在 相同 的 trusted 风险配置文件上，因此它们作为同一配置文件的对等方相互访问；它们在模型和运行时配置文件（迭代预算）上有所不同，而非信任面。

前线智能体使用 Haiku 处理每一条入站消息。当需要更深入的推理时，它会调用 delegate 工具并设置 agent = "heavy"；由于两个智能体共享 trusted 风险配置，且该配置允许委派，因此更重量级的智能体将使用 Opus 接管该子任务。

非流式错误处理

非流式调用的可重试失败包括：

  1. 超时：提供程序未在配置的超时时间内响应
  2. 连接错误：网络或 DNS 故障
  3. 速率限制 (429)：将提供商配置文件置于临时的内存冷却状态，并在存在其他条目时继续处理
  4. 服务不可用 (503)：临时性服务问题

重试不会由以下情况触发：

  1. 无效请求 (400)：输入格式有误；重试无济于事
  2. 永久身份验证失败：API 密钥格式无效
  3. 模型输出错误：模型已响应，但返回了错误负载

当所有已实例化的条目都已耗尽或处于冷却状态时，失败会连同收集到的尝试失败信息一起传递到调用通道。

调试

持久化日志（"rolling" 为默认值）会记录重试、冷却和回退行为。然后查询跟踪信息：

sh

zeroclaw doctor traces --contains 重试
zeroclaw doctor traces --contains "429"
zeroclaw doctor traces --contains "model_provider"

最佳实践

  1. 每个路由意图对应一个 agent。 如果两个渠道需要不同的模型行为，请命名两个 agent。
  2. 为回退配置文件明确归属。 将每个端点、凭据、模型和能力覆盖项保留在为其提供服务的配置文件中。
  3. 将 OpenRouter 作为可选的路由层。 当服务端的供应商选择有用时使用它；当应由运行时控制顺序时，使用 ZeroClaw 回退配置文件。
  4. 不要依赖 reliability.api_keys。在 问题 #9190 修复之前，请使用单独构建的配置文件。
  5. 单独对每个 agent 进行冒烟测试。 zeroclaw agent -a <alias> 可在不受通道连接干扰的情况下运行 agent。
  6. 记录代理意图。 添加 # comment 行，说明每个代理服务于哪些通道以及原因。
  7. 通过 env 注入密钥，而非内联。 ZEROCLAW_providers__models__<type>__<alias>__api_key=... 会在启动时设置 api_key；参见环境变量。
  8. 分离开发和生产代理。 每个环境都有各自的 [agents.<alias>] 条目，并绑定到各自的通道。

凭证解析

每个提供商条目按以下顺序解析凭据：

  1. 内联 api_key（在 provider 条目中）。
  2. ~/.zeroclaw/secrets 中的密钥存储。
  3. 通用环境变量覆盖：在启动时设置 ZEROCLAW_providers__models__<type>__<alias>__api_key=...。如果您的 shell 已导出 ANTHROPIC_API_KEY、OPENROUTER_API_KEY 或类似的供应商默认名称，请在启动前将其桥接到此 schema-mirror 变量，除非该提供商系列明确记录了原生运行时环境桥接。有关完整语法和桥接示例，请参阅环境变量。

凭据不会在提供商配置之间共享；请为每个配置分别设置。路由级别的 model_routes[].api_key 是在构建其路由目标时优先级更高的覆盖项。路由目标按 model_provider 去重，因此第一个匹配的路由凭据可以构建由多个提示共同使用的提供商。路由共享目标时，优先使用配置自有的凭据。

相关文档