概述 - 通义千问 API

大模型在面对实时性问题、数学计算等问题时可能效果不佳。您可以使用 Function Calling 功能，通过引入外部工具，使得大模型可以与外部世界进行交互。

支持的模型

当前支持通义千问的大语言模型。支持的模型为：

通义千问-Max

暂不支持通义千问多模态模型。

建议您优先选择通义千问-Plus，它在效果、速度和成本上相对均衡。

如果您对响应的速度与成本控制有较高要求，商业版模型建议使用通义千问-Turbo系列，开源版模型建议使用Qwen2.5 系列的小参数模型；

如果您对响应的准确率有较高要求，商业版模型建议使用通义千问-Max系列，开源版模型建议使用 qwen2.5-72b-instruct 模型。

概述

如果直接向通义千问 API 提问“阿里云最近有什么新闻？”，大模型并不能准确回答：

我无法提供实时信息，因为我的数据只更新到2021年。

如果这个问题需要人类帮助大模型来解决，那么一个有效的操作步骤为：

选择工具

由于问题是关于实时新闻的，打开浏览器工具；

提取参数

由于提问的问题是“阿里云最近有什么新闻？”，用浏览器输入框查询“阿里云新闻”；

运行工具

浏览器返回了许多网页，如“阿里云成为总台《2025年春节联欢晚会》云计算AI独家合作伙伴”等；

将工具的输出提供给大模型

将网页内容输入到提示词对通义千问 API 进行提问：“这是查询到的信息：阿里云成为总台《2025年春节联欢晚会》云计算AI独家合作伙伴......。请总结并回答：阿里云最近有什么新闻？”由于向大模型提供了足够的参考信息，可以得到类似的回复：

阿里云最近的重要新闻是它成为了中央广播电视总台《2025年春节联欢晚会》的云计算AI独家合作伙伴。
...
这些信息表明，阿里云不仅在技术基础设施方面具有优势，而且也在积极探索如何将AI技术应用于大型文化活动中，以创造新的用户体验。

大模型此时可以回答关于实时新闻的问题了，然而这个过程需要人的参与（选择工具、提取参数、运行工具），无法实现自动化运行的效果。

Function Calling（工具调用）可以自动化完成以上流程，在接收到提问后可以自动选择工具、提取参数、运行工具并总结工具的输出。效果对比如下所示：

已关闭 function calling

发送

以上组件仅供您参考，并未真实发送请求。

工作流程示意图如下所示：

前提条件

您需要已获取API Key并配置API Key到环境变量。如果通过 OpenAI SDK 或 DashScope SDK 进行调用，需要安装SDK。如果您是子业务空间的成员，请确保超级管理员已为该业务空间进行模型授权操作。

如何使用

本部分以 OpenAI 兼容调用方式为例，向您分步骤介绍 Function Calling 的详细用法，备选的工具为天气查询与时间查询。

如果您使用 DashScope SDK，或需要直接获取完整代码，请点击下表的对应位置。

DashScope	DashScope Python SDK
DashScope Java SDK
OpenAI 兼容	OpenAI Python SDK
OpenAI Node.js SDK

1. 定义工具

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

1.1. 定义工具函数

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

天气查询工具

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

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

时间查询工具

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

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

Python

运行工具后，得到输出：

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

1.2 创建 tools 数组

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

type字段固定为"function"；function字段为 Object 类型；name字段为自定义的工具函数名称，建议使用与函数相同的名称，如get_current_weather或get_current_time；description字段是对工具函数功能的描述，大模型会参考该字段来选择是否使用该工具函数。parameters字段是对工具函数入参的描述，类型是 Object ，大模型会参考该字段来进行入参的提取。如果工具函数不需要输入参数，则无需指定parameters参数。type字段固定为"object"；properties字段描述了入参的名称、数据类型与描述，为 Object 类型，Key 值为入参的名称，Value 值为入参的数据类型与描述；required字段指定哪些参数为必填项，为 Array 类型。对于天气查询工具来说，工具描述信息的格式如下： { "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

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

3. 发起 Function Calling

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

Python

大模型通过返回对象的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

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

上海今天是多云。

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

5. 大模型总结工具函数输出（可选）

进阶用法

流式输出

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

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

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

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

Python

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

{"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。

指定工具调用方式

并行工具调用

上文中的问题“上海天气”只需经过一次工具调用即可得到准确回复，如果输入问题需要调用多次工具，如“四个直辖市的天气如何”或“杭州天气，以及现在几点了”，发起 Function Calling 后只会返回一个工具调用信息，以提问“四个直辖市的天气如何”为例：

{
    "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
        }
    ]
}

返回结果中只有北京市的入参信息。为了解决这一问题，您可以在发起 Function Calling时，将请求参数parallel_tool_calls设置为true，这样返回对象中将包含所有需要调用的工具函数与入参信息。

Python

