开发指南

如何使用 Decisions API：构建类型化 AI 决策的实用指南

学习如何使用 Decisions API，把文本或结构化状态转换为 Choice、Score、Noul 类型化结果，再安全地接入路由、审核和业务动作。

文 / DecisionsApi2026年10月1日13 分钟阅读

title: "如何使用 Decisions API：构建类型化 AI 决策的实用指南" seoTitle: "如何使用 Decisions API：类型化 AI 决策实战指南" slug: "how-to-use-decisions-api" description: "学习如何使用 Decisions API，把文本或结构化状态转换为 Choice、Score、Noul 类型化结果，再安全地接入路由、审核和业务动作。" seoDescription: "Decisions API 使用教程：选择模型、准备 state、定义类型化问题、调用 REST 接口、读取概率，并为生产环境加入安全边界。" image: "https://file.decisionapi.net/uploads/how-to-use-decisions-api/cover.png" imageAlt: "极简手绘草图展示应用状态经过决策 API 转换为结构化结果" ogImage: "https://file.decisionapi.net/uploads/how-to-use-decisions-api/cover.png" ogImageAlt: "一张展示输入如何变成类型化 AI 决策的技术草图" canonical: "https://decisionapi.net/zh/blog/how-to-use-decisions-api" authorName: "DecisionsApi" category: "开发指南" publishedAt: "2026-10-01" locale: "zh" keywords: "how to use decisions api, 如何使用 Decisions API, Decisions API 教程, AI 决策 API, Choice Score Noul, 结构化 AI 决策, 分类 API" toc: auto

如何使用 Decisions API：构建类型化 AI 决策的实用指南

即将上线： OpenAI Decisions API 即将上线。本文使用 DecisionsApi 当前提供的 Jev AI 格式来演示完整工作流；示例用于说明决策 API 的接入方式，不代表 OpenAI 最终正式发布的请求或响应规范。

如果你正在搜索 how to use decisions api，最实用的理解方式是：把完成一个判断所需的最小状态交给决策模型，提出一个或多个边界清晰的问题，再由应用决定如何处理类型化结果。

Decisions API 面向的是软件里的决策，而不是另一个聊天窗口。它通过统一接口连接多个可用的决策模型，包括 Jev、Solar Decide、Kev、Mercury、Tev1 和 Span 系列。你可以向 POST https://decisionapi.net/v1/systemone 发送 model、state 和 questions，让代码接收结构化答案、概率信号、部分问题类型的置信度、usage 和耗时信息。

本文会完整走一遍使用流程：先在 Decisions API Playground 验证想法，再选择问题类型、从服务端调用 API、读取结果，最后加入足够的生产防护。示例使用客服工单场景，但相同方法也适用于请求路由、评分、证据核验、内容审核、模型选择以及 Agent 下一步判断。

Decisions API 能做什么

传统语言模型调用通常返回开放式文本。当产品需要解释、写作、摘要或计划时，这种形式很有价值。但如果程序真正需要的只是 billing、technical 或 manual_review 这样的信号，先生成一段文字再解析就会让链路变得更长。

Decisions API 把这个信号直接表达出来。一次请求可以包含：

State： 提供上下文的文本、JSON 对象或文本数组。
Model： 负责评估状态的当前可用决策模型。
Questions： 一个或多个带名称的问题，每个问题有类型、说明和类型专属的 criteria。

你定义的问题 ID 会原样出现在响应中，因此可以直接把结果接入业务代码，不需要从一段自然语言里猜测答案在哪一句。

最重要的边界是：模型提供判断，应用拥有动作。billing 可以建议把工单放入计费队列，但不能授权退款；较高的 noul 值可以说明某个判断更可能为真，但不能替代数据库核验、权限规则或人工审核。

五步快速开始

学习产品最快的方法，是先选择一个低风险、真实存在的判断：

打开 Playground，选择一个可用模型。
输入包含判断证据的最小状态。
添加 Choice、Score 或 Noul 问题，并写清 criteria。
生成决策，检查类型化结果和概率信号。
创建 API key，把同一个请求从服务端接入产品。

