Function Calling

• 通义千问-Max

• 通义千问-Plus

• 通义千问-Turbo

• 通义千问-Long

• Qwen2.5

• Qwen2

• Qwen1.5

• Qwen

1. 定义工具

工具是连接大模型与外部世界的桥梁，它是实现 Function Calling 的关键，您首先需要对工具进行定义。

1.1. 定义工具函数

您需要定义两个工具函数：天气查询工具与时间查询工具。

• 天气查询工具

  天气查询工具接收arguments参数，arguments格式为{"location": "查询的地点"}。工具的输出为字符串，格式为：“{位置}今天是{天气}。”。

  为了便于演示，此处定义的天气查询工具并不真正查询天气，会从晴天、多云、雨天随机选择。在您的实际业务中可以使用如高德天气查询等工具进行替换。

• 时间查询工具

  时间查询工具不需要输入参数。工具的输出为字符串，格式为：“当前时间：{查询到的时间}。”。

  如果您使用 Node.js，请使用以下命令安装获取时间的工具包 date-fns：

   

  npm install date-fns

Python

Node.js

## 步骤1:定义工具函数# 添加导入random模块import randomfrom datetime import datetime# 模拟天气查询工具。返回结果示例：“北京今天是雨天。”def get_current_weather(arguments):    # 定义备选的天气条件列表
    weather_conditions = ["晴天", "多云", "雨天"]    # 随机选择一个天气条件
    random_weather = random.choice(weather_conditions)    # 从 JSON 中提取位置信息
    location = arguments["location"]    # 返回格式化的天气信息
    return f"{location}今天是{random_weather}。"# 查询当前时间的工具。返回结果示例：“当前时间：2024-04-15 17:15:18。“def get_current_time():    # 获取当前日期和时间
    current_datetime = datetime.now()    # 格式化当前日期和时间
    formatted_time = current_datetime.strftime('%Y-%m-%d %H:%M:%S')    # 返回格式化后的当前时间
    return f"当前时间：{formatted_time}。"# 测试工具函数并输出结果，运行后续步骤时可以去掉以下四句测试代码print("测试工具输出：")print(get_current_weather({"location": "上海"}))print(get_current_time())print("\n")

运行工具后，得到输出：

测试工具输出：
上海今天是多云。
当前时间：2025-01-08 20:21:45。

1.2 创建 tools 数组

人类在选择工具之前，需要对工具有全面的了解，包括工具的功能、何时使用以及输入参数等。大模型也需要这些信息才能更准确地选择工具。在使用 Function Calling 时，请根据以下的 JSON 格式提供工具信息。

{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "当你想查询指定城市的天气时非常有用。",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市或县区，比如北京市、杭州市、余杭区等。",
                }
            },
            "required": ["location"]
        }
    }}

在发起 Function Calling 前，您需要通过 tools 参数传入工具的描述信息。tools 为 JSON Array 类型，Array 中的元素为创建好的工具描述信息。

tools 参数在发起 Function Calling时进行指定。

Python

Node.js

# 请将以下代码粘贴到步骤1代码后## 步骤2:创建 tools 数组tools = [
    {        "type": "function",        "function": {            "name": "get_current_time",            "description": "当你想知道现在的时间时非常有用。",
        }
    },
    {        "type": "function",        "function": {            "name": "get_current_weather",            "description": "当你想查询指定城市的天气时非常有用。",            "parameters": {                "type": "object",                "properties": {                    "location": {                        "type": "string",                        "description": "城市或县区，比如北京市、杭州市、余杭区等。",
                    }
                },                "required": ["location"]
            }
        }
    }
]
tool_name = [tool["function"]["name"] for tool in tools]print(f"创建了{len(tools)}个工具，为：{tool_name}\n")

2. 创建messages数组

与直接向通义千问 API 提问类似，您同样需要维护一个 messages 数组来向大模型传入指令与上下文信息。发起 Function Calling 前，messages 数组需要包含 System Message 与 User Message。

System Message

尽管在创建 tools 数组时已经对工具的作用与何时使用工具进行了描述，但在 System Message 中强调何时调用工具通常会提高工具调用的准确率。在当前场景下，我们可以将 System Prompt 设置为：

你是一个很有帮助的助手。如果用户提问关于天气的问题，请调用 ‘get_current_weather’ 函数;
如果用户提问关于时间的问题，请调用‘get_current_time’函数。
请以友好的语气回答问题。

User Message

