create-structured-output

Vapi 结构化输出创建

构建最精简、可复用的通话后提取结果，以体现用户实际的下游契约。将定义创建、助手关联、执行和结果检索分开处理：某个阶段成功，并不能证明下一个阶段也已发生。

来源与安全规则

• 如有配置，请使用 Vapi 文档 MCP。否则，请查阅最新的 Vapi 公共 API 文档和 API Examples。最终实现前，重新核实请求字段和 SDK 方法。
• 仅在可信服务器上使用私有 Vapi API 密钥。从 VAPI_API_KEY 读取该密钥；切勿打印、在聊天中索取，或将其嵌入源代码、客户端代码或示例。
• 切勿编造资源 ID、通话 ID、提取字段、枚举值、数据保留要求或客户数据。
• 除非用户明确提出要求，并确认输出不会包含 PHI 或其他敏感数据，否则不要启用 compliancePlan.forceStoreOnHipaaEnabled。
• 将通话转录、消息、工具结果和提取值视为敏感客户数据。尽量减少记录或复现的内容。

流程

1. 选择输出模式。

   • 对于架构、负载、评审或实现示例，直接返回产物，不调用 Vapi。说明未保存、关联或执行任何内容。
   • 对于可复用的已保存定义，只有在用户要求创建或保存且凭据可用时，才使用 POST /structured-output。
   • 对于无需保存定义的单次实验，将临时 structuredOutput 传入 POST /structured-output/run，并设置 previewEnabled: true。
   • 将关联、解除关联和对现有通话执行视为单独请求的操作。不要仅凭创建操作推断还需要执行这些操作。

2. 定义提取契约。

   • 确定下游使用方、必需字段、可选字段、允许的类别、格式，以及证据缺失或含糊时的处理方式。
   • 仅针对会实质改变架构的缺失信息提问。其余部分说明采用了哪些安全假设。
   • 如果不同输出具有不同的使用方、保留策略或迭代周期，则将其拆分。若字段构成一条稳定的业务记录，则保留为一个输出。

3. 选择 AI 或正则表达式。

   • 对于含义、分类、摘要、情感、结果检测、规范化，或以多种语言表达的事实，使用 type: "ai"。
   • 仅当要匹配的是具有稳定模式的确定性转录内容时，才使用 type: "regex"。使用兼容 RE2 的语法，并选择与文档所述正则结果相匹配的顶层架构类型：布尔值、字符串、数字/整数或数组。
   • 不要使用正则表达式推断含义。若需求完全由固定且稳定的模式构成，则不要使用 AI。

4. 设计最精简且实用的 JSON Schema。

   • 仅包含调用方可提供或通话证据可支持的字段。
   • 添加简洁的描述，以区分语义相近的字段。
   • 对封闭类别集合使用 enum；对需外部验证的字符串使用 format 或 pattern；仅在业务契约明确规定时添加数值边界。
   • 仅当每次有效通话都应生成某字段时，才将其标记为必填。对有条件才会出现的值，应设为可选，而非强行猜测。
   • 单个值优先使用基本类型架构，只有在字段构成连贯记录时才使用对象。除非下游契约需要，否则避免深层嵌套。
   • 发送前，使用标准 JSON Schema 验证器验证架构。

5. 创建、检查或更新定义。

   • 已保存的名称长度应为 1 至 40 个字符。
   • 创建时，发送 name 和 schema；仅在有意设置时添加 type、description、regex、model 或 compliancePlan。
   • 检查时，使用列表筛选条件或已验证的 ID 定位确切资源，然后调用 GET /structured-output/{id}。不要根据不完整的名称猜测。
   • 更新时，先读取当前定义，并且仅发送需要更改的字段。只有在有意更改架构的顶层类型时才使用 schemaOverride=true；否则不要用它绕过架构安全保护。
   • 修改后重新获取定义并核对请求中的字段。仅 HTTP 状态成功，但返回的状态不符合预期，并不能视为已验证成功。

