Function Calling 入门:让大模型学会"用工具"

┌─────────────┐                                ┌──────────┐
│   你的代码   │                                │   模型    │
└─────┬───────┘                                └────┬─────┘
      │                                              │
      │  1. messages=[用户:"北京天气"]               │
      │     tools=[get_weather, send_email, ...]    │
      ├────────────────────────────────────────────►│
      │                                              │
      │  2. 模型决定要调工具                          │
      │     finish_reason: "tool_calls"             │
      │     tool_calls: [{                          │
      │       name: "get_weather",                  │
      │       arguments: { city: "北京" }            │
      │     }]                                       │
      │◄────────────────────────────────────────────┤
      │                                              │
      │  3. 你的代码真的去调 get_weather("北京")     │
      │     拿到 "晴,28℃,东南风 3 级"                │
      │                                              │
      │  4. messages=[                              │
      │       用户:"北京天气",                      │
      │       助手:tool_calls,                      │
      │       工具结果:"晴,28℃,东南风 3 级"         │
      │     ]                                        │
      ├────────────────────────────────────────────►│
      │                                              │
      │  5. 模型基于真实数据组织自然语言              │
      │     "北京今天天气晴朗,气温 28 度..."         │
      │◄────────────────────────────────────────────┤
      │                                              │

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "获取指定城市当前的天气情况。仅支持中国大陆城市,不支持港澳台和海外。",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "城市的中文名,例如 '北京' / '上海' / '深圳'"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"],
          "description": "温度单位,默认摄氏度",
          "default": "celsius"
        }
      },
      "required": ["city"]
    }
  }
}

from openai import OpenAI
import json

client = OpenAI(api_key="sk-...")

def get_weather(city: str, unit: str = "celsius") -> dict:
    return {
        "city": city,
        "temperature": 28 if unit == "celsius" else 82,
        "condition": "晴",
        "wind": "东南风 3 级",
    }

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市当前的天气。仅支持中国大陆城市。",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市的中文名"},
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "default": "celsius",
                },
            },
            "required": ["city"],
        },
    },
}]

messages = [
    {"role": "user", "content": "北京今天天气怎么样?"}
]

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
)

msg = resp.choices[0].message
messages.append(msg)

if msg.tool_calls:
    for call in msg.tool_calls:
        name = call.function.name
        args = json.loads(call.function.arguments)
        print(f"模型想调用 {name}({args})")

        if name == "get_weather":
            result = get_weather(**args)
        else:
            result = {"error": f"unknown tool: {name}"}

        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result, ensure_ascii=False),
        })

    final = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools,
    )
    print(final.choices[0].message.content)
else:
    print(msg.content)

模型想调用 get_weather({'city': '北京'})
北京今天天气晴朗,气温约 28℃,东南风 3 级,适合外出。

{
  "tool_calls": [
    { "id": "call_1", "name": "get_weather", "arguments": "{\"city\":\"北京\"}" },
    { "id": "call_2", "name": "get_weather", "arguments": "{\"city\":\"上海\"}" }
  ]
}

{
  "name": "search",
  "description": "搜索"
}

{
  "name": "search_internal_docs",
  "description": "在公司内部技术文档库里检索。适用场景:用户问 '我们公司用 xxx 框架的最佳实践'、'部署流程文档在哪'。不适用:通用编程问题、外部新闻、实时数据 —— 这些场景应该让我直接回答或者使用 web_search 工具。"
}

"description": "查询订单表"

"description": "根据订单号查询订单的当前状态、下单时间、收货地址。只支持最近 90 天的订单;查询历史订单请用 query_archived_order。"

def get_weather(city: str):
    if city not in SUPPORTED_CITIES:
        return {
            "error": "city_not_supported",
            "message": f"暂不支持 {city} 的天气查询,目前只支持中国大陆地级市及以上",
            "hint": "如果用户问的是港澳台或海外,请明确告知用户暂不支持",
        }

调 search("ABC") → 没结果
调 search("ABC ") → 没结果(就多了个空格)
调 search(" ABC") → 没结果
...

       ┌──────────────────────────┐
       │   Agent / AI 应用层       │  ← Cursor / Claude Desktop / 你的产品
       └────────────┬─────────────┘
                    │
       ┌────────────▼─────────────┐
       │   MCP(工具发现 / 分发)   │  ← 可选,用于把工具做成"插件"
       └────────────┬─────────────┘
                    │
       ┌────────────▼─────────────┐
       │   Function Calling 协议   │  ← 模型层 API 的能力
       └────────────┬─────────────┘
                    │
       ┌────────────▼─────────────┐
       │       基础模型             │  ← GPT / Claude / Gemini / ...
       └──────────────────────────┘