Function calling
更新时间：2025-09-25
能力介绍
Function call是能将大模型与外部工具或代码相连的功能，可通过该功能增强大模型在实时性、数据计算等应用场景的推理效果或进行其他外部操作，包括信息检索、数据库操作、图谱搜索与处理等工具调用场景。
tools是模型服务API中的可选参数，用于向模型提供函数定义。通过此参数，模型能够生成符合用户所提供规范的函数参数。请注意，模型服务API实际上并不会执行任何函数调用，仅返回是否调用函数，以及调用的函数名与调用函数所需要的参数。开发者可以利用模型输出的参数在系统中进一步执行函数调用。
支持模型范围
-
DeepSeek系列
- deepseek-v3.1-250821（非思考模式）
- deepseek-v3.1-think-250821（思考模式）
- deepseek-v3
- deepseek-r1
- deepseek-r1-250528
-
ERNIE系列
- ernie-x1.1-preview
- ernie-x1-turbo-系列
- ernie-speed-pro-128k
- ernie-lite-pro-128k
- ernie-4.5-21b-a3b-thinking
-
kimi系列
- kimi-k2-instruct
-
Qwen系列
- qwen3-coder-480b-a35b-instruct
- qwen3-coder-30b-a3b-instruct
- qwen3-235b-a22b
- qwen3-235b-a22b-thinking-2507
- qwen3-235b-a22b-instruct-2507
- qwen3-30b-a3b
- qwen3-30b-a3b-instruct-2507
- qwen3-30b-a3b-thinking-2507
- qwen3-32b
- qwen3-14b
- qwen3-8b
- qwen3-4b
- qwen3-1.7b
- qwen3-0.6b
- qwq-32b
token用量说明
使用Function calling功能时，内置启动prompt模板拼接，会存在prompt_tokens膨胀，膨胀token数量预计在300token。
tool_choice 参数使用说明
参数行为
tool_choice参数控制模型调用 tool 的行为，参数选项如下：
"tool_choice": "none": 意味着模型不会调用任何 tool，而是生成一条消息。"tool_choice": "auto": 意味着模型可以选择生成一条消息或调用一个或多个 tool。"tool_choice": "required": 意味着模型必须调用一个或多个 tool。"tool_choice": {"type": "function", "function": {"name": "my_function"}}: 指定特定 tool，会强制模型调用该 tool。- 当入参没有 tools 时，tool_choice不生效。
- 当入参有 tools 时，默认值为 auto。可以设置为none、required，以及指定特定tool。
支持范围
-
none、auto：
- 支持functioncall的模型，都支持none、auto模式
-
required、指定特定tool：
- 支持ernie系列
- 支持deepseek-v3、deepseek-r1系列
- deepseek-v3.1、qwen3和kimi-k2，即将支持
效果说明
tool_choice只是尽量让模型按照指定模式运行，但是如果用户输入prompt与tool定义差距太大，大模型不一定能够按照指令强制执行。
快速开始
调用步骤说明
- 使用JSON Schema格式定义函数；
- 通过tools参数将定义好的函数提交给支持function call的大模型，可一次提交多个函数；
- 大模型将根据当前聊天上下文，决定使用哪个函数，也可能不使用函数；
- 若大模型决定使用函数，大模型会将调用函数所需要的参数和信息通过JSON格式返回；
- 使用大模型输出的参数，执行对应的函数，并将此函数执行结果提交给大模型；
- 大模型将根据函数执行结果，给予用户回复。
SDK调用示例
Python
1from openai import OpenAI
2
3client = OpenAI(
4 api_key=api_key ##
5 base_url="https://qianfan.baidubce.com/v2", ##
6)
7
8tools = [
9 {
10 "type": "function",
11 "function": {
12 "name": "get_current_weather",
13 "description": "Get the current weather in a given location",
14 "parameters": {
15 "type": "object",
16 "properties": {
17 "location": {
18 "type": "string",
19 "description": "The city and state, e.g. San Francisco, CA",
20 },
21 "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
22 },
23 "required": ["location"],
24 },
25 }
26 }
27]
28messages = [{"role": "user", "content": "What's the weather like in Boston today?"}]
29completion = client.chat.completions.create(
30 model="deepseek-v3",
31 messages=messages,
32 tools=tools,
33 tool_choice="auto"
34)
35
36print(completion)典型案例
以下示例当中的model可以替换为支持范围内的模型
同个工具多次调用
调用get_current_weather工具2次
- get_current_weather，参数上海
- get_current_weather，参数北京
第一轮
请求
Bash
1curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
2--header 'Content-Type: application/json' \
3--data '{
4 "model": "deepseek-r1",
5 "messages": [
6 {
7 "role": "user",
8 "content": "查一下上海和北京现在的天气"
9 }
10 ],
11 "tools": [{
12 "type": "function",
13 "function": {
14 "name": "get_current_weather",
15 "description": "天气查询工具",
16 "parameters": {
17 "properties": {
18 "location": {
19 "description": "地理位置，精确到区县级别",
20 "type": "string"
21 },
22 "time": {
23 "description": "时间，格式为YYYY-MM-DD",
24 "type": "string"
25 }
26 },
27 "type": "object"
28 }
29 }
30
31 }],
32 "stream": false,
33 "tool_choice" : "auto"
34}
35'返回
JSON
1{
2 "id": "as-iyiscjp3qj",
3 "object": "chat.completion",
4 "created": 1746955406,
5 "model": "deepseek-r1",
6 "choices": [
7 {
8 "index": 0,
9 "message": {
10 "role": "assistant",
11 "content": "",
12 "reasoning_content": "好的，用户让我查上海和北京现在的天气。我需要用天气查询工具。首先，确认工具的参数要求，需要地理位置和时间。用户提到“现在”，所以时间应该是今天的日期。地理位置要精确到区县，但用户只给了城市，可能需要默认行政区，比如上海市和北京市。然后生成两个工具调用，分别处理上海和北京。检查参数是否正确，确保日期格式是YYYY-MM-DD，比如今天的2023-10-10。然后按照输出格式，两次调用函数，分别传入location为上海和北京，时间都是今天。最后组合成正确的响应格式。\n",
13 "tool_calls": [
14 {
15 "id": "5acc5ea7a2584225b2eee9cf45390ffa",
16 "type": "function",
17 "function": {
18 "name": "get_current_weather",
19 "arguments": "{\"location\": \"上海\", \"time\": \"2023-10-10\"}"
20 }
21 },
22 {
23 "id": "9a3208f72b124140b862adc6adb240bd",
24 "type": "function",
25 "function": {
26 "name": "get_current_weather",
27 "arguments": "{\"location\": \"北京\", \"time\": \"2023-10-10\"}"
28 }
29 }
30 ]
31 },
32 "finish_reason": "tool_calls",
33 "flag": 0
34 }
35 ],
36 "usage": {
37 "prompt_tokens": 370,
38 "completion_tokens": 347,
39 "total_tokens": 717,
40 "completion_tokens_details": {
41 "reasoning_tokens": 123
42 }
43 }
44}第二轮
请求
Bash
1curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
2--header 'Content-Type: application/json' \
3--data '{
4 "model": "deepseek-r1",
5 "messages": [
6 {
7 "role": "user",
8 "content": "查一下上海和北京现在的天气"
9 },
10 {
11 "role": "assistant",
12 "content": "",
13 "reasoning_content": "好的，用户让我查上海和北京现在的天气。我需要用天气查询工具。首先，确认工具的参数要求，需要地理位置和时间。用户提到“现在”，所以时间应该是今天的日期。地理位置要精确到区县，但用户只给了城市，可能需要默认行政区，比如上海市和北京市。然后生成两个工具调用，分别处理上海和北京。检查参数是否正确，确保日期格式是YYYY-MM-DD，比如今天的2023-10-10。然后按照输出格式，两次调用函数，分别传入location为上海和北京，时间都是今天。最后组合成正确的响应格式。\n",
14 "tool_calls": [
15 {
16 "id": "5acc5ea7a2584225b2eee9cf45390ffa",
17 "type": "function",
18 "function": {
19 "name": "get_current_weather",
20 "arguments": "{\"location\": \"上海\", \"time\": \"2023-10-10\"}"
21 }
22 },
23 {
24 "id": "9a3208f72b124140b862adc6adb240bd",
25 "type": "function",
26 "function": {
27 "name": "get_current_weather",
28 "arguments": "{\"location\": \"北京\", \"time\": \"2023-10-10\"}"
29 }
30 }
31 ]
32 },
33 {
34 "role": "tool",
35 "tool_call_id": "5acc5ea7a2584225b2eee9cf45390ffa",
36 "name": "get_current_weather",
37 "content": "{\"temperature\": \"25\", \"unit\": \"摄氏度\", \"description\": \"上海\"}"
38 },
39 {
40 "role": "tool",
41 "tool_call_id": "9a3208f72b124140b862adc6adb240bd",
42 "name": "get_current_weather",
43 "content": "{\"temperature\": \"20\", \"unit\": \"摄氏度\", \"description\": \"北京\"}"
44 }
45 ],
46 "tools": [
47 {
48 "type": "function",
49 "function": {
50 "name": "get_current_weather",
51 "description": "天气查询工具",
52 "parameters": {
53 "properties": {
54 "location": {
55 "description": "地理位置，精确到区县级别",
56 "type": "string"
57 },
58 "time": {
59 "description": "时间，格式为YYYY-MM-DD",
60 "type": "string"
61 }
62 },
63 "type": "object"
64 }
65 }
66 }
67 ],
68 "stream": false,
69 "tool_choice": "auto"
70}'返回
JSON
1{
2 "id": "as-0hcayp93mq",
3 "object": "chat.completion",
4 "created": 1746955575,
5 "model": "deepseek-r1",
6 "choices": [
7 {
8 "index": 0,
9 "message": {
10 "role": "assistant",
11 "content": "根据最新的天气数据：上海当前天气情况：25摄氏度，天气状况良好。北京当前天气情况：20摄氏度，温度适宜。两地昼夜温差较大，建议您根据出行时间携带薄外套备用。",
12 "reasoning_content": "好的，我现在需要处理用户查询上海和北京天气的请求。用户已经提供了工具调用的结果，分别是上海和北京的天气数据。首先，我要确认用户的目标是获取这两个城市当前的天气状况，所以需要将这些数据整合成自然流畅的回答。\n\n接下来，我要检查工具返回的数据是否完整，温度、单位和天气描述都有提供。上海的温度是25摄氏度，天气描述可能需要更具体的信息，比如“晴”或“多云”，但用户这里只给出了“上海”，可能描述字段有误或者不完整。不过根据现有数据，应该可以形成基本回答。北京的天气是20摄氏度，描述同样只提到了城市名称，可能需要推测或保持简洁。\n\n然后，我需要将两个城市的天气信息分开呈现，避免混淆。通常用户希望每个城市的信息清晰列出，比如分点说明或者用分隔符隔开。同时，要注意使用用户友好的语言，避免机械式的重复数据。\n\n还要考虑是否需要补充额外的信息，比如提醒用户根据天气情况携带雨具或增减衣物，但根据当前数据，温度适中，可能不需要特别提醒，不过如果有描述中的天气情况比如下雨，就需要提及。但这里描述字段可能存在问题，所以可能需要保持简洁。\n\n最后，确保回答准确无误，温度单位正确，城市对应正确，没有数据混淆。如果有不确定的地方，比如描述字段的问题，可能需要在回答中稍作调整，或者保持原有信息的呈现，避免猜测。\n\n总结，回答的结构应该是先上海后北京，分别列出温度、单位和天气描述（如果有的话），或者直接呈现温度和可能的简要描述。由于用户给出的描述字段可能存在问题，这里可能需要简化处理，直接报告温度和单位，并确认城市名称。\n"
13 },
14 "finish_reason": "stop",
15 "flag": 0
16 }
17 ],
18 "usage": {
19 "prompt_tokens": 508,
20 "completion_tokens": 729,
21 "total_tokens": 1237,
22 "completion_tokens_details": {
23 "reasoning_tokens": 341
24 }
25 }
26}多个不同工具调用
同时调用如下2个工具
- get_current_time
- get_current_weather
请求
Bash
1curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer api-key' \
4--data '{
5 "model": "deepseek-r1",
6 "messages": [
7 {
8 "role": "user",
9 "content": "杭州的天气情况，以及现在几点了"
10 }
11 ],
12 "tools": [
13 {
14 "type": "function",
15 "function": {
16 "name": "get_current_time",
17 "description": "获取当前时间，可指定时区和输出格式",
18 "parameters": {
19 "type": "object",
20 "properties": {
21 "timezone": {
22 "type": "string",
23 "description": "时区名称，例如Asia/Shanghai、UTC"
24 },
25 "format": {
26 "type": "string",
27 "description": "时间格式字符串，默认%Y-%m-%d %H:%M:%S"
28 }
29 },
30 "required": []
31 }
32 }
33 },
34 {
35 "type": "function",
36 "function": {
37 "name": "get_current_weather",
38 "description": "当你想查询指定城市的天气时非常有用。",
39 "parameters": {
40 "type": "object",
41 "properties": {
42 // 查询天气时需要提供位置，因此参数设置为location
43 "location": {
44 "type": "string",
45 "description": "城市或县区，比如北京市、杭州市、余杭区等。"
46 }
47 },
48 "required": [
49 "location"
50 ]
51 }
52 }
53 },
54 {
55 "type": "function",
56 "function": {
57 "name": "query_train_info",
58 "description": "根据用户提供的信息，查询对应的车次",
59 "parameters": {
60 "type": "object",
61 "properties": {
62 "departure": {
63 "type": "string",
64 "description": "出发城市或车站"
65 },
66 "destination": {
67 "type": "string",
68 "description": "目的地城市或车站"
69 },
70 "date": {
71 "type": "string",
72 "description": "要查询的车次日期"
73 }
74 },
75 "required": [
76 "departure",
77 "destination",
78 "date"
79 ]
80 }
81 }
82 }
83 ],
84 "stream": false
85}'返回
Plain Text
1{
2 "id": "as-unkecbb1ap",
3 "object": "chat.completion",
4 "created": 1755174023,
5 "model": "deepseek-r1",
6 "choices": [
7 {
8 "index": 0,
9 "message": {
10 "role": "assistant",
11 "content": "",
12 "reasoning_content": "好的，用户问杭州的天气和现在的时间。首先我需要确认需要调用哪些工具。用户提到了天气，所以应该用get_current_weather，参数是location设为杭州市。然后用户问现在几点，需要用get_current_time，可能需要指定时区，因为杭州在中国，应该用Asia/Shanghai时区。接下来要检查这两个工具的参数是否齐全。天气工具需要location，用户已经提供了。时间工具的参数是可选的，但最好指定时区，确保时间准确。然后生成两个函数调用的JSON参数，分别对应这两个工具。确保参数格式正确，没有语法错误。最后按照指定的输出格式排列，用tool_calls_begin和tool_call_end包裹每个调用。检查是否遗漏了任何必填参数，比如日期或时间格式，但时间工具的必填参数是空的，可以不用填。确认无误后输出结果。\n",
13 "tool_calls": [
14 {
15 "id": "68e892c388e44c83a06867f44ecee6f3",
16 "type": "function",
17 "function": {
18 "name": "get_current_weather",
19 "arguments": "{\"location\": \"杭州市\"}"
20 }
21 },
22 {
23 "id": "8de2c4c50bf0440995e7a496767d13d2",
24 "type": "function",
25 "function": {
26 "name": "get_current_time",
27 "arguments": "{\"timezone\": \"Asia/Shanghai\"}"
28 }
29 }
30 ]
31 },
32 "finish_reason": "tool_calls",
33 "flag": 0
34 }
35 ],
36 "usage": {
37 "prompt_tokens": 664,
38 "completion_tokens": 258,
39 "total_tokens": 922,
40 "prompt_tokens_details": {
41 "cached_tokens": 1
42 },
43 "completion_tokens_details": {
44 "reasoning_tokens": 179
45 }
46 }
47}单个工具单次调用
请求
Bash
1curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer api-key' \
4--data '{
5 "model": "deepseek-v3",
6 "messages": [
7 {
8 "role": "system",
9 "content": "你是一个智能助手"
10 },
11 {
12 "role": "user",
13 "content": "你能帮我查询2024年1月1日从北京南站到上海的火车票吗？"
14 }
15 ],
16 "stream": false,
17 "tools": [
18 {
19 "type": "function",
20 "function": {
21 "name": "query_train_info",
22 "description": "根据用户提供的信息，查询对应的车次",
23 "parameters": {
24 "type": "object",
25 "properties": {
26 "departure": {
27 "type": "string",
28 "description": "出发城市或车站"
29 },
30 "destination": {
31 "type": "string",
32 "description": "目的地城市或车站"
33 },
34 "date": {
35 "type": "string",
36 "description": "要查询的车次日期"
37 }
38 },
39 "required": [
40 "departure",
41 "destination",
42 "date"
43 ]
44 }
45 }
46 }
47 ]
48}'返回
JSON
1{
2 "id": "as-ubsiihj8d5",
3 "object": "chat.completion",
4 "created": 1732887366,
5 "model": "deepseek-v3",
6 "choices": [
7 {
8 "index": 0,
9 "message": {
10 "role": "assistant",
11 "content": "",
12 "tool_calls": [
13 {
14 "id": "19d8e571660dd000",
15 "type": "function",
16 "function": {
17 "name": "query_train_info",
18 "arguments": "{\"departure\": \"北京南站\", \"destination\": \"上海\", \"date\": \"2024-01-01\"}"
19 }
20 }
21 ]
22 },
23 "finish_reason": "tool_calls",
24 "flag": 0
25 }
26 ],
27 "usage": {
28 "prompt_tokens": 19,
29 "completion_tokens": 33,
30 "total_tokens": 52
31 }
32}指定工具调用
请求
Bash
1curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer api-key' \
4--data '{
5 "model": "deepseek-r1",
6 "messages": [
7 {
8 "role": "user",
9 "content": "查一下上海和北京现在的天气"
10 }
11 ],
12 "tool_choice": {
13 "type": "function",
14 "function": {
15 "name": "query_train_info"
16 }
17 },
18 "tools": [
19 {
20 "type": "function",
21 "function": {
22 "name": "get_current_weather",
23 "description": "天气查询工具",
24 "parameters": {
25 "properties": {
26 "location": {
27 "description": "地理位置，精确到区县级别",
28 "type": "string"
29 },
30 "time": {
31 "description": "时间，格式为YYYY-MM-DD",
32 "type": "string"
33 }
34 },
35 "type": "object"
36 }
37 }
38 },
39 {
40 "type": "function",
41 "function": {
42 "name": "query_train_info",
43 "description": "根据用户提供的信息，查询对应的车次",
44 "parameters": {
45 "type": "object",
46 "properties": {
47 "departure": {
48 "type": "string",
49 "description": "出发城市或车站"
50 },
51 "destination": {
52 "type": "string",
53 "description": "目的地城市或车站"
54 },
55 "date": {
56 "type": "string",
57 "description": "要查询的车次日期"
58 }
59 },
60 "required": [
61 "departure",
62 "destination",
63 "date"
64 ]
65 }
66 }
67 }
68 ],
69 "stream": false
70}'返回
JSON
1{
2 "id": "as-vzy3tpikdm",
3 "object": "chat.completion",
4 "created": 1755191184,
5 "model": "deepseek-r1",
6 "choices": [
7 {
8 "index": 0,
9 "message": {
10 "role": "assistant",
11 "content": "",
12 "reasoning_content": "好的，用户让我查上海和北京现在的天气。不过我需要先检查一下可用的工具。根据提供的工具列表，目前只有一个工具是query_train_info，用于查询车次信息，参数包括日期、出发地和目的地。\n\n用户的问题是关于天气的，但现有的工具并不支持天气查询。这意味着我需要调用正确的工具来回答问题，但明显工具不匹配。因此，我必须按照规则，即使用给定的工具来回复，所以可能需要告知用户无法处理天气请求，或者尝试用现有工具处理。\n\n不过，用户提到的是“现在”的天气，而工具需要日期、出发地和目的地。假设用户可能想查询今天的车次，可能出发地是上海，目的地是北京，日期是今天。或者用户可能混淆了车次查询和天气查询。\n\n根据规则，无论如何必须调用给定的工具，即使不相关。因此，我需要提取可能的参数。用户提到上海和北京，可能作为出发和到达地。日期需要当前日期。假设今天是2023年10月5日，但实际应用中可能需要动态获取日期。不过用户没有提供具体日期，所以可能需要提示用户补充信息，或者使用默认值。\n\n但根据工具的参数要求，必须包含date、departure和destination。用户没有提供日期，所以可能需要补全。例如，假设用户想查询今天从上海到北京的车次，或者相反。因此，可能需要生成两个调用，一个是上海到北京，另一个是北京到上海，或者询问日期。\n\n但按照输出格式，必须调用工具，所以需要构造参数。例如，date设为今天的日期，出发和目的地分别为上海和北京。但用户的问题是关于天气，所以调用车次查询工具可能无法满足需求，但根据规则必须调用工具，所以只能生成这样的调用，但结果可能不相关。\n\n这可能意味着系统存在局限性，但作为助手必须遵循规则。因此，我需要构造一个调用，例如出发地为上海，目的地为北京，日期为今天，调用query_train_info。但用户实际上需要天气信息，所以正确的做法应是告知无法处理，但根据给定规则，必须调用工具，所以只能生成这样的调用，即使不相关。\n\n不过，这可能不是最佳做法。但根据用户的指示，无论用户输入是否相关，都必须调用工具。因此，我需要生成对应的JSON参数，即使参数不全。例如用户没有提供日期，但工具要求必填，可能需要假设日期，比如今天，或者提示用户补充，但根据规则必须调用工具，所以必须包含所有必填参数。\n\n所以，我需要构造date参数为今天的日期，比如\"2023-10-05\"，departure为上海，destination为北京。但用户的问题是关于天气，所以调用车次查询工具可能无法得到有用的信息，但根据规则必须调用。因此，生成对应的tool call。\n\n总结，必须调用query_train_info，参数为date（假设今天）、departure（上海）、destination（北京），即使用户的问题不相关。因此，输出对应的JSON调用。\n",
13 "tool_calls": [
14 {
15 "id": "2ee8479cbd6c40cab0bf2ea45e3c53a0",
16 "type": "function",
17 "function": {
18 "name": "query_train_info",
19 "arguments": "{ \"date\": \"2023-10-05\", \"departure\": \"上海\", \"destination\": \"北京\"}"
20 }
21 }
22 ]
23 },
24 "finish_reason": "tool_calls",
25 "flag": 0
26 }
27 ],
28 "usage": {
29 "prompt_tokens": 475,
30 "completion_tokens": 677,
31 "total_tokens": 1152,
32 "prompt_tokens_details": {
33 "cached_tokens": 2
34 },
35 "completion_tokens_details": {
36 "reasoning_tokens": 609
37 }
38 }
39}