1. 从“调个API”到“跑通全链路”一次请求背后的完整工程几个月前我接手了一个内部数据中台的项目需求很直白把业务人员提交的自然语言查询转成结构化数据交给下游报表系统。听起来不就是调个大模型接口吗真正动手才发现“调通接口”和“跑通链路”之间隔着大量的工程细节。今天想把“单次模型请求与数据结构化输出完整链路”这件事从头到尾拆一遍聊聊我在实操中踩过的坑、验证过的方法以及最终沉淀下来的一套可复用的流程。先给刚入门的朋友一个整体认知所谓“单次模型请求与数据结构化输出完整链路”指的是从你构造一条请求发给大模型到模型返回结果再到结果被清洗、校验、转换成程序可直接使用的结构化数据比如JSON、表格、对象的整个过程。它看似只是“发请求-收响应”两步实际上中间包含请求构造、参数调优、响应解析、容错重试、数据校验等多个环节任何一个环节掉链子下游程序都会直接崩给你看。这套东西适合谁如果你是做AI应用开发的工程师或者想在自己项目里接入大模型能力的产品经理、数据分析师又或者正在研究Agent、RAG这类依赖模型输出的架构这篇内容都值得花几分钟读完。我不会只讲概念更多是分享一条实际可落地的路径以及那些文档里不会写清楚的经验。2. 整体链路设计核心环节与方案取舍2.1 一条请求从发起到落地的全流程拆解我在实际项目中把“单次模型请求与数据结构化输出”拆成了五个核心环节。画在纸上就是一条流水线每个环节都有明确的输入和输出。环节核心任务关键产出1. 意图解析与提示词构造把用户原始输入翻译成模型能理解的任务结构化的prompt模板2. 请求参数配置设定模型参数控制生成行为完整的API请求体3. 调用模型接口发送请求并等待响应原始响应文本4. 输出解析与清洗从原始文本中提取目标数据中间态数据5. 数据校验与转换验证数据合法性并转换为目标格式最终结构化数据为什么这个顺序很重要因为每一步都在为下一步铺路。比如第1步如果prompt写得模糊第4步解析时就会遭遇各种格式漂移第2步温度参数设太高第5步的数据合法性校验就会频繁失败。整条链路的稳定性是由最薄弱的那一环决定的而不是最强的。我见过很多团队在模型选型上花大力气却忽略了链路设计结果换了更强的模型输出还是乱七八糟。原因就是他们在第4步和第5步没有建立严格的规则模型输出稍微变化一点解析脚本就挂。2.2 为什么“结构化输出”是AI应用落地的关键门槛自然语言模型天然输出的是文本而程序需要的是数据。这个矛盾是整条链路存在的根本原因。你可以让模型输出“明天北京晴转多云气温12到22度”但你的天气应用需要的是{city: 北京, weather: 晴转多云, temp_low: 12, temp_high: 22}。结构化输出要解决的就是把后者从前者中稳定、可靠地提取出来。这里有两个关键词稳定和可靠。稳定意味着100次请求里有95次以上返回相同结构可靠意味着提取出来的数据在语义上和用户意图一致没有丢失或臆造。我在实践中的一个体会是结构化的核心不是格式而是约束。格式只是外在表现约束才是内在机制。你需要在prompt里约束模型在解析层约束文本在程序层约束数据类型层层递进才能把模型的自由度一点点收窄最终得到可控的产出。2.3 方案选型直接调API、还是上封装框架现在市面上有很多封装好的框架比如LangChain、LlamaIndex它们提供了丰富的输出解析器能自动把模型输出转成Pydantic对象或JSON。那是不是直接用框架就够了我个人的建议是初期必须手写一遍完整链路再用框架优化。原因有两点。第一手写能让你真正理解每个细节——为什么这里要加一个校验为什么那里要设计重试这些因果关系只有亲手踩过坑才能建立。第二框架的输出解析器虽然方便但它们往往在底层做了一些假设比如模型一定返回特定标记一旦你的模型或prompt不满足这个假设排查问题反而更困难。我这边的选型策略是自研核心链路请求构造、输出解析、数据校验在此基础上再考虑要不要引入框架来加速开发。你可以理解成“先学会造轮子再决定要不要用轮子”这样既能保证深度可控又能保持一定的开发效率。3. 核心细节解析从prompt设计到输出约束3.1 提示词模板的工程化设计提示词设计是这个链路里最像“手艺活”的部分但手艺活的背后也有方法论。我在实践中总结了一套“三段式”模板结构稳定性很高。第一段是角色与任务定义告诉模型“你是一个数据提取助手你的任务是从用户输入中提取结构化信息”。第二段是输出格式说明用明确的schema或示例告知模型期望的输出结构。第三段是输入与约束给出原始输入并附加不可违反的规则。这里的关键细节是不要只在prompt里描述格式要给模型一个“示例”。描述是抽象的示例是具体的模型对具体示例的理解准确度远高于抽象描述。我在一个实体抽取任务里对比过加了两个示例之后格式合规率从78%直接拉到了94%。原因很简单模型通过示例学到了“边界情况怎么处理”和“空值怎么表达”这些都是文字描述很难讲清楚的。另一个容易被忽略的细节是系统级指令的优先级设计。模型对指令的理解是有层级的系统消息里的指令优先级最高用户消息次之。所以输出格式的硬性要求应该放在系统消息里而不是用户消息里这样能有效防止用户输入“覆盖”掉格式约束。3.2 输出格式控制的三种主流方法对比在控制模型输出格式这件事上目前主流的方法有三种我各踩过一遍可以给你做个对比。第一种是纯Prompt约束。也就是在提示词里写清楚“请以JSON格式输出”然后靠解析逻辑去兜底。优点是简单不需要改模型和接口缺点是稳定性一般模型偶尔会多输出几句解释文字或者JSON里出现注释、尾逗号这类不合法的东西。第二种是JSON Mode。现在主流模型厂商的API基本都支持比如OpenAI的response_format: {type: json_object}或者国产模型的对应参数。它的原理是在模型解码阶段做约束让模型只输出合法JSON。实际用下来格式乱飞的概率大幅下降但仍然不保证schema一定符合你的预期——它只是保证“合法JSON”不保证“你要的字段”。第三种是Function Calling / Tool Calling。这是目前我用下来最稳的方案。你把输出结构定义成工具函数的参数模型会返回一个结构化的调用请求天然就是合法JSON而且schema由你定义模型会在你的约束内填充。代价是实现复杂度稍高需要处理工具定义和参数回传。我把三者的差异整理成一张表方案稳定性实现复杂度推荐场景纯Prompt约束中等低快速原型JSON Mode较高低通用结构化输出Function Calling高中复杂schema、生产级应用从我目前的生产经验来看除非是特别简单的场景否则最好直接上Function Calling或者至少把JSON Mode作为底线。纯Prompt约束只适合自己调试时用上线风险太大。3.3 JSON Schema定义与Pydantic模型的联动如果你的项目用的是Python大多数AI应用项目都是那有一个配合利器你一定要学会用Pydantic定义模型类然后自动生成JSON Schema再用这个Schema去约束模型输出。Pydantic是Python生态里做数据验证的事实标准它能定义一个带类型注解的数据模型并自动生成对应的JSON Schema文档。这个文档可以直接嵌入到Function Calling的工具定义里告诉模型“这个字段是字符串、那个字段是整数数组”。模型遵循Schema填入数据之后返回结果又可以再用同一个Pydantic模型做一次校验把类型错误、缺失字段在程序层面拦截掉。我在一个实际项目里做过一次对比同一套数据提取任务不用Pydantic校验时脏数据率字段缺失、类型错误、非法枚举值大概是3%~5%加上校验之后降到0.1%以下。这个提升不是模型变强了而是错误不再流向下游在链路中间就被拦截了。这对于生产系统来说是质变。一个小细节Pydantic模型里务必设置extraforbid这样模型输出里如果多出了未定义字段校验直接失败而不是默默忽略。多出来的字段往往是幻觉的产物让它通过只会埋雷。4. 实操过程一次完整请求链路的落地实现4.1 环境准备与依赖安装开始之前先把基础环境准备好。我用的Python版本是3.10需要安装以下依赖示例以OpenAI接口风格为主国产模型的OpenAI兼容接口同样适用。pip install openai pydantic如果你后面要做结果缓存或日志记录再加一个redis或直接先用文件日志。这里我保持最小依赖方便你快速复现。4.2 定义数据结构Pydantic模型先行按照我刚才说的思路第一步永远先定义数据结构而不是先写请求代码。数据结构是整个链路的锚点后面所有环节都围绕它展开。这个例子要提取的数据是“用户查询中的天气意图”from pydantic import BaseModel, Field from typing import List, Literal from datetime import date class WeatherQuery(BaseModel): 从用户查询中提取天气检索意图 city: str Field(description目标城市必须是中国城市名) date: date Field(description查询日期格式为YYYY-MM-DD) intent: Literal[current, forecast, history] Field(description天气查询意图类型) model_config {extra: forbid}这段代码做了什么它定义了三个字段每个字段都描述了类型和语义。Literal限制了intent字段只能是三个枚举值之一date强制要求日期格式。extraforbid负责拒绝未定义字段。4.3 构造请求把Pydantic转成模型可读的Schema接下来要做的是把Pydantic模型转成模型接口能识别的Schema。这里有两种做法一种是用model_json_schema()直接生成JSON Schema另一种是配合Function Calling使用时手动构造工具定义。我推荐后者因为工具定义允许你附加更丰富的描述信息。import json from openai import OpenAI client OpenAI() tools [ { type: function, function: { name: extract_weather_info, description: 从用户的自然语言查询中提取天气检索的三要素信息, parameters: WeatherQuery.model_json_schema(), } } ] response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个信息提取助手请从用户消息中提取结构化参数。}, {role: user, content: 帮我查一下北京后天会不会下雨} ], toolstools, tool_choice{type: function, function: {name: extract_weather_info}}, temperature0, )这里有几个参数我必须单独拎出来说。tool_choice设置为强制调用指定函数这样就杜绝了模型“决定不调用函数”的情况——既然你已经明确是提取任务就不应该给它“拒绝提取”的自由。temperature0为什么重要因为提取任务是确定性的你不希望同样的输入在两次请求里得到不同结果。温度越高输出的随机性越大对结构化提取来说百害无一利。4.4 解析响应从API返回值中剥出JSON拿到API的响应之后要做的事情是从嵌套的对象结构里剥出实际的JSON文本。这个环节看着简单其实很多人会在这里出错——直接打印response.choices[0].message.content发现是None懵了。原因是你用了工具调用模型的实际输出不在content里而在tool_calls里。正确做法是tool_call response.choices[0].message.tool_calls[0] arguments tool_call.function.arguments print(arguments) # 输出: {city: 北京, date: 2025-01-20, intent: forecast}到这一步你已经拿到了一个JSON字符串但还没法直接当数据用——下一步校验才是关键。4.5 数据校验用同一个模型做二次拦截JSON字符串拿到手直接用json.loads转成字典就完事了吗不行。json.loads只保证“这是合法JSON”不保证“这个JSON符合业务约束”。city是不是中文城市名date是不是合法日期intent是不是在枚举范围内这些json.loads统统不管。你需要用之前定义的Pydantic模型再做一次校验from pydantic import ValidationError try: weather WeatherQuery.model_validate_json(arguments) print(weather) except ValidationError as e: # 记录结构化错误日志 print(格式校验失败:, e.json())这一步会把非法的数据全部拦截。比如模型输出了{city: 北京, date: 2025-13-45, intent: sunny}WeatherQuery模型会拒绝它因为date不是有效日期、intent不在枚举范围内。这就是我在前面反复强调的“双重校验”——模型层靠Schema约束程序层靠Pydantic兜底。我实际测试过加了这一步之后脏数据完全无法流入下游逻辑排错时间大幅减少。4.6 完整代码串联把上面几段串成一个完整的可运行函数方便你整体把握import json from typing import Type, TypeVar from pydantic import BaseModel T TypeVar(T, boundBaseModel) def structured_extract(user_input: str, model_type: Type[T]) - T: 从用户输入中提取结构化数据返回Pydantic对象 client OpenAI() tools [{ type: function, function: { name: extract_info, description: f从用户消息中提取 {model_type.__name__} 定义的结构化信息, parameters: model_type.model_json_schema(), } }] response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是信息提取助手严格按给定schema返回参数。}, {role: user, content: user_input} ], toolstools, tool_choice{type: function, function: {name: extract_info}}, temperature0, ) arguments response.choices[0].message.tool_calls[0].function.arguments return model_type.model_validate_json(arguments) # 使用示例 result structured_extract(深圳最近三天的天气适合穿什么, WeatherQuery) print(result)这个函数只有二十几行代码但它串起了整条链路schema定义、请求构造、工具调用、响应解析、数据校验。你只需要换掉Pydantic模型和prompt里的任务描述这个骨架就能复用到几乎所有的结构化提取场景。5. 链路稳定性保障重试、容错与日志5.1 网络异常与API错误的分类处理单次请求相比批量任务有一个优势上下文简单、依赖少但它同样要面对网络抖动、API限流、服务端超时这些非业务层面的问题。我把可能出现的错误分成了三类分别处理。第一类是网络层错误比如连接超时、DNS解析失败。这类错误通常是瞬时的重试往往能解决。第二类是API错误比如限流429、服务端错误500、503这类错误也值得重试但要注意控制频率。第三类是数据校验错误比如模型返回的参数schema不匹配这类错误重试的意义不大因为大概率是prompt或schema本身有问题需要人工介入。我个人的重试策略是前两类采用指数退避算法第一次等1秒第二次等2秒第三次等4秒最多重试3次。第三类不重试直接抛给上层处理。为什么不用固定间隔重试因为瞬时故障的发生往往是集中式的大家都在失败疯狂重试只会加剧服务端压力。5.2 结构化解析的兜底策略即便用了Function Calling也不能保证100%的返回结果都能被正常解析。比如极端情况下模型可能返回一个空的tool_calls数组或者参数JSON里含有非法字符。这时候你需要一个兜底策略。我的做法是设计一个“三级降级”方案。第一级直接解析tool_calls里的arguments如果成功直接用。第二级如果第一级失败去读message.content看看模型是否把答案写在了普通内容里如果可以按schema解析就用。第三级如果前两级都失败返回一个预定义的空对象并标记该次请求为“解析失败”写入日志。这个兜底策略在我一次线上事故里救了命。那次上游模型接口做了升级有一小部分请求的响应格式发生了变化第一级解析直接崩了。但因为二级兜底的存在整体成功率只降了不到2%没有造成大规模故障。5.3 日志记录把“不可见”的链路变得“可追踪”单次请求看起来简单出了问题却最难排查因为你无法复现现场。怎么解决答案是事无巨细地记录日志。我这边给每一条请求分配一个request_id然后把整个链路的日志串起来。日志记录的信息包括请求时间、prompt的版本号、模型名称、温度参数、原始响应全文、解析后的中间结果、校验结果、耗时以及最终的结构化数据。这样任何一个环节出问题都可以用request_id串联出完整的上下文。踩过一次很深的坑当时我在一个数字抽取任务里发现个别请求返回的城市字段是乱码。如果没有日志这问题根本没法定位因为模型在重放时不一定复现同样的输出。后来翻了日志发现乱码出现在一个特定字符编码的输入上才定位到是上游数据源的编码不一致在进入prompt前没有做归一化处理。没有日志这个问题会变成一笔糊涂账。6. 常见问题与排查技巧实录在实际跑链路的过程中下面这几个问题是出现频率最高的我把排查思路和解决方法列成了一张速查表。问题现象可能原因排查方法解决方案返回的JSON总是多出解释性文字Prompt约束不够或温度过高检查生成参数查看原始响应加温度调低启用JSON Mode或Function Calling必填字段偶尔缺失模型理解偏差或Schema描述不清检查字段description是否准确强化字段描述补充示例值日期格式不统一模型输出格式受输入语言影响检查原始输入文本在Prompt中显式指定格式并做后置校验Pydantic校验总是失败Schema和任务不匹配打印校验错误详情修正Schema定义或者给模型更好的参考示例API请求偶发超时服务端不稳定或请求体过大查看耗时分布配置重试机制压缩prompt长度相同输入返回不同结果温度设置过高核对生成参数将temperature置为0或接近0接着说几个单独的排查故事。第一个是关于“模型输出字段名变化”的坑。有一次我定义了gmt_create这个字段模型有时候返回它有时候返回gmtCreate还有时候返回created_at。问题的根因是训练数据里这些变体都出现过模型在自由生成时会随机选择。解决办法有两个一是在字段description里强调“严格返回原始字段名gmt_create”二是用Pydantic的alias机制接受多个别名但核心字段名不动。两个方案我都试过后者更稳因为不依赖模型响应prompt的意愿。第二个是关于“城市名称标准化”的坑。业务方要求城市名必须是“北京”而不是“北京市”。但模型天然的常识里“北京市”才是全称。一开始我在prompt里加了一条“不要带‘市’字后缀”效果不稳定。后来我换了个思路在Pydantic模型里定义城市为枚举只接受“北京”“上海”“广州”等标准值模型在枚举约束下反而能正确输出。这说明约束越明确模型的表现越稳定。第三个是关于“空值表达不一致”的坑。当用户查询里缺少某个字段时模型有时输出空字符串有时输出null有时干脆省略字段。三种表达进入下游逻辑后行为完全不同。我的解决办法是在prompt里明确规定“缺失字段一律输出null不要省略”同时在Pydantic模型里把字段设为可选Optional[str] None双保险。7. 性能优化与成本控制7.1 控制Token消耗的三个关键点对于单次模型请求链路来说成本主要来自Token消耗而Token消耗集中在输入prompt和输出模型返回的内容。这里有三个控制点。首先是精简prompt。结构化提取场景并不需要长篇大论的角色设定核心信息和示例够了就行。我把同样一个任务从300字prompt精简到150字后准确率没有变化但每次请求的输入Token直接省了一半。然后是限制输出Token。可以在API请求里设置max_tokens上限防止模型因为意外情况输出超长文本。比如一个提取任务正常输出不到100个Token你可以把max_tokens设为300上限足够覆盖就算模型抽风也不会烧太多钱。最后是合理使用缓存。如果同一个用户输入反复出现这在企业内部的固定业务流程里特别常见可以用Redis对输入做hash后缓存对应的结构化输出。命中缓存直接返回既不消耗Token也不消耗延迟。7.2 延迟优化减少不必要的等待单次请求的延迟大头在模型推理时间但小头也不能忽略。我实测过一个复杂的抽取任务模型推理耗时800ms网络传输反而占掉了120ms。优化网络层面能省下不少体感时间。具体做法有两点。第一如果有条件把应用服务器和API服务放在同一个可用区网络延迟能下降一个量级。第二连接复用不要每次请求都新建HTTP连接用连接池技术可以把建连的耗时省掉。这些属于常规后端优化但在AI应用里往往被忽略。另外一个容易忽略的点是不要把链路写成单线程阻塞的。如果同一时间有多个提取请求用asyncio并发发送能极大地提升吞吐量。单次请求的延迟没变但你单位时间能处理的请求数翻很多倍。8. 从单次请求到批处理链路复用的边界聊完了单次请求最后想提一嘴批处理场景。很多读者一开始是单条调用开发完发现要处理的数据变成了一万条怎么办批处理不是简单地把单条逻辑套个for循环就完事你需要考虑三个额外的问题。第一是并发控制。单次请求链路里的重试逻辑在并发场景下需要加信号量限制并发数避免瞬间打满API配额。我一般用asyncio.Semaphore(10)同时跑10个任务看起来保守但胜在稳定。第二是失败隔离。一万条数据里总会有几十条解析失败的不要让这些失败影响整批任务。我的做法是每一条任务独立捕获异常失败的任务单独写入failed队列全部结束后统一分析和重试。第三是断点续跑。批处理跑到一半如果中断了重启时要有办法接着跑而不是从头再来。最简单的方案是给每条数据生成一个唯一ID处理完的结果写库或写文件下次启动时跳过已处理的数据。把单次链路做到万无一失再套上批处理框架就能组合出一个既灵活又稳固的完整数据处理系统。这个扩展路径在这条链路搭建之初就值得想清楚。回到开头那句话调通一个API并不难难的是“跑通一条链路”。每一个环节都有人踩过坑每一个坑都有迹可循。希望这篇拆解能帮你少走一些弯路把那些水下的问题提前浮上来。如果按照文中方案完整跑一遍你对“模型请求”这件事的理解应该能上一个台阶。 大模型结构化输出完整链路：从Prompt设计到数据校验
1. 从“调个API”到“跑通全链路”一次请求背后的完整工程几个月前我接手了一个内部数据中台的项目需求很直白把业务人员提交的自然语言查询转成结构化数据交给下游报表系统。听起来不就是调个大模型接口吗真正动手才发现“调通接口”和“跑通链路”之间隔着大量的工程细节。今天想把“单次模型请求与数据结构化输出完整链路”这件事从头到尾拆一遍聊聊我在实操中踩过的坑、验证过的方法以及最终沉淀下来的一套可复用的流程。先给刚入门的朋友一个整体认知所谓“单次模型请求与数据结构化输出完整链路”指的是从你构造一条请求发给大模型到模型返回结果再到结果被清洗、校验、转换成程序可直接使用的结构化数据比如JSON、表格、对象的整个过程。它看似只是“发请求-收响应”两步实际上中间包含请求构造、参数调优、响应解析、容错重试、数据校验等多个环节任何一个环节掉链子下游程序都会直接崩给你看。这套东西适合谁如果你是做AI应用开发的工程师或者想在自己项目里接入大模型能力的产品经理、数据分析师又或者正在研究Agent、RAG这类依赖模型输出的架构这篇内容都值得花几分钟读完。我不会只讲概念更多是分享一条实际可落地的路径以及那些文档里不会写清楚的经验。2. 整体链路设计核心环节与方案取舍2.1 一条请求从发起到落地的全流程拆解我在实际项目中把“单次模型请求与数据结构化输出”拆成了五个核心环节。画在纸上就是一条流水线每个环节都有明确的输入和输出。环节核心任务关键产出1. 意图解析与提示词构造把用户原始输入翻译成模型能理解的任务结构化的prompt模板2. 请求参数配置设定模型参数控制生成行为完整的API请求体3. 调用模型接口发送请求并等待响应原始响应文本4. 输出解析与清洗从原始文本中提取目标数据中间态数据5. 数据校验与转换验证数据合法性并转换为目标格式最终结构化数据为什么这个顺序很重要因为每一步都在为下一步铺路。比如第1步如果prompt写得模糊第4步解析时就会遭遇各种格式漂移第2步温度参数设太高第5步的数据合法性校验就会频繁失败。整条链路的稳定性是由最薄弱的那一环决定的而不是最强的。我见过很多团队在模型选型上花大力气却忽略了链路设计结果换了更强的模型输出还是乱七八糟。原因就是他们在第4步和第5步没有建立严格的规则模型输出稍微变化一点解析脚本就挂。2.2 为什么“结构化输出”是AI应用落地的关键门槛自然语言模型天然输出的是文本而程序需要的是数据。这个矛盾是整条链路存在的根本原因。你可以让模型输出“明天北京晴转多云气温12到22度”但你的天气应用需要的是{city: 北京, weather: 晴转多云, temp_low: 12, temp_high: 22}。结构化输出要解决的就是把后者从前者中稳定、可靠地提取出来。这里有两个关键词稳定和可靠。稳定意味着100次请求里有95次以上返回相同结构可靠意味着提取出来的数据在语义上和用户意图一致没有丢失或臆造。我在实践中的一个体会是结构化的核心不是格式而是约束。格式只是外在表现约束才是内在机制。你需要在prompt里约束模型在解析层约束文本在程序层约束数据类型层层递进才能把模型的自由度一点点收窄最终得到可控的产出。2.3 方案选型直接调API、还是上封装框架现在市面上有很多封装好的框架比如LangChain、LlamaIndex它们提供了丰富的输出解析器能自动把模型输出转成Pydantic对象或JSON。那是不是直接用框架就够了我个人的建议是初期必须手写一遍完整链路再用框架优化。原因有两点。第一手写能让你真正理解每个细节——为什么这里要加一个校验为什么那里要设计重试这些因果关系只有亲手踩过坑才能建立。第二框架的输出解析器虽然方便但它们往往在底层做了一些假设比如模型一定返回特定标记一旦你的模型或prompt不满足这个假设排查问题反而更困难。我这边的选型策略是自研核心链路请求构造、输出解析、数据校验在此基础上再考虑要不要引入框架来加速开发。你可以理解成“先学会造轮子再决定要不要用轮子”这样既能保证深度可控又能保持一定的开发效率。3. 核心细节解析从prompt设计到输出约束3.1 提示词模板的工程化设计提示词设计是这个链路里最像“手艺活”的部分但手艺活的背后也有方法论。我在实践中总结了一套“三段式”模板结构稳定性很高。第一段是角色与任务定义告诉模型“你是一个数据提取助手你的任务是从用户输入中提取结构化信息”。第二段是输出格式说明用明确的schema或示例告知模型期望的输出结构。第三段是输入与约束给出原始输入并附加不可违反的规则。这里的关键细节是不要只在prompt里描述格式要给模型一个“示例”。描述是抽象的示例是具体的模型对具体示例的理解准确度远高于抽象描述。我在一个实体抽取任务里对比过加了两个示例之后格式合规率从78%直接拉到了94%。原因很简单模型通过示例学到了“边界情况怎么处理”和“空值怎么表达”这些都是文字描述很难讲清楚的。另一个容易被忽略的细节是系统级指令的优先级设计。模型对指令的理解是有层级的系统消息里的指令优先级最高用户消息次之。所以输出格式的硬性要求应该放在系统消息里而不是用户消息里这样能有效防止用户输入“覆盖”掉格式约束。3.2 输出格式控制的三种主流方法对比在控制模型输出格式这件事上目前主流的方法有三种我各踩过一遍可以给你做个对比。第一种是纯Prompt约束。也就是在提示词里写清楚“请以JSON格式输出”然后靠解析逻辑去兜底。优点是简单不需要改模型和接口缺点是稳定性一般模型偶尔会多输出几句解释文字或者JSON里出现注释、尾逗号这类不合法的东西。第二种是JSON Mode。现在主流模型厂商的API基本都支持比如OpenAI的response_format: {type: json_object}或者国产模型的对应参数。它的原理是在模型解码阶段做约束让模型只输出合法JSON。实际用下来格式乱飞的概率大幅下降但仍然不保证schema一定符合你的预期——它只是保证“合法JSON”不保证“你要的字段”。第三种是Function Calling / Tool Calling。这是目前我用下来最稳的方案。你把输出结构定义成工具函数的参数模型会返回一个结构化的调用请求天然就是合法JSON而且schema由你定义模型会在你的约束内填充。代价是实现复杂度稍高需要处理工具定义和参数回传。我把三者的差异整理成一张表方案稳定性实现复杂度推荐场景纯Prompt约束中等低快速原型JSON Mode较高低通用结构化输出Function Calling高中复杂schema、生产级应用从我目前的生产经验来看除非是特别简单的场景否则最好直接上Function Calling或者至少把JSON Mode作为底线。纯Prompt约束只适合自己调试时用上线风险太大。3.3 JSON Schema定义与Pydantic模型的联动如果你的项目用的是Python大多数AI应用项目都是那有一个配合利器你一定要学会用Pydantic定义模型类然后自动生成JSON Schema再用这个Schema去约束模型输出。Pydantic是Python生态里做数据验证的事实标准它能定义一个带类型注解的数据模型并自动生成对应的JSON Schema文档。这个文档可以直接嵌入到Function Calling的工具定义里告诉模型“这个字段是字符串、那个字段是整数数组”。模型遵循Schema填入数据之后返回结果又可以再用同一个Pydantic模型做一次校验把类型错误、缺失字段在程序层面拦截掉。我在一个实际项目里做过一次对比同一套数据提取任务不用Pydantic校验时脏数据率字段缺失、类型错误、非法枚举值大概是3%~5%加上校验之后降到0.1%以下。这个提升不是模型变强了而是错误不再流向下游在链路中间就被拦截了。这对于生产系统来说是质变。一个小细节Pydantic模型里务必设置extraforbid这样模型输出里如果多出了未定义字段校验直接失败而不是默默忽略。多出来的字段往往是幻觉的产物让它通过只会埋雷。4. 实操过程一次完整请求链路的落地实现4.1 环境准备与依赖安装开始之前先把基础环境准备好。我用的Python版本是3.10需要安装以下依赖示例以OpenAI接口风格为主国产模型的OpenAI兼容接口同样适用。pip install openai pydantic如果你后面要做结果缓存或日志记录再加一个redis或直接先用文件日志。这里我保持最小依赖方便你快速复现。4.2 定义数据结构Pydantic模型先行按照我刚才说的思路第一步永远先定义数据结构而不是先写请求代码。数据结构是整个链路的锚点后面所有环节都围绕它展开。这个例子要提取的数据是“用户查询中的天气意图”from pydantic import BaseModel, Field from typing import List, Literal from datetime import date class WeatherQuery(BaseModel): 从用户查询中提取天气检索意图 city: str Field(description目标城市必须是中国城市名) date: date Field(description查询日期格式为YYYY-MM-DD) intent: Literal[current, forecast, history] Field(description天气查询意图类型) model_config {extra: forbid}这段代码做了什么它定义了三个字段每个字段都描述了类型和语义。Literal限制了intent字段只能是三个枚举值之一date强制要求日期格式。extraforbid负责拒绝未定义字段。4.3 构造请求把Pydantic转成模型可读的Schema接下来要做的是把Pydantic模型转成模型接口能识别的Schema。这里有两种做法一种是用model_json_schema()直接生成JSON Schema另一种是配合Function Calling使用时手动构造工具定义。我推荐后者因为工具定义允许你附加更丰富的描述信息。import json from openai import OpenAI client OpenAI() tools [ { type: function, function: { name: extract_weather_info, description: 从用户的自然语言查询中提取天气检索的三要素信息, parameters: WeatherQuery.model_json_schema(), } } ] response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个信息提取助手请从用户消息中提取结构化参数。}, {role: user, content: 帮我查一下北京后天会不会下雨} ], toolstools, tool_choice{type: function, function: {name: extract_weather_info}}, temperature0, )这里有几个参数我必须单独拎出来说。tool_choice设置为强制调用指定函数这样就杜绝了模型“决定不调用函数”的情况——既然你已经明确是提取任务就不应该给它“拒绝提取”的自由。temperature0为什么重要因为提取任务是确定性的你不希望同样的输入在两次请求里得到不同结果。温度越高输出的随机性越大对结构化提取来说百害无一利。4.4 解析响应从API返回值中剥出JSON拿到API的响应之后要做的事情是从嵌套的对象结构里剥出实际的JSON文本。这个环节看着简单其实很多人会在这里出错——直接打印response.choices[0].message.content发现是None懵了。原因是你用了工具调用模型的实际输出不在content里而在tool_calls里。正确做法是tool_call response.choices[0].message.tool_calls[0] arguments tool_call.function.arguments print(arguments) # 输出: {city: 北京, date: 2025-01-20, intent: forecast}到这一步你已经拿到了一个JSON字符串但还没法直接当数据用——下一步校验才是关键。4.5 数据校验用同一个模型做二次拦截JSON字符串拿到手直接用json.loads转成字典就完事了吗不行。json.loads只保证“这是合法JSON”不保证“这个JSON符合业务约束”。city是不是中文城市名date是不是合法日期intent是不是在枚举范围内这些json.loads统统不管。你需要用之前定义的Pydantic模型再做一次校验from pydantic import ValidationError try: weather WeatherQuery.model_validate_json(arguments) print(weather) except ValidationError as e: # 记录结构化错误日志 print(格式校验失败:, e.json())这一步会把非法的数据全部拦截。比如模型输出了{city: 北京, date: 2025-13-45, intent: sunny}WeatherQuery模型会拒绝它因为date不是有效日期、intent不在枚举范围内。这就是我在前面反复强调的“双重校验”——模型层靠Schema约束程序层靠Pydantic兜底。我实际测试过加了这一步之后脏数据完全无法流入下游逻辑排错时间大幅减少。4.6 完整代码串联把上面几段串成一个完整的可运行函数方便你整体把握import json from typing import Type, TypeVar from pydantic import BaseModel T TypeVar(T, boundBaseModel) def structured_extract(user_input: str, model_type: Type[T]) - T: 从用户输入中提取结构化数据返回Pydantic对象 client OpenAI() tools [{ type: function, function: { name: extract_info, description: f从用户消息中提取 {model_type.__name__} 定义的结构化信息, parameters: model_type.model_json_schema(), } }] response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是信息提取助手严格按给定schema返回参数。}, {role: user, content: user_input} ], toolstools, tool_choice{type: function, function: {name: extract_info}}, temperature0, ) arguments response.choices[0].message.tool_calls[0].function.arguments return model_type.model_validate_json(arguments) # 使用示例 result structured_extract(深圳最近三天的天气适合穿什么, WeatherQuery) print(result)这个函数只有二十几行代码但它串起了整条链路schema定义、请求构造、工具调用、响应解析、数据校验。你只需要换掉Pydantic模型和prompt里的任务描述这个骨架就能复用到几乎所有的结构化提取场景。5. 链路稳定性保障重试、容错与日志5.1 网络异常与API错误的分类处理单次请求相比批量任务有一个优势上下文简单、依赖少但它同样要面对网络抖动、API限流、服务端超时这些非业务层面的问题。我把可能出现的错误分成了三类分别处理。第一类是网络层错误比如连接超时、DNS解析失败。这类错误通常是瞬时的重试往往能解决。第二类是API错误比如限流429、服务端错误500、503这类错误也值得重试但要注意控制频率。第三类是数据校验错误比如模型返回的参数schema不匹配这类错误重试的意义不大因为大概率是prompt或schema本身有问题需要人工介入。我个人的重试策略是前两类采用指数退避算法第一次等1秒第二次等2秒第三次等4秒最多重试3次。第三类不重试直接抛给上层处理。为什么不用固定间隔重试因为瞬时故障的发生往往是集中式的大家都在失败疯狂重试只会加剧服务端压力。5.2 结构化解析的兜底策略即便用了Function Calling也不能保证100%的返回结果都能被正常解析。比如极端情况下模型可能返回一个空的tool_calls数组或者参数JSON里含有非法字符。这时候你需要一个兜底策略。我的做法是设计一个“三级降级”方案。第一级直接解析tool_calls里的arguments如果成功直接用。第二级如果第一级失败去读message.content看看模型是否把答案写在了普通内容里如果可以按schema解析就用。第三级如果前两级都失败返回一个预定义的空对象并标记该次请求为“解析失败”写入日志。这个兜底策略在我一次线上事故里救了命。那次上游模型接口做了升级有一小部分请求的响应格式发生了变化第一级解析直接崩了。但因为二级兜底的存在整体成功率只降了不到2%没有造成大规模故障。5.3 日志记录把“不可见”的链路变得“可追踪”单次请求看起来简单出了问题却最难排查因为你无法复现现场。怎么解决答案是事无巨细地记录日志。我这边给每一条请求分配一个request_id然后把整个链路的日志串起来。日志记录的信息包括请求时间、prompt的版本号、模型名称、温度参数、原始响应全文、解析后的中间结果、校验结果、耗时以及最终的结构化数据。这样任何一个环节出问题都可以用request_id串联出完整的上下文。踩过一次很深的坑当时我在一个数字抽取任务里发现个别请求返回的城市字段是乱码。如果没有日志这问题根本没法定位因为模型在重放时不一定复现同样的输出。后来翻了日志发现乱码出现在一个特定字符编码的输入上才定位到是上游数据源的编码不一致在进入prompt前没有做归一化处理。没有日志这个问题会变成一笔糊涂账。6. 常见问题与排查技巧实录在实际跑链路的过程中下面这几个问题是出现频率最高的我把排查思路和解决方法列成了一张速查表。问题现象可能原因排查方法解决方案返回的JSON总是多出解释性文字Prompt约束不够或温度过高检查生成参数查看原始响应加温度调低启用JSON Mode或Function Calling必填字段偶尔缺失模型理解偏差或Schema描述不清检查字段description是否准确强化字段描述补充示例值日期格式不统一模型输出格式受输入语言影响检查原始输入文本在Prompt中显式指定格式并做后置校验Pydantic校验总是失败Schema和任务不匹配打印校验错误详情修正Schema定义或者给模型更好的参考示例API请求偶发超时服务端不稳定或请求体过大查看耗时分布配置重试机制压缩prompt长度相同输入返回不同结果温度设置过高核对生成参数将temperature置为0或接近0接着说几个单独的排查故事。第一个是关于“模型输出字段名变化”的坑。有一次我定义了gmt_create这个字段模型有时候返回它有时候返回gmtCreate还有时候返回created_at。问题的根因是训练数据里这些变体都出现过模型在自由生成时会随机选择。解决办法有两个一是在字段description里强调“严格返回原始字段名gmt_create”二是用Pydantic的alias机制接受多个别名但核心字段名不动。两个方案我都试过后者更稳因为不依赖模型响应prompt的意愿。第二个是关于“城市名称标准化”的坑。业务方要求城市名必须是“北京”而不是“北京市”。但模型天然的常识里“北京市”才是全称。一开始我在prompt里加了一条“不要带‘市’字后缀”效果不稳定。后来我换了个思路在Pydantic模型里定义城市为枚举只接受“北京”“上海”“广州”等标准值模型在枚举约束下反而能正确输出。这说明约束越明确模型的表现越稳定。第三个是关于“空值表达不一致”的坑。当用户查询里缺少某个字段时模型有时输出空字符串有时输出null有时干脆省略字段。三种表达进入下游逻辑后行为完全不同。我的解决办法是在prompt里明确规定“缺失字段一律输出null不要省略”同时在Pydantic模型里把字段设为可选Optional[str] None双保险。7. 性能优化与成本控制7.1 控制Token消耗的三个关键点对于单次模型请求链路来说成本主要来自Token消耗而Token消耗集中在输入prompt和输出模型返回的内容。这里有三个控制点。首先是精简prompt。结构化提取场景并不需要长篇大论的角色设定核心信息和示例够了就行。我把同样一个任务从300字prompt精简到150字后准确率没有变化但每次请求的输入Token直接省了一半。然后是限制输出Token。可以在API请求里设置max_tokens上限防止模型因为意外情况输出超长文本。比如一个提取任务正常输出不到100个Token你可以把max_tokens设为300上限足够覆盖就算模型抽风也不会烧太多钱。最后是合理使用缓存。如果同一个用户输入反复出现这在企业内部的固定业务流程里特别常见可以用Redis对输入做hash后缓存对应的结构化输出。命中缓存直接返回既不消耗Token也不消耗延迟。7.2 延迟优化减少不必要的等待单次请求的延迟大头在模型推理时间但小头也不能忽略。我实测过一个复杂的抽取任务模型推理耗时800ms网络传输反而占掉了120ms。优化网络层面能省下不少体感时间。具体做法有两点。第一如果有条件把应用服务器和API服务放在同一个可用区网络延迟能下降一个量级。第二连接复用不要每次请求都新建HTTP连接用连接池技术可以把建连的耗时省掉。这些属于常规后端优化但在AI应用里往往被忽略。另外一个容易忽略的点是不要把链路写成单线程阻塞的。如果同一时间有多个提取请求用asyncio并发发送能极大地提升吞吐量。单次请求的延迟没变但你单位时间能处理的请求数翻很多倍。8. 从单次请求到批处理链路复用的边界聊完了单次请求最后想提一嘴批处理场景。很多读者一开始是单条调用开发完发现要处理的数据变成了一万条怎么办批处理不是简单地把单条逻辑套个for循环就完事你需要考虑三个额外的问题。第一是并发控制。单次请求链路里的重试逻辑在并发场景下需要加信号量限制并发数避免瞬间打满API配额。我一般用asyncio.Semaphore(10)同时跑10个任务看起来保守但胜在稳定。第二是失败隔离。一万条数据里总会有几十条解析失败的不要让这些失败影响整批任务。我的做法是每一条任务独立捕获异常失败的任务单独写入failed队列全部结束后统一分析和重试。第三是断点续跑。批处理跑到一半如果中断了重启时要有办法接着跑而不是从头再来。最简单的方案是给每条数据生成一个唯一ID处理完的结果写库或写文件下次启动时跳过已处理的数据。把单次链路做到万无一失再套上批处理框架就能组合出一个既灵活又稳固的完整数据处理系统。这个扩展路径在这条链路搭建之初就值得想清楚。回到开头那句话调通一个API并不难难的是“跑通一条链路”。每一个环节都有人踩过坑每一个坑都有迹可循。希望这篇拆解能帮你少走一些弯路把那些水下的问题提前浮上来。如果按照文中方案完整跑一遍你对“模型请求”这件事的理解应该能上一个台阶。