决策模型¶
决策模型 根据评估标准对提供的证据进行评估,并返回类型化答案:选择、分数或布尔概率。将其用于有界判断,例如对请求进行路由、评估其紧急程度或检查其是否满足条件。
decisionModel 是一个具有共享 API 的模型角色。其提供者可以使用不同的模型架构和推理后端。共享接口并不意味着它们的推理能力或概率可以互换。
该角色和 TypeSafe AI 适配器是在已发布的 OpenClaw 2026.9.5 之后添加的。这些说明适用于包含这些功能的开发检出版本,以及包含这些功能的后继版本。宿主要求请参阅每个提供者的设置页面。
| 角色 | 典型工作 | 结果 |
|---|---|---|
| 主模型 | 对话与智能体工作 | 消息和工具调用 |
utilityModel |
简短语言任务,例如标题和摘要 | 生成的文本 |
decisionModel |
分类、评估标准评分和谓词评估 | 类型化答案和概率估计 |
决策模型在 Control UI 中有一个独立的 Decision 选择器。选择会为显式评估和受支持的消费者确定提供者。核心 decision_evaluate 工具遵循该选择以及常规工具策略。选择不会启动后台工作,也不会取代聊天模型。自动实验性消费者还需要显式选择加入 Decision assistance。内置的 OpenClaw 运行时使用该选择加入机制,在有限范围的近期对话中进行会话工具过滤。选定的 Decision 提供者会收到该次级证据;请参阅隐私和回退契约。显式的 decision_evaluate 仍独立于 Labs。
选择提供者和模型¶
在选择其模型之前,请先配置提供者插件:
- ONNX 在持久化子进程中运行本地 CPU 分类器。请遵循其开发检出或兼容包设置,然后显式下载模型或准备本地导出。推理不需要托管 API 凭据。
- TypeSafe AI 连接到托管的 Jev 或本地 System One 服务器(例如 Kev)。安装并启用外部插件,然后配置受保护的托管凭据或显式的回环
baseUrl。托管评估会将选定的证据发送到 TypeSafe,并产生其正常的使用费用。
当前插件声明了以下模型引用:
| 模型引用 | 模型 | 准备 |
|---|---|---|
onnx/deberta-v3-base-zeroshot-v2.0 |
DeBERTa Zero-shot v2 | 下载固定的 ONNX 构件 |
onnx/gliclass-base-v3.0 |
GLiClass Base v3 | 下载固定的 ONNX 构件 |
onnx/gliclass-edge-v3.0 |
GLiClass Edge v3 | 下载固定的 ONNX 构件 |
onnx/gliclass-instruct-base-v1.0 |
GLiClass Instruct Base | 本地导出 |
onnx/gliclass-instruct-edge-v1.0 |
GLiClass Instruct Edge | 本地导出 |
onnx/gliner2.5-base-v1 |
GLiNER 2.5 Base | 下载固定的 ONNX 构件 |
onnx/gliner2.5-small-v1 |
GLiNER 2.5 Small | 下载固定的 ONNX 构件 |
typesafe/jev-1.13.0 |
Jev 1.13.0 | TypeSafe 凭据 |
typesafe/jev-latest |
Jev | TypeSafe 凭据;跟随供应商的最新模型 |
typesafe/kev-latest |
Kev(本地服务器) | 运行中的 System One 服务器和显式回环 URL |
目前这两个插件都是未发布的候选版本。它们的设置页面说明了源代码检出用法与打包宿主的最低要求。该表描述的是插件声明的模型,而不是你的机器上已就绪的构件或凭据。
提供者设置完成后,将角色选择合并到你的配置中:
{
agents: {
ownership: "explicit",
defaults: { decisionModel: "onnx/gliclass-edge-v3.0" },
entries: {
support: { decisionModel: "typesafe/jev-latest" },
quiet: { decisionModel: "" },
},
},
}
未设置的智能体覆盖会继承全局默认值。空的智能体覆盖会为该智能体禁用决策。未设置或为空的全局默认值会关闭该角色。不存在自动回退到对话模型的情况。
如需进行本地设置验证,openclaw onnx models 会列出预设项,openclaw onnx probe gliclass-edge-v3.0 会在模型下载完成后运行 Choice、Score 和 Boolean 冒烟评估。
定义决策¶
每个请求都包含共享的 state 和一个 questions 映射。State 接受文本、JSON 对象或数组,或 null。问题键标识答案;instructions 和 criteria 定义判断方式。评估标准随每个请求一起传递,因此无需单独的评估标准注册步骤。
| 问题类型 | 评估标准 | 答案 |
|---|---|---|
choice |
一个将标签映射到描述的对象 | choice 以及一个具有相同标签的 probabilities 对象 |
score |
评估标准描述的有序数组 | 小数形式的 score 和索引对齐的 probabilities |
| 问题类型 | 标准 | 答案 |
|---|---|---|
boolean |
true 和 false 下的描述 |
probabilityTrue,取值从 0 到 1 |
使用描述性选项和可观察的分数锚点。当目标为 ONNX 时,为布尔问题提供两个描述。让证据聚焦于问题;ONNX 的 Token 预算包括状态、指令和评分标准。
智能体评估工具¶
decision_evaluate 是核心工具。当智能体具有有效的 decisionModel 时,该智能体会收到它,但受正常工具策略、显式拒绝和当前活动 harness 的能力约束。未配置的智能体或具有空按智能体覆盖的智能体不会收到该工具。无论其他实验性消费者是否使用 Decision 模型,该工具都保持可用。提供商插件仍需要它们自己的正常设置。
使用显式共享的 state 和一个 questions 映射来调用它:
{
"state": { "message": "Checkout is failing for all customers." },
"questions": {
"escalate": {
"type": "boolean",
"instructions": "Does this need incident response?",
"criteria": {
"true": { "includes": ["Widespread service outages"] },
"false": "A routine request can follow normal handling"
}
},
"route": {
"type": "choice",
"criteria": { "support": "Service failures", "billing": "Payment questions" }
},
"urgency": {
"type": "score",
"criteria": ["No disruption", "One workflow blocked", "Widespread outage"]
}
}
}
状态、指令和标准描述接受文本、JSON 对象或数组,或 null。每个问题都会看到相同的状态,并且无法看到批次中的其他答案。当一个问题依赖于较早的答案时,请使用后续调用。该工具不会收集环境对话。其受信任的调用智能体绑定会选择提供商和模型;输入无法覆盖该身份或选择。
结果会保留布尔概率、基于零的小数分数、原始分布和舍入、可选的置信度和用量,以及提供商/模型来源信息。它们不会生成解释,也不会授予执行操作的权限。证据会发送到所选提供商配置的端点或本地运行时;仅发送已获授权发送到该目的地的数据。提供商插件负责凭据、模型加载、传输和线路特定验证。
提供商能力与其模型元数据一起声明,并暴露在 models.list.decisionModels 中。不受支持的问题和边界会生成可操作且范围有限的指导。请求会被拒绝,而不是被静默截断或拆分。当已配置的提供商不可用时,不要改用 shell 或 HTTP 调用、在聊天中请求凭据,或将失败视为否定答案。
缺少凭据、速率限制、过载和临时提供商错误会使已配置的工具保持可用,并返回不可用结果。配置更改遵循现有的工具/上下文刷新生命周期;执行时会重新检查有效选择和权限。取消会传播到共享 Decision 运行时,并且不得启动回退工作。
从插件调用¶
从实时工具、钩子或其他自有操作进行调用。此处 api 是插件 API,agentId 标识拥有该工作的智能体,signal 是该操作的取消信号。消费者无需提供商 SDK 或 API 密钥。
const outcome = await api.runtime.decisions.evaluate(
{
state: { message: "Checkout is failing for all customers." },
questions: {
route: {
type: "choice",
instructions: "Which team should handle this?",
criteria: {
support: "Technical problems and service outages",
billing: "Invoices, refunds, and incorrect charges",
sales: "Pricing and purchasing questions",
},
},
urgency: {
type: "score",
instructions: "Assess the operational impact.",
criteria: [
"No service disruption",
"Minor inconvenience with a workaround",
"An important workflow is blocked",
"A widespread production outage",
],
},
escalate: {
type: "boolean",
instructions: "Does this require human incident response?",
criteria: {
true: "A serious service incident needs human attention",
false: "A routine request can follow normal handling",
},
},
},
},
{
agentId,
purpose: "support.triage",
rubricVersion: "1",
timeoutMs: 30000,
signal,
},
);
宿主会根据拥有该工作的智能体的配置选择提供商和模型。purpose 标识消费者操作;rubricVersion 在结果来源信息中标识其评分标准。它们不会替代问题指令。当评分标准的含义发生变化时,请更改评分标准版本。仅在有意使用全局默认选择时省略 agentId。
ok 结果包含 outcome.result.answers,以提交的问题 ID 为键,还包括提供商报告的模型、可选用量以及提供商/评分标准/运行时来源信息。报告的别名(例如 kev-latest)不会标识某个特定已加载的检查点。缺失的用量或置信度会保持缺失。例如,这些是示例答案,而非承诺的模型响应:
{
"route": {
"type": "choice",
"choice": "support",
"probabilities": { "support": 0.97, "billing": 0.02, "sales": 0.01 }
},
"urgency": {
"type": "score",
"score": 2.85,
"probabilities": [0, 0, 0.15, 0.85]
},
"escalate": { "type": "boolean", "probabilityTrue": 0.96 }
}
宿主在返回任何答案之前会验证完整批次。在 TypeScript 中访问特定于类型的字段之前,请先按其 type 对答案进行类型收窄。
解释分数和概率¶
Scores are zero-based rubric positions. The four urgency descriptions above define a scale from 0 to 3, including fractions. A score of 2.85 lies near the highest-impact anchor. A display can rescale that position:
if (outcome.status === "ok") {
const urgency = outcome.result.answers.urgency;
if (urgency?.type === "score") {
const scoreOutOf100 = (100 * urgency.score) / 3;
}
}
The divisor is the last rubric index: criteria.length - 1. The display value
is a position on the scale, not a confidence percentage or probability of being
correct. Rubric wording determines what that scale means.
ONNX normalizes actual label logits with softmax. Choice uses the largest value; Score is the probability-weighted rubric index. TypeSafe preserves Jev's reported label, score, and probability estimates. Rounded vendor probabilities need not sum exactly to one, and its reported score need not equal an expectation computed from those rounded values.
A low Boolean probability favors false; a value near 0.5 gives similar weight to both outcomes. Missing evidence does not guarantee a value near 0.5. Include an explicit insufficient-evidence Choice alternative when that outcome matters. Choice alternatives compete; use separate Boolean questions for independent labels.
Your consumer chooses an action policy, such as escalating when probabilityTrue
is at least 0.9. Validate that threshold on representative examples. Probabilities
and optional provider-specific confidence values are estimates, not demonstrated
accuracy guarantees. An answer does not grant permission to send a message or
perform another effect.
限制与不可用结果¶
对于可移植的评分标准,最多使用 32 个问题、2–64 个 Choice 备选、2–10 个有意义的 Score 锚点、明确的 true/false 描述以及简洁的证据。供应商限制各不相同:
| 供应商 | Choice 备选 | Score 级别 | 其他限制 |
|---|---|---|---|
| ONNX | 2–64 | 2–64 | 最多 32 个问题;每个编码输入 512 tokens;一个 MiB 的已编译批处理输入 |
| TypeSafe AI | 2–255 | 2–10 | 受宿主批处理限制和供应商输入契约约束 |
宿主将请求限制在 1 MiB、20,000 个 JSON 节点、深度 32 和 256 个问题以内。它最多允许每个供应商四个请求,并将每个截止时间上限设为 30 秒。供应商特定限制可能更严格。不支持的输入会被拒绝,而不是被静默截断。
unavailable 结果包含一个原因,例如 disabled、not-configured、unsupported-input、overloaded 或 deadline。消费者决定是跳过、延迟还是使用其现有回退。调用方取消、已关闭的消费者权限以及契约错误都会导致拒绝;不要将取消转换为回退工作。有关完整生命周期和错误行为,请参阅 SDK 契约。
消费者应构建有界且有用的证据,只评估一次,并在供应商返回 unsupported-input(包括上下文溢出)时保持其正常行为。运行时不会估计模型 tokens、截断证据、重试或选择另一个供应商/模型。输入拒绝不会打开供应商熔断器;取消和权限关闭仍然是终态。
decisions 日志记录器记录 DEBUG 结果、分发状态、耗时、问题数量、提供的 JSON 字节数,以及可用时的实际供应商使用情况。JSON 字节不是模型 tokens。用途/供应商/模型标识符会被哈希;现有的环境跟踪关联会被保留。它不记录提交的文本、评分标准、凭据或供应商错误正文,并且在 DEBUG 禁用时不会进行额外的输入序列化。通用的输入拒绝警告会受到速率限制。日志区分供应商结果和调用方副作用,后者在此处保持未观察状态。
对于 ONNX,在较慢的机器上冷加载大型模型可能会超过截止时间。在内存允许时保持活动模型处于热状态,或选择更小的模型。有关缓存设置和活动取消的影响,请参阅 ONNX 生命周期和运行时。如果缺少 TypeSafe 凭据,请遵循其 设置说明。
从插件提供模型¶
供应商插件实现来自 openclaw/plugin-sdk/decisions 的 DecisionProviderV1,并通过 api.registerDecisionProvider(provider) 注册它。其 id 和 contractVersion: 1 标识契约;evaluate(batch, context) 返回经过验证的类型化答案或受支持的不可用原因。上下文包括所选模型、可选的 agent ID、组合的取消信号、单调截止时间,以及一个可选的宿主拥有的 isAdmissible() 谓词,用于自动消费者。外部传输在最终同步 I/O 时、在异步准备完成后检查该谓词;请参阅 供应商契约。
在插件清单中声明供应商所有权和静态模型元数据:
{
"contracts": { "decisionProviders": ["example-decisions"] },
"decisionModels": [{ "provider": "example-decisions", "id": "fast", "name": "Fast decisions" }]
}
此清单片段在独立的决策目录中暴露选择器 example-decisions/fast。消费者对每个供应商使用相同的评估 API。它本身不注册供应商。
供应商负责模型特定的输入转换、传输或本地推理、在需要时准备凭据,以及取消时的物理清理。注册和可选的 isReady() 必须是同步且无网络的;isReady() 检查已准备凭据的可用性,而不是模型预热。返回真实的模型估计值,而不是从仅标签响应中制造确定性。
提供商契约 拥有完整的 SDK 规则;清单参考 拥有发现字段。对于现有集成,请使用 ONNX 或 TypeSafe AI 设置页面。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw