模型清单

模型清单用于管理 Provider、模型实例、默认模型和模型测试结果。进行模型配置前，需要了解下面几个概念：

配置项	说明	示例
Provider	模型服务提供方或接入方式，用于区分不同模型来源	OpenAI Compatible、本地模型网关、第三方模型平台
Base URL	模型服务的 API 访问地址	https://api.example.com/v1、http://127.0.0.1:8001/v1
API Key	调用模型服务所需的鉴权凭据	第三方平台密钥、企业模型网关 Token
模型名称	实际调用的模型标识，需与服务端模型 ID 保持一致	gpt-4.1、qwen2.5-72b-instruct
默认模型	平台上未单独指定模型的会话、Agent、任务和 Workflow 使用的模型	默认会话模型、默认任务模型

模型配置完成后，建议立即进行连接测试，并将稳定可用的模型设置为系统默认模型。这样后续新建会话、运行 Agent 或执行 Workflow 时，平台可以直接使用已验证的模型能力。对于关键 Agent，也可以在 Agent 卡片中单独指定模型，使它不跟随系统默认模型变化。

1. 微步模型平台推荐模型

微步模型平台提供了面向 Flocks 推荐使用的模型 Provider：ThreatBook-cn-llm。该 Provider 中的模型已经按 Flocks 运行场景整理到模型清单中，适合作为默认模型、任务模型或子 Agent 模型使用。

推荐模型包括：

模型 ID	上下文长度	适合场景
minimax-m2.7	197K	长上下文分析、复杂任务、主 Agent 默认模型。
minimax-m2.5	197K	通用任务、长会话、稳定默认模型。
GLM-5	200K	推理、工具调用、综合分析任务。
qwen3.6-plus	991K	超长上下文任务、大批量日志或告警分析。
qwen3-max	252K	高复杂度推理、关键任务、主 Agent 或重要 Workflow。
kimi-k2.6	256K	长文本理解、报告整理、材料归纳。
deepseek-v4-flash	128K	响应速度优先、成本敏感的常规任务。
minimax-m3	128K	子 Agent、轻量任务、日常问答和工具辅助。

使用建议：

• 首次部署 Flocks 时，可以优先从 ThreatBook-cn-llm 中选择一个稳定模型作为系统默认模型。
• 主 Agent Rex 建议选择推理能力更强、上下文更长的模型，例如 minimax-m2.7、GLM-5、qwen3-max 或 qwen3.6-plus。
• 子 Agent 通常可以选择成本更低、响应更快的模型，例如 deepseek-v4-flash 或 minimax-m3。
• 批量告警、日志、资产数据等长输入场景，优先选择上下文长度更大的模型。
• 即使是推荐模型，也建议在设置为默认模型前先点击 测试连接，并用真实任务做一次验证。

2. 添加模型

第一次配置时，按下面顺序走最稳：

1. 打开 WebUI，进入 模型清单。
2. 点击页面右上角的 添加模型供应商，选择对应模型供应商。本地模型通常选择 OpenAI Compatible。
3. 填写 Base URL 和 API Key。
4. 保存 Provider 配置，并关闭 Provider 配置窗口。
5. 点击页面右上角的 添加模型，开始添加具体模型。
6. 填写模型名称，模型名称必须和服务端实际模型 ID 保持一致。
7. 保存后点击 测试连接。
8. 测试通过后，将这个模型设置为默认模型。
9. 新建一个会话，发送一句简单问题，确认 Flocks 能正常回复。

完成以上步骤后，模型才算真正可用。只保存配置但没有测试通过，通常还不能说明系统已经接通。

3. 配置系统默认模型

系统默认模型是 Flocks 的基础模型选择。新建会话、Rex 默认执行、未单独指定模型的 Agent、任务中心和多数 Workflow 节点，都会优先使用这里配置的默认模型。

3.1 在模型清单页设置默认模型

设置步骤：

1. 打开 WebUI，进入 模型清单。
2. 在页面左上角找到 默认模型 卡片。
3. 点击卡片上的编辑按钮。
4. 在弹窗中选择要作为默认模型的 Provider 和模型。
5. 保存后，确认 默认模型 卡片显示新的模型名称。

如果当前默认模型被删除，或者所在 Provider 被删除，系统会自动清除默认模型，需要重新选择。

3.2 默认模型影响哪些地方

默认模型会影响以下场景：

• 新建 WebUI 会话时 Rex 使用的模型。
• 任务中心中新建任务时默认使用的模型。
• 未单独指定模型的 Agent。
• Workflow 中留空 model 的模型推理节点或 Agent 节点。
• IM 通道中新建 Session 时使用的默认模型。

已经在 Agent 卡片里手动指定模型的 Agent，不会因为系统默认模型变化而自动切换。

3.3 什么时候需要调整默认模型

建议在以下情况下调整系统默认模型：

• 首次部署完成，需要选择一个稳定模型作为全局入口。
• 当前默认模型调用失败、延迟过高或成本过高。
• 团队希望统一切换到新的模型 Provider。
• Rex 主会话需要更强上下文、更强推理或更稳定的工具调用能力。

默认模型应优先选择稳定、上下文足够、工具调用表现可靠的模型。成本敏感的子 Agent 可以单独配置更轻量的模型，而不是把系统默认模型整体降级。

4. 为每个 Agent 配置模型

每个 Agent 都可以使用系统默认模型，也可以单独绑定一个具体模型。这个配置在 Agent 智能体 页面完成。

4.1 使用系统默认模型

默认情况下，Agent 的模型选择是"系统默认"。这表示：

• Agent 不在自身配置里固定 Provider / 模型。
• 每次运行时会读取模型清单页当前的系统默认模型。
• 当系统默认模型被修改后，这个 Agent 会自动跟随新的默认模型。