在返回对象的tool_calls数组中包含了四个直辖市的入参信息：

{
    "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"
        }
    ]
}

强制工具调用

大模型生成内容具有不确定性，有时会选择错误的工具进行调用。如果您希望对于某一类问题，大模型能够采取制定好的工具选择策略（如强制使用某个工具、强制使用至少一个工具、强制不使用工具等），可以通过修改tool_choice参数来强制指定工具调用的策略。

tool_choice参数的默认值为"auto"，表示由大模型自主判断如何进行工具调用。

如果需要大模型总结工具函数输出，请在发起总结的请求时将tool_choice参数去除，否则大模型 API 仍会返回工具调用信息。

强制使用某个工具

如果您希望对于某一类问题，Function Calling 能够强制调用某个工具，可以设定tool_choice参数为{"type": "function", "function": {"name": "the_function_to_call"}}，大模型将不参与工具的选择，只参与输入参数的选择。

假设当前场景中只包含天气查询的问题，您可以修改 function_calling 代码为：

Python

无论输入什么问题，返回对象的工具函数都会是get_current_weather。

使用该策略前请确保问题与选择的工具相关，否则可能返回不符合预期的结果。

强制使用至少一个工具

对于某些需要使用工具的问题，大模型可能会判断无需调用工具。如果您希望无论输入什么问题，Function Calling 都可以进行工具调用（即返回对象中tool_calls参数不为空），可以设定tool_choice参数为"required"，Function Calling 将始终返回工具与入参信息。

假设当前场景中的问题均需要调用工具，您可以修改 function_calling 代码为：

Python

无论输入什么问题，返回对象的tool_calls参数将始终不为空。

使用该策略前请确保问题与工具相关，否则可能返回不符合预期的结果。

强制不使用工具

如果您希望无论输入什么问题，Function Calling 都不会进行工具调用（返回对象中包含回复内容content而tool_calls参数为空），可以设定tool_choice参数为"none"，或不传入tools参数，Function Calling 返回的tool_calls参数将始终为空。

假设当前场景中的问题均无需调用工具，您可以修改 function_calling 代码为：

Python

如何计费

在发起 Function Calling 时，您需要提供 tools 和 messages 参数。计费不仅基于 messages 参数中的内容，还包括 tools 参数中工具描述信息所转化的输入 Token。

完整代码

OpenAI兼容

您可以通过OpenAI SDK或OpenAI兼容的HTTP方式调用通义千问模型，体验Function Call的功能。

Python

示例代码

返回结果

当输入：几点了？时，程序会进行如下输出：

以下是发起Function Call流程（模型的第一轮调用）时模型的返回信息。当输入“杭州天气”时，模型会返回tool_calls参数；当输入“你好”时，模型判断无需调用工具，模型不会返回tool_calls参数。

输入：杭州天气

{
    'id': 'chatcmpl-e2f045fd-2604-9cdb-bb61-37c805ecd15a',
    'choices': [
        {
            'finish_reason': 'tool_calls',
            'index': 0,
            'logprobs': None,
            'message': {
                'content': '',
                'role': 'assistant',
                'function_call': None,
                'tool_calls': [
                    {
                        'id': 'call_7a33ebc99d5342969f4868',
                        'function': {
                            'arguments': '{
                                "location": "杭州市"
                            }',
                            'name': 'get_current_weather'
                        },
                        'type': 'function',
                        'index': 0
                    }
                ]
            }
        }
    ],
    'created': 1726049697,
    'model': 'qwen-max',
    'object': 'chat.completion',
    'service_tier': None,
    'system_fingerprint': None,
    'usage': {
        'completion_tokens': 18,
        'prompt_tokens': 217,
        'total_tokens': 235
    }
}

错误码

如果模型调用失败并返回报错信息，请参见错误信息进行解决。

概述

支持的模型#

概述#

前提条件#

如何使用#

1. 定义工具#

1.1. 定义工具函数#

Python#

1.2 创建 tools 数组#

Python#

2. 创建messages数组#

System Message#

User Message#

Python#

3. 发起 Function Calling#

Python#

4. 运行工具函数#

Python#

进阶用法#

流式输出#

Python#

指定工具调用方式#

并行工具调用#

Python#

强制工具调用#

Python#

Python#

Python#

如何计费#

完整代码#

OpenAI兼容#

Python#

示例代码#

返回结果#

输入：杭州天气#

错误码#

支持的模型

概述

前提条件

如何使用

1. 定义工具

1.1. 定义工具函数

Python

1.2 创建 tools 数组

Python

2. 创建messages数组

System Message

User Message

Python

3. 发起 Function Calling

Python

4. 运行工具函数

Python

进阶用法

流式输出

Python

指定工具调用方式

并行工具调用

Python

强制工具调用

Python

Python

Python

如何计费

完整代码

OpenAI兼容

Python

示例代码

返回结果

输入：杭州天气

错误码