Decisions API 文档是当前模型列表、问题类型、请求字段、响应字段和错误码的参考。模型可用性与价格会变化，因此应该在产品中检查当前列表，而不是在长期运行的代码或文章里永久写死一个模型假设。

第一步：准备 state

State 是请求里每个问题都会读取的上下文。简单消息可以用字符串；需要多个命名字段时使用对象；如果证据天然由多段文本组成，也可以使用文本数组。

客服工作流的对象可以这样写：

{
  "ticket_text": "我的提现已经失败三天，还有两位客户在等待。",
  "account_tier": "business",
  "recent_events": ["payout_failed", "payout_failed", "customer_waiting"]
}

目标不是发送尽可能大的上下文，而是提供一个审慎的人工审核者回答当前问题所需的证据。额外历史会增加噪声、成本、延迟和隐私暴露。删除密钥、访问令牌、无关个人数据，以及不应该被模型评估的内部备注。

好的 state 通常有三个特点：

它和决策有关

如果问题是“哪个队列应该处理这个工单”，就传入能够区分队列的事实。除非账户历史确实属于路由规则，否则不要把整份账户导出数据全部塞进请求。

它可以被检查

使用命名字段更容易复现决策、脱敏敏感值，并理解结果为什么发生变化。如果可审计性重要，可以分别保存原始记录与规范化后的 state 版本。

它足够小，便于测试

先使用紧凑状态和有标签的代表性样本。只有在评估显示模型确实需要时再增加字段，避免上下文不断增长却没有对应的回归测试。

第二步：定义类型化问题

每个问题只问一件具体的事。把“分类、排优先级、决定是否升级”拆成不同问题。当前接口提供三种常用的问题形状。

Choice：从选项中选择一个

Choice 适合分类、路由、过滤和选择 Agent 下一步。criteria 把每个选项映射到描述，让模型和后续审核者对标签有共同理解。

{
  "type": "choice",
  "instructions": "这个工单应该由哪个已批准的团队处理？",
  "criteria": {
    "billing": "扣款、账单、退款或支付失败",
    "technical": "产品缺陷或集成故障",
    "account": "登录、身份或账户安全问题",
    "manual_review": "证据不足，或不符合其他选项"
  }
}

真实世界可能超出预设标签时，应加入兜底选项。强制选择看起来很精确，却可能把陌生案例悄悄分到错误队列。

Score：按照有序标准评分

Score 适合紧急程度、严重性、相关性、完整度等有序指标。criteria 应该从低到高描述可测试的等级。分数不是模糊的“总体质量”，而是一份可以执行的评分标准。

{
  "type": "score",
  "instructions": "这个支持问题有多紧急？",
  "criteria": [
    "常规：没有正在发生的客户影响",
    "较高：客户被阻塞，但有可行的临时方案",
    "紧急：多个客户或关键流程被阻塞"
  ]
}

响应可能根据概率分布得出位于等级之间的加权分数。这对排序和阈值很有帮助，但应用仍应提前定义每个区间对应的业务动作。

Noul：判断一个明确的“是/否”命题

当问题可以写成一个命题时使用 Noul，例如“这条消息是否表达了紧急需求？”或“提供的证据是否足以发布这个结论？”返回值是 0 到 1 之间的数字，表示“是”的概率。

{
  "type": "noul",
  "instructions": "这个工单是否需要立即人工处理？",
  "criteria": {
    "true": "关键流程被阻塞，或影响多个客户",
    "false": "问题常规、孤立，或存在安全的临时方案"
  }
}

不要把多个条件塞进一个 Noul 问题。如果结果同时依赖紧急程度、客户影响和策略授权，可以拆成几个问题，再让业务代码明确组合它们。

第三步：发送请求

在 Playground 中得到有用结果后，把同样的 state 和问题设计迁移到服务端。接口是：

POST https://decisionapi.net/v1/systemone

每次请求都发送 Bearer API key 和 Content-Type: application/json。API key 必须放在服务端环境变量中，不要写进浏览器 JavaScript、公开仓库、客户端 bundle 或可能被记录的 prompt。

下面是一个完整的 curl 示例：

