# 决策评估（beta） > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 决策评估可通过 System One API 将文本、图片、视频或音频等输入转换为业务可直接使用的结构化判断结果，适用于内容分类、请求路由、风险评估和优先级判断等场景。它可以返回某个条件为真的概率、从固定选项集合中选择某个选项的结果和概率，或者根据评分标准给出分数。 > **注意** > > System One API 当前处于 beta 测试阶段。调用该接口时，必须在 HTTP 请求头中传入 `ark-beta-systemone-api: true`。 ## 支持模型与 API - 支持模型： 请参见[决策评估能力（beta）](/docs/model-list#f2b7c91d)。 - 支持 API： [System One API（beta）](/docs/system-one-api) ## 工作方式 System One API 通过 `state` 和 `questions` 描述一次决策评估任务，并在响应的 `answers` 中返回结构化判断结果。 请求包含以下部分： | 参数 | 说明 | | --- | --- | | `model` | 执行本次评估的模型 ID 或推理接入点 ID。 | | `state` | 待评估内容，可以是文本、结构化 JSON 或多模态对象数组。 | | `questions` | 评估问题集合。每个问题用于定义一个判断维度，包括问题类型、判断目标和判定标准。 | 响应中的 `answers` 会按问题 ID 返回结果，不同问题类型的典型场景及对应结果如下： | 问题类型 | 典型场景 | 主要结果 | | --- | --- | --- | | `noul` | 是非判断 | 返回 `[0, 1]` 区间内的概率值，表示结果符合 `criteria.true` 的概率。 | | `choice` | 分类选择 | 返回概率最高的选项作为命中结果，并返回各选项的概率。 | | `score` | 评分判断 | 返回档位编号的概率加权值，并返回各档位的概率。 | ## 典型场景 以下示例展示决策评估在分类选择、是非判断和评分判断场景中的请求与响应。 ### 分类选择 分类选择可使用 `choice`。例如在工单路由场景中，可将处理团队写入 `criteria`，并增加 `其他` 或 `信息不足` 兜底选项。 请求示例如下： ```Bash curl "https://ark.cn-beijing.volces.com/api/v1/systemone" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "ark-beta-systemone-api: true" \ -d '{ "model": "doubao-seed-2-1-lite-260915", "state": { "ticket_id": "ticket-001", "customer_message": "我收到的杯子有裂纹，申请退款，不接受换货。", "order": { "order_id": "order-104", "product": "陶瓷杯", "payment_status": "paid" } }, "questions": { "routing_team_v1": { "type": "choice", "instructions": "根据客户反馈的主要问题选择优先处理团队。", "criteria": { "财务": "扣款、发票或退款到账问题", "质量": "商品损坏、质量缺陷或与描述不符", "物流": "配送延迟、丢件或物流状态问题", "信息不足": "缺少判断主要问题所需的信息" } } } }' ``` 响应示例如下： ``` { "model": "doubao-seed-2-1-lite-260915", "answers": { "routing_team_v1": { "type": "choice", "choice": "质量", "confidence": 0.91, "probabilities": { "财务": 0.04, "质量": 0.91, "物流": 0.02, "信息不足": 0.03 } } }, "usage": { "input_tokens": 183, "output_tokens": 32 } } ``` ### 是非判断 是非判断可使用 `noul`。例如判断是否需要转人工时，可用 `criteria.true` 和 `criteria.false` 明确自动转人工的边界，并在业务代码中设置上下阈值。 请求示例如下： ```Bash curl "https://ark.cn-beijing.volces.com/api/v1/systemone" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "ark-beta-systemone-api: true" \ -d '{ "model": "doubao-seed-2-1-lite-260915", "state": { "ticket_id": "ticket-002", "customer_message": "已经联系三次还没解决，请马上安排人工处理，否则我要投诉。", "order": { "order_id": "order-205", "product": "蓝牙耳机", "payment_status": "paid" } }, "questions": { "needs_human_support_v1": { "type": "noul", "instructions": "该工单是否需要转人工处理？", "criteria": { "true": "存在退款、投诉、风险、证据不充分或客户明确要求人工介入", "false": "问题清晰、风险较低，且可由自动化流程处理" } } } }' ``` 响应示例如下： ``` { "model": "doubao-seed-2-1-lite-260915", "answers": { "needs_human_support_v1": { "type": "noul", "noul": 0.94 } }, "usage": { "input_tokens": 169, "output_tokens": 18 } } ``` ### 评分判断 评分判断可使用 `score`。例如评估风险等级时，`criteria` 应描述同一风险维度下从低到高的档位，不要把多个维度混在一道题中。 请求示例如下： ```Bash curl "https://ark.cn-beijing.volces.com/api/v1/systemone" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "ark-beta-systemone-api: true" \ -d '{ "model": "doubao-seed-2-1-lite-260915", "state": { "ticket_id": "ticket-003", "customer_message": "退款金额一直不到账，我已经准备向监管平台投诉。", "order": { "order_id": "order-309", "refund_status": "processing", "refund_amount": 299 } }, "questions": { "risk_level_v1": { "type": "score", "instructions": "该工单的处理风险等级是多少？", "criteria": [ "风险较低，不涉及资金、合规或客户投诉", "存在一定风险，需要补充材料或人工确认", "风险较高，涉及资金损失、投诉升级或合规问题" ] } } }' ``` 响应示例如下： ``` { "model": "doubao-seed-2-1-lite-260915", "answers": { "risk_level_v1": { "type": "score", "score": 1.82, "confidence": 0.88, "legend": { "0": "风险较低，不涉及资金、合规或客户投诉", "1": "存在一定风险，需要补充材料或人工确认", "2": "风险较高，涉及资金损失、投诉升级或合规问题" }, "probabilities": { "0": 0.03, "1": 0.12, "2": 0.85 } } }, "usage": { "input_tokens": 178, "output_tokens": 63 } } ``` ## 评估流程 使用 System One API 进行决策评估时，可按以下步骤设计请求。 ### 步骤一：设置被评估内容 将需要评估的业务内容放入 `state`。`state` 应包含完成判断所需的事实、证据、业务对象和上下文信息，避免把判定规则混入被评估内容中。 ### 步骤二：设置评估问题和判定标准 在 `questions` 中传入评估问题，并设置以下字段： - `type`：设置问题类型，可选值为 `noul`、`choice` 或 `score`。 - `instructions`：说明判断目标。 - `criteria`：补充判定边界、候选选项或评分档位。简单场景可以只设置 `instructions`；需要更稳定的业务判断时，建议补充 `criteria`。 以下示例使用 `noul` 判断客户是否明确要求退款。 请求示例如下： ```Bash curl "https://ark.cn-beijing.volces.com/api/v1/systemone" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "ark-beta-systemone-api: true" \ -d '{ "model": "doubao-seed-2-1-lite-260915", "state": { "工单": { "客户反馈": "收到的杯子裂了，请退回货款，我不接受换货。" }, "订单": { "订单号": "订单-104" } }, "questions": { "refund_requested_v1": { "type": "noul", "instructions": "客户是否明确要求退回已支付的款项？" } } }' ``` ### 步骤三：处理评估结果 读取响应中对应问题 ID 的结果，并根据业务自定义阈值或策略执行后续动作。 对于 `noul` 类型问题，返回值为 `[0, 1]` 区间内的概率值。业务代码可以根据该概率值和自定义阈值判断是否执行“是”分支、进入“否”分支或转人工复核。 响应示例如下： ``` { "model": "doubao-seed-2-1-lite-260915", "answers": { "refund_requested_v1": { "type": "noul", "noul": 0.96 } }, "usage": { "input_tokens": 128, "output_tokens": 16 } } ``` ## 进阶使用 ### 多模态输入 当 `state` 同时包含文本、图片、视频或音频时，可传入多模态对象数组，并在 `instructions` 中说明每种材料的作用，区分“用户主张”和“材料证据”，避免模型仅凭文字描述替代证据判断。 多模态内容支持以下传入方式： - 本地文件上传： - [Files API 上传](/docs/upload-files-api)（推荐）：适用于文件较大，或需要在多个请求中复用同一文件的场景。文件上传并变为可用后，可在 System One API 请求中引用该文件。 - Base64 输入：适用于文件体积较小、无需复用文件的场景。 - 公网 URL 输入：适用于文件已存在公网可访问 URL 的场景。 > **说明** > > - 多模态内容的文件格式、大小、尺寸、数量、时长及 Files API 上传限制，详见[图片理解](/docs/image-understanding)、[视频理解](/docs/video-understanding)、[音频理解](/docs/audio-understanding)和[文件输入(Files API)](/docs/file-api)。 > - 同一图片、视频或音频需要在多次评估请求中复用时，建议在 `state` 中通过 `file_id` 引用素材。对同一个媒体元素，不要同时传入 `file_id`、公网 URL 或 Base64。 > - 多模态输入会增加请求处理时间；如需保持较低响应延迟，建议仅传入完成判断所需的图片、视频或音频内容。 以下示例展示通过 `file_id`、公网 URL 和 Base64 传入多模态内容的方式。 ```Bash BASE64_AUDIO=$(base64 < /Users/doc/demo.mp3) && curl "https://ark.cn-beijing.volces.com/api/v1/systemone" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "ark-beta-systemone-api: true" \ -d @- <", "detail": "high" }, { "type": "video", "video_url": "https://example.com/unboxing-video.mp4", "fps": 1 }, { "type": "audio", "audio_url": "data:audio/mpeg;base64,$BASE64_AUDIO" } ], "questions": { "package_damaged_on_arrival_v1": { "type": "noul", "instructions": "图片、视频和音频证据是否支持商品到货时已破损？文本只提供客户主张，不能仅凭客户文字认定到货即破损。", "criteria": { "true": "图片或视频中可见商品破损，且音频或视频内容能够辅助确认破损发生在到货或开箱阶段", "false": "多模态材料无法确认商品到货时已破损，或关键证据不清晰、不连续" } } } } EOF ``` ### 同一请求传入多个问题 如果需要基于同一份 `state` 完成多个相互独立的判断，可在同一次请求的 `questions` 中传入多道问题。每个问题只对应一个判断维度；如果某个问题依赖另一道问题的答案，建议拆分为多次请求。 > **说明** > > 为保持较低响应延迟，建议控制单次请求中的 `questions` 数量；问题数量较多时，可拆分为多次请求。 以下示例使用同一份工单内容，同时判断客户是否要求退款、选择优先处理团队，并评估客户不满程度。 ```Bash curl "https://ark.cn-beijing.volces.com/api/v1/systemone" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "ark-beta-systemone-api: true" \ -d '{ "model": "doubao-seed-2-1-lite-260915", "state": { "工单": { "客户反馈": "收到的杯子裂了，请退回货款，我不接受换货。" }, "订单": { "订单号": "订单-104" } }, "questions": { "refund_requested_v1": { "type": "noul", "instructions": "客户是否明确要求退回已支付的款项？" }, "routing_team_v1": { "type": "choice", "instructions": "根据客户反馈的主要问题选择优先处理团队。", "criteria": { "财务": "扣款、发票或退款到账问题", "质量": "商品损坏、质量缺陷或与描述不符", "物流": "配送延迟、丢件或物流状态问题", "信息不足": "缺少判断主要问题所需的信息" } }, "dissatisfaction_level_v1": { "type": "score", "instructions": "客户在反馈中表达的不满程度如何？", "criteria": [ "平静陈述事实，没有表达不满", "明确表达不满，但措辞克制", "强烈愤怒，使用激烈措辞或威胁投诉" ] } } }' ``` ### 组合使用评估结果 业务代码不应只读取最高概率结果，还应结合 `probabilities`、`confidence` 和自定义阈值执行后续动作。 响应示例如下： ``` { "model": "doubao-seed-2-1-lite-260915", "answers": { "refund_requested_v1": { "type": "noul", "noul": 0.96 }, "routing_team_v1": { "type": "choice", "choice": "质量", "confidence": 0.91, "probabilities": { "财务": 0.04, "质量": 0.91, "物流": 0.02, "信息不足": 0.03 } }, "dissatisfaction_level_v1": { "type": "score", "score": 1.82, "confidence": 0.88, "probabilities": { "0": 0.03, "1": 0.12, "2": 0.85 } } }, "usage": { "input_tokens": 245, "output_tokens": 75 } } ``` 业务代码可先分别读取每个问题的结果，再结合业务策略形成最终处理动作。不同类型结果可参考以下方式使用： | 结果类型 | 示例结果 | 结果使用方式 | | --- | --- | --- | | `noul` 是非判断 | `refund_requested_v1.noul` 为 `0.96`。 | 高于业务定义的“是”阈值时，可执行“是”分支；低于“否”阈值时，可执行“否”分支；介于两个阈值之间时进入人工复核。 | | `choice` 分类 | `routing_team_v1.choice` 为 `质量`，`confidence` 为 `0.91`。 | 当目标选项概率和 `confidence` 均高于业务阈值时，可按该分类路由；`confidence` 低或兜底选项概率高时进入人工复核。 | | `score` 打分 | `dissatisfaction_level_v1.score` 为 `1.82`。 | 可根据加权 `score` 所处的业务区间执行后续动作；最高两个档位概率接近时保留人工判断。 | 例如，当 `refund_requested_v1.noul` 高于业务定义的“是”阈值，且 `routing_team_v1.choice` 为 `质量` 时，可将工单路由到质量团队；如果任一结果置信度不足，可进入人工复核。 ## 计费说明 决策评估按照所选模型的输入、输出 token 计费。单次请求中的 `state` 和 `questions` 会计入输入 token，模型返回的 `answers` 会计入输出 token。 具体价格请参见[模型价格](/docs/model-pricing)。 ## 使用限制与注意事项 - System One API 返回结构化判断结果，不用于生成面向用户的自然语言回复；如需生成客服话术、摘要、解释或完整报告，建议使用 [Chat API](/docs/chat-api) 或 [Responses API](/docs/create-model-responses-api)。 - System One API 当前支持最大 128k 上下文窗口，单次请求中的 `state` 和 `questions` 共同占用上下文窗口。 - 使用 `choice` 时，建议在 `criteria` 中设置 `其他`、`信息不足` 或 `无法判断` 等兜底选项，避免证据不足时被迫命中业务分类。 - 使用 `score` 时，每道问题应只评估一个有序维度；不同问题的档位数量或档位含义不一致时，`score` 不应直接横向比较。 - 批量评估、实时高并发评估或周期性任务中，建议控制请求并发；遇到限流或服务繁忙类错误时，使用指数退避重试。