这种方式适合大多数普通 Agent，便于统一维护模型配置。

4.2 为单个 Agent 指定模型

操作步骤：

1. 进入 Agent 智能体 页面。
2. 点击要调整的 Agent 卡片。
3. 在 Agent 详情或编辑面板中找到 模型 字段。
4. 从模型列表中选择具体 Provider / 模型。
5. 按需调整温度等参数。
6. 保存后，在 Agent 卡片或详情中确认模型已经显示为指定模型。
7. 用该 Agent 执行一个小任务，确认调用正常。

手动指定模型后，即使模型清单页的系统默认模型发生变化，这个 Agent 也会继续使用你指定的模型。只有把 Agent 的模型重新改回"系统默认"，它才会继续跟随默认模型。

4.3 什么时候给 Agent 单独指定模型

建议在以下场景为 Agent 单独指定模型：

• 关键 Agent 的效果需要稳定，不希望受系统默认模型调整影响。
• 某个 Agent 执行复杂推理，需要更强模型。
• 某个 Agent 任务量大，希望用成本更低或响应更快的模型。
• 某个 Agent 依赖特定模型的工具调用稳定性。
• 子 Agent 只处理窄领域任务，可以使用 30B 左右的中小型模型降低成本。

模型选择建议：

• Rex 主 Agent 一定需要使用能力最强的模型。优先使用微步模型平台推荐模型；如果是本地自部署模型，建议使用 200B 以上规模的模型。
• 子 Agent 一般可以切换到更小的模型上。根据任务复杂度，可以选择 7B、30B 或 70B 级别模型，在效果、成本和响应速度之间做平衡。

4.4 默认模型和 Agent 指定模型的关系

Agent 模型配置	系统默认模型变化后	适合场景
系统默认	自动跟随新的默认模型	普通 Agent、临时 Agent、希望统一管理的 Agent
指定具体模型	不会变化，继续使用指定模型	关键 Agent、成本优化 Agent、模型能力有特殊要求的 Agent

如果不确定该怎么选，先保持"系统默认"。当发现某个 Agent 的效果、成本、速度或工具调用稳定性需要单独优化时，再为它指定模型。

5. 如何判断配置成功

请同时满足下面几项：

• 模型清单中能看到 Provider 和模型。
• 模型测试连接通过。
• 已设置默认模型。
• 新会话可以正常回复。
• 使用系统默认模型的 Agent 可以正常执行。
• 单独指定模型的 Agent 可以正常执行，并且详情中显示指定模型。

如果新会话无法正常回复，通常需要回到模型名称、上下文长度、API Key 或模型服务连通性继续排查。

6. 本地与第三方模型接入

接入本地模型时，模型服务需要提供 OpenAI Compatible 格式的接口。完成模型服务部署后，在 Flocks 中安装并选择 OpenAI Compatible Provider 进行接入；添加模型时，需要根据实际模型能力填写模型名称和上下文长度。

7. 模型报错排查

排查模型调用异常时，应先定位故障范围，再调整配置。常见故障范围包括 Provider 连接异常、单个模型不可用，以及复杂任务场景下的调用失败。

7.1 先看影响范围

现象	更可能的问题	下一步
所有模型都失败	Provider、网络、鉴权、网关异常	检查 Base URL、API Key、服务状态、网络连通性
同一 Provider 下只有一个模型失败	模型名称、模型下线、权限不足	核对模型 ID，换同 Provider 其他模型对照
测试连接通过，但真实任务失败	上下文、输出长度、工具调用兼容性	用短任务复测，再逐步增加复杂度
上下文长度相关报错	配置的上下文长度超过模型或网关实际支持范围	适当降低模型上下文参数后重新测试
简单问答正常，长会话失败	上下文限制或模型能力不足	换长上下文模型，降低输入长度或输出上限
偶发超时	模型平台负载、网络波动、反向代理超时	查看模型服务日志和代理超时配置

7.2 推荐排查顺序

1. 回到模型清单页，重新点击 测试连接。
2. 如果所有模型都失败，先查 Provider：Base URL、API Key、网络、模型服务状态。
3. 如果只有某个模型失败，先核对模型名称和平台权限。
4. 如果新会话失败，确认系统默认模型是否已经设置，且默认模型仍在可用列表中。
5. 如果只有某个 Agent 失败，检查该 Agent 是否单独指定了不可用模型。
6. 如果测试通过但任务失败，用一句短问题验证会话，再用真实任务验证工具调用。
7. 如果只在复杂任务失败，检查上下文长度、最大输出、模型能力和服务端限流。Flocks 建议将模型上下文长度配置为 128000 Token；如果模型服务不支持该长度，先手动降低上下文参数后再测试。
8. 查看 Flocks 后端日志和模型服务日志，确认具体错误来自哪一层。

7.3 常见错误怎么理解

错误或现象	通常含义	处理建议
401 / 403	API Key 无效或权限不足	重新生成 Key，确认模型权限
404	Base URL 路径不对，或模型名不存在	检查是否缺少 /v1，核对模型 ID
timeout	服务响应慢或网络链路不稳定	降低任务复杂度，检查模型服务负载和代理超时
empty content	模型服务返回内容为空或兼容层异常	换模型对照，查看模型服务日志
peer closed connection	服务端主动断开连接	检查模型服务状态、网关、反向代理配置

7.4 验收建议

模型上线前，建议至少做三类测试：

• 简单会话：确认基础问答能返回。
• 长一点的分析问题：确认上下文和输出能力够用。
• 带工具或业务场景的任务：确认 Flocks 的真实工作流可以跑通。

只有这三类都稳定，才建议把该模型作为团队默认模型长期使用。