月明的文档中心 分享AI实践与思考
入门
上手
教程
基础
概念解释
Microsoft Foundry
开发工具
操作指南
参考
治理与网络
工具与知识
概念解释
操作指南
Agent Service
总览
概念解释
Azure OpenAI
API 与开发
总览
Azure AI Search
权限与安全
参考
检索概念
概念解释
快速上手
教程
Foundry Tools
其他与已退役
总览
概念解释
RAG 与知识工程
智能体与工具
MCP 与 Skills
操作指南
基础
评测、观测与安全
安全
评测
概念解释
参考
企业架构与成本
解决方案场景
样例与学习资源
附录
结构化输出
让模型输出严格符合你提供的 JSON Schema 的结构化数据，用于数据抽取、函数参数和多步骤工作流，而不是只靠提示词要求“返回 JSON”。
适用场景
- 从非结构化文本中抽取固定字段（如日程的名称、日期、参与人）。
- 函数调用时要求参数严格符合 schema（需
strict: true）。
- 下游系统需要稳定的字段名与类型，不能容忍解析失败。
与 JSON mode 的区别
维度 | JSON mode（旧） | 结构化输出（Structured outputs） |
保证 | 保证输出是合法 JSON | 保证输出遵循给定的 JSON Schema |
定义方式 | 无 schema | 提供 JSON Schema |
Chat Completions 字段 | 旧 JSON mode 的具体参数名：待核实（本次未读取 JSON mode 页面） | response_format，并设置 JSON Schema |
Responses API 字段 | 待核实（本次未读取 JSON mode 页面） | text.format |
前提
项目 | 要求 |
API 版本 | 2024-08-01-preview 是首个支持的版本；最新预览版与 GA 的 v1 也支持（官方说明） |
模型 | 官方列出的模型与版本（示例：gpt-5、gpt-5-mini、gpt-5.1、gpt-4o 2024-08-06、gpt-4.1 2025-04-14 等）；完整列表以官方页面为准（待核实） |
SDK | Python 示例使用 openai，并可配合 Pydantic；JavaScript 示例使用 zod；.NET 与 REST 也有示例 |
两种 API 中的写法
API | 位置 | 说明 |
Chat Completions | response_format，type 为 json_schema，json_schema.strict 为 true | 可使用 SDK 的 parse 辅助方法 |
Responses | text.format，包含 type、name、schema、strict | 结果在 output_text 或 SDK 的 output_parsed 中 |
函数调用 | 函数定义中设置 strict: true | 需设置 parallel_tool_calls 为 false |
步骤
- 用 JSON Schema（或 Pydantic、zod 等库）定义输出结构。
- 在请求中设置
response_format（Chat Completions）或text.format（Responses）。
- 解析结果；如果存在拒绝（refusal），按拒绝处理，不做解析。
写 schema 的规则（官方限制）
规则 | 说明 |
所有字段必须 required | 可选字段用 ["string", "null"] 这类联合类型模拟 |
additionalProperties 为 false | 每个对象都要设置 |
支持的类型 | string、number、boolean、integer、object、array、enum、anyOf |
根对象 | 不能是 anyOf 类型 |
规模 | 最多 100 个对象属性，嵌套最多 5 层（官方说明） |
字段顺序 | 输出顺序与 schema 中的顺序一致 |
支持 $defs 与递归（$ref） | 支持 |
不支持的关键字
类型 | 不支持的关键字 |
字符串 | minLength、maxLength、pattern、format |
数字 | minimum、maximum、multipleOf |
对象 | patternProperties、unevaluatedProperties、propertyNames、minProperties、maxProperties |
数组 | unevaluatedItems、contains、minContains、maxContains、minItems、maxItems、uniqueItems |
不支持结构化输出的场景
- Bring your own data（使用自有数据）场景。
- Assistants 与 Foundry Agent 服务。
- gpt-audio 与 gpt-audio-mini。
验证
检查项 | 预期结果 |
响应内容 | 能被目标结构解析，字段齐全 |
拒绝 | 若存在 refusal，应用应给出提示而非解析失败 |
函数调用 | parallel_tool_calls 为 false，且参数符合 schema |
排错表
现象 | 处理方式 |
请求被拒绝，提示 schema 不支持 | 对照“不支持的关键字”表删除对应约束，改在应用端校验 |
可选字段缺失 | 将字段改为必填并使用 null 联合类型 |
函数调用中出现多个并行调用 | 设置 parallel_tool_calls 为 false |
在 Agent 服务或 Assistants 中使用无效 | 这些场景不支持，改用普通 Responses 或 Chat Completions 调用 |
示例说明
官方页面提供了 Python、JavaScript、.NET 与 REST 的完整示例，包括抽取日程、数学推理步骤和函数调用场景。本页不复制示例代码，实际使用时以官方示例为准。
来源与核对
- 核对范围：正文已读（概述、与 JSON mode 的差异、两种 API 写法、schema 限制与不支持场景、支持模型与 API 版本已核对；各语言示例代码未逐段核对）。
- 获取日期：2026-11-05。模型版本清单、API 版本与示例中的模型名称待核实。
上一篇
第一个检索索引
下一篇
函数调用
Loading...