大模型应用开发 / 系统课时

定义工具接口

定义工具接口

模型只有在准确理解工具用途、参数含义和调用边界后,才能稳定连接外部系统。本课将把一个普通函数整理成清晰的工具定义,并用参数模式阻止缺字段、错类型和无效取值。

学习目标

  • 为工具选择明确且不歧义的名称与说明
  • 使用 JSON Schema 描述必填参数、类型和约束
  • 在执行前验证模型生成的工具参数

工具接口包含什么

一个工具接口通常由三部分组成:名称、说明和参数模式。名称用于唯一识别能力,说明告诉模型“何时调用”,参数模式则规定“如何调用”。这三部分必须共同表达业务边界,不能只写一个函数名让模型猜测用途。

工具应保持单一职责。例如查询天气和发送通知应拆成两个工具;get_data 这类名称过于宽泛,而 get_order_status 能直接说明动作和对象。说明中还应写清不适用场景,例如“仅查询订单,不执行退款”。

用参数模式消除歧义

参数模式推荐采用 JSON Schema。字段说明应解释业务含义,而不只是重复字段名;可枚举的值用 enum 限制;必要字段放入 required;默认不接受额外字段,避免模型附带未定义参数。

json
{
  "type": "object",
  "properties": {
    "orderNo": {
      "type": "string",
      "description": "需要查询的商户订单号,不能为空"
    },
    "detailLevel": {
      "type": "string",
      "enum": ["basic", "full"],
      "description": "basic 返回状态,full 额外返回支付与退款明细"
    }
  },
  "required": ["orderNo"],
  "additionalProperties": false
}

该模式的生效行为是:缺少 orderNo、传入枚举外的值或增加未知字段时,参数验证应失败。Schema 只负责描述输入,鉴权、限流、幂等和敏感字段脱敏仍由工具执行层负责。

定义并验证一个完整工具

下面使用 Python 字典定义工具,并实现最小参数校验。示例不依赖第三方库,可以直接运行;真实项目可替换为标准 JSON Schema 校验器。

python
from typing import Any

ORDER_STATUS_TOOL = {
    "name": "get_order_status",
    "description": "查询指定商户订单的当前状态;只读,不执行退款或状态修改。",
    "parameters": {
        "type": "object",
        "properties": {
            "orderNo": {
                "type": "string",
                "description": "商户订单号"
            },
            "detailLevel": {
                "type": "string",
                "enum": ["basic", "full"],
                "description": "返回信息详细程度"
            }
        },
        "required": ["orderNo"],
        "additionalProperties": False
    }
}

def validate_arguments(arguments: dict[str, Any]) -> None:
    allowed = {"orderNo", "detailLevel"}
    unknown = set(arguments) - allowed
    if unknown:
        raise ValueError(f"存在未知参数:{sorted(unknown)}")

    order_no = arguments.get("orderNo")
    if not isinstance(order_no, str) or not order_no.strip():
        raise ValueError("orderNo 必须是非空字符串")

    detail_level = arguments.get("detailLevel", "basic")
    if detail_level not in {"basic", "full"}:
        raise ValueError("detailLevel 只能是 basic 或 full")

def execute_tool(arguments: dict[str, Any]) -> dict[str, str]:
    validate_arguments(arguments)
    return {
        "orderNo": arguments["orderNo"],
        "status": "PAID",
        "detailLevel": arguments.get("detailLevel", "basic")
    }

result = execute_tool({
    "orderNo": "MER202608020001",
    "detailLevel": "full"
})
print(result)

预期输出

text
{'orderNo': 'MER202608020001', 'status': 'PAID', 'detailLevel': 'full'}

示例中的订单号和状态仅用于演示接口形状。接入真实系统后,execute_tool 应调用受鉴权保护的服务,并把超时、权限不足和业务不存在转换为稳定的错误结构。

写好说明与边界

工具说明要回答三个问题:何时调用、调用后得到什么、哪些事情不能做。不要把内部实现细节全部塞入说明,也不要写“用于处理订单”这种无法帮助模型选择工具的描述。

参数字段应尽量使用业务上稳定的值。日期要规定格式和时区,金额要规定单位,标识符要说明来源。对于删除、付款、退款等有副作用的工具,还应增加确认参数或在执行层要求人工确认,不能因为模型给出了合法 JSON 就直接执行。

本课总结

  • 工具名称和说明负责帮助模型选对能力,参数模式负责约束调用方式
  • 必填、枚举和 additionalProperties 能显著减少无效参数
  • Schema 校验通过不等于业务安全,执行层仍需鉴权、确认和错误处理

下一课预告

下一课将介绍模型如何选择工具、生成调用参数,并把工具执行结果继续交给模型组织最终回答。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定义工具接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通