AI Agent 开发实战（八）：输出 Schema 约束与结构化输出

上一篇我们用 Harness Engineering 把 LLM 的行为范围框住但还有一类问题没解决输出格式。LLM 默认吐的是自由文本而下游系统要的是 JSON、枚举、数组——格式不对整条链路就断了。今天聊输出 Schema 约束让 LLM 的输出像 API 返回值一样可预测。一、为什么需要结构化输出先看一个没有约束的 Agent 输出用户帮我查一下某市的租房补贴政策 Agent好的某市的租房补贴政策如下 1. 补贴标准本科500元/月硕士800元/月博士1200元/月 2. 申请条件需要在本区就业并缴纳社保满3个月... 3. 申请方式通过人才服务中心官网在线申请看起来没问题但对下游系统来说这是一坨文本不是数据。前端没法渲染成卡片数据库没法存入字段。我们真正想要的是{subsidy:{bachelor:500,master:800,doctor:1200},requirements:[本区就业,社保满3个月],applyUrl:https://...}结构化输出的核心价值让 LLM 的输出从文本变成数据下游可直接消费。二、结构化输出的三种策略结构化输出策略 │ ├── 1. Prompt 约束最弱 │ ├── 在 Prompt 中要求返回 JSON │ ├── 给出 JSON 示例 │ └── 问题LLM 可能不听话格式不稳定 │ ├── 2. 函数调用 / Tool Use中等 │ ├── 利用 LLM 的 function calling 能力 │ ├── 输出自然就是结构化的 │ └── 问题不是所有场景都适合伪装成工具调用 │ └── 3. 输出 Schema 约束最强 ├── 强制 LLM 按 Schema 输出 ├── 支持 JSON Schema、Pydantic、Zod 等 └── 原理引导采样过程 输出校验 自动重试策略约束强度兼容性实现复杂度典型框架Prompt 约束弱所有模型低无需框架函数调用中需模型支持中OpenAI / Spring AISchema 约束强需模型或框架支持高Instructor / Spring AI Structured三、Prompt 约束最基础的方式# 在 Prompt 中要求返回 JSONprompt请分析以下文本的情感倾向以 JSON 格式返回。 要求 - sentiment: 正面/负面/中性 - confidence: 0-1 之间的浮点数 - keywords: 关键词数组 示例输出 {sentiment: 正面, confidence: 0.85, keywords: [好, 优秀]} 待分析文本{text}问题在哪可能出现的意外输出 │ ├── 1. 输出前后多了解释文字 │ 好的分析结果如下\n{\sentiment\: ...}\n希望对你有帮助 │ ├── 2. JSON 格式不规范 │ {sentiment: 正面, confidence: 0.85, keywords: [好, 优秀],} ← 末尾多了逗号 │ ├── 3. 字段名不一致 │ {emotion: 正面, score: 0.85} ← 你要的是 sentiment它给了 emotion │ └── 4. 嵌套结构错误 {result: {sentiment: ...}} ← 多包了一层Prompt 约束的本质是请求而非要求。LLM 大部分时候会配合但你无法保证 100%。四、函数调用借力 Tool Use利用 LLM 原生的 function calling 能力让输出天生就是结构化的// Spring AI 方式BeanpublicChatClientchatClient(ChatClient.Builderbuilder){returnbuilder.build();}// 定义函数描述Description(分析文本情感返回结构化结果)publicrecordSentimentAnalysis(Description(情感倾向正面、负面、中性)Stringsentiment,Description(置信度 0-1)Doubleconfidence,Description(关键词列表)ListStringkeywords){}// 调用varresponsechatClient.prompt().user(分析这段文本的情感今天天气真好).functions(sentimentAnalysis).call().entity(SentimentAnalysis.class);函数调用的局限函数调用的局限 │ ├── 1. 语义不匹配 │ 帮我分析情感不是调用工具而是返回结果 │ 强行用 tool call 表达语义上有点别扭 │ ├── 2. 不是所有模型都支持 │ 开源模型如 Qwen、DeepSeek对 function calling 支持参差不齐 │ ├── 3. 只能返回单层结构 │ 复杂嵌套 Schema 用 function call 描述起来很别扭 │ └── 4. 一次只能调一个函数 多个输出字段需要拆成多个函数不合理五、Schema 约束终极方案5.1 核心原理Schema 约束的底层机制 │ ├── 1. Schema 转化为 Prompt 引导 │ ├── JSON Schema → 自然语言描述注入 System Prompt │ ├── 告诉 LLM 必须按以下格式输出 │ └── 相当于 Prompt 约束的工程化版本 │ ├── 2. 约束解码Constrained Decoding │ ├── 某些框架/模型支持在 token 采样时强制合法 │ ├── 例如当 Schema 要求整数采样时只允许数字 token │ ├── 效果100% 格式合规如果模型支持 │ └── 实现llama.cpp 的 GBNF 语法、Outlines 的 FSM │ └── 3. 输出校验 自动重试 ├── 解析 LLM 输出校验是否符合 Schema ├── 不符合则将错误信息拼回 Prompt 重试 └── 最多重试 N 次兜底返回错误5.2 JSON Schema 示例{type:object,properties:{subsidy:{type:object,properties:{bachelor:{type:integer,description:本科补贴元/月},master:{type:integer,description:硕士补贴元/月},doctor:{type:integer,description:博士补贴元/月}},required:[bachelor,master,doctor]},requirements:{type:array,items:{type:string},description:申请条件列表},applyUrl:{type:string,format:uri,description:申请链接}},required:[subsidy,requirements,applyUrl]}5.3 Spring AI 结构化输出Spring AI 从 1.0.0 开始支持结构化输出底层是 JSON Schema 自动映射// 定义输出结构publicrecordSubsidyInfo(JsonProperty(requiredtrue)Description(各学历补贴标准)SubsidyDetailsubsidy,Description(申请条件列表)ListStringrequirements,Description(申请链接)StringapplyUrl){}publicrecordSubsidyDetail(intbachelor,intmaster,intdoctor){}// 使用varresultchatClient.prompt().user(查询某市租房补贴政策).call().entity(SubsidyInfo.class);// ← 一行搞定Spring AI 的.entity()做了什么.entity() 内部流程 │ ├── 1. 将 SubsidyInfo.class 转换为 JSON Schema │ ├── 2. 将 Schema 注入 Prompt作为格式要求 │ ├── 3. 调用 LLM获取文本输出 │ ├── 4. 尝试将输出解析为 SubsidyInfo 对象 │ ├── 解析成功 → 返回 │ └── 解析失败 → 拼入错误信息重试 │ └── 5. 重试 N 次后仍失败 → 抛出异常六、约束解码从引导到强制Prompt 引导 重试只是软约束。真正的硬约束是约束解码Constrained Decoding。6.1 原理常规解码自由采样 │ ├── 每步从词表中采样一个 token ├── 任何 token 都可能被选中 └── 输出可能是任意文本 约束解码Constrained Decoding │ ├── 根据 Schema 构建一个有限状态机FSM或文法Grammar ├── 每步只允许生成 FSM 当前状态合法的 token ├── 例如Schema 要求整数 → 只允许 0-9 token ├── 例如Schema 要求布尔 → 只允许 true/false token └── 输出 100% 符合 Schema在模型支持的前提下6.2 实现方案对比方案语言原理支持模型接入方式OutlinesPythonFSM 约束解码本地模型Python 库llama.cpp GBNFC文法约束GGUF 模型API 参数InstructorPythonSchema 重试OpenAI 兼容 APIPython 库Spring AIJavaSchema 注入 重试任何模型Java 框架OpenAI Structured OutputsAPI约束解码GPT-4o 等API 参数6.3 OpenAI Structed Outputs 示例fromopenaiimportOpenAIfrompydanticimportBaseModelclassSubsidyDetail(BaseModel):bachelor:intmaster:intdoctor:intclassSubsidyInfo(BaseModel):subsidy:SubsidyDetail requirements:list[str]apply_url:strclientOpenAI()responseclient.beta.chat.completions.parse(modelgpt-4o,messages[{role:user,content:查询某市租房补贴政策}],response_formatSubsidyInfo,# ← 直接传 Pydantic 类)# 输出 100% 符合 SubsidyInfo 结构七、实战多层 Schema 设计真实 Agent 的输出往往不是扁平的 JSON而是多层嵌套结构。7.1 一个商机分析 Agent 的输出 SchemapublicrecordOpportunityAnalysis(Description(商机基本信息)BasicInfobasicInfo,Description(风险评估)RiskAssessmentrisk,Description(推荐动作)ListActionactions,Description(综合评分 0-100)intscore){}publicrecordBasicInfo(Description(客户行业)Stringindustry,Description(预计预算万元)doublebudget,Description(决策周期天)intdecisionCycle){}publicrecordRiskAssessment(Description(风险等级低/中/高)Stringlevel,Description(风险因素列表)ListStringfactors,Description(风险说明)Stringdescription){}publicrecordAction(Description(动作类型联系/跟进/放弃/升级)Stringtype,Description(动作描述)Stringdescription,Description(优先级 1-5)intpriority){}7.2 枚举约束// 使用枚举限制取值范围publicenumRiskLevel{LOW,MEDIUM,HIGH}publicenumActionType{CONTACT,FOLLOW_UP,ABANDON,ESCALATE}publicrecordRiskAssessment(RiskLevellevel,// ← 只能是四个值之一ListStringfactors,Stringdescription){}publicrecordAction(ActionTypetype,// ← 只能是四个值之一Stringdescription,Min(1)Max(5)intpriority// ← 限制范围){}枚举约束的效果没有枚举约束 ├── risk.level 比较危险 ← 不在预期范围内 ├── action.type 打电话 ← 下游系统无法识别 └── score 150 ← 超出 0-100 范围 有枚举约束 ├── risk.level MEDIUM ← 严格限定 ├── action.type CONTACT ← 严格限定 └── score 75 ← 范围限定八、Schema 约束的代价结构化输出不是免费的有三个关键代价8.1 推理质量下降自由输出 vs 结构化输出 │ ├── 自由输出 │ 经过分析这个商机值得跟进但预算可能需要调整 │ 建议先与客户技术负责人建立联系... │ → 表达丰富推理自然 │ └── 结构化输出 │ {score: 75, risk: {level: MEDIUM, ...}} │ → 表达受限推理被压缩进字段 │ → 某些微妙判断可能丢失缓解策略在 Schema 中加reasoning或explanation字段让 LLM 先推理再输出结构。publicrecordOpportunityAnalysis(Description(推理过程先思考再给结论)Stringreasoning,// ← 给 LLM 一个思考空间BasicInfobasicInfo,RiskAssessmentrisk,ListActionactions,intscore){}8.2 Token 消耗增加自由输出~200 tokens 结构化输出~500 tokensJSON key 语法 枚举值 增加约 2-3 倍 token 消耗8.3 延迟增加自由输出1-2 秒 结构化输出 ├── 首次调用 解析2-3 秒 ├── 重试 1 次2-3 秒 └── 重试 2 次2-3 秒 最差情况7-9 秒代价总结代价幅度缓解方式推理质量下降 5-15%加 reasoning 字段Token 消耗增加 2-3 倍精简 Schema少用嵌套延迟增加 1-3 秒限制重试次数选快速模型九、Schema 约束 vs Harness 约束互补而非替代上一篇讲的 Harness Engineering 和这篇的 Schema 约束两者互补约束体系 │ ├── Harness 约束行为层面 │ ├── 限制可用工具 │ ├── 限制执行流程 │ ├── 限制输入范围 │ └── 解决Agent 能做什么、不能做什么 │ └── Schema 约束输出层面 ├── 限制输出格式 ├── 限制字段取值 ├── 限制嵌套结构 └── 解决Agent 输出什么、怎么输出实战中的组合// Harness限制工具和流程varagentChatAgent.builder().tools(List.of(searchTool,calculatorTool))// 只允许两个工具.maxSteps(5)// 最多 5 步.build();// Schema限制输出格式varresultagent.run(分析这个商机).entity(OpportunityAnalysis.class);// 输出必须是这个结构完整约束链 │ ├── 输入约束Harness 限制可接收的用户输入范围 │ ├── 工具约束Harness 限制可用工具集 │ ├── 流程约束Harness 限制执行路径和步骤数 │ └── 输出约束Schema 限制输出格式和字段取值 ├── 格式约束必须是 JSON ├── 字段约束字段名、类型、必填 ├── 取值约束枚举、范围、正则 └── 嵌套约束对象引用、递归结构十、框架实战对比10.1 InstructorPythonimportinstructorfromopenaiimportOpenAIfrompydanticimportBaseModel clientinstructor.from_openai(OpenAI())classAnalysis(BaseModel):score:intreason:strresultclient.chat.completions.create(modelgpt-4o-mini,messages[{role:user,content:分析这段文本}],response_modelAnalysis,# ← 核心参数max_retries3,# ← 自动重试次数)特点Pydantic 定义 自动重试 流式支持Python 生态最成熟的方案。10.2 Spring AIJavavarresultchatClient.prompt().user(分析这段文本).call().entity(Analysis.class);// ← 一行搞定特点Java 生态最简洁的方案但底层是 Prompt 注入 重试非约束解码。10.3 LangChainPython/JSfromlangchain_core.output_parsersimportPydanticOutputParser parserPydanticOutputParser(pydantic_objectAnalysis)promptChatPromptTemplate.from_messages([(system,按以下格式输出\n{format_instructions}),(human,{input})])chainprompt|model|parser resultchain.invoke({input:分析这段文本,format_instructions:parser.get_format_instructions()})特点Parser 模式灵活但啰嗦适合已有 LangChain 链的项目。十一、选择建议如何选择结构化输出方案 │ ├── 场景一只需要简单字段容忍偶尔格式错误 │ └── Prompt 约束就够了 │ ├── 场景二需要稳定的 JSON 输出Python 生态 │ └── Instructor首选或 LangChain Pydantic │ ├── 场景三需要稳定的 JSON 输出Java 生态 │ └── Spring AI .entity() │ ├── 场景四需要 100% 格式保证使用 OpenAI API │ └── OpenAI Structured Outputs │ └── 场景五需要 100% 格式保证使用本地模型 └── Outlines 或 llama.cpp GBNF十二、最佳实践 Checklist#实践说明1优先用 Schema 约束而非 Prompt 约束工程化 提示词技巧2给 Schema 的每个字段加 DescriptionLLM 看到 description 才知道该填什么3枚举字段用 enum 而非 string避免 LLM 自由发挥4加 reasoning 字段保留推理质量让 LLM 先思考再结构化输出5限制重试次数建议 2-3 次避免无限重试浪费 token6监控 Schema 校验失败率失败率高说明 Schema 设计有问题7嵌套不超过 3 层太深 LLM 容易出错8Schema 和 Harness 配合使用输入约束 输出约束 完整约束9用 Min/Max 限制数值范围防止 LLM 输出离谱的数值10输出校验失败时降级为文本给用户兜底体验下一篇我们聊Grill Me 反问式规划Agent 不是应该什么都听用户的而是要学会反问——在动手之前先搞清楚需求边界、风险点和遗漏信息。这是一套让 Agent 从执行者变成协作者的关键模式。本文是 AI Agent 开发实战系列第 8 篇系列目录AI Agent 核心概念与架构三大基石之 LLM 调用与 Prompt 工程三大基石之记忆系统三大基石之工具调用Java 生态 Agent 框架横评用 Spring AI 搭建第一个 AgentHarness Engineering 与约束管理本文输出 Schema 约束与结构化输出