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

接入业务工具

接入业务工具

本节把一个订单查询能力接入助手,并在真正调用业务函数之前增加参数校验、权限判定和审计记录,使模型只能提出调用意图,不能绕过服务端安全边界直接访问业务数据。

学习目标

  • 为业务工具定义稳定的名称、参数和返回契约。
  • 在服务端依次执行参数校验、权限控制和真实业务调用。
  • 记录成功与拒绝调用的审计信息,形成可追踪证据。

把模型调用变成受控请求

工具调用的安全边界必须放在服务端。模型可以决定“想调用 get_order 并给出参数”,但工具网关仍要重新验证参数、用户身份和权限;只有全部通过后,才允许访问业务系统。

业务工具受控调用与审计时序

这条链路还有一个重要性质:审计发生在工具网关,而不是只记录模型最终回答。否则一旦调用失败、被拒绝或模型隐藏了工具细节,就会失去关键证据。

实现参数、权限与审计

下面用一个内存订单函数模拟业务后端。execute_tool 是唯一调用入口:它检查工具名和参数,再验证调用者是否拥有 order:read 权限,最后执行函数并写入审计记录。

python
import json
from datetime import datetime, timezone

AUDIT_LOG = []

def get_order(order_id):
    data = {
        "ORD-1001": {"orderId": "ORD-1001", "status": "PAID", "amount": 199.0}
    }
    return data.get(order_id, {"orderId": order_id, "status": "NOT_FOUND"})

def validate_get_order(args):
    # 服务端不信任模型生成的参数,字段和格式都要重新校验。
    if set(args) != {"order_id"}:
        raise ValueError("get_order only accepts order_id")
    order_id = args["order_id"]
    if not isinstance(order_id, str) or not order_id.startswith("ORD-"):
        raise ValueError("invalid order_id")

def write_audit(context, tool, outcome):
    AUDIT_LOG.append({
        "time": datetime.now(timezone.utc).isoformat(),
        "user": context["user_id"],
        "tool": tool,
        "outcome": outcome,
    })

def execute_tool(name, args, context):
    if name != "get_order":
        raise ValueError("unknown tool")

    validate_get_order(args)

    if "order:read" not in context["permissions"]:
        write_audit(context, name, "DENIED")
        raise PermissionError("permission denied: order:read")

    result = get_order(args["order_id"])
    write_audit(context, name, "SUCCESS")
    return result

allowed = {"user_id": "u-42", "permissions": {"order:read"}}
denied = {"user_id": "u-77", "permissions": set()}

result = execute_tool("get_order", {"order_id": "ORD-1001"}, allowed)
print("允许调用:", json.dumps(result, ensure_ascii=False))

try:
    execute_tool("get_order", {"order_id": "ORD-1001"}, denied)
except PermissionError as exc:
    print("拒绝调用:", str(exc))

print("审计:")
for item in AUDIT_LOG:
    print(json.dumps(item, ensure_ascii=False))

预期输出

text
允许调用: {"orderId": "ORD-1001", "status": "PAID", "amount": 199.0}
拒绝调用: permission denied: order:read
审计:
{"time": "<TIME>", "user": "u-42", "tool": "get_order", "outcome": "SUCCESS"}
{"time": "<TIME>", "user": "u-77", "tool": "get_order", "outcome": "DENIED"}

<TIME> 是运行时生成的 UTC 时间,实际值会不同。示例故意让无权限用户也经过同一个网关入口,因此拒绝行为同样进入审计。

收紧工具契约

参数校验不应只判断“有没有字段”,还应限制类型、长度、枚举值和业务范围。涉及订单、账号或租户数据时,还要校验资源归属,不能因为用户拥有某个泛化权限,就允许读取任意对象。

权限也不应从模型提示词里读取。可信身份应来自会话、API 网关或认证中间件,再由服务端映射为权限集合。模型生成的 user_id、role 或“管理员”文本都只能当普通输入,不能当授权依据。

让审计真正可用

最小审计至少记录时间、调用者、工具名、结果状态;生产环境通常还会记录请求 ID、资源 ID、耗时和失败原因。敏感参数应按字段脱敏,避免为了可追踪而把完整身份证号、令牌或支付信息写进日志。

验收时要同时测试三类路径:合法参数且有权限时成功;非法参数在进入业务函数前失败;合法参数但无权限时被拒绝,并且业务函数未执行。这样才能证明工具接入不仅“能调用”,还具备可控、可拒绝、可追踪的边界。

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

目录与阅读设置

阅读设置

17

记录一个想法

接入业务工具

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

登录哪都通