AI Agent结构化输出四层约束：从Prompt到代码校验的完整工程方案

AI Agent结构化输出四层约束：从Prompt到代码校验的完整工程方案

发布时间：2026/8/30 8:36:19
AI Agent结构化输出四层约束：从Prompt到代码校验的完整工程方案 AI Agent 面试如果只能准备一个技术点我建议你把重心放在“结构化输出”上。原因很简单不管你的 Agent 用例是信息抽取、数据清洗、流程编排还是内容生成最终都要把模型输出接入业务逻辑。模型今天给一版纯 JSON明天夹带一段解释文字后天把字段名从total_price改成totalPrice下游代码就要写一堆正则和异常分支。面试官真正想确认的不是你会不会调用大模型 API而是你有没有一套方法论把“碰运气式输出”变成“工程上可收敛的输出”。很多人的第一反应是“我在 Prompt 里写了‘请输出 JSON’”但做过生产级 Agent 的人都知道这种软约束在复杂任务、长输出、低温度场景下都未必稳定。所以这篇文章给出一套可以直接背下来、也可以直接落地的答题框架四层约束。第一层是用 Prompt 强制约定格式第二层是用正例和反例让模型理解边界第三层是使用模型原生参数比如 JSON Mode、JSON Schema 和 function calling第四层是在代码层做校验与自动修复。越往后越刚性越接近“程序保证”。文章会先讲为什么模型输出不稳定再逐层拆解每一层怎么设计、怎么写代码、有什么局限最后用一个“订单信息提取 Agent”把四层串起来并补充面试官最爱追问的几个问题。你可以把这篇文章当面试复习提纲也可以当工程落地的检查清单。1. 核心能力速览四层约束体系对照表约束层核心手段成本保证强度负责解决的问题第一层Prompt 强制系统提示词、角色设定、输出格式描述极低弱模型不知道要输出 JSON或者不知道要包含哪些字段第二层正反示例few-shot 示例包含正确示例和错误示例低中模型知道什么是“好 JSON”什么是“不可接受的输出”第三层原生参数response_format、json_schema、function calling、temperature中较强模型在解码层被强制约束到合法 JSON 或函数参数结构第四层代码校验JSON Schema、Pydantic、重试修复中最强无论模型输出什么下游只接收通过校验的数据这四层不是互斥关系而是叠加关系。生产环境通常同时启用四层用 Prompt 和示例给模型明确指令用原生参数压缩非法输出概率最后再用代码校验兜住剩余问题。这套体系适合所有基于大语言模型的 Agent 场景信息抽取、工具调用、内容标签化、搜索结构化、数据清洗、多步 Agent 间传递参数等。不适合的场景是纯开放式闲聊那种场景不需要强约束强行约束反而破坏生成质量。2. 为什么 Agent 输出结构化内容这么难大模型的本质是“根据前文预测下一个 token 的概率分布”。它没有内存里的数据结构也没有编译器的类型检查所有输出都是字符串。只要约束不够强模型就会在几个地方出现偏差。先看最常见的失败类型。JSON 输出失败主要分成三类。第一类是语法层失败比如多了一个尾逗号、使用了中文引号“”、键没有加双引号、转义字符处理错误。这类问题在长文本和复杂嵌套结构下尤其明显。第二类是结构层失败比如字段缺失、字段名拼写不一致、数组嵌套层级错误、把字符串8999写成了数字8999。第三类是“夹带内容”失败比如在 JSON 前面加了“好的这是提取结果”或者在 JSON 外面包了一层 Markdown 代码块。失败类型典型示例下游影响JSON 语法错误{id: 123,}json.loads()直接抛异常字段缺失没有items字段业务代码空指针、KeyError类型不匹配total_price: 8999元类型转换失败入库报错夹带额外文本“好的结果如下{...}”需要预处理才能解析嵌套层级错误items里多包了一层list下游遍历逻辑出错这些失败的共同点在于模型本身无法感知下游代码对数据的硬性要求。Prompt 里写“严格输出 JSON”模型会努力照做但概率采样天然导致偶发偏离。因此工程上必须承认一个事实不能指望模型输出 100% 合法只能在约束层一层层提高命中率。3. 第一层约束Prompt 强制3.1 系统提示词模板设计Prompt 强制是所有约束的基础。它的目标不是让模型“理解业务”而是让模型明确“输出契约”。一个合格的系统提示词应该包含四个元素角色、任务、输出格式、反例警告。下面是一个订单信息抽取场景的 Prompt 模板SYSTEM_PROMPT 你是订单信息抽取Agent。 你的任务是从用户输入中提取订单信息并输出结构化JSON。 输出格式要求 1. 只输出一个JSON对象不要包含任何解释文字。 2. 不要使用Markdown代码块包裹JSON。 3. JSON必须包含以下字段 - order_id: 字符串订单号没有则生成UNKNOWN - user_name: 字符串用户姓名 - items: 数组每个元素包含 product_name(字符串) 和 quantity(整数) - total_price: 浮点数订单总金额 如果你无法提取某个字段使用null或默认值不要省略字段。 示例输出 {order_id: A0001, user_name: 张三, items: [{product_name: 美式咖啡, quantity: 2}], total_price: 30.0} 这段提示词做了三件重要的事第一把输出范围缩小到 JSON第二把字段名、字段类型、是否必填写清楚第三用“不要省略字段”这个约束避免模型自作主张删字段。3.2 内嵌 JSON Schema 描述如果字段较多可以在 Prompt 里直接贴 JSON Schema 的核心描述这种方式对模型的指令遵循能力要求更高但效果通常比自然语言描述更好。因为 JSON Schema 本身就是一种无歧义的格式契约模型在训练数据里见过大量 JSON Schema按格式理解字段关系比读一大段文字更高效。SYSTEM_PROMPT 你是信息抽取Agent。根据用户输入提取结构化数据输出必须满足以下JSON Schema { type: object, properties: { order_id: {type: string}, user_name: {type: string}, items: { type: array, items: { type: object, properties: { product_name: {type: string}, quantity: {type: integer} }, required: [product_name, quantity] } }, total_price: {type: number} }, required: [order_id, user_name, items, total_price] } 只输出JSON对象不输出其他内容。 3.3 这一层的边界Prompt 强制不是银弹。它的效果高度依赖模型的指令遵循能力。指令遵循能力强的模型比如 GPT-4o 系列、Claude 系列、DeepSeek-V3、Qwen 系列等在简单场景下命中率很高但遇到以下情况依然会失败用户输入特别长模型上下文被大量无关内容占据任务本身高度复杂模型需要多次推理后才给出结果需要输出的 JSON 嵌套层级深、字段数量多用户输入里包含明显与系统提示词冲突的指令。所以面试时不要只说“我在 Prompt 里写了输出 JSON”。加分回答是“Prompt 强制是最低成本的约束但它不提供硬保证所以需要后面几层补充。”4. 第二层约束正反示例4.1 few-shot 示例为什么有效有些人觉得既然已经在 Prompt 里写了格式说明为什么还要示例因为大模型对“抽象规则”的遵循不稳定但对“具体例子”的模仿更自然。few-shot 示例相当于在推理时给模型提供了条件分布的锚点模型会倾向于输出与示例结构一致的内容。好的 few-shot 示例应该覆盖正常情况也应该覆盖边界情况。只给一个正例等于只告诉模型“照着做”给一个正例加一个反例等于告诉模型“照这个做但不要做成那种”。4.2 正例设计正例要完整、简洁、字段齐全。它展示的是模型应该输出的标准形态。FEW_SHOT_MESSAGES [ { role: user, content: 用户李四下单了一台iPhone 15还买了两个充电器总共付了8999元 }, { role: assistant, content: ( {order_id: UNKNOWN, user_name: 李四, items: [{product_name: iPhone 15, quantity: 1}, {product_name: 充电器, quantity: 2}], total_price: 8999.0} ) } ]注意这里order_id用UNKNOWN而不是省略这告诉模型即使信息缺失也要保持 JSON 结构完整。4.3 反例设计与错误示例反例同样重要甚至更重要。常见错误包括字段类型错误、遗漏字段、夹带解释文字、字段名不一致。反例的核心价值是给模型划定“不可逾越的边界”。FEW_SHOT_MESSAGES.append( { role: user, content: 用户王五买了一本书付了59元 } ) FEW_SHOT_MESSAGES.append( { role: assistant, content: ( 以下是一个错误示例\n {order_id: UNKNOWN, user_name: 王五, items: [{product_name: 书, quantity: 1}], total_price: 59元}\n 错误点quantity应该是整数total_price应该是浮点数 且数字不能附带单位。 ) } )4.4 使用时的注意事项添加正反示例会消耗 token。实际使用时建议把示例压缩到 2 到 4 组优先覆盖最容易出错的边界情况而不是把所有可能场景都塞进去。示例太多种类容易让模型混乱尤其是在上下文长度受限时。面试中回答这一层时可以提到一个细节反例不需要太多一个错误类型给一个示例即可。重点是让模型看到“错误会被指出来”这比单纯堆示例更能提升格式遵循质量。5. 第三层约束原生参数这一层是模型 API 提供的原生结构化能力。不同的模型服务商有不同的参数设计核心思路是在解码阶段就限制输出空间而不是生成之后再清洗。5.1 JSON ModeOpenAI 等模型服务商提供response_format{type: json_object}参数开启后模型被强制生成合法 JSON。这是一个很强的约束但注意它只保证“合法 JSON”不保证“包含你需要的字段”。调用示例from openai import OpenAI client OpenAI(api_keyyour_api_key) response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: ( 你是订单信息抽取Agent。 抽取用户输入中的订单信息输出JSON包含order_id、user_name、items、total_price四个字段。 )}, {role: user, content: 张三买了两杯美式和三块蛋糕共86元} ], response_format{type: json_object}, temperature0.1 ) content response.choices[0].message.content print(content)5.2 JSON Schema 与 Structured Outputs更强的一层是让 API 直接接收 JSON Schema模型会按照这个 Schema 生成内容并且在部分实现中会校验输出是否符合 Schema。这是目前生产环境推荐的做法。以 OpenAI 的 Structured Outputs 为例思路如下from openai import OpenAI client OpenAI(api_keyyour_api_key) order_schema { type: object, properties: { order_id: {type: string}, user_name: {type: string}, items: { type: array, items: { type: object, properties: { product_name: {type: string}, quantity: {type: integer} }, required: [product_name, quantity] } }, total_price: {type: number} }, required: [order_id, user_name, items, total_price] } response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是订单信息抽取Agent}, {role: user, content: 张三买了两杯美式和三块蛋糕共86元} ], response_format{ type: json_schema, json_schema: { name: order_info, schema: order_schema } } )这种方式把字段约束直接传给解码器模型生成total_price时更倾向于输出数字而不是字符串。5.3 Function Calling / Tool Callingfunction calling 是另一种原生结构化输出方案。它让模型选择一个函数并生成符合函数签名的参数。这种方式特别适合工具调用型 Agent模型先决定调用哪个工具再填参数。from openai import OpenAI client OpenAI(api_keyyour_api_key) tools [ { type: function, function: { name: record_order, description: 记录用户订单信息, parameters: { type: object, properties: { order_id: {type: string}, user_name: {type: string}, items: { type: array, items: { type: object, properties: { product_name: {type: string}, quantity: {type: integer} }, required: [product_name, quantity] } }, total_price: {type: number} }, required: [order_id, user_name, items, total_price] } } } ] response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是订单助手}, {role: user, content: 张三买了两杯美式和三块蛋糕共86元} ], toolstools, tool_choice{type: function, function: {name: record_order}}, temperature0.1 ) print(response.choices[0].message.tool_calls)5.4 参数配合使用原生参数时同时要注意temperature和max_tokens。结构化输出场景建议把temperature调低比如 0 到 0.2减少随机性。max_tokens也要留足余量避免 JSON 被截断。截断是结构化输出的隐形杀手模型本来输出是对的结果生成到一半被max_tokens切断下游拿到的就是一个残缺 JSON这种问题 Prompt 永远救不了。6. 第四层约束代码校验与自动修复前面三层做的都是“提高概率”第四层做的是“保证结果”。不管模型输出什么代码校验通过才能进入业务逻辑失败就触发重试或修复。这是四层约束里最刚性的一层也是面试官最看重的一层。6.1 在校验之前先做预处理有些情况下模型已经把 JSON 写对了只是外面包了 Markdown 代码块或解释文字。可以在解析前先做一次轻量清洗把形如json和的包裹符号去掉。但这只是兜底手段不能替代严格校验。import re import json def extract_json(text: str) - dict: # 去掉Markdown代码块标记 text text.strip() text re.sub(r^(?:json)?, , text).strip() text re.sub(r$, , text).strip() return json.loads(text)6.2 用 Pydantic 做字段级校验json.loads()只能保证 JSON 语法合法不能保证字段类型正确。要保证 值正确用 Pydantic 做字段级校验是更稳的做法。from pydantic import BaseModel, ValidationError class OrderItem(BaseModel): product_name: str quantity: int class OrderInfo(BaseModel): order_id: str user_name: str items: list[OrderItem] total_price: float def parse_and_validate(raw_content: str) - OrderInfo: data extract_json(raw_content) return OrderInfo(**data)如果total_price是86元这种字符串OrderInfo(**data)会直接抛出ValidationError根本不会进入业务逻辑。6.3 用 JSON Schema 做跨语言校验如果你不是 Python 技术栈或者需要把 Schema 同时给多个服务用可以用 JSON Schema 标准。几乎所有语言都有对应的校验库。import json import jsonschema from jsonschema import validate with open(order_schema.json, r, encodingutf-8) as f: schema json.load(f) data extract_json(raw_content) validate(instancedata, schemaschema)对应的order_schema.json文件{ type: object, properties: { order_id: {type: string}, user_name: {type: string}, items: { type: array, items: { type: object, properties: { product_name: {type: string}, quantity: {type: integer} }, required: [product_name, quantity] } }, total_price: {type: number} }, required: [order_id, user_name, items, total_price] }6.4 校验失败后重试与修复校验失败后的处理策略非常关键。最简单且有效的方式是把报错信息回传给模型让它自己修复。def generate_structured_output(user_input: str, max_retries: int 3) - OrderInfo: history [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for attempt in range(max_retries): response client.chat.completions.create( modelgpt-4o-mini, messageshistory, response_format{type: json_object}, temperature0.1 ) raw response.choices[0].message.content try: order parse_and_validate(raw) return order except (json.JSONDecodeError, ValidationError) as e: history.append({role: assistant, content: raw}) history.append({ role: user, content: ( f你上一次的输出无法通过校验。错误信息{e}\n f上一次输出{raw}\n 请修正后重新输出只输出合法的JSON对象。 ) }) raise RuntimeError(f连续 {max_retries} 次校验失败请检查模型或提示词)这套重试逻辑在生产环境里很有价值。因为它把模型自身犯错后的“自我修正能力”也变成了约束层的一部分。实现上还可以增加超时控制、失败计数和告警。重试不是无限循环达到阈值后要进入人工处理或降级路径。6.5 校验层的架构位置校验层不应该只出现在最终输出。当一个 Agent 内部有多个步骤时每一步的工具调用参数都应该校验。比如检索 Agent 决定调用搜索工具搜索关键词必须格式正确数据分析 Agent 决定生成代码代码必须能编译。这些都可以复用一个校验框架定义 Schema、校验、失败重试、进入下一步。7. 四层约束综合实战订单信息提取 Agent下面用一个完整案例说明四层约束如何协作。假设我们需要做一个“订单提取 Agent”目标是从用户任意表达中提取订单信息并写入数据库。第 1 步定义 Schema同时用于 Prompt、原生参数和代码校验三处ORDER_SCHEMA { type: object, properties: { order_id: {type: string}, user_name: {type: string}, items: { type: array, items: { type: object, properties: { product_name: {type: string}, quantity: {type: integer} }, required: [product_name, quantity] } }, total_price: {type: number} }, required: [order_id, user_name, items, total_price] }第 2 步组装 System Prompt包含角色、格式说明、Schema 和正反示例SYSTEM_PROMPT 你是订单信息抽取Agent输出内容必须是合法JSON对象。 不要输出解释文字不要使用Markdown代码块。 输出结构必须符合以下Schema {json.dumps(ORDER_SCHEMA, ensure_asciiFalse)} 正例 输入用户李四买了一台iPhone 15和一个充电器共8999元 输出{order_id: UNKNOWN, user_name: 李四, items: [{product_name: iPhone 15, quantity: 1}, {product_name: 充电器, quantity: 1}], total_price: 8999.0} 反例 输入用户王五买了一本书59元 输出{order_id: UNKNOWN, user_name: 王五, items: [{product_name: 书, quantity: 1}], total_price: 59元} 这是错误输出quantity和total_price类型错误。 .format(json.dumps(ORDER_SCHEMA, ensure_asciiFalse))第 3 步调用时叠加原生参数并在返回后做代码校验import json from openai import OpenAI from pydantic import BaseModel, ValidationError client OpenAI(api_keyyour_api_key) def parse_and_validate(raw_content: str): data json.loads(raw_content) # 这里可以用Pydantic或JSON Schema校验 from jsonschema import validate validate(instancedata, schemaORDER_SCHEMA) return data def run_agent(user_input: str, max_retries: int 3) - dict: history [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for attempt in range(max_retries): response client.chat.completions.create( modelgpt-4o-mini, messageshistory, response_format{type: json_object}, temperature0.1 ) raw response.choices[0].message.content try: return parse_and_validate(raw) except Exception as e: history.append({role: assistant, content: raw}) history.append({ role: user, content: f输出校验失败{e}请重新输出JSON。 }) raise RuntimeError(重试失败)在这个案例里四层约束各司其职Prompt 告诉模型任务和格式正反示例告诉模型好的长什么样、坏的会报错response_format让模型在解码阶段就尽量只生成合法 JSON最终validate()保证只有合法数据才能进入下一步。这就是工程上应该有的完整闭环。验证这一步是否成功不只看一两次输出要看一组评估数据。建议准备 20 到 50 条不同表达方式的输入统计格式通过率、字段正确率、平均重试次数再和只加一层约束的效果做对比。8. 面试加分项常见追问与高质量回答面试官抛出“如何让 Agent 稳定输出结构化内容”后通常会追加几个问题来区分“背概念”和“真做过”。8.1 追问 1如果模型连续重试三次都失败怎么办这是最经典的追问。低水平回答“那就不停重试。”高水平回答要分情况先看是不是模型太弱换一个指令遵循能力更强的模型再试一次再看是不是 Schema 太过复杂尝试把嵌套层级变浅或者拆成多个子任务再看是不是输入本身无法提取目标字段这时应该返回“无法解析”而不是硬编一个错误结果最后要有降级路径放入人工处理队列同时记录失败样本后续用这些样本做评估和 Prompt 优化。重试不是目的收敛才是目的。你已经设置了重试上限超限后走人工兜底这才是一个合格 Agent 工程的完整闭环。8.2 追问 2四层约束都用了成本会不会很高这个问题考察工程权衡。回答思路Prompt 和示例只增加输入 token成本最低原生参数基本不增加 token成本增加很小代码校验纯粹是本地计算几乎没有成本成本主要来自重试。重试一次等于多一次模型调用所以要用“重试次数统计”来监控每层约束的效果不断优化 Prompt 和示例压低重试率。8.3 追问 3怎么量化结构化输出的稳定性这是区分“做过”和“没做过”的关键问题。可以这样回答建立评估集包含常见输入、边界输入、恶意输入每次修改 Prompt 或升级模型都跑一遍评估集记录三个指标格式通过率、字段正确率、平均重试次数用这些指标决定是否上线新 Prompt 或新模型。回答里带出“评估集”和“回归”这两个词面试官基本能确认你有生产经验。8.4 追问 4流式输出场景下结构化输出怎么做流式输出时无法等全部文本生成后再校验。简单场景可以先关闭流式等完整 JSON 返回再解析。如果必须流式可以用两种策略一是模型先输出一段不展示的“结构化草稿”解析成功后再以流式方式输出给用户二是对流式内容做按 token 的增量解析在遇到结构错误时截断并触发修复。生产环境建议优先用第一种语义更稳定实现也更简单。9. 工程落地最佳实践面试题方法落地到项目里还有一些容易被忽略的工程细节。建立评估集。不要让 Prompt 凭感觉优化。项目开始就准备一个评估集至少覆盖正常情况、字段缺失情况、极端输入情况。每修改一次 Prompt或者切换一次模型都跑一遍评估用数据说话。记录失败样本。生产环境中所有校验失败的原始输出都应该落日志。这些样本是优化 Prompt 和反例的金矿。定期抽看失败样本你会发现模型在某些输入上存在系统性的偏差针对这些偏差补充正反示例效果立竿见影。监控三个指标格式通过率、平均重试次数、P50/P95 响应延迟。格式通过率反映整体质量重试次数反映 Prompt 和模型配合是否顺畅延迟反映用户体验。这三个指标在一个仪表盘上线上问题一眼就能看出来。设置超时与熔断。模型调用不是本地函数要设置 HTTP 超时时间比如 30 秒或 60 秒。连续失败达到阈值后要有熔断机制避免大量请求同时卡在模型调用上打爆下游系统。人工兜底永远要存在。即使四层约束全上还是会有少量疑难输入无法解析。这时不要让任务无限重试而是把任务标记为“需要人工处理”扔进人工队列。合规与安全边界。如果 Agent 处理的是真实用户的订单、个人信息或受版权保护的素材必须确保数据在合法授权范围内使用。涉及人脸、声音、文件内容时要明确告知用户用途并获得授权。结构化输出本身不涉及敏感能力但被提取的数据如果涉及隐私存储和传输都要遵循最小化原则。10. 高频踩坑点速查表踩坑点现象原因解决方案只写 Prompt不加原生参数偶发 JSON 语法错误典型生成概率问题叠加response_format或 JSON Schema没给反例模型输出格式对但类型不对模型缺少边界认知补一个反例明确错误点max_tokens设置太小JSON 被截断语法错误生成到一半被切断调大max_tokens或分块输出temperature设置太高输出忽好忽坏采样随机性过大降到 0.1 以下只校验 JSON 语法字段类型错误仍流入业务没做字段级校验用 Pydantic 或 JSON Schema重试不带上下文重试后错误相同模型不知道错在哪里把错误信息回传给模型重试无上限接口超时、费用失控缺少熔断机制设置最大重试次数超限走人工Schema 与 Prompt 不一致输出字段对不上两处定义漂移用同一份 Schema一处定义多处引用11. 总结与下一步四层约束的答题框架已经从原理、代码到面试追问完整过了一遍。你可以在面试里直接说出这套体系也可以回到项目里逐层检查现在的 Agent 卡在哪一层哪一层最薄弱先补哪一层收益最大。最容易踩的坑往往不是 Prompt 写不好而是只写了 Prompt 就上线缺少原生参数和代码校验两道兜底。建议第一次试验时先做最小闭环准备 10 条测试输入用一个订单抽取场景先只加 Prompt记录纯格式命中率然后加原生参数对比命中率最后加代码校验和重试对比重试后的最终成功率。跑完这组对比你就能直观理解四层约束各自的边界和代价。下一步可以继续扩展的方向是把同样的约束思路迁移到多步 Agent 工具调用、内容生成后处理、多模型切换评估等场景。结构化输出不是某一个模型的特殊能力而是一个可以复用的工程方法值得沉淀成团队内部的标准模板。