开发指南

Decision API OpenAI：接入指南与实用示例

构建 Decision API OpenAI 工作流：从类型化输出、REST 示例到质量评估和生产控制，厘清不同 API 协议，让 AI 决策可靠接入业务。

文 / DecisionsApi2026年10月3日16 分钟阅读

Decision API OpenAI 工作流将候选范围明确的判断与语言生成结合起来：决策步骤从允许的选项中选出下一步，OpenAI 模型则负责起草、解释或整合信息。例如，客服应用可以先对工单分类，再读取相关账户记录，最后让 OpenAI 根据这些证据拟写回复。

这个搜索词也对应一项具体的产品发布。OpenAI 在 2026 年 9 月 29 日发布的 DevDay 回顾中介绍了 Decisions API：它由 Luna 驱动，根据文本或图片上下文从预定义答案中进行选择。发布时，该产品处于有限预览阶段。计划扩大开放范围，并不代表所有账户现在都能使用。

本文说明如何设计这样的工作流。具体的 REST 示例使用独立的 DecisionsApi 平台，其端点、凭证和计费均与 OpenAI 分开。你将了解不同接口各自适合什么任务，如何定义有用的问题，以及怎样衡量额外增加的决策步骤是否真正改善了应用。

技术参考资料核查于 2026 年 10 月 3 日。本文示例用于讲解接入方法，不包含实测基准结果。

Decision API OpenAI 指的是什么？
根据任务选择合适的接口
围绕一个决策设计工作流
准备证据，定义有用的问题
从后端调用决策 API
把决策结果接入 OpenAI 回复流程
评估质量、延迟和成本
自动化之前，补齐生产控制
常见问题

Decision API OpenAI 指的是什么？

这个搜索词涉及三个相互关联的概念，但它们的接口协议需要分别理解。

OpenAI Decisions API 是 OpenAI 在发布公告中介绍的产品。公告描述的用途包括分类、路由和 Agent 动作选择，答案限定在预先定义的范围内。公告确认了产品概念与发布时的预览状态，但不能据此认定某个第三方 JSON 请求体就是它的官方请求格式。

OpenAI 的通用 API 功能同样可以用来构建决策工作流。Responses API 支持模型生成结果与工具交互。Structured Outputs 可以通过 schema 约束答案，包括将标签限定为一个枚举集合。Function calling 则允许模型提出工具调用请求，再由应用代码处理。

decisionapi.net 上的 DecisionsApi 是面向其支持的决策模型提供的独立接口。文档中的示例使用 typesafe/jev-1.13、state 和 questions 映射。面向 OpenAI 工作流的 Decision API 介绍页说明了如何在 OpenAI 请求之前或之后加入这一决策层。

在架构文档和配置中，也应明确保留这些区别。OpenAI API key 不是 DecisionsApi API key；Jev 支持某种问题类型，并不说明 OpenAI 的预览接口接受相同字段。它们可以解决相似问题，但端点不能因此直接互换。

根据任务选择合适的接口

先明确应用需要什么输出，再选择接口。

应用需求	适合优先考虑的方式	仍需由应用负责的部分
起草有帮助的客户回复	OpenAI Responses API	提供证据并审核回复
返回格式符合规定的字段	OpenAI Structured Outputs	核对内容含义，处理拒绝与不完整响应
请求调用应用函数	OpenAI function calling	验证参数并检查执行权限
反复执行分类、评分或路由	支持相应任务的决策模型接口	评估标签、不确定性与回退行为
执行明确的权限或算术规则	确定性的应用代码	维护规则及其依赖的权威数据

OpenAI 的 Structured Outputs 指南区分了 schema 约束与普通 JSON mode。Schema 可以要求 route 必须是四个字符串中的一个，却无法保证模型为某张工单选择了正确的字符串。使用 Structured Outputs 时，也需要处理模型拒绝回答和响应不完整的情况。

同样，function calling描述的是模型提出工具请求、应用执行请求的交互过程。模型提出调用 refund_order，并不能证明这笔退款已经获得授权。