curl -X POST https://decisionapi.net/v1/systemone \
  -H "Authorization: Bearer $DECISIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": {
      "ticket_text": "我的提现已经失败三天。",
      "account_tier": "business"
    },
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "这个工单应该由哪个团队处理？",
        "criteria": {
          "billing": "支付、扣款、退款或提现",
          "technical": "产品或集成故障",
          "account": "账户访问或安全问题",
          "manual_review": "证据不足或互相冲突"
        }
      },
      "needs_attention": {
        "type": "noul",
        "instructions": "这个问题是否需要立即人工处理？"
      }
    }
  }'

这里的模型 ID 代表当前文档中的一个示例。实际接入时，应使用当前可用列表中的 ID，并确认选定模型支持你发送的问题类型。多个问题可以共享同一个 state 并在一次请求中评估，适合同时得到路由和紧急程度信号。

JavaScript 适配层应把解析后的响应当作不可信数据，并在使用前校验答案：

const response = await fetch('https://decisionapi.net/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DECISIONS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(request),
});

if (!response.ok) {
  throw new Error(`Decision request failed: ${response.status}`);
}

const result: unknown = await response.json();
// 读取 answers.department 或执行动作前，先校验 result。

第四步：读取结构化响应

响应会返回选中的模型和 answers 对象，键名就是你发送的问题 ID。通常还会有包含输入/输出 token 数的 usage，以及 elapsedMs 等请求耗时信息。

简化后的响应可能是：

{
  "model": "typesafe/jev-1.13",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.88,
        "technical": 0.08,
        "account": 0.02,
        "manual_review": 0.02
      },
      "confidence": 0.81
    },
    "needs_attention": {
      "type": "noul",
      "noul": 0.76
    }
  },
  "usage": {
    "input_tokens": 296,
    "output_tokens": 38
  }
}

Choice 返回概率最高的选项、所有选项的概率和置信度信号；Score 返回概率加权分数、legend、每个等级的概率和置信度；Noul 返回“是”的概率。这些信号适合用于阈值和审核队列，但不是业务准确率保证。

阈值应该匹配动作风险。低风险标签可以使用较低阈值并抽样审核；退款、锁定账户、删除数据或修改权限通常需要更强证据、确定性校验或人工批准。

第五步：把结果接入业务策略

安全的接入方式通常有两层：

模型判断 → 响应校验 → 确定性业务策略 → 执行动作或人工审核

例如，客服路由器可以这样处理：

const department = result.answers.department;
const needsAttention = result.answers.needs_attention;

if (!allowedDepartments.has(department.choice)) {
  return sendToManualReview('Unknown department');
}

if (needsAttention.noul >= 0.8 && ticket.accountTier === 'business') {
  return escalateToOnCall(department.choice);
}

return routeToQueue(department.choice);

模型不会执行工具、绕过权限检查或直接进行不可逆修改。它只是为一个已经知道允许队列和动作的函数提供判断依据。把决策放进 AI Agent 时，这个分离尤其重要：Agent 可以询问“下一步应该做什么”，但宿主应用仍然控制工具可用性、作用范围、确认、权限和审计日志。

如何选择模型并评估质量

Decisions API 用统一请求形状暴露多个模型，因此你可以比较一个完整工作流，而不必为每个提供方重写集成。模型目录和文档会展示当前可用 ID 与支持的问题类型。当前文档将 Jev 1.13 描述为通用结构化决策模型，而 Span 系列更偏向 Noul 形式的对话行为判断。正式上线前仍要重新确认可用性、性能和价格。

在自动化之前，准备一个小型评估集：

收集清晰、模糊和超出分布的样本。
写下期望答案，以及审核者为什么会这样选择。
用相同问题对候选模型运行测试。
同时测量答案质量、不确定性、延迟和成本。
按业务影响检查误报和漏报。
先以 shadow mode 运行，再允许结果改变生产状态。

不要只因为某个模型平均置信度最高就选它。对高成本案例自信地判断错误，可能比把不确定案例交给人工审核更糟。真正应该衡量的是完整工作流的质量，包括审核量和错误动作的代价。

