1. 422 不是网络问题是协议问题先说个结论遇到 422 的时候别急着怀疑网络、别重启服务、别在 API Key 上反复折腾问题几乎都出在请求体本身。HTTP 422 的语义是 Unprocessable Entity翻译成人话就是——服务器接收到了你的请求语法没问题但语义上过不去校验。放到大模型接口这个场景里就是你的消息序列没按协议规定的格式组织好服务端在校验层直接给你拦下来了。我最初接手这个项目时第一次遇到 deepseek-v4.1-flash 报 422第一反应是去翻网络代理日志查超时重试折腾了半小时。后来把响应体完整打出来才看到具体提示大意是 tool role 消息的 content 字段触发了非空校验。那一刻我才意识到这压根不是基础设施的问题是调用方对 tool calling 协议的细节理解有偏差。很多开发者对 422 的认知停留在“参数错误”这个层面但实际踩坑时会发现这类错误往往藏得很深。尤其是当你的业务场景涉及 function calling / tool calling 时接口校验的是整个消息数组的结构闭环任何一个角色顺序错位、字段类型不对、ID 对不上号都会在最后一刻爆出 422。这篇文章就把我在模拟项目 X 里完整踩过的坑、调试过程和最终的正确写法整理出来希望帮你少走弯路。需要先说清楚适合谁来读凡是接 DeepSeek 这类 OpenAI 兼容接口、并且业务中要用到工具调用查数据库、调外部 API、执行计算等的开发者这篇文章是为你写的。如果你只是单纯做文本对话、不涉及 tool calling那 422 的概率其实很低但了解一下消息协议的设计思路也有好处。2. tool 角色消息的正确姿势先搞懂消息序列2.1 tool calling 的消息闭环要理解为什么 tool 角色的 content 会被校验得先清楚一次完整的工具调用在消息层面长什么样。大模型接口不是无状态闲聊它要求你每次调用都携带完整的历史消息上下文。正常情况下一次接到工具调用的完整消息序列是这样的系统消息可选的 system 角色定义行为边界。用户消息user 角色提出需求比如“帮我查一下这个订单的状态”。助手消息assistant 角色它不直接给答案而是返回一个 tool_calls 数组里面声明“我需要调用某个函数参数是这样的”。工具消息tool 角色你把函数执行的结果放进来告诉模型“刚才那个调用的返回结果是什么”。最终助手消息assistant 角色模型根据工具返回的结果生成面向用户的最终回答。注意第四步这一步的 tool 角色消息在协议层面是一个承上启下的关键节点。它承接第三步里 assistant 生成的 tool_call_id启下给模型提供函数执行结果。如果这个环节的消息格式有问题服务端会判定为你没有正确履行工具调用的闭环协议于是抛出 422。有人可能会问为什么前几步都好好的一加 tool 消息就挂原因是在 OpenAI 兼容协议里assistant 的 tool_calls 与后续的 tool 消息是强关联的。服务端在解析请求时会先扫描整个消息数组中所有 assistant 角色带 tool_calls 的消息然后在后续消息里寻找对应的 tool 角色消息并逐一比对 tool_call_id。任何一个 tool_call_id 找不到对应关系、或者出现的顺序不合法整个请求就会被判定为“不可处理”。2.2 content 非空校验到底在查什么回到标题里那个核心报错tool 角色 content 非空校验失败。这里要敲黑板了很多人第一次看到这个提示会下意识理解为——“tool 消息里的 content 字段不能为空你必须给个返回值”。这个理解是反的。我在实际调试中确认DeepSeek 的 v4.1-flash 接口在这条校验规则上的设计是tool 角色的 content 字段必须为空字符串不能是 null也不能是实际文本内容。为什么这跟大多数人的直觉相反所以特别容易踩坑。原因要从协议兼容性说起。OpenAI 的 tool calling 协议里tool 角色消息的标准结构是{role: tool, tool_call_id: xxx, content: 函数返回的字符串}。这是原版协议的定义content 放的是函数返回值。但 DeepSeek 在实现 v4.1-flash 这个模型服务时可能为了内部处理和某些下游兼容性考虑调整了校验逻辑——它要求 tool 消息的 content 必须是空字符串真正的结果内容要走别的字段传递或者模型会忽略这部分文本由后续消息承载。这个设计初看很反直觉但实际有它的道理。你可以把 tool 消息理解为一个“凭证”或者“握手信号”它存在的意义只是告诉服务端“我已经拿到了工具返回结果请你继续”。至于结果内容本身可以由调用方在下一轮 user 消息里附带也可以由服务端内部自行处理。如果 content 字段被塞入了业务文本反而会造成语义歧义——到底哪个字段是权威内容空字符串就是个干干净净的约定。注意不同版本的模型接口可能对这条规则的实现不同。我在别的一些模型上试过tool 角色 content 传实际内容是可以的。唯独在这个模型的接口上content 非空直接 422。这个差异非常坑特别是做过其他平台适配的开发者最容易带着旧习惯踩进来。3. 触发 422 的 5 种常见姿势与复现3.1 姿势一assistant 没回 tool_callstool 消息却先到了这是我自己最早踩的坑。当时我的流程代码里有个 bug工具函数提前执行了结果消息组装时直接拼了一条 tool 角色消息进数组但前面的 assistant 消息根本没有声明过任何 tool_calls。服务端扫描时发现tool 消息找不到对应的 tool_call_id直接判定非法。复现路径很简单messages [ {role: system, content: You are a helpful assistant.}, {role: user, content: 查询订单 10086 的状态}, {role: tool, tool_call_id: call_abc, content: } # 前面没有对应的assistant.tool_calls ]这个请求发过去必然 422。因为服务端拿着call_abc去前面的消息里找翻遍所有 assistant 消息的 tool_calls 数组找不到这个 ID于是整个请求作废。这个错误很隐蔽因为你单看某一条消息格式完全没问题字段名、角色名都正确。但只要放在整个消息序列里看它的前置条件不存在协议闭环就断了。3.2 姿势二content 传了 null 或非字符串类型还有一种常见情况代码里组装消息时工具返回的结果是 null或者你用了 None / null 直接作为 content 的值。这也会触发校验失败因为协议要求 content 是字符串类型哪怕是空字符串也行但 null 不行。比如这样messages.append({ role: tool, tool_call_id: result.tool_call_id, content: None # 类型错误 })这个问题的本质是类型校验。服务端在做字段校验时如果发现 content 不是 string 类型直接报 422。解决办法很简单确保 content 一定是字符串没有返回值就传有返回值但不需要文本语义时也传。有些人会问那函数返回值放哪这就要看你的业务数据流了。如果是给模型看的你可以在工具执行后把结果拼到下一轮 user 消息里。如果模型本身只是要一个执行完成的信号那 tool 消息的 content 为空完全不影响后续生成。3.3 姿势三content 非空字符串这是标题里提到的那个场景。举例说明假设你的工具返回了一段 JSON 字符串你原样塞进了 tool 消息的 contentmessages.append({ role: tool, tool_call_id: call_abc, content: {status: success, order: 10086} })这个请求发出去很大概率就是 422报错信息会明确指向 content 非空校验失败。为什么如前面所说这个接口的设计要求 tool 角色 content 必须为空字符串。你传了实际内容违反了约定。我当时一度很困惑OpenAI 官方文档明明说 content 放工具结果为什么这个接口不行后来查了项目里的历史 issue 和更新日志才知道这个模型的 tool calling 实现走的是内部精简链路content 字段被要求置空函数结果通过其他协商字段传递。服务端的校验就卡在这里。所以正确的做法是把工具返回结果放到下一步的 user 消息里或者通过自定义字段传递。tool 消息本身的 content 一律传。3.4 姿势四tool_call_id 对不上还有一种情况工具执行过程中如果你做了异步并发调用返回结果的顺序乱了你把 tool_call_id 搞混了也会 422。服务端会拿你的 tool_call_id 跟前面 assistant 消息里声明的 ID 比对只要不一致立刻判定非法。好在我当时是串行调用没踩这个坑但群里有人问过类似问题。并发工具调用的场景下assistant 可能一次返回多个 tool_calls比如同时查订单和查库存。你必须以 assistant 返回的 tool_calls 数组里的 id 为准逐一对应地和 tool 消息配对顺序错位、ID 错配都会触发 422。这里有个排查技巧把 assistant 返回的完整 JSON 先打日志然后从里面提取 tool_calls 的 id 列表再对照你组装 tool 消息时使用的 id 列表一致性检查通过后再发起第二轮请求。3.5 姿势五多轮历史没带全最后一个比较隐蔽的场景发生在多轮对话里。假设第一轮你已经完成了一次工具调用assistant 给出了最终答案。第二轮用户继续问“那这个订单的物流呢”你组装消息时没把第一轮完整的 tool_calls / tool 消息对带上只带了 assistant 的最终文本回复。这时候服务端一检查发现这一轮请求里存在“孤立的”tool 消息或“无响应”的 tool_calls也可能触发校验失败。这类问题的排查难度更高因为报错不一定明确指向“历史消息缺失”可能就是笼统的 422。我的经验是只要涉及工具调用就完整保留每一轮的消息数组不要做任何截断和重写。你可以在内存里维护一个长上下文列表每轮结束后把新产生的 assistant 消息、tool 消息、最终 assistant 消息都追加进去下一轮直接全量带上。4. 正确写法从请求体到 SDK 调用4.1 手写 HTTP 请求的正确请求体先说最底层的方式方便理解协议本质。不管你是用 requests、curl 还是别的 HttpClient都建议先按下面这个结构组织请求体。我以一次真实场景为例用户要查订单状态工具函数名叫get_order_status。完整的请求体如下messages参数太长写进curl会有shell转义问题容易出错所以我这里给一段 Python requests 的示例import requests import json url https://api.example.com/v1/chat/completions api_key your-api-key # 第一轮让模型决定是否调用工具 messages [ {role: system, content: 你是一个订单助手可以查询订单状态。}, {role: user, content: 帮我查一下订单 10086 的状态} ] payload { model: deepseek-v4.1-flash, messages: messages, tools: [ { type: function, function: { name: get_order_status, description: 查询订单状态, parameters: { type: object, properties: { order_id: {type: string} }, required: [order_id] } } } ] } # 第一次请求 resp requests.post(url, headers{ Authorization: fBearer {api_key}, Content-Type: application/json }, jsonpayload) assistant_msg resp.json()[choices][0][message] # 假设模型返回了 tool_calls提取第一个 tool_call tool_call assistant_msg[tool_calls][0] tools_payload { type: function, function: { name: tool_call.function.name, # 实际业务里这里是安全执行你的真实函数 arguments: json.loads(tool_call.function.arguments) } } # 模拟执行函数返回结果 result {order_id: 10086, status: 已发货, eta: 明天到达} # 第二轮传入 assistant 消息 tool 消息注意 content 为空字符串 messages.append(assistant_msg) # 注意assistant 消息必须原样带回 tool_calls messages.append({ role: tool, tool_call_id: tool_call.id, # 必须是 assistant 返回的那个 id content: # 关键这里必须为空字符串 }) # 如果你需要把工具结果给模型看到放到这里 messages.append({ role: user, content: f工具返回结果{json.dumps(result, ensure_asciiFalse)}。请根据结果回答用户。 }) payload[messages] messages # 第二轮请求 resp2 requests.post(url, headers{ Authorization: fBearer {api_key}, Content-Type: application/json }, jsonpayload) print(resp2.json()[choices][0][message][content])重点看两个地方。第一个是消息顺序assistant 消息必须原样带回它的 tool_calls 字段不能丢。第二个是 tool 消息的 content 必须为空字符串工具返回的实际内容是通过一条新的 user 消息传给模型的。这里解释一下为什么我会选择把结果放在 user 消息里而不依赖模型自己理解“空白 tool 消息”。因为我实际测下来的结果是content 置空后如果后续没有携带工具结果模型要么不知道工具执行得怎么样要么会自行脑补一个结果这在你需要精确传递结构化数据时是致命的。把结果以 text 形式放在 user 消息里模型能明确看到回答质量会稳定很多。当然如果你的场景只是“让模型知道工具已完成”那不加这条 user 消息也行但记得多测几轮确保行为符合预期。4.2 用 SDK 的推荐写法如果你是用官方 SDK 或 OpenAI 兼容 SDK写法会简洁一些但核心约束不变。我自己用的是 Python openai 库风格的 sdk代码大致长这样from openai import OpenAI client OpenAI(api_keyyour-api-key, base_urlhttps://api.example.com/v1) # 第一轮请求 response client.chat.completions.create( modeldeepseek-v4.1-flash, messages[ {role: system, content: 你是一个订单助手可以查询订单状态。}, {role: user, content: 帮我查一下订单 10086 的状态} ], tools[{ type: function, function: { name: get_order_status, description: 查询订单状态, parameters: { type: object, properties: { order_id: {type: string} }, required: [order_id] } } }] ) assistant_message response.choices[0].message tool_call assistant_message.tool_calls[0] # 模拟执行工具函数 result {order_id: 10086, status: 已发货} # 第二轮请求注意 tool 消息 content 为空字符串 second_response client.chat.completions.create( modeldeepseek-v4.1-flash, messages[ {role: system, content: 你是一个订单助手可以查询订单状态。}, {role: user, content: 帮我查一下订单 10086 的状态}, assistant_message, # 原样传回包含 tool_calls { role: tool, tool_call_id: tool_call.id, content: }, { role: user, content: f工具返回结果{result}。请根据结果回答。 } ], tools[{...}] # 可以继续传入 ) print(second_response.choices[0].message.content)SDK 的好处是assistant_message 对象可以原样放进 messages 数组不用手动构造字典减少低级错误。但要注意SDK 不会帮你决定 tool 消息的 content 是什么这个业务判断必须自己做。传空字符串是你与这个模型接口之间的约定SDK 无法替你兜底。另外一个容易忽略的点即便 SDK 支持自动把 assistant_message 序列化成字典你也得确认序列化后的 tool_calls 字段没有被丢弃。某些 SDK 在把 message 对象转 dict 时可能会把 null 字段省略掉如果 assistant 的 tool_calls 被省略第二轮请求照样会触发 422。我的经验是直接把 response.choices[0].message 原对象放进列表让 SDK 自己处理不要手动构造。提示工具函数的 arguments 字段在协议里是 JSON 字符串。如果你在业务里用了类型化的函数调用库记得在传给接口前把 dict 转成 json.dumps在接收时用 json.loads 解析回来。这个字段类型错了也会变成 422。4.3 如何快速定位是哪种校验失败422 的报错信息有时候很直接有时候很笼统。如果你拿到的是笼统的报错可以用下面这个方法很快就能定位问题也是我在排障时发现最高效的手段。第一步把完整的请求体打印出来重点看消息数组里每条消息的 role、content、tool_call_id 和 tool_calls 字段。第二步自己写一个一致性检查脚本遍历消息数组按下面规则检查每条 tool 消息向前找是否存在对应的 assistant 消息声明了相同 id 的 tool_call每条 assistant 消息的 tool_calls 数组里的 id向后找是否都有对应的 tool 消息每条 tool 消息的 content 字段是否为字符串且值等于空字符串是否出现内容为 null 的 content 或缺失 content 字段。我实际用的是下面这个简化脚本能覆盖 80% 的 422 问题def validate_messages(messages): tool_call_ids set() for msg in messages: role msg.get(role) if role assistant and msg.get(tool_calls): for tc in msg[tool_calls]: tool_call_ids.add(tc[id]) if role tool: content msg.get(content, None) if not isinstance(content, str) or content ! : return ftool消息content应为空字符串当前: {repr(content)} if msg.get(tool_call_id) not in tool_call_ids: return ftool_call_id {msg.get(tool_call_id)} 未在之前的 assistant 消息中声明 return None把 messages 数组扔进这个函数如果有返回值那一行日志基本就是服务端校验的报错源头。这比反复发请求试错要快得多。还有一个很实用的技巧用 curl 直接发一个最简化的请求体做对照实验。比如只发 system user assistant带 tool_calls toolcontent 为空串这四层消息不带任何业务参数。如果这个最小序列能通说明你的业务组装逻辑出了问题如果这个最小序列也 422那你该检查接口版本或者模型名是否写错了。这个二分定位法在排障时极其有效帮我快速锁定过不少问题。5. 常见问题速查表与最后的一点心得把这次踩坑涉及的核心规则整理成下面这张表方便你复制到项目文档里团队协作时也能减少踩坑概率。场景错误示例正确姿势原因tool 消息 content 字段content 填了 JSON 字符串content 一律为空字符串 该接口的校验要求 content 必须为空tool 消息 content 类型content 传 None / nullcontent 传 类型必须是 string服务端做类型校验null 不是合法字符串tool_call_id 来源自己生成的 id必须取 assistant 返回的 tool_calls[].id服务端靠 id 把工具消息和模型决策关联起来assistant 消息的 tool_calls第二轮组装时丢弃 tool_calls原样传回 assistant 消息对象协议闭环要求历史决策信息完整保留多轮历史只保留文本回复丢掉工具消息完整保留每轮所有消息服务端会校验整个消息序列的结构一致性工具结果传递只放在 tool.content 里tool.content 置空结果放下一轮 user 消息与该模型约定保持一致同时保证模型能看见结果并发工具调用顺序错乱、id 混用按 assistant 返回的 tool_calls 依次配对每个 tool 消息必须找到唯一的对应声明在排查时如果你的项目里用了消息自动压缩工具一定要注意压缩逻辑很可能把带 tool_calls 的 assistant 消息截断或者把 tool 消息合并成普通文本。这类隐形的协议破坏很难一眼看出来建议对经过压缩的消息也跑一遍上面的一致性检查脚本。另外还有几点实际操作中的体会关于空字符串值有些语言里字符串序列化时容易忽略空值。比如某些 HttpClient 在序列化时会顺手把空字符串转成 null这个坑非常隐蔽。我就是排查到最后才发现框架层把空字符串转成了 null请求体看起来没问题实际发出去的类型不对。关键要抓实际发出的请求而不是内存里的对象。关于调试成本建议把每次发送给接口的完整请求体打日志至少保留最近一次。线上环境里 422 往往只发生在特定业务分支没有请求日志几乎没法查。我把请求体日志加上后后面的排障效率直线上升。关于模型版本同一个协议在不同模型的实现上是有差异的。deepseek-v4.1-flash 这个接口对 tool 消息 content 非空的限制在别的模型上不一定存在。做多模型适配时不要假设一致用一个模型调通之后另一个模型还可能踩同样的坑。最好把各个模型的约束差异单独写成配置文档不要硬编码在代码里。最后再分享一个小技巧如果你用的是流式接口streamtruetool calling 的响应会被切成多个 chunk。有些服务端会把 tool_calls 的 id 放在第一个 chunk 里后面的 chunk 只有增量片段。组装消息时你要把所有 chunk 累加之后把完整的 tool_calls 存下来再和 tool 消息配对。只拿最后一个 chunk 去拼消息会直接导致 id 缺失。这个细节我在另一个项目上栽过好在这次提前规避了。整体看下来422 这个错误虽然吓人但本质上就是一次协议层面的“沟通失败”。把消息序列的闭环逻辑理顺把 content 空串这个约定记住绝大多数的坑都能轻松绕开。如果你也在接这个模型并遇到了其他奇怪的 422 提示欢迎把你的请求体匿名化之后拿出来一起看看很多时候问题就藏在不经意的那一行字段上。 
长河君 · 2026/10/20 14:13:29 · 阅读 1.2k DeepSeek tool calling 422错误：tool消息content必须为空字符串的坑
1. 422 不是网络问题是协议问题先说个结论遇到 422 的时候别急着怀疑网络、别重启服务、别在 API Key 上反复折腾问题几乎都出在请求体本身。HTTP 422 的语义是 Unprocessable Entity翻译成人话就是——服务器接收到了你的请求语法没问题但语义上过不去校验。放到大模型接口这个场景里就是你的消息序列没按协议规定的格式组织好服务端在校验层直接给你拦下来了。我最初接手这个项目时第一次遇到 deepseek-v4.1-flash 报 422第一反应是去翻网络代理日志查超时重试折腾了半小时。后来把响应体完整打出来才看到具体提示大意是 tool role 消息的 content 字段触发了非空校验。那一刻我才意识到这压根不是基础设施的问题是调用方对 tool calling 协议的细节理解有偏差。很多开发者对 422 的认知停留在“参数错误”这个层面但实际踩坑时会发现这类错误往往藏得很深。尤其是当你的业务场景涉及 function calling / tool calling 时接口校验的是整个消息数组的结构闭环任何一个角色顺序错位、字段类型不对、ID 对不上号都会在最后一刻爆出 422。这篇文章就把我在模拟项目 X 里完整踩过的坑、调试过程和最终的正确写法整理出来希望帮你少走弯路。需要先说清楚适合谁来读凡是接 DeepSeek 这类 OpenAI 兼容接口、并且业务中要用到工具调用查数据库、调外部 API、执行计算等的开发者这篇文章是为你写的。如果你只是单纯做文本对话、不涉及 tool calling那 422 的概率其实很低但了解一下消息协议的设计思路也有好处。2. tool 角色消息的正确姿势先搞懂消息序列2.1 tool calling 的消息闭环要理解为什么 tool 角色的 content 会被校验得先清楚一次完整的工具调用在消息层面长什么样。大模型接口不是无状态闲聊它要求你每次调用都携带完整的历史消息上下文。正常情况下一次接到工具调用的完整消息序列是这样的系统消息可选的 system 角色定义行为边界。用户消息user 角色提出需求比如“帮我查一下这个订单的状态”。助手消息assistant 角色它不直接给答案而是返回一个 tool_calls 数组里面声明“我需要调用某个函数参数是这样的”。工具消息tool 角色你把函数执行的结果放进来告诉模型“刚才那个调用的返回结果是什么”。最终助手消息assistant 角色模型根据工具返回的结果生成面向用户的最终回答。注意第四步这一步的 tool 角色消息在协议层面是一个承上启下的关键节点。它承接第三步里 assistant 生成的 tool_call_id启下给模型提供函数执行结果。如果这个环节的消息格式有问题服务端会判定为你没有正确履行工具调用的闭环协议于是抛出 422。有人可能会问为什么前几步都好好的一加 tool 消息就挂原因是在 OpenAI 兼容协议里assistant 的 tool_calls 与后续的 tool 消息是强关联的。服务端在解析请求时会先扫描整个消息数组中所有 assistant 角色带 tool_calls 的消息然后在后续消息里寻找对应的 tool 角色消息并逐一比对 tool_call_id。任何一个 tool_call_id 找不到对应关系、或者出现的顺序不合法整个请求就会被判定为“不可处理”。2.2 content 非空校验到底在查什么回到标题里那个核心报错tool 角色 content 非空校验失败。这里要敲黑板了很多人第一次看到这个提示会下意识理解为——“tool 消息里的 content 字段不能为空你必须给个返回值”。这个理解是反的。我在实际调试中确认DeepSeek 的 v4.1-flash 接口在这条校验规则上的设计是tool 角色的 content 字段必须为空字符串不能是 null也不能是实际文本内容。为什么这跟大多数人的直觉相反所以特别容易踩坑。原因要从协议兼容性说起。OpenAI 的 tool calling 协议里tool 角色消息的标准结构是{role: tool, tool_call_id: xxx, content: 函数返回的字符串}。这是原版协议的定义content 放的是函数返回值。但 DeepSeek 在实现 v4.1-flash 这个模型服务时可能为了内部处理和某些下游兼容性考虑调整了校验逻辑——它要求 tool 消息的 content 必须是空字符串真正的结果内容要走别的字段传递或者模型会忽略这部分文本由后续消息承载。这个设计初看很反直觉但实际有它的道理。你可以把 tool 消息理解为一个“凭证”或者“握手信号”它存在的意义只是告诉服务端“我已经拿到了工具返回结果请你继续”。至于结果内容本身可以由调用方在下一轮 user 消息里附带也可以由服务端内部自行处理。如果 content 字段被塞入了业务文本反而会造成语义歧义——到底哪个字段是权威内容空字符串就是个干干净净的约定。注意不同版本的模型接口可能对这条规则的实现不同。我在别的一些模型上试过tool 角色 content 传实际内容是可以的。唯独在这个模型的接口上content 非空直接 422。这个差异非常坑特别是做过其他平台适配的开发者最容易带着旧习惯踩进来。3. 触发 422 的 5 种常见姿势与复现3.1 姿势一assistant 没回 tool_callstool 消息却先到了这是我自己最早踩的坑。当时我的流程代码里有个 bug工具函数提前执行了结果消息组装时直接拼了一条 tool 角色消息进数组但前面的 assistant 消息根本没有声明过任何 tool_calls。服务端扫描时发现tool 消息找不到对应的 tool_call_id直接判定非法。复现路径很简单messages [ {role: system, content: You are a helpful assistant.}, {role: user, content: 查询订单 10086 的状态}, {role: tool, tool_call_id: call_abc, content: } # 前面没有对应的assistant.tool_calls ]这个请求发过去必然 422。因为服务端拿着call_abc去前面的消息里找翻遍所有 assistant 消息的 tool_calls 数组找不到这个 ID于是整个请求作废。这个错误很隐蔽因为你单看某一条消息格式完全没问题字段名、角色名都正确。但只要放在整个消息序列里看它的前置条件不存在协议闭环就断了。3.2 姿势二content 传了 null 或非字符串类型还有一种常见情况代码里组装消息时工具返回的结果是 null或者你用了 None / null 直接作为 content 的值。这也会触发校验失败因为协议要求 content 是字符串类型哪怕是空字符串也行但 null 不行。比如这样messages.append({ role: tool, tool_call_id: result.tool_call_id, content: None # 类型错误 })这个问题的本质是类型校验。服务端在做字段校验时如果发现 content 不是 string 类型直接报 422。解决办法很简单确保 content 一定是字符串没有返回值就传有返回值但不需要文本语义时也传。有些人会问那函数返回值放哪这就要看你的业务数据流了。如果是给模型看的你可以在工具执行后把结果拼到下一轮 user 消息里。如果模型本身只是要一个执行完成的信号那 tool 消息的 content 为空完全不影响后续生成。3.3 姿势三content 非空字符串这是标题里提到的那个场景。举例说明假设你的工具返回了一段 JSON 字符串你原样塞进了 tool 消息的 contentmessages.append({ role: tool, tool_call_id: call_abc, content: {status: success, order: 10086} })这个请求发出去很大概率就是 422报错信息会明确指向 content 非空校验失败。为什么如前面所说这个接口的设计要求 tool 角色 content 必须为空字符串。你传了实际内容违反了约定。我当时一度很困惑OpenAI 官方文档明明说 content 放工具结果为什么这个接口不行后来查了项目里的历史 issue 和更新日志才知道这个模型的 tool calling 实现走的是内部精简链路content 字段被要求置空函数结果通过其他协商字段传递。服务端的校验就卡在这里。所以正确的做法是把工具返回结果放到下一步的 user 消息里或者通过自定义字段传递。tool 消息本身的 content 一律传。3.4 姿势四tool_call_id 对不上还有一种情况工具执行过程中如果你做了异步并发调用返回结果的顺序乱了你把 tool_call_id 搞混了也会 422。服务端会拿你的 tool_call_id 跟前面 assistant 消息里声明的 ID 比对只要不一致立刻判定非法。好在我当时是串行调用没踩这个坑但群里有人问过类似问题。并发工具调用的场景下assistant 可能一次返回多个 tool_calls比如同时查订单和查库存。你必须以 assistant 返回的 tool_calls 数组里的 id 为准逐一对应地和 tool 消息配对顺序错位、ID 错配都会触发 422。这里有个排查技巧把 assistant 返回的完整 JSON 先打日志然后从里面提取 tool_calls 的 id 列表再对照你组装 tool 消息时使用的 id 列表一致性检查通过后再发起第二轮请求。3.5 姿势五多轮历史没带全最后一个比较隐蔽的场景发生在多轮对话里。假设第一轮你已经完成了一次工具调用assistant 给出了最终答案。第二轮用户继续问“那这个订单的物流呢”你组装消息时没把第一轮完整的 tool_calls / tool 消息对带上只带了 assistant 的最终文本回复。这时候服务端一检查发现这一轮请求里存在“孤立的”tool 消息或“无响应”的 tool_calls也可能触发校验失败。这类问题的排查难度更高因为报错不一定明确指向“历史消息缺失”可能就是笼统的 422。我的经验是只要涉及工具调用就完整保留每一轮的消息数组不要做任何截断和重写。你可以在内存里维护一个长上下文列表每轮结束后把新产生的 assistant 消息、tool 消息、最终 assistant 消息都追加进去下一轮直接全量带上。4. 正确写法从请求体到 SDK 调用4.1 手写 HTTP 请求的正确请求体先说最底层的方式方便理解协议本质。不管你是用 requests、curl 还是别的 HttpClient都建议先按下面这个结构组织请求体。我以一次真实场景为例用户要查订单状态工具函数名叫get_order_status。完整的请求体如下messages参数太长写进curl会有shell转义问题容易出错所以我这里给一段 Python requests 的示例import requests import json url https://api.example.com/v1/chat/completions api_key your-api-key # 第一轮让模型决定是否调用工具 messages [ {role: system, content: 你是一个订单助手可以查询订单状态。}, {role: user, content: 帮我查一下订单 10086 的状态} ] payload { model: deepseek-v4.1-flash, messages: messages, tools: [ { type: function, function: { name: get_order_status, description: 查询订单状态, parameters: { type: object, properties: { order_id: {type: string} }, required: [order_id] } } } ] } # 第一次请求 resp requests.post(url, headers{ Authorization: fBearer {api_key}, Content-Type: application/json }, jsonpayload) assistant_msg resp.json()[choices][0][message] # 假设模型返回了 tool_calls提取第一个 tool_call tool_call assistant_msg[tool_calls][0] tools_payload { type: function, function: { name: tool_call.function.name, # 实际业务里这里是安全执行你的真实函数 arguments: json.loads(tool_call.function.arguments) } } # 模拟执行函数返回结果 result {order_id: 10086, status: 已发货, eta: 明天到达} # 第二轮传入 assistant 消息 tool 消息注意 content 为空字符串 messages.append(assistant_msg) # 注意assistant 消息必须原样带回 tool_calls messages.append({ role: tool, tool_call_id: tool_call.id, # 必须是 assistant 返回的那个 id content: # 关键这里必须为空字符串 }) # 如果你需要把工具结果给模型看到放到这里 messages.append({ role: user, content: f工具返回结果{json.dumps(result, ensure_asciiFalse)}。请根据结果回答用户。 }) payload[messages] messages # 第二轮请求 resp2 requests.post(url, headers{ Authorization: fBearer {api_key}, Content-Type: application/json }, jsonpayload) print(resp2.json()[choices][0][message][content])重点看两个地方。第一个是消息顺序assistant 消息必须原样带回它的 tool_calls 字段不能丢。第二个是 tool 消息的 content 必须为空字符串工具返回的实际内容是通过一条新的 user 消息传给模型的。这里解释一下为什么我会选择把结果放在 user 消息里而不依赖模型自己理解“空白 tool 消息”。因为我实际测下来的结果是content 置空后如果后续没有携带工具结果模型要么不知道工具执行得怎么样要么会自行脑补一个结果这在你需要精确传递结构化数据时是致命的。把结果以 text 形式放在 user 消息里模型能明确看到回答质量会稳定很多。当然如果你的场景只是“让模型知道工具已完成”那不加这条 user 消息也行但记得多测几轮确保行为符合预期。4.2 用 SDK 的推荐写法如果你是用官方 SDK 或 OpenAI 兼容 SDK写法会简洁一些但核心约束不变。我自己用的是 Python openai 库风格的 sdk代码大致长这样from openai import OpenAI client OpenAI(api_keyyour-api-key, base_urlhttps://api.example.com/v1) # 第一轮请求 response client.chat.completions.create( modeldeepseek-v4.1-flash, messages[ {role: system, content: 你是一个订单助手可以查询订单状态。}, {role: user, content: 帮我查一下订单 10086 的状态} ], tools[{ type: function, function: { name: get_order_status, description: 查询订单状态, parameters: { type: object, properties: { order_id: {type: string} }, required: [order_id] } } }] ) assistant_message response.choices[0].message tool_call assistant_message.tool_calls[0] # 模拟执行工具函数 result {order_id: 10086, status: 已发货} # 第二轮请求注意 tool 消息 content 为空字符串 second_response client.chat.completions.create( modeldeepseek-v4.1-flash, messages[ {role: system, content: 你是一个订单助手可以查询订单状态。}, {role: user, content: 帮我查一下订单 10086 的状态}, assistant_message, # 原样传回包含 tool_calls { role: tool, tool_call_id: tool_call.id, content: }, { role: user, content: f工具返回结果{result}。请根据结果回答。 } ], tools[{...}] # 可以继续传入 ) print(second_response.choices[0].message.content)SDK 的好处是assistant_message 对象可以原样放进 messages 数组不用手动构造字典减少低级错误。但要注意SDK 不会帮你决定 tool 消息的 content 是什么这个业务判断必须自己做。传空字符串是你与这个模型接口之间的约定SDK 无法替你兜底。另外一个容易忽略的点即便 SDK 支持自动把 assistant_message 序列化成字典你也得确认序列化后的 tool_calls 字段没有被丢弃。某些 SDK 在把 message 对象转 dict 时可能会把 null 字段省略掉如果 assistant 的 tool_calls 被省略第二轮请求照样会触发 422。我的经验是直接把 response.choices[0].message 原对象放进列表让 SDK 自己处理不要手动构造。提示工具函数的 arguments 字段在协议里是 JSON 字符串。如果你在业务里用了类型化的函数调用库记得在传给接口前把 dict 转成 json.dumps在接收时用 json.loads 解析回来。这个字段类型错了也会变成 422。4.3 如何快速定位是哪种校验失败422 的报错信息有时候很直接有时候很笼统。如果你拿到的是笼统的报错可以用下面这个方法很快就能定位问题也是我在排障时发现最高效的手段。第一步把完整的请求体打印出来重点看消息数组里每条消息的 role、content、tool_call_id 和 tool_calls 字段。第二步自己写一个一致性检查脚本遍历消息数组按下面规则检查每条 tool 消息向前找是否存在对应的 assistant 消息声明了相同 id 的 tool_call每条 assistant 消息的 tool_calls 数组里的 id向后找是否都有对应的 tool 消息每条 tool 消息的 content 字段是否为字符串且值等于空字符串是否出现内容为 null 的 content 或缺失 content 字段。我实际用的是下面这个简化脚本能覆盖 80% 的 422 问题def validate_messages(messages): tool_call_ids set() for msg in messages: role msg.get(role) if role assistant and msg.get(tool_calls): for tc in msg[tool_calls]: tool_call_ids.add(tc[id]) if role tool: content msg.get(content, None) if not isinstance(content, str) or content ! : return ftool消息content应为空字符串当前: {repr(content)} if msg.get(tool_call_id) not in tool_call_ids: return ftool_call_id {msg.get(tool_call_id)} 未在之前的 assistant 消息中声明 return None把 messages 数组扔进这个函数如果有返回值那一行日志基本就是服务端校验的报错源头。这比反复发请求试错要快得多。还有一个很实用的技巧用 curl 直接发一个最简化的请求体做对照实验。比如只发 system user assistant带 tool_calls toolcontent 为空串这四层消息不带任何业务参数。如果这个最小序列能通说明你的业务组装逻辑出了问题如果这个最小序列也 422那你该检查接口版本或者模型名是否写错了。这个二分定位法在排障时极其有效帮我快速锁定过不少问题。5. 常见问题速查表与最后的一点心得把这次踩坑涉及的核心规则整理成下面这张表方便你复制到项目文档里团队协作时也能减少踩坑概率。场景错误示例正确姿势原因tool 消息 content 字段content 填了 JSON 字符串content 一律为空字符串 该接口的校验要求 content 必须为空tool 消息 content 类型content 传 None / nullcontent 传 类型必须是 string服务端做类型校验null 不是合法字符串tool_call_id 来源自己生成的 id必须取 assistant 返回的 tool_calls[].id服务端靠 id 把工具消息和模型决策关联起来assistant 消息的 tool_calls第二轮组装时丢弃 tool_calls原样传回 assistant 消息对象协议闭环要求历史决策信息完整保留多轮历史只保留文本回复丢掉工具消息完整保留每轮所有消息服务端会校验整个消息序列的结构一致性工具结果传递只放在 tool.content 里tool.content 置空结果放下一轮 user 消息与该模型约定保持一致同时保证模型能看见结果并发工具调用顺序错乱、id 混用按 assistant 返回的 tool_calls 依次配对每个 tool 消息必须找到唯一的对应声明在排查时如果你的项目里用了消息自动压缩工具一定要注意压缩逻辑很可能把带 tool_calls 的 assistant 消息截断或者把 tool 消息合并成普通文本。这类隐形的协议破坏很难一眼看出来建议对经过压缩的消息也跑一遍上面的一致性检查脚本。另外还有几点实际操作中的体会关于空字符串值有些语言里字符串序列化时容易忽略空值。比如某些 HttpClient 在序列化时会顺手把空字符串转成 null这个坑非常隐蔽。我就是排查到最后才发现框架层把空字符串转成了 null请求体看起来没问题实际发出去的类型不对。关键要抓实际发出的请求而不是内存里的对象。关于调试成本建议把每次发送给接口的完整请求体打日志至少保留最近一次。线上环境里 422 往往只发生在特定业务分支没有请求日志几乎没法查。我把请求体日志加上后后面的排障效率直线上升。关于模型版本同一个协议在不同模型的实现上是有差异的。deepseek-v4.1-flash 这个接口对 tool 消息 content 非空的限制在别的模型上不一定存在。做多模型适配时不要假设一致用一个模型调通之后另一个模型还可能踩同样的坑。最好把各个模型的约束差异单独写成配置文档不要硬编码在代码里。最后再分享一个小技巧如果你用的是流式接口streamtruetool calling 的响应会被切成多个 chunk。有些服务端会把 tool_calls 的 id 放在第一个 chunk 里后面的 chunk 只有增量片段。组装消息时你要把所有 chunk 累加之后把完整的 tool_calls 存下来再和 tool 消息配对。只拿最后一个 chunk 去拼消息会直接导致 id 缺失。这个细节我在另一个项目上栽过好在这次提前规避了。整体看下来422 这个错误虽然吓人但本质上就是一次协议层面的“沟通失败”。把消息序列的闭环逻辑理顺把 content 空串这个约定记住绝大多数的坑都能轻松绕开。如果你也在接这个模型并遇到了其他奇怪的 422 提示欢迎把你的请求体匿名化之后拿出来一起看看很多时候问题就藏在不经意的那一行字段上。