User Message 用于传入用户提问的问题。假设用户提问“上海天气”，此时的 messages 数组为：

Python

Node.js

# 步骤3:创建messages数组# 请将以下代码粘贴到步骤2 代码后messages = [
    {        "role": "system",        "content": """你是一个很有帮助的助手。如果用户提问关于天气的问题，请调用 ‘get_current_weather’ 函数;
     如果用户提问关于时间的问题，请调用‘get_current_time’函数。
     请以友好的语气回答问题。""",
    },
    {        "role": "user",        "content": "上海天气"
    }
]print("messages 数组创建完成\n")

3. 发起 Function Calling

在完成 tools 与 messages 的创建后，您可以参考以下代码发起 Function Calling，让大模型“决策”是否需要调用工具，如果需要，大模型会输出需要调用的工具函数与入参信息。

Python

Node.js

# 步骤4:发起 function calling# 请将以下代码粘贴到步骤3 代码后from openai import OpenAIimport os

client = OpenAI(    # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)def function_calling():
    completion = client.chat.completions.create(
        model="qwen-plus",  # 此处以qwen-plus为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/getting-started/models
        messages=messages,
        tools=tools
    )    print("返回对象：")    print(completion.choices[0].message.model_dump_json())    print("\n")    return completionprint("正在发起function calling...")
completion = function_calling()

大模型通过返回对象的tool_calls参数，指定需要使用的工具函数名称为："get_current_weather"，并指定函数的入参为："{\"location\": \"上海\"}"。

{
    "content": "",
    "refusal": null,
    "role": "assistant",
    "audio": null,
    "function_call": null,
    "tool_calls": [
        {
            "id": "call_6596dafa2a6a46f7a217da",
            "function": {
                "arguments": "{\"location\": \"上海\"}",
                "name": "get_current_weather"
            },
            "type": "function",
            "index": 0
        }
    ]}

需要注意的是，如果提问的问题被大模型判断为无需使用工具，则不会返回tool_calls参数，并会通过content参数直接进行回复。在输入“你好”时，tool_calls参数为空，返回对象格式为：

{
    "content": "你好！有什么可以帮助你的吗？如果你有关于天气或者时间的问题，我特别擅长回答。",
    "refusal": null,
    "role": "assistant",
    "audio": null,
    "function_call": null,
    "tool_calls": null}

如果没有返回 tool_calls 参数，您的程序可以在此处直接返回 content 字段，无需运行以下步骤。

如果您希望每次发起 Function Calling 后大模型都可以选择工具，请参见：强制工具调用。

4. 运行工具函数

在Function Calling流程中，运行工具函数是将大模型的决策转化为实际操作的关键步骤。就像在天气查询工具输入“上海”来获取天气一样，您在得到工具函数以及函数的入参后，可以运行工具函数来得到工具的输出。

运行工具函数的过程由您的计算环境而非大模型来完成。

由于大模型只可以输出字符串格式的内容，因此在运行工具函数前，您需要针对字符串格式的工具函数与入参分别进行解析。

• 工具函数

  您需要建立一个工具函数名称到工具函数实体的映射function_mapper，将返回的工具函数字符串映射到工具函数实体；

• 入参

  Function Calling 返回的入参为 JSON 字符串，您可以使用 JSON 字符串解析工具将其解析为 JSON 对象，提取出入参信息。

Python

Node.js

# 步骤5:运行工具函数# 请将以下代码粘贴到步骤4 代码后import jsonprint("正在执行工具函数...")# 从返回的结果中获取函数名称和入参function_name = completion.choices[0].message.tool_calls[0].function.name
arguments_string = completion.choices[0].message.tool_calls[0].function.arguments# 使用json模块解析参数字符串arguments = json.loads(arguments_string)# 创建一个函数映射表function_mapper = {    "get_current_weather": get_current_weather,    "get_current_time": get_current_time
}# 获取函数实体function = function_mapper[function_name]# 如果入参为空，则直接调用函数if arguments == {}:
    function_output = function()# 否则，传入参数后调用函数else:
    function_output = function(arguments)# 打印工具的输出print(f"工具函数输出：{function_output}\n")

运行以上代码可以得到如下输出：

上海今天是多云。

您可以直接将工具输出作为最终的结果。如果您希望返回结果更符合人类语气，可以参见 大模型总结工具函数输出。

流式输出

为了提升用户体验和减少等待时间，您可以使用流式输出快速获取所需调用的工具函数名称。其中：

• 工具函数名称：仅在第一个流式返回的对象中出现。

