本文將介紹函式呼叫功能，說明其運作方式、功能，以及實作最佳做法。
函式呼叫 (亦稱工具使用) 會為大型語言模型提供外部工具的定義 (例如 get_current_weather 函式)。處理提示時，模型會判斷是否需要工具，如果需要，則會輸出結構化資料，指定要呼叫的工具及其參數 (例如 get_current_weather(location='Boston'))。接著，應用程式會執行這項工具，將結果回饋給模型，讓模型完成回覆，並提供動態的實際資訊或動作結果。這項做法可將 LLM 與系統連結，並擴展 LLM 的功能。
函式呼叫功能主要有兩種用途：
- 擷取資料：擷取最新資訊，供模型回覆時參考，例如目前天氣、貨幣換算，或是知識庫和 API 中的特定資料 (RAG)。
- 採取行動：執行外部作業，例如提交表單、更新應用程式狀態，或協調代理程式工作流程 (例如交接對話)。
如要查看更多使用函式呼叫的用途和範例，請參閱「用途」。
功能與限制
如何建立函式呼叫應用程式
如要使用函式呼叫功能，請執行下列工作：
- 將函式宣告和提示提交給模型。
- 將 API 輸出內容提供給模型。
步驟 1：將提示和函式聲明提交給模型
以與 OpenAPI 結構定義相容的結構定義格式，宣告 Tool。詳情請參閱結構定義範例。
下列範例會將提示和函式宣告提交給 Gemini 模型。
使用 Python SDK 時，您可以手動以字典宣告函式結構定義，也可以使用 from_func 輔助程式自動宣告。下表比較這兩種方法。
| 聲明方式 |
說明 |
優點 |
缺點 |
| 手動 (Python 字典) |
使用符合 OpenAPI 規格的 Python 字典，明確定義函式結構定義。 |
可全面掌控結構定義，非常適合用於複雜或非標準的函式定義。 |
較為冗長，且如果 Python 函式簽章有所變更，就必須手動更新。 |
自動 (from_func) |
從 Python 函式的簽章和說明字串自動產生結構定義。 |
簡潔、不易出錯，且會自動與 Python 函式保持同步。 |
對產生的結構定義控制程度較低，且可能不支援所有複雜的結構定義功能。 |
REST
PROJECT_ID=myproject
LOCATION=us-central1
MODEL_ID=gemini-2.0-flash-001
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "What is the weather in Boston?"
}]
}],
"tools": [{
"functionDeclarations": [
{
"name": "get_current_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name of the location for which to get the weather.",
"default": {
"string_value": "Boston, MA"
}
}
},
"required": [
"location"
]
}
}
]
}]
}'
Python
您可以手動使用 Python 字典指定結構定義，也可以使用 from_func 輔助函式自動指定。以下範例說明如何手動宣告函式。
import vertexai
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerationConfig,
GenerativeModel,
Part,
Tool,
ToolConfig
)
# Initialize Vertex AI
# TODO(developer): Update the project
vertexai.init(project="PROJECT_ID", location="us-central1")
# Initialize Gemini model
model = GenerativeModel(model_name="gemini-2.0-flash")
# Manual function declaration
get_current_weather_func = FunctionDeclaration(
name="get_current_weather",
description="Get the current weather in a given location",
# Function parameters are specified in JSON schema format
parameters={
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name of the location for which to get the weather.",
"default": {
"string_value": "Boston, MA"
}
}
},
},
)
response = model.generate_content(
contents = [
Content(
role="user",
parts=[
Part.from_text("What is the weather like in Boston?"),
],
)
],
generation_config = GenerationConfig(temperature=0),
tools = [
Tool(
function_declarations=[get_current_weather_func],
)
]
)
或者，您也可以使用 from_func 輔助函式自動宣告函式，如下列範例所示：
def get_current_weather(location: str = "Boston, MA"):
"""
Get the current weather in a given location
Args:
location: The city name of the location for which to get the weather.
"""
# This example uses a mock implementation.
# You can define a local function or import the requests library to call an API
return {
"location": "Boston, MA",
"temperature": 38,
"description": "Partly Cloudy",
"icon": "partly-cloudy",
"humidity": 65,
"wind": {
"speed": 10,
"direction": "NW"
}
}
get_current_weather_func = FunctionDeclaration.from_func(get_current_weather)
Node.js
這個範例會示範文字情境，其中包含一個函式和一個提示。
Go
這個範例會示範文字情境，其中包含一個函式和一個提示。
瞭解如何安裝或更新 Go。
詳情請參閱
SDK 參考說明文件。
設定環境變數，透過 Vertex AI 使用 Gen AI SDK：
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
C#
這個範例會示範文字情境，其中包含一個函式和一個提示。
如果模型判斷需要函式的輸出內容，模型的回應會包含函式名稱和用於呼叫的參數值。
以下範例顯示模型對「波士頓的天氣如何？」提示的回應。模型建議使用參數 Boston, MA 呼叫 get_current_weather 函式。
candidates {
content {
role: "model"
parts {
function_call {
name: "get_current_weather"
args {
fields {
key: "location"
value {
string_value: "Boston, MA"
}
}
}
}
}
}
...
}
步驟 2：將 API 輸出內容提供給模型
呼叫外部 API，並將 API 輸出內容傳回模型。
以下範例使用合成資料模擬外部 API 的回應酬載，並將輸出內容傳回模型。
REST
PROJECT_ID=myproject
MODEL_ID=gemini-2.0-flash
LOCATION="us-central1"
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
-d '{
"contents": [
{
"role": "user",
"parts": {
"text": "What is the weather in Boston?"
}
},
{
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "Boston, MA"
}
}
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "get_current_weather",
"response": {
"temperature": 20,
"unit": "C"
}
}
}
]
}
],
"tools": [
{
"function_declarations": [
{
"name": "get_current_weather",
"description": "Get the current weather in a specific location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name of the location for which to get the weather."
}
},
"required": [
"location"
]
}
}
]
}
]
}'
Python
function_response_contents = []
function_response_parts = []
# Iterates through the function calls in the response in case there are parallel function call requests
for function_call in response.candidates[0].function_calls:
print(f"Function call: {function_call.name}")
# In this example, we'll use synthetic data to simulate a response payload from an external API
if (function_call.args['location'] == "Boston, MA"):
api_response = { "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy" }
if (function_call.args['location'] == "San Francisco, CA"):
api_response = { "location": "San Francisco, CA", "temperature": 58, "description": "Sunny" }
function_response_parts.append(
Part.from_function_response(
name=function_call.name,
response={"contents": api_response}
)
)
# Add the function call response to the contents
function_response_contents = Content(role="user", parts=function_response_parts)
# Submit the User's prompt, model's response, and API output back to the model
response = model.generate_content(
[
Content( # User prompt
role="user",
parts=[
Part.from_text("What is the weather like in Boston?"),
],
),
response.candidates[0].content, # Function call response
function_response_contents # API output
],
tools=[
Tool(
function_declarations=[get_current_weather_func],
)
],
)
# Get the model summary response
print(response.text)
如需 API 呼叫相關最佳做法，請參閱「驗證 API 呼叫」。
如果模型建議多個並行函式呼叫，應用程式會將所有回應傳回模型。詳情請參閱「平行函式呼叫」。
模型可能會判斷回應提示時，需要另一個函式的輸出內容。在這種情況下，應用程式從模型收到的回應會包含另一個函式名稱和另一組參數值。
如果模型判斷 API 回應足以回覆使用者提示，就會建立自然語言回覆並傳回給應用程式。應用程式接著會將回應傳遞給使用者。以下是自然語言回應的範例：
It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies.
函式呼叫 (附帶想法)
啟用 thinking 呼叫函式時，您需要從模型回應物件取得 thought_signature，並在將函式執行結果傳回模型時傳回該物件。例如：
Python
# Call the model with function declarations
# ...Generation config, Configure the client, and Define user prompt (No changes)
# Send request with declarations (using a thinking model)
response = client.models.generate_content(
model="gemini-2.5-flash", config=config, contents=contents)
# See thought signatures
for part in response.candidates[0].content.parts:
if not part.text:
continue
if part.thought and part.thought_signature:
print("Thought signature:")
print(part.thought_signature)
您不一定要查看想法簽章，但需要調整步驟 2，連同函式執行結果一併傳回簽章，這樣模型才能將想法納入最終回應：
Python
# Create user friendly response with function result and call the model again
# ...Create a function response part (No change)
# Append thought signatures, function call and result of the function execution to contents
function_call_content = response.candidates[0].content
# Append the model's function call message, which includes thought signatures
contents.append(function_call_content)
contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response
final_response = client.models.generate_content(
model="gemini-2.5-flash",
config=config,
contents=contents,
)
print(final_response.text)
傳回想法簽章時，請遵循下列準則：
- 模型會在回應的其他部分傳回簽章，例如函式呼叫、文字、文字或想法摘要部分。在後續回合中，將包含所有部分的完整回覆傳回模型。
- 請勿將含有簽名的部分與另一個也含有簽名的部分合併。簽名無法串連在一起。
- 請勿將有簽章的部分與沒有簽章的部分合併。
這會破壞簽名所代表想法的正確位置。
如要進一步瞭解思維簽章的限制和用途，以及一般思維模型，請參閱「思維」頁面。
平行函式呼叫
如果是「取得波士頓和舊金山的天氣詳細資料？」等提示，模型可能會建議多個平行函式呼叫。如要查看支援平行函式呼叫的模型清單，請參閱「功能和限制」。
REST
這個範例會示範使用一個 get_current_weather 函式的案例。
使用者提示為「Get weather details in Boston and San Francisco?」(取得波士頓和舊金山的天氣詳細資料)。模型會建議兩個並行的 get_current_weather 函式呼叫：一個使用 Boston 參數，另一個使用 San Francisco 參數。
如要進一步瞭解要求參數，請參閱 Gemini API。
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "Boston"
}
}
},
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "San Francisco"
}
}
}
]
},
...
}
],
...
}
以下指令示範如何將函式輸出內容提供給模型。將 my-project 替換為您的 Google Cloud 專案名稱。
模型要求
PROJECT_ID=my-project
MODEL_ID=gemini-2.0-flash
LOCATION="us-central1"
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
-d '{
"contents": [
{
"role": "user",
"parts": {
"text": "What is difference in temperature in Boston and San Francisco?"
}
},
{
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "Boston"
}
}
},
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "San Francisco"
}
}
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "get_current_weather",
"response": {
"temperature": 30.5,
"unit": "C"
}
}
},
{
"functionResponse": {
"name": "get_current_weather",
"response": {
"temperature": 20,
"unit": "C"
}
}
}
]
}
],
"tools": [
{
"function_declarations": [
{
"name": "get_current_weather",
"description": "Get the current weather in a specific location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name of the location for which to get the weather."
}
},
"required": [
"location"
]
}
}
]
}
]
}'
模型產生的自然語言回覆如下：
模型回覆
[
{
"candidates": [
{
"content": {
"parts": [
{
"text": "The temperature in Boston is 30.5C and the temperature in San Francisco is 20C. The difference is 10.5C. \n"
}
]
},
"finishReason": "STOP",
...
}
]
...
}
]
Python
這個範例會示範使用一個 get_current_weather 函式的案例。
使用者提示為「波士頓和舊金山的天氣如何？」。
將 my-project 替換為您的 Google Cloud 專案名稱。
import vertexai
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerationConfig,
GenerativeModel,
Part,
Tool,
ToolConfig
)
# Initialize Vertex AI
# TODO(developer): Update the project
vertexai.init(project="my-project", location="us-central1")
# Initialize Gemini model
model = GenerativeModel(model_name="gemini-2.0-flash")
# Manual function declaration
get_current_weather_func = FunctionDeclaration(
name="get_current_weather",
description="Get the current weather in a given location",
# Function parameters are specified in JSON schema format
parameters={
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name of the location for which to get the weather.",
"default": {
"string_value": "Boston, MA"
}
}
},
},
)
response = model.generate_content(
contents = [
Content(
role="user",
parts=[
Part.from_text("What is the weather like in Boston and San Francisco?"),
],
)
],
generation_config = GenerationConfig(temperature=0),
tools = [
Tool(
function_declarations=[get_current_weather_func],
)
]
)
以下指令示範如何將函式輸出內容提供給模型。
function_response_contents = []
function_response_parts = []
# You can have parallel function call requests for the same function type.
# For example, 'location_to_lat_long("London")' and 'location_to_lat_long("Paris")'
# In that case, collect API responses in parts and send them back to the model
for function_call in response.candidates[0].function_calls:
print(f"Function call: {function_call.name}")
# In this example, we'll use synthetic data to simulate a response payload from an external API
if (function_call.args['location'] == "Boston, MA"):
api_response = { "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy" }
if (function_call.args['location'] == "San Francisco, CA"):
api_response = { "location": "San Francisco, CA", "temperature": 58, "description": "Sunny" }
function_response_parts.append(
Part.from_function_response(
name=function_call.name,
response={"contents": api_response}
)
)
# Add the function call response to the contents
function_response_contents = Content(role="user", parts=function_response_parts)
function_response_contents
response = model.generate_content(
contents = [
Content(
role="user",
parts=[
Part.from_text("What is the weather like in Boston and San Francisco?"),
],
), # User prompt
response.candidates[0].content, # Function call response
function_response_contents, # Function response
],
tools = [
Tool(
function_declarations=[get_current_weather_func],
)
]
)
# Get the model summary response
print(response.text)
您可以強制模型只預測函式呼叫，而非允許模型在自然語言回應和函式呼叫之間選擇。這稱為「強制函式呼叫」。您也可以提供完整的函式宣告集給模型，但將回覆限制在這些函式的一部分。
| 模式 |
說明 |
AUTO |
預設模型行為。模型會判斷要預測函式呼叫或自然語言回覆。 |
ANY |
模型一律會預測函式呼叫。如果未提供 allowed_function_names，模型會從所有可用的函式宣告中挑選。如果提供 allowed_function_names，模型會從允許的函式集中挑選。 |
NONE |
模型不得預測函式呼叫。這項行為等同於沒有任何相關聯函式宣告的模型要求。 |
以下範例會強制模型只預測 get_weather 函式呼叫。
Python
response = model.generate_content(
contents = [
Content(
role="user",
parts=[
Part.from_text("What is the weather like in Boston?"),
],
)
],
generation_config = GenerationConfig(temperature=0),
tools = [
Tool(
function_declarations=[get_weather_func, some_other_function],
)
],
tool_config=ToolConfig(
function_calling_config=ToolConfig.FunctionCallingConfig(
# ANY mode forces the model to predict only function calls
mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
# Allowed function calls to predict when the mode is ANY. If empty, any of
# the provided function calls will be predicted.
allowed_function_names=["get_weather"],
)
)
)
函式結構定義範例
函式宣告與 OpenAPI 結構定義相容。支援的屬性如下：type、nullable、required、format、description、properties、items、enum、anyOf、$ref 和 $defs。系統不支援其餘屬性。
包含物件和陣列參數的函式
下列範例使用 Python 字典宣告函式，該函式會同時採用物件和陣列參數：
extract_sale_records_func = FunctionDeclaration(
name="extract_sale_records",
description="Extract sale records from a document.",
parameters={
"type": "object",
"properties": {
"records": {
"type": "array",
"description": "A list of sale records",
"items": {
"description": "Data for a sale record",
"type": "object",
"properties": {
"id": {"type": "integer", "description": "The unique id of the sale."},
"date": {"type": "string", "description": "Date of the sale, in the format of MMDDYY, e.g., 031023"},
"total_amount": {"type": "number", "description": "The total amount of the sale."},
"customer_name": {"type": "string", "description": "The name of the customer, including first name and last name."},
"customer_contact": {"type": "string", "description": "The phone number of the customer, e.g., 650-123-4567."},
},
"required": ["id", "date", "total_amount"],
},
},
},
"required": ["records"],
},
)
包含列舉參數的函式
下列範例使用 Python 字典宣告函式，該函式會採用整數 enum 參數：
set_status_func = FunctionDeclaration(
name="set_status",
description="set a ticket's status field",
# Function parameters are specified in JSON schema format
parameters={
"type": "object",
"properties": {
"status": {
"type": "integer",
"enum": [ "10", "20", "30" ], # Provide integer (or any other type) values as strings.
}
},
},
)
包含 ref 和 def 的函式
下列 JSON 函式宣告會使用 ref 和 defs 屬性：
{
"contents": ...,
"tools": [
{
"function_declarations": [
{
"name": "get_customer",
"description": "Search for a customer by name",
"parameters": {
"type": "object",
"properties": {
"first_name": { "ref": "#/defs/name" },
"last_name": { "ref": "#/defs/name" }
},
"defs": {
"name": { "type": "string" }
}
}
}
]
}
]
}
使用須知：
- 與 OpenAPI 結構定義不同，請指定
ref 和 defs，但不要使用 $ 符號。
ref 屬性必須參照 defs 的直接子項，不得參照外部項目。- 巢狀結構的深度上限為 32。
defs 中的遞迴深度 (自我參照) 最多為 2。
from_func (含陣列參數)
下列程式碼範例會宣告一個函式，用於將數字陣列相乘，並使用 from_func 生成 FunctionDeclaration 結構定義。
from typing import List
# Define a function. Could be a local function or you can import the requests library to call an API
def multiply_numbers(numbers: List[int] = [1, 1]) -> int:
"""
Calculates the product of all numbers in an array.
Args:
numbers: An array of numbers to be multiplied.
Returns:
The product of all the numbers. If the array is empty, returns 1.
"""
if not numbers: # Handle empty array
return 1
product = 1
for num in numbers:
product *= num
return product
multiply_number_func = FunctionDeclaration.from_func(multiply_numbers)
"""
multiply_number_func contains the following schema:
{'name': 'multiply_numbers',
'description': 'Calculates the product of all numbers in an array.',
'parameters': {'properties': {'numbers': {'items': {'type': 'INTEGER'},
'description': 'list of numbers',
'default': [1.0, 1.0],
'title': 'Numbers',
'type': 'ARRAY'}},
'description': 'Calculates the product of all numbers in an array.',
'title': 'multiply_numbers',
'property_ordering': ['numbers'],
'type': 'OBJECT'}}
"""
函式呼叫的最佳做法
撰寫清楚詳細的函式名稱、參數說明和指令。
- 函式名稱必須以英文字母或底線開頭，且只能包含 a-z、A-Z、0-9、底線、半形句點或破折號，長度上限為 64 個字元。
- 函式說明應清楚詳盡。舉例來說，
book_flight_ticket 函式的說明可以是 book flight tickets after confirming users' specific requirements, such as time, departure, destination, party size and preferred airline。
使用強型別參數。如果參數值來自有限集合，請新增 enum 欄位，而非將值集合放入說明。如果參數值一律為整數，請將類型設為 integer，而非 number。
使用系統指示。使用含有日期、時間或位置參數的函式時，請在系統指令中加入目前的日期、時間或相關位置資訊 (例如城市和國家/地區)。即使使用者提示缺少詳細資料，模型也能根據這些資訊準確處理要求。
提供詳細的使用者提示{: #prompt-bp }。為獲得最佳結果，請在使用者提示前加上下列詳細資料：
- 模型的額外背景資訊，例如
You are a flight API assistant to help with searching flights based on user preferences.
- 如何及何時使用函式的詳細資料或操作說明，例如
Don't make assumptions on the departure or destination airports. Always use a future date for the departure or destination time.
- 如果使用者查詢內容模稜兩可，請按照指示提出釐清問題，例如
Ask clarifying questions if not enough information is available.
設定生成設定{: #generation-config-bp }。對於 temperature 參數，請使用 0 或其他較低的值。這會指示模型生成更可靠的結果，並減少幻覺。
驗證 API 呼叫{: #invoke-api-bp }。如果模型建議的函式呼叫會傳送訂單、更新資料庫，或產生其他重大影響，請先向使用者驗證函式呼叫，再執行該呼叫。
使用想法簽名
為求最佳成效，思維簽章應一律搭配函式呼叫使用。
定價
函式呼叫的價格是根據文字輸入和輸出內容的字元數計算。詳情請參閱 Vertex AI 定價。
文字輸入內容 (提示) 是指目前對話輪次的使用者提示、目前對話輪次的函式宣告，以及對話記錄。對話記錄包含先前的查詢、函式呼叫和函式回覆。Vertex AI 會將對話記錄截斷為 32,000 個字元。
文字輸出內容 (回應) 是指目前對話輪次的函式呼叫和文字回應。
函式呼叫的用途
您可以使用函式呼叫執行下列工作：
其他用途包括：
解讀語音指令：建立與車內工作對應的函式。舉例來說，你可以建立開啟收音機或啟動空調的函式。將使用者語音指令的音訊檔案傳送至模型，並提示模型將音訊轉換為文字，以及找出使用者想呼叫的函式。
根據環境觸發條件自動執行工作流程：建立函式來代表可自動執行的程序。提供環境感應器資料給模型，並提示模型剖析及處理資料，判斷是否應啟動一或多個工作流程。舉例來說，模型可以處理倉庫中的溫度資料，並選擇啟動灑水器功能。
自動指派支援單：提供支援單、記錄和具備情境感知的規則給模型。提示模型處理所有這類資訊，判斷應將工單指派給誰。呼叫函式，將票證指派給模型建議的人員。
從知識庫擷取資訊：建立函式，擷取特定主題的學術文章並摘要內容。如果採取這種做法，模型就能回答學術問題，並提供答案出處。
後續步驟