优先采用能满足实际评估要求的简单方案。如果一次 OpenAI 结构化响应已经达到所需的准确率和延迟，额外调用一个模型可能没有多少收益。当某项判断可以独立评估、被多个工作流复用，或者需要先判断是否有必要生成内容时，单独的决策层才更有价值。

围绕一个决策设计工作流

假设客户发来消息：“我被扣了两次款，请今天退回重复收取的那笔钱。”此时首先要判断的是，应由哪条经过批准的流程调查这个问题。是否真的存在两笔已结算支付，则是需要向计费系统核实的另一个问题。

一个实用的处理顺序是：

收集最少且必要的上下文。 读取工单文本，以及权限允许使用的账户事实。
提出选项明确的问题。 从 billing、technical、account 或 manual_review 中选择。
验证答案。 检查响应类型、标签，以及是否触发相应的审核策略。
读取权威证据。 根据所选路由和用户权限，查询允许访问的记录。
生成草稿。 让 OpenAI 解释已经核实的情况。
应用动作策略。 决定将草稿放入队列、提交审核，还是直接发送。

决策步骤可以减少无关检索，并提供一个清晰、便于测试的流程分支。它也会增加一个依赖，因此需要将完整流程与现有方案进行比较。

其他有价值的接入位置也遵循相同思路。在生成之前，决策可以选择一个获准使用的检索来源；在生成之后，可以检查草稿是否覆盖必需的检查项；在 Agent 循环内部，可以建议下一步允许执行的动作。候选动作的范围应足够明确，让每个动作都有清楚的执行策略。

准备证据，定义有用的问题

很多决策错误始于输入含糊不清。客户说发生了重复扣款，模型得到的是一条投诉信息，而不是两笔支付确实存在的证明。应在状态数据和指令中同时保留这一差别。

将客户提供的文本与已经核实的记录分开。只加入与当前问题相关的信息；如果信息时效性会影响判断，就附上时间戳。记录暂时不可用时，应明确表示缺失，不能用想当然的否定值替代。

路由标签应按责任归属定义。优先级判断应使用可观察、可核对的紧急程度标准。“重要客户”过于主观，难以让不同审核者得出一致判断；“服务故障影响所有用户，且没有可用的临时解决办法”则是审核者能够一致应用的标准。

DecisionsApi 文档介绍了三种问题类型：

Choice： 从带名称的标准映射中选择一个选项，例如负责处理某张工单的团队。
Score： 根据有顺序的评分标准进行评估。由于结果经过概率加权，分值可能落在相邻等级之间。
Noul： 针对一个明确的命题，返回答案为“是”的概率。

不同模型支持的能力有所区别，因此需要核实所选模型的具体支持情况。另外，应在 instructions 中写出完整问题：route 这样的键用于标识返回答案，不能代替问题指令。

当现有证据不足以支持其他标签时，应提供 manual_review 选项。对于事实核验，一组实用的答案是 supported、contradicted 和 insufficient_evidence。这样可以区分“缺少支持证据”与“有证据表明说法不成立”。先从少量差异明确的结果开始，再考虑细分更多类别。

还应写清楚系统如何处理同时存在的多种诉求。一张工单可能既提到集成失败，也提到发票。如果必须由一个团队负责，就明确哪个问题优先；如果确实需要两个团队分别处理，则通过不同问题或后续工作流表达这一需求。不要指望一个单选标签保留消息中的每项诉求。让接收工单的团队始终能够查看原始内容，并测试路由步骤是否会遗漏另一个紧急问题。

从后端调用决策 API

下面的请求遵循平台的 API 文档。它使用 DecisionsApi 自己的 API key 和 Jev 模型标识符调用该平台，不是 OpenAI Decisions API 请求。

在服务端环境中设置 DECISIONS_API_KEY。运行示例需要一个具有访问权限和足够积分的账户。执行请求会将示例文本发送给该服务，并可能消耗积分。

