本指南提供使用 Gemini API 函式呼叫的參考資料。涵蓋下列主題：
- 支援的型號：列出支援函式呼叫的型號。
- 語法範例：顯示函式呼叫 API 要求的基本結構。
- API 參數：詳細說明函式呼叫中使用的參數，例如
FunctionDeclaration 和 FunctionCallingConfig。
- 範例：提供程式碼範例，說明如何傳送函式宣告及設定函式呼叫行為。
函式呼叫功能可提升大型語言模型提供相關且符合情境答案的能力。
透過 Function Calling API，您可以為生成式 AI 模型提供自訂函式。模型不會直接叫用這些函式，而是產生結構化資料輸出內容，指定函式名稱和建議的引數。您可透過這項輸出內容呼叫外部 API 或資訊系統，例如資料庫、客戶關係管理 (CRM) 系統和文件存放區。接著，您可以將 API 輸出內容傳回模型，提升模型的回覆品質。
如要瞭解函式呼叫的概念總覽，請參閱函式呼叫。
支援的模型
限制：
語法範例
以下範例顯示函式呼叫 API 要求的語法。
curl
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": [{
...
}],
"tools": [{
"function_declarations": [
{
...
}
]
}]
}'
API 參數
本節說明函式呼叫的參數。如要瞭解實作方式，請參閱「範例」一節。
FunctionDeclaration
FunctionDeclaration 定義模型可根據 OpenAPI 3.0 規格產生 JSON 輸入內容的函式。
| 參數 |
name
|
string
要呼叫的函式名稱。名稱開頭須為英文字母或底線。可包含字母 (a-z、A-Z)、數字 (0-9)、底線、點或破折號，長度上限為 64 個字元。 |
description
|
自由參加：string 函式用途的說明。模型會根據這項說明，判斷如何呼叫函式，以及是否要呼叫函式。為獲得最佳結果，建議您提供說明。 |
parameters
|
自由參加：Schema 函式的參數，以 OpenAPI JSON 結構定義物件格式說明。 |
response
|
自由參加：Schema 函式的輸出內容，以 OpenAPI JSON 結構定義物件格式說明。 |
詳情請參閱「函式呼叫」。
Schema
Schema 會根據 OpenAPI 3.0 結構定義規格，定義函式呼叫中輸入和輸出資料的格式。
| 參數 |
| 類型 |
string
資料類型。必須是下列其中一個項目：
STRINGINTEGERBOOLEANNUMBERARRAYOBJECT |
description |
自由參加：string 資料說明。 |
enum |
自由參加：string[] 原始型別元素可能的值。 |
items |
自由參加：Schema[] ARRAY 類型元素的結構定義。
|
properties |
自由參加：Schema OBJECT 類型屬性的結構定義。
|
required |
自由參加：string[] OBJECT 類型的必要屬性。
|
nullable |
自由參加：bool 指出值是否可為 null。 |
FunctionCallingConfig
FunctionCallingConfig 可讓你控管模型的行為，並決定要呼叫的函式。
| 參數 |
mode
|
自由參加：enum/string[]
AUTO：這是預設行為。模型會根據情境判斷是否要呼叫函式，或以自然語言回覆。NONE：模型不會呼叫任何函式。ANY：模型一律會預測函式呼叫。如未提供 allowed_function_names，模型會從所有可用的函式宣告中選擇。如果您提供 allowed_function_names，模型會從該組函式中選擇。 |
allowed_function_names
|
自由參加：string[] 要呼叫的函式名稱清單。只有在 mode 為 ANY 時，才能設定這項功能。函式名稱必須符合 FunctionDeclaration.name。如果模式為 ANY，模型會從您提供的函式名稱清單中預測函式呼叫。 |
functionCall
functionCall 是模型傳回的預測結果。其中包含要呼叫的函式名稱 (functionDeclaration.name)，以及含有參數及其值的結構化 JSON 物件。
| 參數 |
name
|
string
要呼叫的函式名稱。 |
args
|
Struct
JSON 物件格式的函式參數及其值。 如需參數詳細資料，請參閱「函式呼叫」。 |
functionResponse
functionResponse 是 FunctionCall 的輸出內容。其中包含呼叫的函式名稱，以及含有函式輸出內容的結構化 JSON 物件。您將這項回覆提供給模型，做為背景資訊。
| 參數 |
name
|
string
呼叫的函式名稱。 |
response
|
Struct
函式的回應 (JSON 物件格式)。 |
範例
傳送函式宣告
以下範例說明如何將查詢和函式宣告傳送至模型。
REST
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您的專案 ID。
- MODEL_ID：正在處理的模型 ID。
- ROLE：建立訊息的實體身分。
- TEXT：要傳送給模型的提示。
- NAME：要呼叫的函式名稱。
- DESCRIPTION：函式的說明和用途。
- 如需其他欄位，請參閱「參數清單」表格。
HTTP 方法和網址：
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent
JSON 要求主體：
{
"contents": [{
"role": "ROLE",
"parts": [{
"text": "TEXT"
}]
}],
"tools": [{
"function_declarations": [
{
"name": "NAME",
"description": "DESCRIPTION",
"parameters": {
"type": "TYPE",
"properties": {
"location": {
"type": "TYPE",
"description": "DESCRIPTION"
}
},
"required": [
"location"
]
}
}
]
}]
}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent"
PowerShell
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content
cURL 指令範例
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 and state, e.g. San Francisco, CA or a zip code e.g. 95616"
}
},
"required": [
"location"
]
}
}
]
}]
}'
REST (OpenAI)
您可以使用 OpenAI 程式庫呼叫 Function Calling API。詳情請參閱「
使用 OpenAI 程式庫呼叫 Vertex AI 模型」。
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：。
- MODEL_ID：正在處理的模型 ID。
HTTP 方法和網址：
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions
JSON 要求主體：
{
"model": "google/MODEL_ID",
"messages": [
{
"role": "user",
"content": "What is the weather in Boston?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
}
},
"required": ["location"]
}
}
}
]
}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions"
PowerShell
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions" | Select-Object -Expand Content
設定函式呼叫行為
以下範例說明如何將 FunctionCallingConfig 傳遞至模型。
您可以使用 functionCallingConfig，要求模型輸出特定函式呼叫。如要設定這項行為，請按照下列步驟操作：
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/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
}]
}],
"tools": [{
"functionDeclarations": [
{
"name": "get_product_sku",
"description": "Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
"parameters": {
"type": "object",
"properties": {
"product_name": {"type": "string", "description": "Product name"}
}
}
},
{
"name": "get_store_location",
"description": "Get the location of the closest store",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "Location"}
},
}
}
]
}],
"toolConfig": {
"functionCallingConfig": {
"mode":"ANY",
"allowedFunctionNames": ["get_product_sku"]
}
},
"generationConfig": {
"temperature": 0.95,
"topP": 1.0,
"maxOutputTokens": 8192
}
}'
Go
import (
"context"
"encoding/json"
"errors"
"fmt"
"io"
"cloud.google.com/go/vertexai/genai"
)
// functionCallsChat opens a chat session and sends 4 messages to the model:
// - convert a first text question into a structured function call request
// - convert the first structured function call response into natural language
// - convert a second text question into a structured function call request
// - convert the second structured function call response into natural language
func functionCallsChat(w io.Writer, projectID, location, modelName string) error {
// location := "us-central1"
// modelName := "gemini-2.0-flash-001"
ctx := context.Background()
client, err := genai.NewClient(ctx, projectID, location)
if err != nil {
return fmt.Errorf("unable to create client: %w", err)
}
defer client.Close()
model := client.GenerativeModel(modelName)
// Build an OpenAPI schema, in memory
paramsProduct := &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"productName": {
Type: genai.TypeString,
Description: "Product name",
},
},
}
fundeclProductInfo := &genai.FunctionDeclaration{
Name: "getProductSku",
Description: "Get the SKU for a product",
Parameters: paramsProduct,
}
paramsStore := &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
"location": {
Type: genai.TypeString,
Description: "Location",
},
},
}
fundeclStoreLocation := &genai.FunctionDeclaration{
Name: "getStoreLocation",
Description: "Get the location of the closest store",
Parameters: paramsStore,
}
model.Tools = []*genai.Tool{
{FunctionDeclarations: []*genai.FunctionDeclaration{
fundeclProductInfo,
fundeclStoreLocation,
}},
}
model.SetTemperature(0.0)
chat := model.StartChat()
// Send a prompt for the first conversation turn that should invoke the getProductSku function
prompt := "Do you have the Pixel 8 Pro in stock?"
fmt.Fprintf(w, "Question: %s\n", prompt)
resp, err := chat.SendMessage(ctx, genai.Text(prompt))
if err != nil {
return err
}
if len(resp.Candidates) == 0 ||
len(resp.Candidates[0].Content.Parts) == 0 {
return errors.New("empty response from model")
}
// The model has returned a function call to the declared function `getProductSku`
// with a value for the argument `productName`.
jsondata, err := json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", " ")
if err != nil {
return fmt.Errorf("json.MarshalIndent: %w", err)
}
fmt.Fprintf(w, "function call generated by the model:\n\t%s\n", string(jsondata))
// Create a function call response, to simulate the result of a call to a
// real service
funresp := &genai.FunctionResponse{
Name: "getProductSku",
Response: map[string]any{
"sku": "GA04834-US",
"in_stock": "yes",
},
}
jsondata, err = json.MarshalIndent(funresp, "\t", " ")
if err != nil {
return fmt.Errorf("json.MarshalIndent: %w", err)
}
fmt.Fprintf(w, "function call response sent to the model:\n\t%s\n\n", string(jsondata))
// And provide the function call response to the model
resp, err = chat.SendMessage(ctx, funresp)
if err != nil {
return err
}
if len(resp.Candidates) == 0 ||
len(resp.Candidates[0].Content.Parts) == 0 {
return errors.New("empty response from model")
}
// The model has taken the function call response as input, and has
// reformulated the response to the user.
jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", " ")
if err != nil {
return fmt.Errorf("json.MarshalIndent: %w", err)
}
fmt.Fprintf(w, "Answer generated by the model:\n\t%s\n\n", string(jsondata))
// Send a prompt for the second conversation turn that should invoke the getStoreLocation function
prompt2 := "Is there a store in Mountain View, CA that I can visit to try it out?"
fmt.Fprintf(w, "Question: %s\n", prompt)
resp, err = chat.SendMessage(ctx, genai.Text(prompt2))
if err != nil {
return err
}
if len(resp.Candidates) == 0 ||
len(resp.Candidates[0].Content.Parts) == 0 {
return errors.New("empty response from model")
}
// The model has returned a function call to the declared function `getStoreLocation`
// with a value for the argument `store`.
jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", " ")
if err != nil {
return fmt.Errorf("json.MarshalIndent: %w", err)
}
fmt.Fprintf(w, "function call generated by the model:\n\t%s\n", string(jsondata))
// Create a function call response, to simulate the result of a call to a
// real service
funresp = &genai.FunctionResponse{
Name: "getStoreLocation",
Response: map[string]any{
"store": "2000 N Shoreline Blvd, Mountain View, CA 94043, US",
},
}
jsondata, err = json.MarshalIndent(funresp, "\t", " ")
if err != nil {
return fmt.Errorf("json.MarshalIndent: %w", err)
}
fmt.Fprintf(w, "function call response sent to the model:\n\t%s\n\n", string(jsondata))
// And provide the function call response to the model
resp, err = chat.SendMessage(ctx, funresp)
if err != nil {
return err
}
if len(resp.Candidates) == 0 ||
len(resp.Candidates[0].Content.Parts) == 0 {
return errors.New("empty response from model")
}
// The model has taken the function call response as input, and has
// reformulated the response to the user.
jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", " ")
if err != nil {
return fmt.Errorf("json.MarshalIndent: %w", err)
}
fmt.Fprintf(w, "Answer generated by the model:\n\t%s\n\n", string(jsondata))
return nil
}
REST (OpenAI)
您可以使用 OpenAI 程式庫呼叫 Function Calling API。詳情請參閱「
使用 OpenAI 程式庫呼叫 Vertex AI 模型」。
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：。
- MODEL_ID：正在處理的模型 ID。
HTTP 方法和網址：
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions
JSON 要求主體：
{
"model": "google/MODEL_ID",
"messages": [
{
"role": "user",
"content": "What is the weather in Boston?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
}
},
"required": ["location"]
}
}
}
],
"tool_choice": "auto"
}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions"
PowerShell
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions" | Select-Object -Expand Content
後續步驟
詳情請參閱下列說明文件：
