Skip to main content

Responses API 结构化输出

结构化输出确保模型返回符合指定JSON Schema的有效JSON,为您提供可预测、易解析的响应格式。这对于函数调用、数据提取和API集成等场景特别有用。

快速开始

只需要替换 <API-KEY> 为你的实际API密钥即可运行。

结构化输出特性

结构化输出通过严格模式确保输出完全符合提供的JSON Schema:

JSON Schema 支持

  • 严格模式: 通过 "strict": true 启用,确保100%遵循schema
  • 完整类型支持: 支持object、array、string、number、integer、boolean等
  • 验证约束: 支持required字段、additionalProperties、enum等
  • 嵌套结构: 支持复杂的嵌套对象和数组结构

格式要求

支持的格式类型

  1. text (默认) - 纯文本响应
  1. json_schema (推荐) - 结构化JSON输出
  1. json_object (不推荐) - 旧版JSON模式

响应结果示例

基础结构化输出

JSON Schema 定义指南

基础类型

高级约束和验证

嵌套对象结构

应用场景

  1. 数据提取 - 从文本中提取结构化信息并格式化为特定JSON格式
  2. API集成 - 生成符合下游系统要求的标准化响应格式
  3. 表单处理 - 将自然语言输入转换为结构化表单数据
  4. 报告生成 - 创建格式一致的分析报告和统计数据
  5. 配置生成 - 基于需求描述生成应用程序配置文件
  6. 数据转换 - 将非结构化数据转换为数据库友好的格式

最佳实践

1. Schema 设计原则

  • 明确性: 为每个字段提供清晰的描述
  • 完整性: 正确标记必需字段和可选字段
  • 约束性: 使用 additionalProperties: false 严格控制输出
  • 验证: 添加适当的类型约束和范围限制

2. 提示优化策略

  • 具体性: 提供明确的数据要求和示例
  • 上下文: 给出足够的背景信息帮助模型理解
  • 格式说明: 明确指出期望的输出格式

3. 错误处理机制

  • 验证: 始终验证返回的JSON是否符合期望的schema
  • 容错: 为无效输出提供合理的fallback机制
  • 日志: 记录结构化输出的成功率和失败原因

4. 性能优化

  • Schema简化: 避免过度复杂的嵌套结构
  • 批处理: 对于大量数据,考虑分批处理
  • 缓存: 对重复的schema定义进行缓存

注意事项

兼容性

  • 模型支持: 结构化输出需要支持该功能的模型(如gpt-4o、gpt-4o-mini等)
  • API版本: 确保使用最新的API版本以获得最佳兼容性

性能影响

  • Token消耗: 结构化输出可能比普通文本输出消耗更多tokens
  • 响应时间: 复杂的schema验证可能增加处理时间
  • 成本考量: 更高的token使用量会影响API调用成本

技术限制

  • Schema复杂度: 过度复杂的schema可能影响生成质量和成功率
  • 严格模式: strict: true 确保100%符合schema,但可能增加失败概率
  • 数据一致性: 某些复杂的约束条件可能难以完全满足

开发建议

  • 渐进式设计: 从简单的schema开始,逐步增加复杂性
  • 充分测试: 在生产环境使用前进行充分的测试验证
  • 监控指标: 监控结构化输出的成功率和错误模式
  • 备用方案: 为关键业务场景准备非结构化输出的备用方案

常见问题解答

Q: 如何确保输出严格符合Schema?
A: 使用 "strict": true 参数,配合明确的schema定义和适当的提示词。
Q: 哪些模型支持结构化输出?
A: 支持的模型包括 gpt-4o、gpt-4o-mini、gpt-4-turbo 等。具体支持情况请查看模型文档。
Q: 如何处理大型复杂结构?
A: 建议分解为多个简单的子结构,或使用分步骤的多次请求来构建复杂数据。
Q: 结构化输出的成本如何?
A: 通常比普通对话消耗更多token,但能保证输出质量和格式一致性,减少后处理成本。
Q: 如何调试Schema定义问题?
A: 从最简单的schema开始测试,逐步增加字段和约束,观察每个变更的影响。
Q: 支持哪些JSON Schema版本?
A: 支持 JSON Schema 的核心功能,具体版本兼容性以官方文档为准。