工具调用参数校验怎么配置或排查

工具调用参数校验出问题时，先别急着改提示词。更稳定的做法是把问题拆成三层：工具定义是否生成了正确的 JSON Schema，模型返回的 tool_calls 是否符合当前框架的数据形状，最后才是业务参数能不能执行。Hugging Face 官方资料把工具名称、描述、参数类型和参数说明都视为模型选择工具的重要契约。

官方地址：https://huggingface.co/docs/transformers/main/chat_extras

先固定工具名、参数名和类型

最容易漏掉的是把自然语言说明写得很长，却没有把参数契约写完整。以天气工具为例，模型需要看到唯一的工具名、用途描述、参数对象、字段类型以及必填字段。函数签名、Python 类型提示、Google 风格 docstring 和手写 JSON Schema，至少要保证参数名一致。

from typing import Literal

def get_weather(location: str, unit: Literal["celsius", "fahrenheit"] = "celsius") -> str:
    """查询指定地点的天气。

    Args:
        location: 城市或地区名称。
        unit: 温度单位，只允许 celsius 或 fahrenheit。
    """
    # 这里只演示工具契约；真实项目应在这里调用受控的数据服务。
    return f"{location}: 22° {unit}"

tools = [get_weather]
# Transformers 会根据函数签名和 docstring 生成模型可见的 JSON Schema。
model_input = tokenizer.apply_chat_template(
    messages, tools=tools, add_generation_prompt=True, return_tensors="pt"
)

如果手写 schema，重点检查三件事：parameters.type 是否为 object，properties 中是否有每个字段的类型和描述，以及 required 是否只包含没有默认值的字段。把可选字段全部塞进 required，会让模型频繁补齐并不必要的参数；反过来漏掉真正必填字段，则会把错误推迟到工具内部。

模型返回异常时先看参数形状

同一个工具调用概念，在不同客户端的表示不完全相同。Transformers 推荐把调用放在 assistant 消息的 tool_calls 列表中，函数名和参数位于 function 内；官方示例中的参数是字典。兼容 OpenAI 风格的适配层有时会返回 JSON 字符串，这时不要直接把字符串当成 **arguments 使用。

import json

def normalize_arguments(raw):
    # 兼容字典和 JSON 字符串，其他类型直接拒绝，避免静默猜值。
    if isinstance(raw, str):
        try:
            raw = json.loads(raw)
        except json.JSONDecodeError as exc:
            raise ValueError("工具参数不是合法 JSON") from exc
    if not isinstance(raw, dict):
        raise TypeError("工具参数必须是 JSON 对象")
    return raw

执行前做结构与业务两层校验

参数能被解析成对象，只说明第一关通过。生产代码至少要在执行前检查必填字段、类型、枚举、字符串长度和数值范围；涉及权限、租户、资源归属或时间窗口时，再做业务校验。可以用 JSON Schema 做通用结构约束，也可以用 Pydantic 把 Python 类型和错误路径集中起来，但校验失败时不要继续调用真实工具。

from pydantic import BaseModel, Field, ValidationError
from typing import Literal

class WeatherArgs(BaseModel):
    # Field 约束用于尽早发现空地点和不支持的单位。
    location: str = Field(min_length=1, max_length=80)
    unit: Literal["celsius", "fahrenheit"] = "celsius"

def validate_before_execute(raw_args):
    # 先做结构校验；异常信息应记录路径，但不要泄露敏感输入。
    try:
        args = WeatherArgs.model_validate(normalize_arguments(raw_args))
    except (TypeError, ValueError, ValidationError) as exc:
        return {"ok": False, "error": str(exc)}
    # 业务层可继续检查租户权限、地点白名单或调用配额。
    return {"ok": True, "args": args.model_dump()}

按证据修复，再做一次反向验证

排查时建议保留四类脱敏记录：原始调用的工具名、参数字段集合、结构校验错误路径、业务拒绝原因。若错误出现在模板渲染前，检查函数类型提示和 docstring；若出现在解析后，检查 arguments 是字符串还是对象；若只有真实执行时失败，就回到权限、范围和外部服务响应。修复后分别用“缺字段、错误类型、合法边界值、越权值”四组样例确认：前三类能给出明确错误，最后一类不能触发真实工具。

常见问题：把 required 写成所有 properties 可以吗？

不建议。只有没有默认值且业务上必须提供的字段才放进 required，可选字段应保留默认值或由业务层补齐。

常见问题：为什么 tool_calls 明明存在，函数仍然调用失败？

先确认消息层级和 function.arguments 类型，再确认字段名与 schema 一致。列表存在不代表参数已经通过校验。

常见问题：JSON Schema 校验通过后还要 Pydantic 吗？

不一定。二者可以择一作为结构校验；但权限、租户、额度和资源状态等业务规则仍应单独执行，不能交给 schema 代替。