导航栏：首页 / AI开发参考资料 / OpenAI API 兼容格式参考资料 / 请求参数详解 / response_format
如果您想深入了解如何借助 OpenAI API 打造人工智能硬件，欢迎访问本站教程目录页，查看太极创客团队为您精心准备的系列教程。
参数说明
请注意:不是所有模型都支持response_format参数。通常较新的模型版本支持此功能，而较旧的模型可能不支持。在使用前，请查阅相关模型的文档，确认是否支持结构化输出功能。如果模型不支持此参数，API可能会返回错误或忽略该参数。
response_format参数用于控制模型返回内容的格式。这是一个可选的高级参数，特别适合需要结构化输出的应用场景。
通过使用response_format，你可以：
- 要求模型返回JSON格式的数据，便于后续解析和处理
- 定义JSON Schema，精确控制输出数据的结构和字段类型
- 提高输出格式的一致性，减少后续数据处理的复杂度
- 简化与现有系统的集成，无需额外的格式转换步骤
必需性
response_format是API请求中的可选参数。如果不提供此参数，模型将返回纯文本格式的响应。如果你的应用需要结构化数据，建议使用此参数。
参数结构
response_format参数是一个对象，包含以下字段：
- type（必需）：指定输出格式类型，支持的值包括：
"text"：返回纯文本（默认行为）"json_object"：返回JSON对象
- json_schema（可选）：当type为”json_object”时，可以使用JSON Schema来定义输出数据的结构和约束条件
基本JSON格式输出
最简单的用法是将type设置为"json_object"，让模型返回JSON格式的响应。这种方式适合需要结构化数据但不需要严格Schema约束的场景
{
"model": "gpt-5.2",
"messages": [
{
"role": "system",
"content": "你是一个数据提取助手，需要从文本中提取关键信息并以JSON格式返回。"
},
{
"role": "user",
"content": "请从以下文本中提取姓名、年龄和职业：张三今年25岁，是一名软件工程师。"
}
],
"response_format": {
"type": "json_object"
}
}模型可能返回的响应示例：
{
"name": "张三",
"age": 25,
"occupation": "软件工程师"
}使用要点
- 在system消息中明确要求模型返回JSON格式，可以提高输出的可靠性
- 确保在user消息中清楚描述期望的JSON结构
- 对于简单的数据提取任务，基本JSON格式通常足够
- 注意：即使设置了JSON格式，模型偶尔也可能返回无效的JSON，需要在代码中进行错误处理
使用JSON Schema定义输出结构
对于需要严格输出格式控制的场景，可以使用json_schema字段来定义详细的JSON Schema。这样可以精确控制输出数据的结构、字段类型、必填项、枚举值等。
{
"model": "gpt-5.2",
"messages": [
{
"role": "system",
"content": "你是一个产品分析助手，需要分析产品信息并返回结构化的JSON数据。"
},
{
"role": "user",
"content": "分析以下产品信息：iPhone 15 Pro，价格7999元，128GB存储，钛金属材质，支持5G网络。"
}
],
"response_format": {
"type": "json_object",
"json_schema": {
"type": "object",
"properties": {
"product_name": {
"type": "string",
"description": "产品名称"
},
"price": {
"type": "number",
"description": "产品价格（元）"
},
"storage": {
"type": "string",
"description": "存储容量"
},
"material": {
"type": "string",
"description": "材质"
},
"network_support": {
"type": "array",
"items": {
"type": "string"
},
"description": "支持的网络类型"
}
},
"required": ["product_name", "price", "storage"]
}
}
}模型可能返回的响应示例：
{
"product_name": "iPhone 15 Pro",
"price": 7999,
"storage": "128GB",
"material": "钛金属",
"network_support": ["5G"]
}JSON Schema常用特性
- type：定义字段类型，如string、number、boolean、array、object等
- properties：定义对象的属性及其类型
- required：指定哪些字段是必填的
- enum：限制字段的取值范围，只能从指定的值中选择
- description：为字段添加描述，帮助模型理解字段的用途
- items：定义数组元素的类型和结构
- additionalProperties：控制是否允许额外的属性
复杂嵌套结构示例
JSON Schema支持复杂的嵌套结构，可以定义多层对象和数组。以下是一个更复杂的示例，展示如何定义包含嵌套对象的输出格式。
{
"model": "gpt-5.2",
"messages": [
{
"role": "system",
"content": "你是一个订单分析助手，需要分析订单信息并返回结构化的JSON数据。"
},
{
"role": "user",
"content": "分析以下订单：订单号ORD-2024-001，客户张三，包含2件商品：iPhone 15 Pro（7999元）和AirPods Pro（1899元），总金额9898元，状态为已支付。"
}
],
"response_format": {
"type": "json_object",
"json_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单编号"
},
"customer": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "客户姓名"
},
"contact": {
"type": "string",
"description": "联系方式"
}
},
"required": ["name"]
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product_name": {
"type": "string",
"description": "商品名称"
},
"price": {
"type": "number",
"description": "商品价格"
},
"quantity": {
"type": "integer",
"description": "商品数量"
}
},
"required": ["product_name", "price"]
},
"description": "订单商品列表"
},
"total_amount": {
"type": "number",
"description": "订单总金额"
},
"status": {
"type": "string",
"enum": ["待支付", "已支付", "已发货", "已完成", "已取消"],
"description": "订单状态"
}
},
"required": ["order_id", "customer", "items", "total_amount", "status"]
}
}
}模型可能返回的响应示例：
{
"order_id": "ORD-2024-001",
"customer": {
"name": "张三"
},
"items": [
{
"product_name": "iPhone 15 Pro",
"price": 7999,
"quantity": 1
},
{
"product_name": "AirPods Pro",
"price": 1899,
"quantity": 1
}
],
"total_amount": 9898,
"status": "已支付"
}使用建议
- 明确输出需求：在system消息中清楚地说明需要返回JSON格式，并描述期望的结构，这有助于模型更好地理解需求
- 使用JSON Schema：对于生产环境，强烈建议使用JSON Schema来定义输出结构，这样可以确保输出格式的一致性和可靠性
- 简化Schema：避免过于复杂的Schema结构，保持简洁明了，这有助于模型更好地遵循格式要求
- 添加描述信息：为Schema中的每个字段添加description，帮助模型理解字段的用途和期望的值
- 设置必填字段：使用required字段明确指定哪些字段是必须的，确保关键信息不会缺失
- 使用枚举值：对于有限取值的字段，使用enum来限制可能的值，提高输出的准确性
- 错误处理：在代码中添加JSON解析错误处理，即使设置了JSON格式，模型偶尔也可能返回无效的JSON
- 测试验证：在部署前充分测试各种场景，验证模型返回的JSON是否符合Schema定义
- 逐步迭代：从简单的Schema开始，逐步增加复杂度，确保每个版本都能正常工作
- 监控质量：在生产环境中监控JSON输出的质量，及时发现和解决问题
常见问题解答
- 问：response_format参数对所有模型都支持吗？
答：不是所有模型都支持response_format参数。通常较新的模型版本支持此功能，而较旧的模型可能不支持。在使用前，请查阅相关模型的文档，确认是否支持结构化输出功能。如果模型不支持此参数，API可能会返回错误或忽略该参数。 - 问：使用response_format会影响模型的性能吗？
答：使用response_format可能会对模型性能产生轻微影响。模型需要额外的计算来确保输出符合指定的格式。对于简单的JSON格式，影响通常很小；对于复杂的JSON Schema，可能会增加一定的响应时间和token消耗。建议在实际应用中进行性能测试，评估对响应时间和成本的影响。 - 问：如果模型返回的JSON不符合Schema定义怎么办？
答：虽然response_format参数可以显著提高JSON输出的准确性，但模型偶尔仍可能返回不符合Schema的JSON。建议采取以下措施：1）在代码中添加JSON Schema验证；2）实现重试机制，当验证失败时重新请求；3）提供更详细的Schema描述和示例；4）对于关键应用，考虑使用后处理来修复常见的格式问题。 - 问：JSON Schema支持哪些数据类型？
答：JSON Schema支持多种数据类型，包括：1）基本类型：string、number、integer、boolean、null；2）复合类型：object（对象）、array（数组）；3）约束类型：enum（枚举）、oneOf、anyOf、allOf；4）其他特性：required（必填）、properties（属性）、items（数组元素）、additionalProperties（额外属性）等。这些类型和特性可以组合使用，定义非常复杂的输出结构。 - 问：如何在JSON Schema中定义可选字段？
答：在JSON Schema中，默认情况下所有字段都是可选的。要定义必填字段，需要在Schema的根级别添加required数组，列出所有必填字段的名称。例如："required": ["name", "email"]表示name和email字段是必填的，其他字段都是可选的。对于嵌套对象，可以在嵌套的Schema中定义自己的required数组。 - 问：可以同时使用response_format和temperature参数吗？
答：可以同时使用这两个参数。response_format控制输出格式，temperature控制输出的随机性。但需要注意的是，较高的temperature值可能会增加输出不符合格式要求的风险。建议在使用JSON Schema时，将temperature设置在较低的范围（如0.1-0.3），以提高输出格式的稳定性。 - 问：如何处理模型返回的JSON中缺少必填字段的情况？
答：即使设置了required字段，模型偶尔也可能返回缺少必填字段的JSON。建议采取以下策略：1）在代码中添加字段完整性检查；2）对于缺失的字段，可以尝试从上下文中推断或使用默认值；3）实现重试机制，当验证失败时重新请求；4）在system消息中强调所有必填字段的重要性；5）考虑使用更详细的Schema描述和示例来引导模型。