如果一个应用使用多个问题，要保持问题含义稳定。对问题 ID、instructions、criteria、模型 ID、阈值和策略做版本管理。规则发生变化时，应把它视为新的决策契约，而不是把不同定义下的结果悄悄放在一起比较。

生产环境检查清单

上线 Decisions API 集成前，至少检查：

密钥处理： API key 放入服务端 secret，需要时进行轮换。
输入最小化： 删除凭据、不必要的个人数据和无关上下文。
Schema 校验： 把响应当作 unknown 校验，拒绝缺失、畸形或未知答案。
策略归属： 权限、allowlist、副作用控制和最终动作都留在确定性的业务代码中。
兜底行为： 超时、无效响应、低置信度和未覆盖案例进入安全的人工路径。
重试纪律： 当前文档中 401 表示认证缺失或无效，422 表示请求校验失败，429 表示超过限流，529 表示临时过载。401 和 422 应该修复原因，而不是盲目重试；429 和 529 应使用带上限的指数退避，并确保工作流具备幂等性。
可观测性： 记录请求 ID（如果返回）、模型 ID、问题版本、策略版本、延迟、usage、最终动作和后续人工结果。
持续评估： 保留独立测试集，在 state、问题、模型或阈值变化后重新监测质量。
人工审核： 对高影响、模糊或新型案例保留审核，不要强迫系统给出看似确定的答案。

关于 credits、并发和计划详情，请查看当前的价格与用量页面。共享余额和请求历史可以帮助你把 Playground 实验与 API 使用联系起来，但对于业务结果，仍应以自己的日志为准。

常见问题

Decisions API 是聊天助手吗？

不是。它是把文本或结构化 state 转换为类型化结果的决策接口。产品需要开放式写作、解释或计划时，应使用通用语言模型；应用可以在调用前定义问题和答案形状时，才适合使用 Decisions API。

`state` 可以放什么？

当前文档描述了文本、JSON 对象和文本数组。选择能让证据清晰的形状，只发送问题实际需要的内容。图片、音频和视频不属于当前文档说明的输入范围。

一次请求应该问多个问题吗？

如果问题共享相同 state，并且属于同一个业务流程，可以。一次请求可以同时得到路由、紧急程度或证据信号。每个问题保持窄范围，再由业务代码根据明确策略组合结果。

置信度等于准确率吗？

不等于。置信度和概率是从响应分布中得到的模型信号。应使用有标签样本测量校准度和业务准确率，再根据错误代价和审核团队的处理能力选择阈值。

API 会执行下一步动作吗？

不会。路由、发信、修改数据、调用工具、请求确认和记录审计轨迹仍由你的服务负责。把 API 响应当作业务控制层的输入。

应该从哪里开始？

选一个可逆、低风险的判断，在 Playground 中测试；然后把请求复制到服务端，根据真实样本评估，并在自动执行重要动作前加入审核路径。如果需要的不只是一次 API 调用，而是完整的业务编排，可以继续了解产品的工作流说明。

总结

“how to use decisions api”的实际答案是：定义一个小而清楚的决策契约，提供聚焦的 state，选择匹配任务的问题类型，检查结构化结果，并把最终权限留在应用中。

从产品已经存在的一个判断开始。当答案空间明确、下一步动作也明确时，类型化决策往往比自由文本更容易校验、评估、路由和监控。这正是这个接口的价值：模型提供有用信号，而你的软件继续负责接下来发生什么。

如何使用 Decisions API：构建类型化 AI 决策的实用指南

目录

Decisions API 能做什么

五步快速开始

第一步：准备 state

它和决策有关

它可以被检查

它足够小，便于测试

第二步：定义类型化问题

Choice：从选项中选择一个

Score：按照有序标准评分

Noul：判断一个明确的“是/否”命题

第三步：发送请求

第四步：读取结构化响应

第五步：把结果接入业务策略

如何选择模型并评估质量

生产环境检查清单

常见问题

Decisions API 是聊天助手吗？

state 可以放什么？

一次请求应该问多个问题吗？

置信度等于准确率吗？

API 会执行下一步动作吗？

应该从哪里开始？

总结

`state` 可以放什么？