一、基础知识
先把一个关键误解纠正过来:Function Calling 不是模型在你的机器上执行 Python 函数。它做的是输出一段结构化意图,大意是「我认为现在应该调用 get_order_status,参数是 order_id=abc123」。真正执行函数的是你写的代码,执行完之后把结果回传,模型再基于结果生成最终回答。
整个循环通常是四步:
- 声明工具:你把函数名单、作用、参数格式用 JSON Schema 描述给模型。
- 模型返回意图:它不直接回答,而是返回工具调用请求(具体字段名以官方文档为准)。
- 程序执行:你的代码校验参数、调用真实函数、捕获异常,把结果回传。
- 生成回答:模型拿到结果,组织成人话返回给用户。
这里有个特别重要的安全认知:模型返回的「函数调用」只是建议,不是许可。它可能被提示词诱导去调用不该调的函数,也可能把参数填错。所以白名单、参数校验、权限控制一个都不能少。
工具声明里最容易写砸的是 description。它不是给人看的注释,而是给模型看的说明书——模型主要靠它判断「什么时候该调用」。写好描述的两个要点是:说清楚函数做什么,也说清楚什么情况下不要调用。
二、实操步骤
第 1 步:准备真实函数与工具声明。
# tools.py —— 业务函数 + 白名单注册表 + 工具声明
from datetime import datetime
def get_order_status(order_id: str) -> dict:
if not order_id.isalnum() or len(order_id) > 32:
raise ValueError("订单号格式不合法")
# 实际使用时换成你的查询逻辑;这里只演示返回结构
return {
"order_id": order_id,
"status": "示例状态",
"query_time": datetime.now().isoformat(),
}
# 白名单:只有登记在这里的函数才允许被调用
TOOLS = {"get_order_status": get_order_status}
# 工具声明:字段结构以你所用服务的官方文档为准
TOOL_SCHEMAS = [
{
"type": "function",
"function": {
"name": "get_order_status",
"description": (
"根据用户提供的订单号查询订单当前状态。"
"仅在用户明确给出订单号时调用;用户只是泛泛询问物流政策时不要调用。"
),
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "订单号,只允许字母和数字,长度不超过 32",
}
},
"required": ["order_id"],
"additionalProperties": False,
},
},
}
]
第 2 步:写完整的调用循环。
# agent.py —— 工具调用主循环
import os
import json
import requests
from tools import TOOLS, TOOL_SCHEMAS
API_URL = os.environ["API_URL"]
API_KEY = os.environ["API_KEY"]
MODEL = os.environ["MODEL"] # 具体模型名以官方文档为准
def chat(messages, tools=None):
payload = {"model": MODEL, "messages": messages}
if tools:
payload["tools"] = tools
r = requests.post(
API_URL,
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
r.raise_for_status()
# 返回结构因服务而异,以官方文档为准
return r.json()["choices"][0]["message"]
def run(user_input: str) -> str:
messages = [{"role": "user", "content": user_input}]
first = chat(messages, TOOL_SCHEMAS)
tool_calls = first.get("tool_calls") or []
if not tool_calls:
return first.get("content", "")
# 关键:把模型这次的返回原样放回对话历史
messages.append(first)
for call in tool_calls:
fn = call["function"]
name = fn["name"]
raw_args = fn.get("arguments", "{}")
if name not in TOOLS:
result = {"error": "该函数不在允许调用的名单中"}
else:
try:
args = json.loads(raw_args)
if not isinstance(args, dict):
raise ValueError("参数必须是 JSON 对象")
result = TOOLS[name](**args)
except Exception as exc:
# 失败也要回传,不能让这个调用悬空
result = {"error": f"执行失败:{type(exc).__name__}"}
messages.append({
"role": "tool",
"tool_call_id": call["id"], # 必须和请求一一对应
"content": json.dumps(result, ensure_ascii=False),
})
final = chat(messages)
return final.get("content", "")
if __name__ == "__main__":
print(run("帮我查一下订单 abc123 的状态"))
第 3 步:运行并观察。
export API_URL="你的服务端点"
export API_KEY="你的密钥"
export MODEL="你实际使用的模型名" # 以官方文档为准
python agent.py
第 4 步:单独测函数,排除业务代码问题。
python -c 'from tools import get_order_status; print(get_order_status("abc123"))'
三、关键细节
description决定调用准确率。 把「什么时候不要调用」也写进去,比只写功能描述有效得多。- 参数是从字符串解析出来的 JSON,必须校验。 不要直接
TOOLS[name](**json.loads(raw_args)),先确认它是对象、字段类型符合预期。 - 一次可能返回多个工具调用。 要循环处理,并让每个结果都带上对应的
tool_call_id,否则后续请求结构不合法。 - 失败也要回传结果。 函数抛异常时,回一条错误信息,而不是什么都不发——悬空的调用会让模型无法继续。
- 注册白名单,而不是暴露全部本地函数。 模型知道的函数只能是你显式放进去的那些,绝不能做「函数名 → eval」的映射。
- 回传结果要脱敏。 只给模型完成任务必需的字段,不要把整行数据库记录原样塞回去。
- 工具声明的粒度要按业务动作拆。 一个工具只做一件事,参数少而必填项明确;把"查询订单状态"和"修改收货地址"合成一个大而全的工具,模型会难以判断该不该调用,参数校验也更复杂。description 要同时写清"做什么"和"何时不要调用",并保留
additionalProperties: False,避免塞进计划外字段。 - 白名单之外还要划权限边界。 注册的函数应默认只读、最小权限,并在函数内部校验当前用户是否有权访问该订单——order_id 合法不等于用户有权查它。支付、删除、外发消息等写操作不要注册,或必须人工确认;每次调用记审计日志。
- 二次调用的会话状态要完整保留。 回传结果后,messages 要按"用户 → 带 tool_calls 的 assistant → 各条 tool 结果"顺序追加,tool_call_id 一一对应,否则第二次请求会报结构不合法。模型可能连续发起多轮调用,循环要设最大轮数防死循环;上下文变长时只压缩更早的历史,别丢掉最近一次工具意图与结果。
- 工具结果不等于最终答案。 第二次返回的 content 仍可能违背材料或编造数字,关键字段要由程序二次核对后再展示。
四、常见错误
| 错误做法 | 现象 | 原因 | 修正 |
|---|---|---|---|
| 只写函数功能,不写触发条件 | 模型不调用工具,自己编答案 | 描述没说清何时该调用 | 在 description 里补上「仅在……时调用」 |
| 漏掉 assistant 消息或 tool 消息顺序错 | 第二次请求报错,提示消息结构不合法 | 调用意图与结果没有正确放回历史 | 严格按「用户 → 模型工具意图 → 工具结果」追加 |
| 多个工具调用时结果对不上号 | 模型拿到张冠李戴的结果 | 没用 tool_call_id 一一对应 |
每个结果都带上对应 call 的 id |
| 把本地所有函数都注册成工具 | 模型尝试调用删除、写库等危险操作 | 缺少白名单与权限控制 | 只注册只读、必要的函数,高风险操作加人工确认 |
| 函数抛异常后什么都不回传 | 对话卡住或模型开始瞎猜 | 工具调用悬空 | 捕获异常并回传结构化错误信息 |
| 直接把查询结果整行回传 | 敏感字段泄露到模型上下文 | 没有字段级过滤 | 只返回必要字段,关键值做脱敏 |
五、排查方法
按顺序查,先排除结构问题,再排除业务问题:
# 1. 确认环境变量与模型名
python -c 'import os; print("URL:", bool(os.getenv("API_URL")), "MODEL:", os.getenv("MODEL"))'
# 2. 打印完整对话历史,检查 role 顺序和 tool_call_id
# 在 agent.py 的 return 前临时加一行:
# print(json.dumps(messages, ensure_ascii=False, indent=2))
python agent.py | head -n 80
# 3. 单独验证业务函数能跑通
python -c 'from tools import get_order_status; print(get_order_status("abc123"))'
# 4. 看原始响应里到底有没有工具调用意图(字段名以官方文档为准)
# 先用 tools.py 里真实的 TOOL_SCHEMAS 生成请求体;空 tools 数组等于没声明工具,不会返回意图
python - <<'PY'
import json, os
from tools import TOOL_SCHEMAS
with open("payload.json", "w", encoding="utf-8") as f:
json.dump({
"model": os.environ["MODEL"],
"messages": [{"role": "user", "content": "查订单 abc123"}],
"tools": TOOL_SCHEMAS,
}, f, ensure_ascii=False)
PY
curl -sS -X POST "$API_URL"
-H "Authorization: Bearer $API_KEY"
-H 'Content-Type: application/json'
-d @payload.json | jq '.choices[0].message'
# 若确实要对照「无工具」行为,可另发一次 tools 为空的请求,预期不返回 tool_calls
# 5. 用一句明确带订单号的话重试,排除触发条件太模糊
python -c 'from agent import run; print(run("订单号是 abc123,请查询状态"))'
如果第 4 步能看到工具调用意图,而程序没执行,问题在你自己的分发逻辑;如果连意图都没有,问题在工具声明或触发条件。
六、注意事项
- 工具调用的字段名、是否支持并行调用、结果消息的格式,各服务差异较大,以官方文档为准。
- 模型只是提出意图,绝不能把它返回的函数名直接映射到
eval、os.system或任意数据库写操作。 - 生产环境请给函数加超时、权限校验、幂等控制和审计日志。
- 涉及支付、删除、发送等高风险操作时,务必加二次确认,不要全自动执行。
- 模型版本升级后调用行为可能变化,工具声明和执行逻辑都要做回归测试。
- 工具数量、单次可返回的调用条数、字段命名随服务变化,请以官方文档为准;报错时先用第 4 步原始响应确认字段结构。
- 工具函数要有超时与幂等保护,网络抖动导致重复调用时查询类应能安全重试;回传结果按字段裁剪,不要把整行数据累积进对话历史。
免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。

评论
还没有评论,来说两句吧。