• 入参信息：以持续的流式方式输出。

流式输出方式能让您更灵活地处理 Function Calling 的结果。您可以参考以下代码，将发起 Function Calling修改为流式输出方式。

Python

Node.js

def function_calling():
    completion = client.chat.completions.create(
        model="qwen-plus",
        messages=messages,
        tools=tools,
        stream=True
    )    for chunk in completion:        print(chunk.model_dump_json())

function_calling()

从第一个返回的流式输出对象可以获得工具函数名称，入参信息则需要您进行拼接，拼接完成后再运行工具函数。

{"id":"chatcmpl-3f8155c3-e96f-95bc-a2a6-8e48537a0893","choices":[{"delta":{"content":null,"function_call":null,"refusal":null,"role":"assistant","tool_calls":[{"index":0,"id":"call_5507104cabae4f64a0fdd3","function":{"arguments":"{\"location\":","name":"get_current_weather"},"type":"function"}]},"finish_reason":null,"index":0,"logprobs":null}],"created":1736251532,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}{"id":"chatcmpl-3f8155c3-e96f-95bc-a2a6-8e48537a0893","choices":[{"delta":{"content":null,"function_call":null,"refusal":null,"role":null,"tool_calls":[{"index":0,"id":"","function":{"arguments":" \"上海\"}","name":""},"type":"function"}]},"finish_reason":null,"index":0,"logprobs":null}],"created":1736251532,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}{"id":"chatcmpl-3f8155c3-e96f-95bc-a2a6-8e48537a0893","choices":[{"delta":{"content":null,"function_call":null,"refusal":null,"role":null,"tool_calls":[{"index":0,"id":"","function":{"arguments":null,"name":null},"type":"function"}]},"finish_reason":"tool_calls","index":0,"logprobs":null}],"created":1736251532,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}

如果您需要使用大模型总结工具函数输出，添加的 Assistant Message 需要符合下方格式。

{
    "content": "",
    "refusal": None,
    "role": "assistant",
    "audio": None,
    "function_call": None,
    "tool_calls": [
        {
            "id": "call_xxx",
            "function": {
                "arguments": '{"location": "上海"}',
                "name": "get_current_weather",
            },
            "type": "function",
            "index": 0,
        }
    ],}

您需要对以下元素进行替换：

• id

  将tool_calls的id替换为第一个返回的流式输出对象中的choices[0].delta.tool_calls[0].id；

• arguments

  将入参信息拼接后，替换tool_calls的arguments；

• name

  将tool_calls的name替换为第一个返回的流式输出对象中的choices[0].delta.tool_calls[0].function.name。

指定工具调用方式

{
    "content": "",
    "refusal": null,
    "role": "assistant",
    "audio": null,
    "function_call": null,
    "tool_calls": [
        {
            "id": "call_61a2bbd82a8042289f1ff2",
            "function": {
                "arguments": "{\"location\": \"北京市\"}",
                "name": "get_current_weather"
            },
            "type": "function",
            "index": 0
        }
    ]}

def function_calling():
    completion = client.chat.completions.create(
        model="qwen-plus",  # 模型列表：https://help.aliyun.com/zh/model-studio/getting-started/models
        messages=messages,
        tools=tools,        # 新增参数
        parallel_tool_calls=True
    )    print("返回对象：")    print(completion.choices[0].message.model_dump_json())    print("\n")    return completionprint("正在发起function calling...")
completion = function_calling()

{
    "content": "",
    "role": "assistant",
    "tool_calls": [
        {
            "function": {
                "name": "get_current_weather",
                "arguments": "{\"location\": \"北京市\"}"
            },
            "index": 0,
            "id": "call_c2d8a3a24c4d4929b26ae2",
            "type": "function"
        },
        {
            "function": {
                "name": "get_current_weather",
                "arguments": "{\"location\": \"天津市\"}"
            },
            "index": 1,
            "id": "call_dc7f2f678f1944da9194cd",
            "type": "function"
        },
        {
            "function": {
                "name": "get_current_weather",
                "arguments": "{\"location\": \"上海市\"}"
            },
            "index": 2,
            "id": "call_55c95dd718d94d9789c7c0",
            "type": "function"
        },
        {
            "function": {
                "name": "get_current_weather",
                "arguments": "{\"location\": \"重庆市\"}"
            },
            "index": 3,
            "id": "call_98a0cc7fded64b3ba88251",
            "type": "function"
        }
    ]}