Function Calling 报“参数格式不对”,通常不是模型不会调工具,而是模型产出的 arguments 字符串和你在工具定义里声明的 schema 之间缺了一层校验。处理方向很明确:先把模型返回的原始参数字符串抓下来,判断是 JSON 层面不合法(多了解释文字、尾逗号、单引号),还是 schema 层面不匹配(类型错、必填缺失、枚举值不在范围内),再决定改提示、改 schema 还是改服务端解析。跳过这一步直接重写提示词,往往只是换个错误复现。
判断顺序建议固定为:抓原始 arguments → JSON 解析 → 按 schema 校验类型与必填 → 看 schema 本身是否含糊。适用场景是所有由模型生成工具入参的调用;操作动作是先落日志再做解析,把两类错误分开计数;验证方式是回放同一批输入,确认错误从解析失败转为 schema 不匹配或直接通过;边界是模型侧的结构化输出能力、schema 复杂度和服务端容错都不能替代日志记录,回退时保留原始字符串,不要只留解析后的对象。
先确认当前场景和目标
动手前先确认三件事。第一,报错发生在哪一层:是 json.loads 直接抛异常,还是 JSON 能解析但字段对不上,还是参数进了业务函数之后才报错。这三种情况对应的改法完全不同,第二和第三种经常被混为一谈。第二,schema 是不是你自己维护的:如果是内部工具,可以直接收窄定义;如果对接第三方接口,只能在你这一侧做映射和归一化。第三,调用链路里有没有结构化输出或严格模式的开关,有就先打开,没有就按普通提示词约束处理,别指望模型每次都严格遵守。
判断条件可以粗糙一点:如果错误集中在某几个字段,通常是 schema 描述不清或字段含义有歧义;如果错误随机分布在不同字段,多半是模型输出不稳定,需要从温度、上下文长度、工具数量上找原因。
按这个顺序处理
第一步,把原始参数字符串落日志,不要只记录解析后的对象。很多问题在看到原文时一眼就能定位,比如模型在 JSON 外面包了一层 Markdown 围栏,或者在字符串里写了注释。

raw = tool_call.function.arguments # 始终按字符串处理
log.info('tool_args_raw', extra={'name': tool_name, 'raw': raw})
try:
args = json.loads(raw)
except json.JSONDecodeError as e:
log.warning('tool_args_json_failed', extra={'raw': raw, 'err': str(e)})
raise ToolArgError('arguments 不是合法 JSON,请只返回一个 JSON 对象')第二步,解析成功后按 schema 做字段级校验,重点看必填项、类型、枚举和日期格式。类型校验要注意模型常把数字写成字符串、把单个对象写成单元素数组,这类偏差可以归一化,但要在日志里标记,便于后续判断是不是 schema 描述有问题。
required = ['city', 'date']
missing = [k for k in required if k not in args]
type_errs = {}
for k, expect in schema_types.items():
if k in args and not isinstance(args[k], expect):
type_errs[k] = f'期望 {expect.__name__},实际 {type(args[k]).__name__}'
if missing or type_errs:
raise ToolArgError(f'missing={missing} type={type_errs}')第三步,把具体错误作为工具结果回传给模型,让它只修正出错字段后重试。错误信息要指名道姓,写清字段名、期望格式和收到的值,这比笼统说“参数错误”有效得多。同时给重试次数设上限,避免死循环。
return {
'error': 'invalid_arguments',
'detail': '字段 date 需要 YYYY-MM-DD',
'received': args.get('date'),
'retry_hint': '只修正 date,其他字段保持不变'
}第四步,回头看 schema 本身。字段描述含糊、用 anyOf 拼联合类型、嵌套过深、可选字段过多,都会让模型猜错。能扁平化就扁平化,日期和枚举在描述里给出显式示例,必填项只保留真正必需的。
改完后怎么验证
先做回放验证:把之前失败的那批输入原样再跑一遍,观察日志里 tool_args_json_failed 是否还有新增,schema 校验失败是否从“多字段报错”收敛到“零报错或单字段报错”。这一步看的是错误类型的变化,不是看一次调用成功就算通过。

再做负向验证:手工构造几个明显错误的入参,比如缺必填字段、数字写成字符串、枚举值越界,确认校验层能拦住并返回可读的错误信息,而不是让错误穿透到业务函数里变成另一条异常。最后观察重试路径:模型收到错误后第二次调用是否只改了出错字段,如果每次都整体重写、反复踩同一个坑,说明错误提示不够具体或 schema 描述仍需调整。
容易忽略的边界
结构化输出或严格模式通常只支持 JSON Schema 的一个子集,anyOf、复杂的嵌套对象、部分格式约束可能不被接受,开启后要先确认你现有的工具定义没有被静默放宽或截断。工具数量多、单个 schema 很长时,模型容易在字段之间串味,这种情况下拆小工具比继续加提示更实际。
还要区分真正的参数问题和被误判的问题:超时、鉴权失败、接口返回非 JSON 体,常常在包装层被统一抛成“参数格式不对”。日志里要保留 HTTP 状态码和响应体前若干字符,否则排查方向会跑偏。回退建议是服务端保留一层宽松归一化和原始入参记录,用于兜底和复盘,但不要把吞异常当成长期方案;一旦发现某类错误持续出现,应当回到 schema 和提示上解决,而不是继续加 try/except。