AI 工具调用怎样区分模型参数校验和业务校验

我第一次把 AI 工具调用接到真实业务接口时，最容易误判的一点是：模型生成了一段符合 JSON Schema 的参数，并不代表这次调用可以执行。Schema 只能回答“字段长什么样”，业务校验还要回答“这个调用现在能不能做、由谁做、做了会影响什么”。

把工具调用分成三层：模型参数校验负责形状和类型，业务校验负责权限、状态、幂等与资源，执行器只接受两层都通过的内部命令。任何副作用都应发生在最后一层之后。

官方资料入口：https://huggingface.co/docs/inference-providers/

先看触发信号：合法参数不等于合法操作

在 Hugging Face Inference Providers 的函数调用模式里，工具定义会用 JSON Schema 描述函数名、参数、类型和必填字段；模型返回的消息可能包含 tool_calls，应用再解析参数、执行函数并把结果放回对话。这个协议解决的是“调用格式统一”，没有替应用判断库存、权限、租户状态或请求是否重复。

值班时可以先看三个信号：

• 解析失败、缺少必填字段、字段类型不符：这是模型参数层的问题，通常不应触碰业务服务。
• 参数格式正确，但用户没有权限、资源不存在或状态不允许：这是业务层拒绝，应返回可解释的业务错误。
• 两层检查都通过，外部服务仍超时或返回失败：这是执行层故障，要根据副作用和幂等能力决定重试或回滚。

把两层边界固定下来

我会把工具调用入口画成一条“边界”，但不让模型直接拥有业务对象。模型只负责提出一个候选命令，入口把它转换成内部命令后再做业务判断。

• 工具定义描述模型可以提交哪些字段，但不写入用户当前余额、订单状态这类瞬时事实。
• 参数解析器只把字符串 JSON 变成受控对象，同时拒绝未知字段、错误类型和空值。
• 业务策略从身份、租户、资源状态和幂等记录中得出是否允许执行。
• 执行器只接收内部命令，负责调用外部系统并记录结果，不再猜测模型意图。

模型参数校验：只检查“能否被理解”

参数层的职责要尽量窄。它适合检查字段是否存在、类型是否正确、字符串是否满足基本格式、枚举值是否在允许集合内，以及对象是否符合工具声明。不要在这里查询数据库，也不要把“当前用户是否可以删除”塞进 Schema 描述里。

import json
from dataclasses import dataclass

@dataclass
class CandidateCall:
    name: str
    arguments: dict
    call_id: str

def parse_tool_call(message: dict) -> CandidateCall:
    # 只处理协议结构，不读取数据库，也不执行副作用。
    calls = message.get("tool_calls") or []
    if len(calls) != 1:
        raise ValueError("tool_calls 数量必须恰好为 1")
    call = calls[0]
    function = call.get("function") or {}
    name = function.get("name")
    raw_arguments = function.get("arguments", "{}")
    if not isinstance(name, str) or not name:
        raise ValueError("工具名称缺失")
    try:
        arguments = json.loads(raw_arguments)
    except json.JSONDecodeError as exc:
        # 解析错误返回给上层，不把原始字符串交给业务执行器。
        raise ValueError("工具参数不是有效 JSON") from exc
    if not isinstance(arguments, dict):
        raise ValueError("工具参数必须是 JSON 对象")
    # 只做通用形状检查；权限和资源状态留给业务层。
    required = {"order_id", "reason", "idempotency_key"}
    if not required.issubset(arguments):
        raise ValueError("缺少工具所需字段")
    if not all(isinstance(arguments[key], str) for key in required):
        raise ValueError("工具字段类型错误")
    return CandidateCall(name=name, arguments=arguments, call_id=str(call.get("id", "unknown")))

生产环境仍应优先使用客户端或提供商支持的严格 Schema；本地解析器是最后一道防线，不是用来替代工具定义的。特别是多提供商场景，某个模型支持的严格模式、枚举约束或字段行为可能不同，不能只看模型返回的文本长得像 JSON。

业务校验：判断“现在是否允许做”

业务校验拿到的是已经能被理解的候选命令。此时要把检查分为四组，避免一个巨大的 validate() 函数把所有错误都变成 400：

一个实用原则是：Schema 可以写“amount 是数字且大于零”，业务层还要检查“这个租户今天是否还有额度”。前者通常是纯函数，后者必须读取当前状态，而且读取和最终写入之间可能发生竞争，因此关键操作要在事务、版本号或服务端原子接口中再次确认。

处理步骤：在副作用前建立一次决策点