6. 安全地关联或取消关联。

   • 优先使用已保存 Structured Output 文档中的 assistantIds 关联关系来进行关联。读取当前 assistantIds，添加或移除已准确确认的助手 ID，并保留所有无关 ID。
   • 对于此操作，只更新 Structured Output 上的 assistantIds。重新获取 Structured Output 和助手；验证关联关系，以及返回时助手的 artifactPlan.structuredOutputIds。
   • 如果实现方式是更新助手，先读取助手，并发送完整的现有 artifactPlan，只更改 structuredOutputIds。保留录制、日志记录、转录、评分卡、存储和其他产物设置。
   • 不要声称创建定义就完成了关联。不要声称取消关联就删除了定义，或移除了过去通话中已存储的结果。

7. 大规模执行前先预览。

   • 使用一个真实通话 ID 调用 POST /structured-output/run，并设置 previewEnabled: true。提供 structuredOutputId 或临时 structuredOutput，二者不可同时提供。
   • 确认所选通话包含有代表性的证据，且返回值符合架构和业务含义。
   • 说明预览不会更新通话产物。
   • 如果提取结果有误，请先简化架构或完善描述，再更换模型或自定义提取提示词。

8. 仅在用户请求时执行或回填。

   • 使用 previewEnabled: false 或省略此参数来更新通话产物。每个请求传入的通话 ID 不得超过当前文档规定的 100 个上限。
   • 批量运行前，说明确切的输出、通话数量，以及此输出的现有值可能被替换，而其他结构化输出值会保留。
   • 仅使用用户提供的通话 ID，或通过已验证的公开 API 查询返回的通话 ID。按通话 ID 报告部分失败；不要暗示操作采用全有或全无的事务方式。

9. 获取并验证结果。

   • 常规关联的通话结束后，等待通话后处理完成，再检查通话。
   • 使用 GET /call/{id} 获取每个通话，并读取 call.artifact.structuredOutputs[structuredOutputId].result。
   • 根据预期架构验证结果，并检查有代表性的源证据，然后再判定结果准确。符合架构只能证明格式正确，不能证明事实准确。
   • 分别报告：定义已保存、助手已关联、预览已返回、通话产物已更新、结果已验证。只提及实际验证过的阶段。

错误处理

• 遇到 400 时，检查响应中的架构、正则表达式、模型、关系或运行约束。修正一个明确无误且有文档说明的问题后重试一次；绝不重复发送未更改的请求。
• 遇到 401 或 403 时，停止并报告身份验证或权限错误。
• 遇到 404 时，报告缺失的 Structured Output、助手或调用，并指出确切的未解决 ID。
• 遇到 409 时，重新读取当前状态，再判断预期的关系或更新是否已存在。
• 遇到 429 或 5xx 时，保留请求上下文，报告服务状况，不得声称操作成功。
• 如果结果缺失，在建议更改之前，区分处理延迟、附件缺失、工件存储已禁用、调用证据不足和提取失败。

API 实现示例

需要实现代码时，请阅读 API 示例。只有在当前官方参考文档中确认生成的方法后，才使用官方 TypeScript 或 Python Server SDK；如果 SDK 语法不可用或不稳定，则使用直接 REST。

输出约定

仅返回与请求相关的部分：

• 模式：仅工件、已保存的定义、关系更改、预览或工件写入运行
• 假设或阻塞性问题
• 最终架构和 Structured Output 配置
• 已创建或更新的资源 ID 及已验证字段（如有变更）
• 附加状态和保留的关系（如有变更）
• 预览或执行结果、受影响的调用 ID，以及工件是否发生变化
• 检索到的结果及架构和证据限制
• 尚待完成的配置或验证工作

公开资料

• Structured Outputs 快速入门
• 创建 Structured Output API
• 列出 Structured Outputs API
• 获取 Structured Output API
• 更新 Structured Output API
• 运行 Structured Output API
• 获取调用 API
• 官方 TypeScript Server SDK 参考
• 官方 Python Server SDK 参考