AI 内容创作 / 系统课时
工具调用与内容安全
工具调用与内容安全
数字人一旦能够查询日历、调用业务接口或修改数据,对话就从“生成文本”变成了“触发真实动作”。本课将设计结构化工具调用、参数校验、权限控制和敏感内容过滤,并用统一兜底策略保证模型请求不可执行时仍能安全回复。
学习目标
- 设计工具注册、参数验证和执行结果回传流程
- 在工具执行前实施权限、范围与危险动作检查
- 建立输入过滤、输出审查和失败兜底机制
工具调用链路
模型不应直接执行函数,而应先生成结构化调用意图,再由应用程序完成工具匹配、参数解析、权限判断和真实执行。执行结果也不应原样拼回用户界面,需要经过字段裁剪、敏感信息脱敏和最终回复生成。

工具定义应包含名称、用途、允许参数和执行函数。参数校验不能只依赖提示词,因为模型可能漏字段、使用错误类型或传入越权标识。危险操作还应增加用户确认、幂等键或审批流程,避免重复调用造成不可逆影响。
安全边界设计
安全控制应覆盖三层。第一层检查用户输入,识别明显的敏感请求和越权意图;第二层检查结构化调用,验证工具名、参数类型、取值范围和调用权限;第三层检查工具结果,移除密钥、内部标识和不应向用户公开的字段。
| 控制位置 | 主要风险 | 典型措施 |
|---|---|---|
| 调用前 | 未知工具、恶意参数、越权动作 | 白名单、模式校验、权限检查 |
| 执行中 | 重复提交、超时、外部服务异常 | 幂等键、超时、重试上限 |
| 调用后 | 敏感字段泄露、不安全回复 | 脱敏、结果裁剪、输出审查 |
调用前拦截可明确说明动作未执行。调用发出后连接中断时,应显示执行结果待核对,并按原操作编号查询,避免用户重复提交。不要伪造工具已经成功,也不要把内部异常堆栈直接返回给用户。
最小可运行实现
下面的 Python 示例注册两个工具,并通过统一调度器完成白名单、参数和角色校验。工具响应是教学夹具,不会查询天气或删除笔记。敏感词检查只覆盖演示字符串,权限和字段裁剪必须独立生效。示例只使用标准库,可以直接运行。
from dataclasses import dataclass
from typing import Any, Callable, Dict
@dataclass
class ToolSpec:
required_role: str
schema: Dict[str, type]
handler: Callable[..., Dict[str, Any]]
def get_weather(city: str) -> Dict[str, Any]:
return {"city": city, "condition": "晴", "temperature_c": 26}
def delete_note(note_id: int) -> Dict[str, Any]:
return {"simulated": True, "note_id": note_id}
TOOLS: Dict[str, ToolSpec] = {
"get_weather": ToolSpec(
required_role="user",
schema={"city": str},
handler=get_weather
),
"delete_note": ToolSpec(
required_role="admin",
schema={"note_id": int},
handler=delete_note
)
}
ROLE_LEVEL = {"guest": 0, "user": 1, "admin": 2}
BLOCKED_TERMS = {"银行卡密码", "访问令牌", "系统密钥"}
def validate_content(text: str) -> None:
for term in BLOCKED_TERMS:
if term in text:
raise ValueError(f"blocked-content:{term}")
def dispatch(call: Dict[str, Any], caller_role: str) -> Dict[str, Any]:
if not isinstance(call, dict):
return {"ok": False, "message": "调用必须是对象"}
tool_name = call.get("tool")
arguments = call.get("arguments")
if not isinstance(tool_name, str) or tool_name not in TOOLS:
return {"ok": False, "message": "未知工具,未执行任何操作"}
if not isinstance(arguments, dict):
return {"ok": False, "message": "参数必须是对象"}
spec = TOOLS[tool_name]
if ROLE_LEVEL.get(caller_role, -1) < ROLE_LEVEL[spec.required_role]:
return {"ok": False, "message": "权限不足,未执行任何操作"}
unexpected = set(arguments) - set(spec.schema)
if unexpected:
return {"ok": False, "message": f"未声明参数: {sorted(unexpected)[0]}"}
for key, expected_type in spec.schema.items():
if key not in arguments:
return {"ok": False, "message": f"缺少参数: {key}"}
if type(arguments[key]) is not expected_type:
return {"ok": False, "message": f"参数类型错误: {key}"}
if tool_name == "delete_note" and arguments["note_id"] <= 0:
return {"ok": False, "message": "笔记编号必须为正整数"}
for value in arguments.values():
if isinstance(value, str):
try:
validate_content(value)
except ValueError:
return {"ok": False, "message": "请求包含敏感内容,未执行任何操作"}
result = spec.handler(**arguments)
return {"ok": True, "result": result}
def main() -> None:
calls = [
{"tool": "get_weather", "arguments": {"city": "上海"}},
{"tool": "delete_note", "arguments": {"note_id": 7}},
{"tool": "get_weather", "arguments": {"city": "系统密钥"}},
{"tool": "unknown_tool", "arguments": {}}
]
for call in calls:
print(dispatch(call, caller_role="user"))
if __name__ == "__main__":
main()运行方式
将代码保存为 tool_safety_demo.py,然后执行:
python tool_safety_demo.py预期输出
{'ok': True, 'result': {'city': '上海', 'condition': '晴', 'temperature_c': 26}}
{'ok': False, 'message': '权限不足,未执行任何操作'}
{'ok': False, 'message': '请求包含敏感内容,未执行任何操作'}
{'ok': False, 'message': '未知工具,未执行任何操作'}示例中的角色等级只是最小模型。生产环境应从服务端会话或身份令牌读取权限,不能相信模型生成的角色字段,也不能让客户端自行声明管理员身份。
失败处理与练习
可以统一响应格式,但应保留不同业务状态,例如 rejected、failed 和 unknown。收到超时或连接中断时,先核验副作用;仅在已确认未执行或有效幂等保护下重试同一个动作。日志中保留工具名、请求标识和错误类型即可,敏感参数应脱敏或完全不记录。
练习 1:为 get_weather 增加城市名称长度限制。验收条件是空字符串或超过 40 个字符的值会被拒绝,并返回明确错误。
练习 2:为 delete_note 增加确认令牌。为真实删除设计服务端签发的一次性确认记录,绑定操作者、目标笔记、版本、动作和有效期;执行前复核对象权限并原子登记同一操作键。模型自行生成的布尔值不能作为确认凭据。验收应覆盖换目标、过期、双击和回执丢失。
本课总结
- 工具调用必须经过结构化意图、白名单匹配、参数校验、权限检查和结果审查
- 内容安全既要检查用户输入,也要检查工具参数和执行结果
- 分别反馈已拦截、明确失败和结果待核对,并提供对应恢复路径
下一课预告
下一阶段将把记忆、角色状态和受控工具调用接入完整数字人链路,重点验证工具结果如何影响回复、语音和形象表现。