[智能体-179]：OpenAI JSON Schema 规范，是理解大模型如何完成对工具调用的关键！！！

下面把 OpenAI 在 **Function CallingTools** 与Structured Outputs中使用的JSON Schema 规范讲清楚基于 2024-08 正式版strict: true强约束。一、适用范围与两个场景OpenAI 的 JSON Schema 主要用于两类场景Tools/Function Calling描述工具参数tools[].function.parameters结构化输出Structured Outputs描述整个回答的格式response_format.json_schema两者底层是同一套 “JSON Schema 子集 strict 约束”。二、核心关键字必掌握1顶层结构工具定义json{ type: function, function: { name: get_weather, description: 获取城市天气, strict: true, parameters: { /* JSON Schema 对象 */ } } }strict: true生产环境必须开启强制模型 100% 符合 Schema。2parameters 里的标准字段JSON Schemajson{ type: object, properties: { city: { type: string, description: 城市名, minLength: 2 }, unit: { type: string, enum: [c, f] } }, required: [city], additionalProperties: false }type只能是object/string/number/integer/boolean/array/null。properties对象的字段定义。required必填字段数组strict 下必须显式列出。additionalProperties: falsestrict 下每个 object 必须加禁止模型输出额外字段。description给模型看的说明强烈建议每个字段都写。三、支持的类型与写法OpenAI 子集1基础类型type: stringtype: number浮点数type: integer整数type: booleantype: null可与其他类型组合[string, null]2枚举jsonunit: { type: string, enum: [c, f, k] }枚举总数 ≤ 1000。3数组jsonitems: { type: object, properties: { name: {type: string} }, required: [name], additionalProperties: false }items数组元素的 schema。4嵌套对象嵌套深度≤5 层。每层都要写additionalProperties: false。5联合类型anyOfjsonvalue: { anyOf: [ { type: string }, { type: number } ] }根不能是 anyOf。6不支持 / 限制不支持oneOf部分文档提但 strict 下不稳定。不支持$ref外部引用内部$defs有限支持。不支持patternProperties、dependencies等复杂关键字。四、strict: true 的强制规则最重要一旦开启strict: true所有 object 必须写additionalProperties: false。所有必填字段必须在required中显式列出。类型严格匹配不能把 string 输出成 number。枚举值严格匹配不能输出 enum 外的值。无额外字段、无缺失字段、无类型错误。→ 结果模型输出一定是合法 JSON且完全符合 SchemaOpenAI。五、Tools 里的完整示例可直接用json{ type: function, function: { name: search_docs, description: 搜索内部文档, strict: true, parameters: { type: object, properties: { query: { type: string, description: 搜索关键词, minLength: 2 }, top_k: { type: integer, description: 返回条数, minimum: 1, maximum: 20 }, filter: { type: [string, null], description: 文档类型过滤 } }, required: [query], additionalProperties: false } } }六、结构化输出response_format示例json{ response_format: { type: json_schema, json_schema: { name: meeting_summary, strict: true, schema: { type: object, properties: { title: { type: string }, attendees: { type: array, items: { type: string } }, action_items: { type: array, items: { type: object, properties: { task: { type: string }, due_date: { type: [string, null] } }, required: [task], additionalProperties: false } } }, required: [title, attendees, action_items], additionalProperties: false } } } }七、最佳实践生产环境永远开启strict: true。每个 object 都写additionalProperties: false。必填字段全部列入required。字段描述清晰减少模型幻觉。类型尽量具体能用 integer 不用 number能用 enum 不用 string。嵌套不超过 5 层。