一、基础知识

先把一个关键误解纠正过来:Function Calling 不是模型在你的机器上执行 Python 函数。它做的是输出一段结构化意图,大意是「我认为现在应该调用 get_order_status,参数是 order_id=abc123」。真正执行函数的是你写的代码,执行完之后把结果回传,模型再基于结果生成最终回答。

整个循环通常是四步:

  1. 声明工具:你把函数名单、作用、参数格式用 JSON Schema 描述给模型。
  2. 模型返回意图:它不直接回答,而是返回工具调用请求(具体字段名以官方文档为准)。
  3. 程序执行:你的代码校验参数、调用真实函数、捕获异常,把结果回传。
  4. 生成回答:模型拿到结果,组织成人话返回给用户。

这里有个特别重要的安全认知:模型返回的「函数调用」只是建议,不是许可。它可能被提示词诱导去调用不该调的函数,也可能把参数填错。所以白名单、参数校验、权限控制一个都不能少。

工具声明里最容易写砸的是 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"))'

三、关键细节

  1. description 决定调用准确率。 把「什么时候不要调用」也写进去,比只写功能描述有效得多。
  2. 参数是从字符串解析出来的 JSON,必须校验。 不要直接 TOOLS[name](**json.loads(raw_args)),先确认它是对象、字段类型符合预期。
  3. 一次可能返回多个工具调用。 要循环处理,并让每个结果都带上对应的 tool_call_id,否则后续请求结构不合法。
  4. 失败也要回传结果。 函数抛异常时,回一条错误信息,而不是什么都不发——悬空的调用会让模型无法继续。
  5. 注册白名单,而不是暴露全部本地函数。 模型知道的函数只能是你显式放进去的那些,绝不能做「函数名 → eval」的映射。
  6. 回传结果要脱敏。 只给模型完成任务必需的字段,不要把整行数据库记录原样塞回去。
  7. 工具声明的粒度要按业务动作拆。 一个工具只做一件事,参数少而必填项明确;把"查询订单状态"和"修改收货地址"合成一个大而全的工具,模型会难以判断该不该调用,参数校验也更复杂。description 要同时写清"做什么"和"何时不要调用",并保留 additionalProperties: False,避免塞进计划外字段。
  8. 白名单之外还要划权限边界。 注册的函数应默认只读、最小权限,并在函数内部校验当前用户是否有权访问该订单——order_id 合法不等于用户有权查它。支付、删除、外发消息等写操作不要注册,或必须人工确认;每次调用记审计日志。
  9. 二次调用的会话状态要完整保留。 回传结果后,messages 要按"用户 → 带 tool_calls 的 assistant → 各条 tool 结果"顺序追加,tool_call_id 一一对应,否则第二次请求会报结构不合法。模型可能连续发起多轮调用,循环要设最大轮数防死循环;上下文变长时只压缩更早的历史,别丢掉最近一次工具意图与结果。
  10. 工具结果不等于最终答案。 第二次返回的 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 步原始响应确认字段结构。
  • 工具函数要有超时与幂等保护,网络抖动导致重复调用时查询类应能安全重试;回传结果按字段裁剪,不要把整行数据累积进对话历史。

免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。