1. Introduction to Function Calling
In the GPT model, Function Calling refers to providing descriptive functions to the model through an API, allowing it to intelligently select and output a JSON object containing parameters for calling one or more functions. It’s important to note that the Chat Completions API does not directly execute function calls, but rather generates JSON that can be used to execute functions in the code.
In simple terms, the Function Calling feature involves providing a set of function definitions (including function descriptions and parameter descriptions) to the GPT model. The model then decides which function to call based on the user’s query. Since the model cannot execute external functions, it can only respond with a request for which function to call (including function call parameters). After receiving the model’s request result, our program executes the function call locally. The result of the function call is then concatenated with the prompt and sent back to the model for further processing before returning the final result to the user.
2. Application Scenarios of Function Calling
Here are some examples of its practical applications:
- Creating an assistant to answer questions by calling external APIs, such as defining functions like
send_email(to: string, body: string)orget_current_weather(location: string, unit: 'celsius' | 'fahrenheit'). - Converting natural language into API calls, for example translating “Who are my top customers?” into
get_customers(min_revenue: int, created_before: string, limit: int)and then making an internal API call. - Extracting structured data from text, for instance defining functions like
extract_data(name: string, birthday: string)orsql_query(query: string).
By utilizing the Function Calling feature, we can implement AI agents that interact with our local systems and databases, such as having AI query the latest weather, check stock prices, order takeaway, or book flights.
3. Models Supporting Function Calling
Not all versions of the model have been trained with function calling data. Currently, the models that support function calling are: gpt-4, gpt-4-turbo-preview, gpt-4-0125-preview, gpt-4-1106-preview, gpt-4-0613, gpt-3.5-turbo, gpt-3.5-turbo-1106, and gpt-3.5-turbo-0613.
Furthermore, the models gpt-4-turbo-preview, gpt-4-0125-preview, gpt-4-1106-preview, and gpt-3.5-turbo-1106 support parallel function calling, allowing them to execute multiple function calls at once and can handle these function calls concurrently to produce effective and efficient results.
Note: The potential risk associated with the Function Calling feature is that it may lead to the model producing erroneous parameters (i.e., phantom parameters). Therefore, before taking any actions that impact the real world (such as sending emails, online publishing, making purchases, etc.), it is advisable to incorporate a user confirmation process at the product level, ensuring that functions are executed only after user confirmation.
4. Function Calling Examples
4.1 Python Example
Implementing Function Calling on the OpenAI platform typically follows the basic steps outlined below. The following will detail the entire process using a Python code example, focusing on querying the weather.
Step 1: Prepare callable functions and function definitions for the model
First, we need to define a function that can be called by the GPT model. This typically means preparing our own function that can perform certain operations based on the input parameters, such as communicating with a third-party API.
import json
def get_current_weather(location, unit="fahrenheit"):
return json.dumps({
"location": location,
"temperature": "18",
"unit": unit
})
Step 2: Call the model based on the query and tools parameter
Next, we need to call the GPT model through the Chat Completion API and pass in the user’s query (e.g. “What is the current weather”) as well as the tools parameter, which includes the description of the get_current_weather function we just defined.
from openai import OpenAI
client = OpenAI()
tools = [{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Get the current weather for a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name, for example: 'San Francisco, CA'"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
}
}]
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "What is the current weather in San Francisco?"}],
tools=tools
)
Step 3: Execute the function locally
The result returned by the model will include information about the function the model wants to call, typically contained in the tool_calls response parameter. We can then execute the corresponding function call locally based on the function call information described in the tool_calls parameter.
tool_calls = response.choices[0].message.tool_calls
if tool_calls:
arguments = json.loads(tool_calls[0].function.arguments)
weather_info = get_current_weather(**arguments)
print(weather_info) # Here we can see the weather information queried by the function call
Step 4: Call the model again with the function return result
Now, we can send the function’s return result as a new message to the model, so that the model can process these results and generate a response tailored to the user.
follow_up_response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[
{"role": "user", "content": "What is the current weather in San Francisco?"},
{"role": "function", "name": "get_current_weather", "content": weather_info}
],
tools=tools
)
Explanation:
In the example above, the function return content is sent to the GPT model through the function message as follows:
{"role": "function", "name": "get_current_weather", "content": weather_info}
In practice, you can also simply put the function’s return content as reference content into the system message prompt for AI to refer to when answering questions.
Step 5: Obtain the final response from the model
Finally, we can retrieve the model’s final response and provide it to the user. In this step, the model will output a user-friendly answer based on the weather information we provided.
final_output = follow_up_response.choices[0].message.content
print(final_output) # This output is the weather information we want to show to the user
Following the above steps, we have completed a complete example of querying the weather using the GPT model and function calls.
4.2. Function call function definition explanation
4.2.1 Meaning of the ‘Tools’ Parameter Fields
When making a function call, you need to define the relevant information of the function in the tools parameter. The tools parameter is an array containing multiple function definitions, and each function definition includes the following fields:
type: This field represents the type of the tool. In a function call, this field should be set to"function".function: This field contains detailed information about the function and is an object with the following specific fields:name: The name of the function, which is a string.description: A description of the function’s purpose, which can help the model generate parameters that meet user expectations.parameters: Describes the function’s parameter definitions and is an object that contains the following sub-fields:type: Defines the type of the parameter, which should mostly be set to"object".properties: The specific definitions of each function parameter, where each parameter definition is an object typically containing the following sub-fields:type: The data type of the parameter (such as"string","integer","boolean", etc.).description: The description of the parameter to help the model understand its purpose.enum(optional): Whentypeis"string", theenumfield can specify an array of strings representing the set of valid values.
required: An array of strings containing the names of the required parameters.
4.2.2 Tools Definition Examples
Now let’s provide some examples of tools definitions to help understand how each field is used.
Example 1: Get Current Weather Information
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Get current weather information for the specified location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city for which weather needs to be queried, e.g., 'San Francisco, CA'"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit, 'celsius' for Celsius, 'fahrenheit' for Fahrenheit"
}
},
"required": ["location", "unit"]
}
}
}
In the above example, we have defined a function named get_current_weather for getting the current weather of a specified location. The parameters include location and unit, where unit has two valid values: “celsius” (Celsius) and “fahrenheit” (Fahrenheit).
Example 2: Find Albums for a Specific Artist
{
"type": "function",
"function": {
"name": "find_artist_albums",
"description": "Find all albums for a specific artist",
"parameters": {
"type": "object",
"properties": {
"artist_name": {
"type": "string",
"description": "The name of the artist"
}
},
"required": ["artist_name"]
}
}
}
In this example, we have created a function called find_artist_albums to find all albums for a specific artist. This function only requires one parameter: artist_name (the name of the artist).
4.3. Example of an HTTP Request Function Call
OpenAI provides an API that is accessible through the HTTP protocol. Below, we will explain how to use the function call feature through the HTTP API. Developers of other programming languages can refer to this example.
4.3.1. Step 1: Call the Model with User Query and Function Declaration
First, we need to send the user’s query and the list of functions we support to the GPT model, so that the model can automatically analyze which function to call to answer the user’s query based on the user’s question.
In the following example, we inform GPT that we have a get_current_weather function that can be used to query the weather information for a specified city.
curl --location 'https://api.aiproxy.io/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {OPENAI_KEY}' \
--data '{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "user",
"content": "What's the weather like in Shanghai today?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Get the current weather information for the specified location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city for which weather needs to be queried, e.g. 'San Francisco, CA'"
},
"unit": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Temperature unit, 'celsius' for Celsius, 'fahrenheit' for Fahrenheit"
}
},
"required": [
"location",
"unit"
]
}
}
}
]
}'
Request parameter explanation:
{
"model": "gpt-3.5-turbo", // The GPT model to be called
"messages": [ // This is the list of messages for GPT, including the user's query
{
"role": "user",
"content": "What's the weather like in Shanghai today?"
}
],
"tools": [
// This is your function definition, informing GPT of the available functions
]
}
Refer to section 4.2.2 for the definition of the tools parameter.
In the normal processing by the GPT model, you will receive an API response similar to the following:
{
"model": "gpt-3.5-turbo-0613",
"object": "chat.completion",
"usage": {
"prompt_tokens": 122,
"completion_tokens": 27,
"total_tokens": 149
},
"id": "chatcmpl-8mL4hS4zNMocyR2ajKyAvSTcbNaao",
"created": 1706531447,
"choices": [
{
"index": 0,
"delta": null,
"message": {
"role": "assistant",
"tool_calls": [ // The tool_calls parameter represents the list of functions that GPT wishes to call
{
"id": "call_1iF09ttX1R9ESR18Ul2nLe1R",
"type": "function",
"function": {
"name": "get_current_weather", // Indicates that GPT wishes to answer the user's query by calling the get_current_weather function
"arguments": "{\n \"location\": \"Shanghai, China\",\n \"unit\": \"celsius\"\n}" // This is the input parameter for calling the get_current_weather function
}
}
]
},
"finish_reason": "tool_calls"
}
]
}
4.3.2. Step 2: Local Function Call Execution
Since the GPT model itself cannot execute specific function calls and only informs us which function it wishes to call, our local program needs to execute the specific function call based on the tool_calls parameter returned by the model. The way to execute local functions varies in different programming languages. For example, in Python, you can refer to the earlier section.
4.3.3. Step 3: Call the Model Again with the Function’s Return Result
Because the function call is executed locally, we need to pass the result of the function execution and the user’s question back to the GPT model to make the final response.
curl --location 'https://api.aiproxy.io/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk-Roc5MX1zEuVxiuaMaETV6wZ2jXcCehjUCzwP9AcNErUiwppQ' \
--data '{
"model": "gpt-3.5-turbo",
"messages": [
{
"role": "user",
"content": "What's the weather like in Shanghai today?"
},
{
"role": "function",
"name": "get_current_weather",
"content": "{\"city\":\"Shanghai\", \"temperature\":\"25 degrees Celsius\"}"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Get the current weather information for the specified location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city for which to query the weather, e.g., 'San Francisco, CA'"
},
"unit": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "The unit of temperature, 'celsius' for Celsius, 'fahrenheit' for Fahrenheit"
}
},
"required": [
"location",
"unit"
]
}
}
}
]
}'
Note: The above request includes an additional function message to inform the GPT model of the function’s return value. GPT will directly answer the user’s question based on the function’s return information and will not call the function again.
The function message represents the function’s return value and follows the format below:
{
"role": "function", // Message type is function, indicating the function's return value
"name": "get_current_weather", // Informs GPT that the current message is the return value of the get_current_weather function
"content": "{\"city\":\"Shanghai\", \"temperature\":\"25 degrees Celsius\"}" // Function return content, can be in JSON format or other text content.
}
Below is the final response generated by GPT:
{
"model": "gpt-3.5-turbo-0613",
"object": "chat.completion",
"usage": {
"prompt_tokens": 144,
"completion_tokens": 17,
"total_tokens": 161
},
"id": "chatcmpl-8mLmvvKAjSql7rGF8fvQeddKhWYvr",
"created": 1706534189,
"choices": [
{
"index": 0,
"delta": null,
"message": {
"role": "assistant",
"content": "The weather in Shanghai today is 25 degrees Celsius."
},
"finish_reason": "stop"
}
]
}