函数调用 - moxus

函数调用（Function Calling，亦称工具调用 / Tool Calling）允许模型判断需要调用哪个外部函数，并生成相应的参数。模型本身不执行函数，而是将调用意图与参数返回给调用方，由调用方执行后再将结果回传给模型，以生成最终响应。这是构建「能查询天气、查询数据库、执行操作」的 AI 助手的核心机制。

工作流程

函数调用是多轮往返的过程：

用户向模型发送问题，并提供可用工具列表。
模型返回需调用的函数及参数。
调用方在本地执行该函数，获得结果。
调用方将执行结果回传给模型。
模型基于执行结果生成最终响应。

步骤一：定义工具并发起请求

在请求中通过 tools 字段声明可用函数。每个函数使用 JSON Schema 描述其名称、用途与参数。

{
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "北京今天天气怎么样？"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询指定城市的当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称，例如 北京、上海"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

tools：可用工具数组。
tool_choice：控制工具选择策略。可选值包括：
- "auto"（默认）：模型自行决定是否调用及调用哪个。
- "none"：禁止调用工具，强制普通响应。
- {"type": "function", "function": {"name": "get_weather"}}：强制调用指定函数。

步骤二：模型返回调用意图

模型不会直接回答天气，而是返回 tool_calls，说明需调用 get_weather 及参数：

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"北京\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

finish_reason 为 tool_calls，表示模型请求调用工具。
arguments 为 JSON 字符串，需解析为对象。
id（call_abc123）需在步骤四回传结果时使用。

步骤三：执行函数

在本地代码中执行 get_weather("北京")，假设得到结果：{"temp": "25℃", "condition": "晴"}。

步骤四：回传执行结果

将对话历史、模型的 tool_calls 及执行结果一并发送。执行结果使用 role: "tool" 的消息表示，并通过 tool_call_id 对应步骤二的 id：

{
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "北京今天天气怎么样？"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\": \"北京\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temp\": \"25℃\", \"condition\": \"晴\"}"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询指定城市的当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "城市名称"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

步骤五：模型生成最终响应

模型基于天气数据返回自然语言响应：

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "北京今天天气晴朗，气温 25℃，适合外出活动。"
      },
      "finish_reason": "stop"
    }
  ]
}

完整 Python 示例

import json
from openai import OpenAI

client = OpenAI(api_key="sk-你的密钥", base_url="https://moxus.ai/v1")

def get_weather(city: str) -> dict:
    # 实际应调用天气 API
    return {"temp": "25℃", "condition": "晴"}

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"}
                },
                "required": ["city"],
            },
        },
    }
]

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

# 第一轮：模型判断是否调用工具
resp = client.chat.completions.create(
    model="gpt-4o", messages=messages, tools=tools, tool_choice="auto"
)
msg = resp.choices[0].message

if msg.tool_calls:
    messages.append(msg)
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)
        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)

并行调用多个工具

模型可能一次请求调用多个工具（tool_calls 数组包含多项）。需全部执行，并为每个 id 各回传一条 role: "tool" 消息。可通过 parallel_tool_calls 参数控制是否允许并行（默认允许）。

注意事项

并非所有模型均支持函数调用，请在模型广场确认所选模型的能力。
arguments 为 JSON 字符串，需先解析。
工具执行结果须转为字符串（通常为 JSON 字符串）再回传。
每轮往返均消耗 Token（历史越长消耗越多），应注意成本。
模型生成的参数可能不完全符合预期，执行前应进行校验与容错。

后续步骤

强制返回规范 JSON：参阅结构化输出。
深度推理：参阅推理模型。

​工作流程

​步骤一：定义工具并发起请求

​步骤二：模型返回调用意图

​步骤三：执行函数

​步骤四：回传执行结果

​步骤五：模型生成最终响应

​完整 Python 示例

​并行调用多个工具

​注意事项

​后续步骤