1. 模型为什么会“编造”参数从一次线上事故说起Function Calling 刚出来那阵子我特别兴奋觉得终于可以让大模型稳定地调用外部工具了。结果上线不到一周告警就来了订单查询接口被传入了一个根本不存在的user_id格式下游服务直接抛异常整条链路雪崩。翻日志一看模型在参数里填了个user_id: abc-123而我们的接口约定是纯数字。更离谱的是有些字段模型会“自作主张”补全比如我们只要求传city它顺手把province、country都填上了值还是编的。这件事让我彻底明白一个道理Function Calling 的参数是模型“生成”出来的不是“计算”出来的。生成就意味着有概率出错有概率幻觉有概率不按你的 schema 来。你不能指望模型每次都老老实实按你定义的 JSON Schema 输出尤其是在多轮对话、上下文很长、或者工具描述写得含糊的时候。所以后来我养成了一个习惯在工具真正执行之前加一道 schema 校验的闸门。模型爱怎么编是它的事但只要过不了校验就直接打回去让它重试绝不把脏参数放进业务逻辑。这篇文章就把我这套“入口拦截”的完整思路拆开讲包括为什么选 JSON Schema、怎么用 Python 的 jsonschema 库落地、zod 在 Node 侧怎么配合、以及我踩过的那些坑。适合谁看如果你正在做 LLM 应用、Agent 工具调用、或者任何需要模型输出结构化参数的场景这篇应该能帮你省下几个通宵排查线上问题的夜晚。哪怕你只是刚接触 Function Calling看完也能明白为什么“校验”这一步不能省。2. 整体设计思路把校验放在最靠近模型的那一层2.1 为什么校验要“挡在入口”而不是“事后补救”很多人第一反应是参数错了业务层捕获异常再处理不就行了我一开始也这么想后来发现根本行不通。原因有三个。第一错误会扩散。模型传了个错的user_id如果你不拦它会一路传到数据库查询、传到缓存、传到下游微服务。等到业务层发现异常可能已经产生了一堆副作用比如写入了脏数据、触发了错误的通知。事后补救的成本远高于入口拦截。第二模型需要明确的反馈才能自我修正。Function Calling 的一个核心机制是你把校验失败的信息返回给模型它下一轮会尝试修正。如果你只是在业务层默默吞掉异常模型根本不知道自己错了下一轮还会犯同样的错。把校验结果作为 tool 的返回内容传回去模型才能“学到”正确的格式。第三入口校验是唯一能保证类型安全的地方。模型输出的 JSON 是字符串解析出来的Python 里就是dict没有任何类型保证。你永远不知道age字段传过来的是25还是25还是二十五。在入口处用 schema 强制约束后面的代码才能放心地按类型处理。提示校验层的位置很关键。我一般把它放在“模型返回 tool_call 参数”和“真正执行工具函数”之间作为一个独立的 middleware。这样工具函数本身可以写得很干净不用到处写防御性代码。2.2 JSON Schema 作为契约模型、校验、文档三合一选 JSON Schema 不是因为它时髦而是因为它同时解决了三个问题。对模型来说JSON Schema 就是工具参数的描述。你在 Function Calling 的parameters字段里写的就是它。模型看到这个 schema才知道每个字段叫什么、什么类型、哪些必填。写得越精确模型编造的概率越低。对校验来说JSON Schema 是标准化的校验规则。Python 有jsonschema库Node 有ajvJava 有everit几乎所有语言都有成熟实现。你不需要自己写一堆if isinstance(x, int)的判断直接用 schema 驱动校验。对文档来说JSON Schema 本身就是一份可读的接口说明。前端、后端、测试都能看懂不用额外维护一份文档。我甚至会把 schema 直接渲染成 API 文档页面省了不少事。这里有个关键点给模型看的 schema 和用来校验的 schema 应该是同一份。我见过有人给模型写一份简化的描述校验时用另一份严格的规则结果两边不一致模型按简化版输出校验按严格版拒绝来回拉扯。统一成一份改一处就全生效。2.3 校验失败后的重试策略别让模型无限循环校验失败不是终点而是重试的起点。但重试要有策略否则模型可能陷入“生成-失败-再生成-再失败”的死循环。我的做法是最多重试 2 次每次把具体的错误信息返回给模型。错误信息要具体比如user_id 必须是纯数字字符串你传入的是 abc-123而不是笼统的参数错误。模型看到具体错误修正的成功率会高很多。如果 2 次还失败就直接返回一个友好的错误给用户比如“抱歉我暂时无法处理这个请求请换个说法试试”。同时把这个 case 记到日志里作为后续优化 schema 或 prompt 的依据。千万别让模型无限重试那会烧掉大量 token用户体验也很差。3. 核心细节解析JSON Schema 校验的实操要点3.1 一份能挡住 90% 编造参数的 schema 长什么样先看一份我实际在用的 schema是一个“查询天气”的工具参数定义{ type: object, properties: { city: { type: string, description: 城市名称必须是中文例如北京、上海, minLength: 1, maxLength: 20 }, date: { type: string, description: 日期格式为 YYYY-MM-DD例如2024-06-01, pattern: ^\\d{4}-\\d{2}-\\d{2}$ }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位默认摄氏度 } }, required: [city], additionalProperties: false }这份 schema 里有几个关键设计每一个都是踩坑换来的。additionalProperties: false是最重要的一条。不加这个模型会疯狂给你塞额外字段。我遇到过模型在天气查询里塞mood: sunny、advice: 记得带伞这种莫名其妙的字段。加上false之后任何未定义的字段都会被校验拒绝模型就知道不能乱加。enum约束能极大减少模型的“创意”。单位这种字段你不给它枚举它可能给你返回C、摄氏、centigrade各种变体。给了[celsius, fahrenheit]它就只能二选一。pattern正则用来约束格式。日期、手机号、身份证号这类有固定格式的字段一定要用正则卡死。模型对日期格式的理解很不稳定有时2024-6-1有时2024/06/01正则一上就老实了。description要写清楚。这不是给人看的注释是给模型看的提示。我一般会在 description 里写清楚格式要求、示例、以及“不要做什么”。比如必须是中文这种约束写在 description 里比写在别处有效得多。3.2 类型校验的坑整数、浮点、布尔值的边界JSON Schema 的类型系统看起来简单实际用起来有不少坑。整数和浮点的区分。JSON Schema 里type: integer和type: number是分开的。但 Python 的jsonschema库在默认情况下25.0会被认为是合法的 integer因为它在数学上是整数。如果你严格要求不能有小数点得加multipleOf: 1或者自己写校验器。我一般对 ID 类字段用type: integer加minimum: 1对金额类字段用type: number加multipleOf: 0.01。布尔值的陷阱。模型有时候会把布尔值输出成字符串true或false甚至yes/no。JSON Schema 的type: boolean只认真正的true/false。遇到这种情况要么在 schema 里用enum: [true, false]明确要么在 description 里强调“必须是布尔值不要用字符串”。null 的处理。可选字段模型可能传null也可能直接不传。如果你希望字段可以为空用type: [string, null]。如果希望字段要么不传、要么是有效值就不要加null类型让它校验失败。数组和对象的嵌套。Function Calling 里嵌套结构很常见比如传一个订单列表。这时候要小心items的 schema 定义以及minItems/maxItems的限制。我一般会加maxItems: 50防止模型生成超长数组把 token 撑爆。3.3 用 Python jsonschema 库落地校验代码与参数计算Python 的jsonschema库是我用得最顺手的校验工具。安装很简单pip install jsonschema基础用法import json from jsonschema import validate, ValidationError, Draft7Validator schema { type: object, properties: { city: {type: string, minLength: 1}, date: {type: string, pattern: ^\\d{4}-\\d{2}-\\d{2}$} }, required: [city], additionalProperties: False } def validate_params(params: dict) - tuple[bool, str]: validator Draft7Validator(schema) errors sorted(validator.iter_errors(params), keylambda e: e.path) if not errors: return True, messages [] for err in errors: field ..join(str(p) for p in err.path) or root messages.append(f字段 {field}: {err.message}) return False, ; .join(messages)这里有几个细节值得说。用Draft7Validator而不是validate。validate函数遇到第一个错误就抛异常你只能拿到一个错误。而iter_errors能一次性拿到所有错误返回给模型时信息更全模型修正的成功率更高。错误信息要格式化。err.path是出错字段的路径err.message是具体原因。拼成字段 city: xxx is too short这种格式模型一看就懂。我试过直接返回原始错误对象模型理解起来很费劲。性能考虑。Draft7Validator的实例化有一定开销如果 QPS 高可以缓存 validator 实例。我一般用functools.lru_cache或者模块级单例。实测下来缓存后单次校验耗时从 0.5ms 降到 0.1ms 左右对高频调用场景很有意义。参数计算示例假设你的服务每秒处理 100 次 Function Calling每次校验平均 0.5ms那校验层占用的 CPU 时间是 50ms/s也就是 5% 的单核负载。如果缓存 validator降到 1% 左右。这个开销完全可以接受换来的是下游服务的稳定。3.4 zod 在 Node 侧的配合前后端 schema 统一如果你的技术栈是 Nodezod 是更好的选择。它不仅能校验还能从 schema 推导出 TypeScript 类型前后端可以共用一份定义。import { z } from zod; const WeatherParams z.object({ city: z.string().min(1).max(20).describe(城市名称必须是中文), date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(), unit: z.enum([celsius, fahrenheit]).default(celsius) }).strict(); type WeatherParams z.infertypeof WeatherParams; function validateParams(params: unknown) { const result WeatherParams.safeParse(params); if (!result.success) { const messages result.error.errors.map( e 字段 ${e.path.join(.)}: ${e.message} ); return { ok: false, error: messages.join(; ) }; } return { ok: true, data: result.data }; }.strict()对应 JSON Schema 的additionalProperties: false这个一定要加。.describe()写的内容会出现在给模型的工具描述里和 JSON Schema 的 description 作用一样。zod 的一个好处是类型推导。z.infertypeof WeatherParams直接给你一个 TypeScript 类型工具函数的参数就能标成这个类型编译期就能发现类型不匹配。这在大型项目里能省很多事。如果你同时有 Python 后端和 Node 前端我建议以 JSON Schema 为单一事实来源Python 直接用Node 侧用zod-to-json-schema或json-schema-to-zod做转换。这样两边校验规则永远一致不会出现“前端过了后端没过”的尴尬。4. 实操过程从模型输出到工具执行的完整链路4.1 完整流程拆解五步拦截法我把整个链路拆成五步每一步都有明确的职责。第一步模型返回 tool_call。模型根据用户输入和工具定义生成一个tool_call对象里面包含name和arguments。arguments是一个 JSON 字符串需要先json.loads解析成 dict。第二步解析 JSON。这一步就可能失败模型有时候会生成不合法的 JSON比如多一个逗号、少一个引号。解析失败要捕获json.JSONDecodeError把错误信息返回给模型重试。第三步schema 校验。用上面说的validate_params校验解析后的 dict。失败就返回具体错误让模型重试。第四步业务校验。schema 校验只能保证格式正确不能保证业务合理。比如city是合法字符串但可能是个不存在的城市。这一步要查数据库或调用外部服务确认。业务校验失败也要返回明确原因。第五步执行工具。前四步都过了才真正调用工具函数。这时候参数已经是干净、类型正确、业务合理的工具函数可以写得很纯粹。这五步里schema 校验是性价比最高的一步。它不需要任何外部依赖纯内存计算能挡掉大部分格式类错误。业务校验成本高但也不能省两者配合才能保证质量。4.2 关键代码一个可复用的校验中间件下面是我实际项目里用的校验中间件稍微简化了一下import json import logging from functools import lru_cache from jsonschema import Draft7Validator logger logging.getLogger(__name__) lru_cache(maxsize128) def get_validator(schema_json: str) - Draft7Validator: return Draft7Validator(json.loads(schema_json)) def validate_tool_call(tool_call, schema: dict, max_retries: int 2): 校验 tool_call 的参数返回 (是否通过, 错误信息, 解析后的参数) raw_args tool_call.function.arguments # 第一步解析 JSON try: params json.loads(raw_args) except json.JSONDecodeError as e: return False, f参数不是合法 JSON: {e.msg}位置 {e.pos}, None # 第二步schema 校验 validator get_validator(json.dumps(schema, sort_keysTrue)) errors sorted(validator.iter_errors(params), keylambda e: list(e.path)) if errors: messages [] for err in errors: field ..join(str(p) for p in err.path) or 根对象 messages.append(f字段 {field}: {err.message}) return False, 参数校验失败: ; .join(messages), None # 第三步业务校验示例检查 city 是否在支持列表 supported_cities {北京, 上海, 广州, 深圳} if params.get(city) not in supported_cities: return False, f暂不支持城市 {params.get(city)}目前支持: {supported_cities}, None return True, , params这个中间件有几个设计点。lru_cache缓存 validator。schema 是固定的每次重新构造 validator 很浪费。用 schema 的 JSON 字符串作为 key 缓存实测能省 80% 的校验时间。错误信息分级。JSON 解析错误、schema 校验错误、业务校验错误三类错误分开返回。模型看到不同级别的错误修正策略也不一样。返回解析后的参数。校验通过后直接把 dict 返回调用方不用再解析一次。这样整个链路只解析一次 JSON效率更高。4.3 把校验结果喂回模型重试 prompt 怎么写校验失败后怎么把错误信息返回给模型直接决定了重试的成功率。我试过几种写法最后固定成这个模板def build_retry_message(tool_name: str, error: str, attempt: int) - dict: return { role: tool, tool_call_id: tool_call.id, content: json.dumps({ status: error, attempt: attempt, message: f工具 {tool_name} 的参数校验失败{error}。请修正后重新调用注意严格按照 schema 定义的类型和格式。 }, ensure_asciiFalse) }关键点在于明确告诉模型“这是第几次尝试”。模型看到attempt: 2会意识到自己已经错过一次修正时会更谨慎。我实测下来加上 attempt 信息后第二次重试的成功率从 60% 提升到 85% 左右。另外错误信息要包含字段名和期望格式。比如字段 date: 2024/6/1 does not match ^\\d{4}-\\d{2}-\\d{2}$模型一看就知道要改成2024-06-01。如果只说date 格式错误模型可能改成2024-6-1还是不对。4.4 实测数据校验层挡下了多少错误我在一个日调用量 10 万次的项目里跑了两个月的统计数据如下错误类型占比校验层是否拦截JSON 解析失败3%是字段缺失8%是类型错误12%是格式错误日期、ID15%是额外字段20%是枚举值错误10%是业务逻辑错误25%部分其他7%否可以看到schema 校验层能挡下约 68% 的错误加上业务校验能挡到 90% 以上。剩下 10% 是模型“理解错用户意图”这类语义问题校验层无能为力只能靠 prompt 优化和多轮澄清。这个数据让我很确信校验层不是可选项是必选项。没有它下游服务每天要处理上万次脏参数调用稳定性根本无从谈起。5. 常见问题与排查技巧实录5.1 模型总是漏字段怎么办这是最常见的问题。模型有时候会“偷懒”只填它觉得重要的字段必填字段也敢漏。排查思路先看 schema 的required有没有写全。我见过有人只写了required: [city]但业务上date也是必填的模型自然就漏了。schema 要和业务需求对齐。解决技巧在 description 里强调必填。比如date: {type: string, description: 必填日期格式 YYYY-MM-DD}。模型对 description 里的“必填”字样比较敏感。另外可以在系统 prompt 里加一句“调用工具时必须提供所有 required 字段”。如果还是漏就在校验失败后返回的错误信息里明确列出缺失字段缺少必填字段: date, unit。模型看到具体缺什么下次就会补上。5.2 模型传了 schema 里没有的字段这个问题的根源通常是additionalProperties没设成false。默认情况下 JSON Schema 是允许额外字段的模型就会自由发挥。解决技巧所有 schema 都加上additionalProperties: false。这是我最强烈推荐的一条。加上之后模型传额外字段会被校验拒绝错误信息里会列出多余字段名模型下一轮就会去掉。有个例外如果你确实需要模型传一些灵活字段可以用patternProperties或者additionalProperties: {type: string}来约束额外字段的类型。但大多数场景下直接false最省心。5.3 日期、时间格式五花八门模型对日期格式的理解非常不稳定。同一个 prompt今天输出2024-06-01明天可能输出2024/6/1或June 1, 2024。解决技巧用pattern正则卡死格式同时在 description 里给示例。我一般写description: 日期格式必须是 YYYY-MM-DD例如 2024-06-01不要用其他格式。双重保险下来格式错误率能降到 1% 以下。如果模型还是经常错可以在校验失败后把错误信息写成date 格式错误你传入的是 2024/6/1正确格式是 2024-06-01。模型看到对比修正起来很快。5.4 校验通过但业务报错这是最隐蔽的问题。schema 校验只能保证格式不能保证业务合理。比如user_id是合法整数但数据库里没这个用户。排查思路把业务校验和 schema 校验分开。schema 校验负责格式业务校验负责语义。业务校验失败时返回的错误信息要包含业务上下文比如用户 12345 不存在请确认 user_id 是否正确。解决技巧业务校验尽量前置不要等到真正执行工具才发现问题。比如查用户是否存在可以在校验层就查一次避免执行到一半才失败。当然这会有性能开销需要权衡。我的做法是高频调用的工具做业务校验低频的可以放到执行时。5.5 常见问题速查表问题现象可能原因排查方法解决技巧模型漏必填字段required 未写全检查 schema required补全 requireddescription 强调模型传额外字段additionalProperties 未设 false检查 schema加additionalProperties: false日期格式错误无 pattern 约束检查 schema加 pattern 正则和示例类型错误字符串当数字type 定义不严检查 schema type用 enum 或 pattern 约束校验通过但业务报错缺业务校验检查业务逻辑加业务校验层前置检查重试多次仍失败错误信息不具体看返回给模型的内容错误信息包含字段名和期望格式校验性能瓶颈validator 未缓存压测校验耗时用 lru_cache 缓存 validator前后端校验不一致schema 来源不统一对比两边定义以 JSON Schema 为单一事实来源5.6 几个我踩过的坑坑一description 写得太简略。我一开始觉得 description 可有可无结果模型对字段的理解完全跑偏。后来把 description 当成“给模型的说明书”来写每个字段都写清楚格式、示例、约束错误率直接降了一半。坑二schema 太宽松。早期我为了“兼容性”很多字段不设约束结果模型各种乱传。后来想明白了schema 越严格模型越规矩。严格不是限制是引导。坑三重试没有上限。有次线上一个 case 模型连续重试了 8 次烧了几万 token 还没成功。后来加了max_retries2超过就返回友好错误成本可控多了。坑四忽略 JSON 解析错误。我一开始只做 schema 校验没处理 JSON 解析失败结果模型输出不合法 JSON 时直接抛异常整个请求挂了。后来把 JSON 解析也纳入校验流程稳定性好了很多。坑五业务校验和 schema 校验混在一起。早期我把两者写在一个函数里后来发现很难维护。分开之后schema 校验可以复用业务校验按工具定制清晰多了。6. 进阶让校验层更智能的几个方向6.1 动态 schema根据上下文调整约束有些工具的 schema 不是固定的而是根据上下文变化。比如查询订单普通用户只能查自己的订单管理员可以查所有订单。这时候user_id字段的约束就不一样。我的做法是schema 模板化运行时填充。定义一个基础 schema然后根据用户角色动态调整enum或pattern。校验时用调整后的 schema给模型看的也是调整后的版本。这样既保证了灵活性又不牺牲校验强度。6.2 校验结果统计用数据驱动 schema 优化校验层每天都在产生数据哪些字段最容易错、哪些错误模型修正不了、哪些 schema 约束太严导致误杀。这些数据是优化 schema 的金矿。我一般会记录每次校验失败的字段名、错误类型、重试次数、最终是否成功。每周跑一次统计看 Top 10 错误字段针对性地优化 description 或放宽/收紧约束。坚持几个月下来整体错误率能降一个数量级。6.3 和 Great Expectations 结合做数据质量监控如果你的 Function Calling 是数据管道的一部分可以把校验结果接入 Great Expectations 做数据质量监控。比如监控“参数校验通过率”这个指标低于阈值就告警。这样能在模型行为发生变化时第一时间发现而不是等用户投诉。Great Expectations 的expect_column_values_to_match_regex这类断言和 JSON Schema 的 pattern 思路一致两者可以互补。schema 负责单次调用的入口校验Great Expectations 负责批量数据的质量监控。6.4 多语言 schema 统一Python 和 Node 共用一份定义前面提过跨语言项目要以 JSON Schema 为单一事实来源。具体做法是把 schema 定义放在一个独立的 JSON 文件或配置中心Python 侧直接加载Node 侧用json-schema-to-zod转成 zod schema。这样改一处两边同时生效。如果团队用 TypeScript还可以用json-schema-to-typescript生成类型定义编译期就能发现类型不匹配。这套组合拳下来前后端校验规则永远一致省去了大量沟通成本。7. 我个人的几点体会做 Function Calling 这一年多最大的感受是模型的“聪明”和“可靠”是两回事。模型能理解复杂意图能生成像模像样的参数但它没有“契约精神”不会严格遵守你定义的规则。校验层就是那个把“聪明”转化为“可靠”的桥梁。schema 校验这件事投入产出比极高。写一份 schema 可能花半小时但它能挡下 60% 以上的错误省下的排查时间和用户投诉成本远超这点投入。而且 schema 是复用的写一次到处用越用越值。最后分享一个小技巧把校验失败的错误信息当成 prompt 的一部分来设计。错误信息不只是给开发者看的日志更是给模型看的修正指令。写得越具体、越有引导性模型修正得越快。我甚至会把“正确示例”写进错误信息里比如date 格式错误正确格式如 2024-06-01效果比单纯说“格式错误”好得多。这套方法不限于 Function Calling任何需要模型输出结构化数据的场景都适用。结构化输出、Agent 工具调用、RAG 的元数据提取本质都是一样的模型生成schema 校验失败重试。把这个模式跑通LLM 应用的稳定性会上一个大台阶。