函式呼叫 (亦稱工具使用) 可為大型語言模型提供外部工具的定義 (例如 get_current_weather 函式)。處理提示時，模型會智慧判斷是否需要工具，如果需要，則會輸出結構化資料，指定要呼叫的工具及其參數 (例如 get_current_weather(location='Boston'))。接著，應用程式會執行這項工具，將結果回饋給模型，讓模型能以動態的實際資訊或動作結果完成回覆。這項功能可有效連結 LLM 與您的系統，並擴充 LLM 的功能。
函式呼叫功能主要有兩種用途：
擷取資料：擷取最新資訊，供模型回覆時參考，例如目前天氣、貨幣換算，或是知識庫和 API 中的特定資料 (RAG)。
採取行動：執行外部作業，例如提交表單、更新應用程式狀態，或協調代理工作流程 (例如交接對話)。
如要查看更多函式呼叫用途和範例，請參閱「用途」。
功能與限制
下列模型支援函式呼叫：
Gemini 模型：
- Gemini 3 Pro 預先發布版模型
- Gemini 2.5 Pro
- Gemini 2.5 Flash 預先發布版模型
- Gemini 2.5 Flash-Lite 預先發布版模型
- Gemini 2.5 Flash
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash (支援 Live API 原生音訊) 預先發布版模型
- Gemini 2.0 Flash with Live API Preview model
- Gemini 2.0 Flash
- Gemini 2.0 Flash-Lite
開放式模型：
最多可指定 512 個
FunctionDeclarations以 OpenAPI 結構定義格式定義函式。
如果是 Gemini 3 Pro 以上版本，您可以在傳回模型的
functionResponse訊息中加入多模態內容 (圖片和 PDF)。詳情請參閱「多模態函式回應」。如果是 Gemini 3 Pro 以上版本，您可以將
streamFunctionCallArguments設為true，在functionCallingConfig中串流函式呼叫引數，因為這些引數是由系統產生。詳情請參閱「串流函式呼叫引數」。如要瞭解函式宣告相關最佳做法，包括名稱和說明的提示，請參閱「最佳做法」。
如要使用開放模型，請參閱這份使用者指南。
如何建立函式呼叫應用程式
如要使用函式呼叫功能，請執行下列工作：
步驟 1：將提示和函式宣告提交至模型
以相容於 OpenAPI 結構定義 的結構定義格式宣告 Tool。詳情請參閱結構定義範例。
下列範例會將提示和函式宣告提交給 Gemini 模型：
REST
PROJECT_ID=myproject
LOCATION=us-central1
MODEL_ID=gemini-2.5-flash
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"
]
}
}
]
}]
}'
Gen AI SDK for Python
from google import genai
from google.genai.types import GenerateContentConfig, Part
# The project and location are passed directly to the client,
# and vertexai=True is added to specify the use of the Vertex AI backend.
client = genai.Client(vertexai=True, project="marklu", location="global")
def get_current_weather(location: str) -> str:
"""Returns the current weather.
Args:
location: The city and state, e.g. San Francisco, CA
"""
return 'sunny'
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="What is the weather in boston?",
config=GenerateContentConfig(tools=[get_current_weather]),
)
Vertex AI SDK for 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.5-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
這個範例會示範文字情境，其中包含一個函式和一個提示。
Node.js
在試用這個範例之前，請先按照「使用用戶端程式庫的 Vertex AI 快速入門導覽課程」中的 Node.js 設定操作說明進行操作。詳情請參閱 Vertex AI Node.js API 參考說明文件。
如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
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#
這個範例會示範文字情境，其中包含一個函式和一個提示。
C#
在試用這個範例之前，請先按照「使用用戶端程式庫的 Vertex AI 快速入門導覽課程」中的 C# 設定操作說明進行操作。詳情請參閱 Vertex AI C# API 參考說明文件。
如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
Java
在試用這個範例之前，請先按照「使用用戶端程式庫的 Vertex AI 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 Vertex AI Java API 參考說明文件。
如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
如果模型判斷需要特定函式的輸出內容，應用程式從模型收到的回覆會包含函式名稱，以及應呼叫函式的參數值。
以下是模型對使用者提示「波士頓的天氣如何？」的回覆範例。模型建議使用參數 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.5-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"
]
}
}
]
}
]
}'
Vertex AI SDK for 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.5-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.5-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)
Go
多模態函式回應
如果是 Gemini 3 Pro 和後續版本，您可以在傳送給模型的回覆部分中加入多模態內容。模型可以在下一個回合處理這類多模態內容，進而生成更實用的回覆。函式回應中的多模態內容支援下列 MIME 類型：
- 圖片：
image/png、image/jpeg、image/webp - 文件：
application/pdf、text/plain
如要在函式回覆中加入多模態資料，請將資料做為一或多個部分，巢狀內嵌在 functionResponse 部分中。每個多模態部分都必須包含 inlineData 或 fileData。如果您從結構化 response 欄位中參照多模態部分，該欄位必須包含不重複的 displayName。
您也可以使用 JSON 參照格式 {"$ref": "<displayName>"}，從 functionResponse 部分的結構化 response 欄位中參照多模態部分。模型會在處理回覆時，以多模態內容取代參照。每個 displayName 在結構化 response 欄位中只能參照一次。
以下範例顯示包含 functionResponse 的訊息，適用於名為 get_image 的函式，以及包含圖片資料和 displayName: "wakeupcat.jpg" 的巢狀部分。functionResponse's response 欄位會參照這個圖片部分：
Python
from google import genai
from google.genai import types
client = genai.Client()
# This is a manual, two turn multimodal function calling workflow:
# 1. Define the function tool
get_image_declaration = types.FunctionDeclaration(
name="get_image",
description="Retrieves the image file reference for a specific order item.",
parameters={
"type": "object",
"properties": {
"item_name": {
"type": "string",
"description": "The name or description of the item ordered (e.g., 'green shirt')."
}
},
"required": ["item_name"],
},
)
tool_config = types.Tool(function_declarations=[get_image_declaration])
# 2. Send a message that triggers the tool
prompt = "Show me the green shirt I ordered last month."
response_1 = client.models.generate_content(
model="gemini-3-pro-preview",
contents=[prompt],
config=types.GenerateContentConfig(
tools=[tool_config],
)
)
# 3. Handle the function call
function_call = response_1.function_calls[0]
requested_item = function_call.args["item_name"]
print(f"Model wants to call: {function_call.name}")
# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {requested_item}")
function_response_data = {
"image_ref": {"$ref": "dress.jpg"},
}
function_response_multimodal_data = types.FunctionResponsePart(
file_data=types.FunctionResponseFileData(
mime_type="image/png",
display_name="dress.jpg",
file_uri="gs://cloud-samples-data/generative-ai/image/dress.jpg",
)
)
# 4. Send the tool's result back
# Append this turn's messages to history for a final response.
history = [
types.Content(role="user", parts=[types.Part(text=prompt)]),
response_1.candidates[0].content,
types.Content(
role="tool",
parts=[
types.Part.from_function_response(
name=function_call.name,
response=function_response_data,
parts=[function_response_multimodal_data]
)
],
)
]
response_2 = client.models.generate_content(
model="gemini-3-pro-preview",
contents=history,
config=types.GenerateContentConfig(
tools=[tool_config],
thinking_config=types.ThinkingConfig(include_thoughts=True)
),
)
print(f"\nFinal model response: {response_2.text}")
REST
"contents": [
...,
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "get_image",
"response": {
"image_ref": {
"$ref": "wakeupcat.jpg"
}
},
"parts": [
{
"fileData": {
"displayName": "wakeupcat.jpg",
"mimeType": "image/jpeg",
"fileUri": "gs://cloud-samples-data/vision/label/wakeupcat.jpg"
}
}
]
}
}
]
}
]
串流函式呼叫引數
如果是 Gemini 3 Pro 和後續版本模型，您可以要求系統在模型生成函式呼叫引數時串流傳輸引數，不必等待生成完整引數集。如果需要呼叫函式，這項功能有助於縮短感知延遲。
這項功能含有以下限制：
- 這項功能適用於
v1和v1beta1API 版本。
如要為函式呼叫引數啟用串流，請在呼叫 streamGenerateContent 時，將 toolConfig.functionCallingConfig 內的 streamFunctionCallArguments 設為 true。
啟用 streamFunctionCallArguments 後，中繼回應會包含具有 partialArgs 和 willContinue 欄位的 functionCall 物件。partialArgs 包含產生的引數片段，而 willContinue 則表示是否預期會有更多函式呼叫片段。
partialArgs：PartialArg物件的陣列，每個物件都包含：jsonPath：JSONPath 字串，指出函式參數物件中這個片段的路徑。路徑可以指向引數 (例如$.location)，也可以指向引數內的元素 (如果引數是物件，例如$.location.latitude)。- 片段的值，可以是
numberValue、stringValue、boolValue或nullValue。 willContinue：partialArgs物件中的布林值。只有在字串值以區塊形式串流，且預期這個引數會有更多區塊時，這個欄位才適用於stringValue片段。true
willContinue：functionCall物件中的布林值。如果true，後續串流回應中整體函式呼叫的partialArgs預期會更多。如果false或缺席，這是目前函式呼叫的最終串流回應。
以下範例顯示串流 generateContent 區塊的序列，其中單一函式呼叫的引數會串流：
{
"parts": [
{
"functionCall": {
"name": "controlLight",
"partialArgs": [
{
"jsonPath": "$.brightness",
"numberValue": 50
}
],
"willContinue": true
}
}
],
"role": "model"
}
{
"parts": [
{
"functionCall": {
"partialArgs": [
{
"jsonPath": "$.colorTemperature",
"stringValue": "warm",
"willContinue": true
}
],
"willContinue": true
}
}
],
"role": "model"
}
{
"parts": [
{
"functionCall": {
"partialArgs": [
{
"jsonPath": "$.colorTemperature"
}
],
"willContinue": true
}
}
],
"role": "model"
}
{
"parts": [
{
"functionCall": {}
}
],
"role": "model"
}
以下範例說明如何針對「What is difference in temperature in New Delhi and San Francisco?」(新德里和舊金山的溫差是多少？) 提示，透過多個回應串流處理平行函式呼叫的引數：
{
"candidates": [{
"content": {
"role": "model",
"parts": [{
"functionCall": {
"name": "get_current_weather",
"willContinue": true
},
}]
}
}],
}
{
"candidates": [{
"content": {
"role": "model",
"parts": [{
"functionCall": {
"partialArgs": [{
"jsonPath": "$.location",
"stringValue": "New Delhi",
"willContinue": true
}],
"willContinue": true
}
}]
}
}],
}
{
"candidates": [{
"content": {
"role": "model",
"parts": [{
"functionCall": {
"partialArgs": [{
"jsonPath": "$.location",
"stringValue": ""
}],
"willContinue": true
}
}]
}
}],
}
{
"candidates": [{
"content": {
"role": "model",
"parts": [{
"functionCall": {
}
}]
}
}],
}
{
"candidates": [{
"content": {
"role": "model",
"parts": [{
"functionCall": {
"name": "get_current_weather",
"willContinue": true
},
}]
}
}],
}
{
"candidates": [{
"content": {
"role": "model",
"parts": [{
"functionCall": {
"partialArgs": [{
"jsonPath": "$.location",
"stringValue": "San Francisco",
"willContinue": true
}],
"willContinue": true
}
}]
}
}],
}
{
"candidates": [{
"content": {
"role": "model",
"parts": [{
"functionCall": {
"partialArgs": [{
"jsonPath": "$.location",
"stringValue": ""
}],
"willContinue": true
}
}]
}
}],
}
{
"candidates": [{
"content": {
"role": "model",
"parts": [{
"functionCall": {
}
}]
}
}],
}
Python
from google import genai
from google.genai import types
client = genai.Client()
get_weather_declaration = types.FunctionDeclaration(
name="get_weather",
description="Gets the current weather temperature for a given location.",
parameters={
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
)
get_weather_tool = types.Tool(function_declarations=[get_weather_declaration])
for chunk in client.models.generate_content_stream(
model="gemini-3-pro-preview",
contents="What's the weather in London and New York?",
config=types.GenerateContentConfig(
tools=[get_weather_tool],
tool_config = types.ToolConfig(
function_calling_config=types.FunctionCallingConfig(
mode=types.FunctionCallingConfigMode.AUTO,
stream_function_call_arguments=True,
)
),
),
):
function_call = chunk.function_calls[0]
if function_call and function_call.name:
print(f"{function_call.name}")
print(f"will_continue={function_call.will_continue}")
函式呼叫模式
您可以在 function_calling_config 中設定模式，控管模型使用所提供工具 (函式宣告) 的方式。
| 模式 | 說明 |
|---|---|
AUTO |
預設模型行為。模型會根據情境，決定要預測函式呼叫或以自然語言回應。這是最彈性的模式，建議在大多數情況下使用。 |
VALIDATED (預先發布版) |
模型只能預測函式呼叫或自然語言，並確保符合函式結構定義。如果未提供 allowed_function_names，模型會從所有可用的函式宣告中挑選。如果提供 allowed_function_names，模型會從允許的函式集中挑選。 |
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。
工具選取
模型可以使用任意數量的工具，但如果提供的工具過多，選取錯誤或次佳工具的風險就會增加。為獲得最佳結果，請盡量只提供與情境或工作相關的工具，最好將有效工具組維持在最多 10 到 20 個。如果工具總數較多，請考慮根據對話內容動態選取工具。
如果您提供一般低階工具 (例如 bash)，模型可能會更常使用該工具，但準確度會降低。如果您提供特定高階工具 (例如 get_weather)，模型就能更準確地使用該工具，但可能不會經常使用。
使用系統指令
使用含有日期、時間或位置參數的函式時，請在系統指令中加入目前日期、時間或相關位置資訊 (例如城市和國家/地區)。即使使用者提示缺少詳細資料，模型也能取得必要背景資訊，準確處理要求。
提示工程
為獲得最佳結果，請在使用者提示前加上下列詳細資料：
- 模型的額外背景資訊，例如
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.
使用生成設定
如為 temperature 參數，請使用 0 或其他較低的值。這會指示模型生成更可靠的結果，並減少幻覺。
使用結構化輸出內容
函式呼叫功能可與結構化輸出內容搭配使用，讓模型一律預測函式呼叫或符合特定結構定義的輸出內容，因此模型未生成函式呼叫時，您也能收到格式一致的回覆。
驗證 API 呼叫
如果模型建議呼叫會傳送訂單、更新資料庫或產生重大影響的函式，請先向使用者確認函式呼叫，再執行函式。
使用想法簽名檔
為求最佳成效，思維簽章應一律搭配函式呼叫使用。
定價
函式呼叫的價格是根據文字輸入和輸出內容的字元數計算。詳情請參閱 Vertex AI 定價。
這裡的文字輸入內容 (提示) 是指目前對話輪次的使用者提示、目前對話輪次的函式宣告，以及對話記錄。對話記錄包含先前的查詢、函式呼叫和函式回覆。Vertex AI 會將對話記錄截斷為 32,000 個字元。
文字輸出內容 (回覆) 是指目前對話輪次的函式呼叫和文字回覆。
函式呼叫的用途
您可以使用函式呼叫執行下列工作：
| 用途 | 範例說明 | 範例連結 |
|---|---|---|
| 整合外部 API | 使用氣象 API 取得天氣資訊 | 筆記本教學課程 |
| 將地址轉換為經緯度座標 | 筆記本教學課程 | |
| 使用貨幣匯率 API 換算貨幣 | Codelab | |
| 建構進階聊天機器人 | 回答顧客對產品和服務的疑問 | 筆記本教學課程 |
| 建立助理，回答有關公司的財務和新聞問題 | 筆記本教學課程 | |
| 規劃並控管函式呼叫 | 從原始記錄資料中擷取結構化實體 | 筆記本教學課程 |
| 從使用者輸入內容擷取單一或多個參數 | 筆記本教學課程 | |
| 在函式呼叫中處理清單和巢狀資料結構 | 筆記本教學課程 | |
| 處理函式呼叫行為 | 處理平行函式呼叫和回應 | 筆記本教學課程 |
| 管理模型可呼叫的函式和時間 | 筆記本教學課程 | |
| 以自然語言查詢資料庫 | 將自然語言問題轉換為 BigQuery 的 SQL 查詢 | 範例應用程式 |
| 多模態函式呼叫 | 使用圖片、影片、音訊和 PDF 檔做為輸入內容，觸發函式呼叫 | 筆記本教學課程 |
以下列舉更多用途：
解讀語音指令：建立與車內工作對應的函式。舉例來說，你可以建立開啟收音機或啟動空調的函式。將使用者語音指令的音訊檔案傳送至模型，並要求模型將音訊轉換為文字，以及找出使用者想呼叫的函式。
根據環境觸發條件自動執行工作流程：建立函式來代表可自動執行的程序。提供環境感應器資料給模型，並要求模型剖析及處理資料，判斷是否應啟動一或多個工作流程。舉例來說，模型可以處理倉庫中的溫度資料，並選擇啟動灑水器功能。
自動指派支援單：提供支援單、記錄和具備情境感知的規則給模型。要求模型處理所有資訊，判斷應將支援單指派給誰。呼叫函式，將票證指派給模型建議的人員。
從知識庫檢索資訊：建立函式，檢索特定主題的學術文章並摘要內容。啟用這項功能後，模型就能回答學術科目相關問題，並在答案中附上出處。
後續步驟
請參閱函式呼叫的 API 參考資料。