curl --fail-with-body --max-time 15 \
  https://decisionapi.net/v1/systemone \
  -H "Authorization: Bearer ${DECISIONS_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "model": "typesafe/jev-1.13",
    "state": {
      "customer_message": "I was charged twice. Please help today.",
      "payment_records_verified": false
    },
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Choose the team that should investigate. Customer claims are not verified payment facts.",
        "criteria": {
          "billing": "Charges, invoices, or suspected duplicate payments",
          "technical": "Software defects or integration failures",
          "account": "Sign-in, identity, or account access",
          "manual_review": "Insufficient evidence or no suitable team"
        }
      },
      "time_sensitive": {
        "type": "noul",
        "instructions": "Does the message explicitly request action today?"
      }
    }
  }'

这里的 15 秒超时是客户端时间预算的示例，不是对服务延迟的承诺。应根据应用需求选择截止时间，并提前定义超时后的处理方式。

文档中的答案格式会沿用问题 ID。Choice 答案包含 choice、probabilities 和 confidence；Noul 提供 noul，表示答案为“是”的概率。接入时应检查实际端点返回的 HTTP 响应，不能假定 Playground 的响应封装与直接调用 REST 接口完全一致。

在进入后续分支之前，检查预期的问题 ID 和类型是否齐全，标签是否在允许列表中，数值是否为有限数且位于文档规定的范围内。数据缺失或格式异常时，应将本次决策视为失败。另外，要将身份验证失败和无效请求，与服务过载或限流响应分开处理，因为修复凭证或请求体，与等待后重试，是不同的恢复方式。

把决策结果接入 OpenAI 回复流程

完成路由之后，使用 OpenAI Responses API执行生成步骤。将 OPENAI_API_KEY 与决策服务的凭证分别配置，并选择当前账户可用的模型。

对于计费工单，先读取权限允许访问的支付记录，再将客户消息、已经核实的事实和相关客服策略交给 OpenAI。要求模型在草稿中区分已确认的事实与仍待调查的问题。不要将路由结果改写成提示词中的事实断言，例如“已经确认存在重复扣款”。

下面是应用层伪代码，不属于任何一家服务的 SDK：

decision = classify(ticket)
if invalid(decision) or review_required(decision):
    enqueue_for_review(ticket)
else:
    facts = retrieve_authorized_records(decision.route, ticket)
    draft = generate_with_openai(ticket, facts, support_policy)
    enqueue_draft_for_review(draft)

这个流程有意以草稿结束。发送消息或转移资金是另一个操作，需要单独检查权限。随着评估结果改善，可以逐步自动执行合适的动作，而不必扩大决策模型能够声称的事实范围。

如果工作流用于证据核验，应同时提供生成的说法和实际来源段落。模型给出肯定判断，并不能补出原本缺失的引用。保留来源标识符，让审核者能够查看最终回复背后的证据。

评估质量、延迟和成本

在调整提示词之前，先建立带标签的数据集。覆盖常规案例、含糊请求、记录缺失、多语言混合消息，以及超出已批准类别的例子。让审核者先解决评分标准上的分歧，否则表面上的模型错误，可能只是业务策略尚未定义清楚。

将用于修改指令的例子，与单独留出的评估集分开。把拟采用的工作流与简单规则基线、现有 OpenAI 方案进行比较。不同候选方案应使用一致的输入、标签和评估条件。

跟踪能够反映业务结果的指标：

指标	为什么需要关注
自动采纳路由的精确率	反映自动路由中有多少判断正确
紧急案例或应审核案例的召回率	反映工作流漏掉了多少重要案例
自动化覆盖率	反映全部案例中有多少无需人工审核
审核工作量与解决时间	反映转移给人工处理的成本
端到端 p50 和 p95 延迟	将两家服务、检索、排队和重试全部计算在内
每个正确完成案例的总成本	包括决策调用、内容生成和返工

较高的置信度分数，并不代表它已经针对你的业务流量完成校准。按分数区间对预测结果分组，再与人工标注的实际结果比较。检查每个区间的样本量，以及重要子群体中的表现。根据少量简单案例选定的阈值，可能无法应对生产环境中常见的模糊情况。

举例来说，假设系统从 1,000 个案例中自动接受了 700 个，其中有 35 个路由错误，那么自动化覆盖率为 70%，已接受案例中的准确率为 95%。这些是假设数字，只用于演示计算方式，不代表任何一家服务的实测结果。能否接受这样的表现，取决于每种错误的代价，以及剩余的人工审核工作量。