1. 接收调用：保存模型、提供商、工具名和调用 ID，但不要把模型原文直接拼进命令或 SQL。
2. 解析参数：按工具名选择 Schema，解析 JSON，拒绝缺字段、错误类型和不允许的额外字段。
3. 构造内部命令：把用户身份、租户和服务端生成的资源版本补进内部对象，模型不能自行覆盖这些值。
4. 执行前检查：检查权限、资源状态、幂等键、并发版本和需要人工确认的策略。
5. 提交副作用：调用业务服务；把 call_id 与幂等键传入，方便查找和重放。
6. 返回结构化结果：区分成功、业务拒绝、可重试故障和未知状态，避免让模型把异常猜成成功。

def dispatch(candidate: CandidateCall, actor: dict, store) -> dict:
    # 先把候选参数映射成服务端可控的内部命令。
    command = {
        "order_id": candidate.arguments["order_id"],
        "reason": candidate.arguments["reason"],
        "idempotency_key": candidate.arguments["idempotency_key"],
        "tenant_id": actor["tenant_id"],  # 租户来自认证上下文
        "actor_id": actor["user_id"],
    }
    # 业务校验读取实时状态；失败时不调用外部副作用接口。
    if not store.can_cancel(command["tenant_id"], command["order_id"]):
        return {"kind": "business_rejected", "code": "ORDER_NOT_CANCELABLE"}
    if store.already_processed(command["idempotency_key"]):
        # 幂等命中优先返回已有结果，避免重复写入。
        return store.previous_result(command["idempotency_key"])
    try:
        result = store.cancel_order(command)
    except TimeoutError:
        # 未知提交状态不能直接重试，交给幂等查询或人工确认。
        return {"kind": "unknown", "code": "EXECUTION_TIMEOUT"}
    return {"kind": "success", "result": result}

错误分类：让模型知道该改参数还是停止

我建议把错误分成四个稳定类别，并让外层对话只看到安全、短小的提示。详细堆栈进入服务日志，避免把内部表名、访问令牌或供应商响应原样回传给模型。

• parameter_invalid：字段缺失、类型错误、JSON 无法解析。可以让模型修正参数，但要限制重试次数。
• business_rejected：权限、资源状态或策略不满足。应停止工具执行，必要时要求用户确认或换用其他操作。
• execution_failed：外部服务明确返回失败且确认没有提交成功。是否重试取决于错误是否临时以及接口是否幂等。
• unknown：超时、连接断开或响应丢失，无法判断副作用是否已经发生。先查幂等状态，不要让模型自动重复提交。

回滚路径：先保护状态，再处理对话

参数错误通常只需要丢弃候选调用；业务拒绝不应“回滚”数据库，因为它根本没有执行。真正需要回滚的是已经写入部分状态、但后续步骤失败的工作流。

对不可逆操作，例如发送通知、扣减额度或删除资源，优先采用幂等键、预留—确认两阶段接口或补偿动作。对超时状态，保留调用 ID、幂等键和资源版本，后台查询最终状态后再决定给用户“已完成”“未完成”还是“需要人工处理”。不要仅依据模型收到的错误文本判断回滚成功。

告警确认与复盘项

告警不要只统计“工具调用失败次数”。至少拆开以下指标：Schema 解析失败率、业务拒绝率、执行明确失败率、未知状态率、幂等命中率，以及单个模型或提供商的异常分布。这样才能看出是提示词或 Schema 变了，还是业务状态本身变差。

每次异常保留一条不含敏感值的审计记录：trace_id、call_id、工具名、Schema 版本、模型与提供商、错误类别、业务码、是否发生副作用、幂等键摘要和最终处置。复盘时重点问三件事：

1. 模型是否被允许提交了不该由模型决定的字段？
2. 业务服务是否在真正写入前又做了一次权威状态检查？
3. 未知状态是否有查询、补偿或人工接管路径？

最后的判断清单

如果只记住一句话，就是“Schema 验证可理解，业务验证可执行”。把两者拆开，工具调用的错误会更容易定位，模型也不会因为一次业务拒绝就不断重复同一个危险动作。对需要接入真实写操作的 Agent，这个边界比再加一段提示词更可靠。

相关问题

Schema 已经 strict 了，还需要业务校验吗？

需要。strict 主要约束生成结果是否符合定义的结构，不能替代权限、资源状态、额度、幂等和并发版本检查。

业务拒绝应该让模型自动重试吗？

只有当错误明确表示参数可修正时才考虑有限重试。权限不足、状态不允许和未知提交状态都不应盲目重试。

多个提供商的工具调用怎样保持一致？

把工具 Schema、内部命令和业务错误码放在自己的适配层，提供商只负责生成候选调用；最终是否执行必须由自己的业务服务决定。