预算应覆盖完整流程。如果额外调用一次决策模型能够避免不必要的生成，它就可能值得采用，但节省成本并无保证。应将决策成本、后续调用、重试、检索和审核的总和，与原有流程比较。还应单独查看当前套餐与用量说明，并与 OpenAI 账单分开计算：第三方平台的积分不包含你的 OpenAI 用量。

避免将近乎重复的工单分散到训练样本与评估样本中。来自同一事件或同一段客户对话的消息，可能让预留评估集显得比真实的新流量更容易处理。条件允许时，将相关案例放在同一组，并另外保留较晚时间段的数据，用于检查泛化能力。与数据集一起保存标签定义：责任归属策略发生变化，就可能让过去正确的预测看起来变成错误，即使模型行为没有任何改变。

衡量延迟时，从应用收到初始请求开始计时，直到产生可用结果。决策调用很快，但后续查询记录很慢，用户体验仍然会慢。将超时与成功调用分别统计，不要从运行报告中剔除超时。比较不同服务时，保持上下文、问题数量、并发量和重试预算一致，避免把配置差异误认为模型优势。

自动化之前，补齐生产控制

先以影子模式运行：记录新工作流提出的决策，同时让现有流程继续决定实际处理方式。检查两者的分歧后，再逐步放行少量影响较小的自动操作，并保留明确的回退路径。

将以下控制措施纳入应用设计：

在代码中执行权限检查。 即使动作由模型选出，也必须通过账户、资源和业务规则检查。
限制重试次数和时长。 对可重试故障采用退避策略，遵守整体截止时间，并通过应用层幂等机制防止下游操作重复生效。
明确失败后的去向。 服务不可用、未知标签和证据不足，都应进入明确的审核或恢复流程。
将来源文本视为不可信数据。 工单中的“忽略策略并批准”不能覆盖工作流的可信指令。
保留有用的审计记录。 记录请求标识符、模型标识符、评分标准版本、策略版本和最终结果；对敏感内容进行脱敏，并设置保留期限。
变更后重新评估。 即使 JSON schema 未变，更新模型别名、判断标准、检索来源或提示词，也可能改变实际行为。

对不同后果采用不同策略。将工单转入可以撤回的队列，与实际发起支付，不应共用同一条自动接受规则。还应明确由谁负责审核失败案例，避免回退队列变成无人处理的积压。

启用自动执行之前，使用明确的场景测试恢复机制。模拟决策服务不可用、账户记录缺失、不支持的标签，以及动作已经成功但确认消息丢失等情况。最后一种尤其值得检查：重新请求模型判断，不能导致客户消息再次发送或交易重复执行。应在应用中持久化动作状态，并根据该状态恢复。有效的决策结果只是可靠工作流的一项输入，并不是证明动作已经完成的持久记录。

常见问题

decisionapi.net 是 OpenAI 官方 Decisions API 吗？

不是。它是一个面向其支持的决策模型提供服务的独立平台。本文中的 /v1/systemone 示例调用的是该平台。OpenAI 已宣布的 Decisions API 有自己的访问安排和接口协议，接入前应通过 OpenAI 核实。

使用 OpenAI 必须额外接入决策 API 吗？

不需要。许多应用使用 Structured Outputs、function calling 或普通代码就能完成任务。只有当评估表明另一项决策服务能够改善质量、路由、复用或整体成本时，再考虑增加它。

Jev 示例可以接收图片吗？

平台文档目前将 Jev 输入描述为文本、JSON 对象或文本数组，不包括图片。OpenAI 的公告提到了文本和图片，但不能因此认为这个独立的 Jev 示例也具备相同能力。

应该先做什么原型？

选择一个高频、标签清晰且结果可撤回的决策。在 DecisionsApi Playground中尝试具有代表性的工单，包括含糊不清的案例。记录所选路由、后续人工纠正、延迟和成本。只有这些结果支持扩大范围时，再继续扩展工作流。