Pengantar panggilan fungsi

Panggilan fungsi, yang juga dikenal sebagai penggunaan alat, menyediakan definisi alat eksternal (misalnya, fungsi get_current_weather) untuk LLM. Saat memproses perintah, model akan secara cerdas menentukan apakah alat diperlukan dan, jika ya, akan menghasilkan data terstruktur yang menentukan alat yang akan dipanggil dan parameternya (misalnya, get_current_weather(location='Boston')). Aplikasi Anda kemudian akan menjalankan alat ini, mengirimkan kembali hasilnya ke model, sehingga model dapat menyelesaikan responsnya dengan informasi dunia nyata yang dinamis atau hasil dari suatu tindakan. Hal ini secara efektif menghubungkan LLM dengan sistem Anda dan memperluas kemampuannya.

Interaksi Panggilan Fungsi 

Panggilan fungsi memungkinkan dua kasus penggunaan utama:

  • Mengambil data: Mengambil informasi terbaru untuk respons model, seperti cuaca saat ini, konversi mata uang, atau data tertentu dari pusat informasi dan API (RAG).

  • Mengambil tindakan: Lakukan operasi eksternal seperti mengirimkan formulir, memperbarui status aplikasi, atau mengatur alur kerja berbasis agen (misalnya, pengalihan percakapan).

Untuk kasus penggunaan dan contoh lainnya yang didukung oleh pemanggilan fungsi, lihat Kasus penggunaan.

Fitur dan batasan

Cara membuat aplikasi panggilan fungsi

Untuk menggunakan panggilan fungsi, lakukan tugas berikut:

  1. Kirimkan deklarasi fungsi dan perintah ke model.
  2. Berikan output API ke model.

Langkah 1: Kirimkan perintah dan deklarasi fungsi ke model

Deklarasikan Tool dalam format skema yang kompatibel dengan skema OpenAPI. Untuk mengetahui informasi selengkapnya, lihat Contoh skema.

Contoh berikut mengirimkan perintah dan deklarasi fungsi ke model Gemini.

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

Anda dapat menentukan skema secara manual menggunakan kamus Python atau secara otomatis dengan fungsi helper from_func. Contoh berikut menunjukkan cara mendeklarasikan fungsi secara manual.

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],       )     ] ) 

Atau, Anda dapat mendeklarasikan fungsi secara otomatis dengan fungsi helper from_func seperti yang ditunjukkan dalam contoh berikut:

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

Contoh ini menunjukkan skenario teks dengan satu fungsi dan satu prompt.

Node.js

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Node.js Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

const {   VertexAI,   FunctionDeclarationSchemaType, } = require('@google-cloud/vertexai');  const functionDeclarations = [   {     function_declarations: [       {         name: 'get_current_weather',         description: 'get weather in a given location',         parameters: {           type: FunctionDeclarationSchemaType.OBJECT,           properties: {             location: {type: FunctionDeclarationSchemaType.STRING},             unit: {               type: FunctionDeclarationSchemaType.STRING,               enum: ['celsius', 'fahrenheit'],             },           },           required: ['location'],         },       },     ],   }, ];  const functionResponseParts = [   {     functionResponse: {       name: 'get_current_weather',       response: {name: 'get_current_weather', content: {weather: 'super nice'}},     },   }, ];  /**  * TODO(developer): Update these variables before running the sample.  */ async function functionCallingStreamContent(   projectId = 'PROJECT_ID',   location = 'us-central1',   model = 'gemini-2.0-flash-001' ) {   // Initialize Vertex with your Cloud project and location   const vertexAI = new VertexAI({project: projectId, location: location});    // Instantiate the model   const generativeModel = vertexAI.getGenerativeModel({     model: model,   });    const request = {     contents: [       {role: 'user', parts: [{text: 'What is the weather in Boston?'}]},       {         role: 'ASSISTANT',         parts: [           {             functionCall: {               name: 'get_current_weather',               args: {location: 'Boston'},             },           },         ],       },       {role: 'USER', parts: functionResponseParts},     ],     tools: functionDeclarations,   };   const streamingResp = await generativeModel.generateContentStream(request);   for await (const item of streamingResp.stream) {     console.log(item.candidates[0].content.parts[0].text);   } }

Go

Contoh ini menunjukkan skenario teks dengan satu fungsi dan satu perintah.

Pelajari cara menginstal atau mengupdate Go.

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Gen AI SDK dengan Vertex AI:

# 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

import ( 	"context" 	"fmt" 	"io"  	genai "google.golang.org/genai" )  // generateWithFuncCall shows how to submit a prompt and a function declaration to the model, // allowing it to suggest a call to the function to fetch external data. Returning this data // enables the model to generate a text response that incorporates the data. func generateWithFuncCall(w io.Writer) error { 	ctx := context.Background()  	client, err := genai.NewClient(ctx, &genai.ClientConfig{ 		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"}, 	}) 	if err != nil { 		return fmt.Errorf("failed to create genai client: %w", err) 	}  	weatherFunc := &genai.FunctionDeclaration{ 		Description: "Returns the current weather in a location.", 		Name:        "getCurrentWeather", 		Parameters: &genai.Schema{ 			Type: "object", 			Properties: map[string]*genai.Schema{ 				"location": {Type: "string"}, 			}, 			Required: []string{"location"}, 		}, 	} 	config := &genai.GenerateContentConfig{ 		Tools: []*genai.Tool{ 			{FunctionDeclarations: []*genai.FunctionDeclaration{weatherFunc}}, 		}, 		Temperature: genai.Ptr(float32(0.0)), 	}  	modelName := "gemini-2.5-flash" 	contents := []*genai.Content{ 		{Parts: []*genai.Part{ 			{Text: "What is the weather like in Boston?"}, 		}, 			Role: "user"}, 	}  	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config) 	if err != nil { 		return fmt.Errorf("failed to generate content: %w", err) 	}  	var funcCall *genai.FunctionCall 	for _, p := range resp.Candidates[0].Content.Parts { 		if p.FunctionCall != nil { 			funcCall = p.FunctionCall 			fmt.Fprint(w, "The model suggests to call the function ") 			fmt.Fprintf(w, "%q with args: %v\n", funcCall.Name, funcCall.Args) 			// Example response: 			// The model suggests to call the function "getCurrentWeather" with args: map[location:Boston] 		} 	} 	if funcCall == nil { 		return fmt.Errorf("model did not suggest a function call") 	}  	// Use synthetic data to simulate a response from the external API. 	// In a real application, this would come from an actual weather API. 	funcResp := &genai.FunctionResponse{ 		Name: "getCurrentWeather", 		Response: map[string]any{ 			"location":         "Boston", 			"temperature":      "38", 			"temperature_unit": "F", 			"description":      "Cold and cloudy", 			"humidity":         "65", 			"wind":             `{"speed": "10", "direction": "NW"}`, 		}, 	}  	// Return conversation turns and API response to complete the model's response. 	contents = []*genai.Content{ 		{Parts: []*genai.Part{ 			{Text: "What is the weather like in Boston?"}, 		}, 			Role: "user"}, 		{Parts: []*genai.Part{ 			{FunctionCall: funcCall}, 		}}, 		{Parts: []*genai.Part{ 			{FunctionResponse: funcResp}, 		}}, 	}  	resp, err = client.Models.GenerateContent(ctx, modelName, contents, config) 	if err != nil { 		return fmt.Errorf("failed to generate content: %w", err) 	}  	respText := resp.Text()  	fmt.Fprintln(w, respText)  	// Example response: 	// The weather in Boston is cold and cloudy with a temperature of 38 degrees Fahrenheit. The humidity is ...  	return nil } 

C#

Contoh ini menunjukkan skenario teks dengan satu fungsi dan satu perintah.

C#

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API C# Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

 using Google.Cloud.AIPlatform.V1; using System; using System.Threading.Tasks; using Type = Google.Cloud.AIPlatform.V1.Type; using Value = Google.Protobuf.WellKnownTypes.Value;  public class FunctionCalling {     public async Task<string> GenerateFunctionCall(         string projectId = "your-project-id",         string location = "us-central1",         string publisher = "google",         string model = "gemini-2.0-flash-001")     {         var predictionServiceClient = new PredictionServiceClientBuilder         {             Endpoint = $"{location}-aiplatform.googleapis.com"         }.Build();          // Define the user's prompt in a Content object that we can reuse in         // model calls         var userPromptContent = new Content         {             Role = "USER",             Parts =             {                 new Part { Text = "What is the weather like in Boston?" }             }         };          // Specify a function declaration and parameters for an API request         var functionName = "get_current_weather";         var getCurrentWeatherFunc = new FunctionDeclaration         {             Name = functionName,             Description = "Get the current weather in a given location",             Parameters = new OpenApiSchema             {                 Type = Type.Object,                 Properties =                 {                     ["location"] = new()                     {                         Type = Type.String,                         Description = "Get the current weather in a given location"                     },                     ["unit"] = new()                     {                         Type = Type.String,                         Description = "The unit of measurement for the temperature",                         Enum = {"celsius", "fahrenheit"}                     }                 },                 Required = { "location" }             }         };          // Send the prompt and instruct the model to generate content using the tool that you just created         var generateContentRequest = new GenerateContentRequest         {             Model = $"projects/{projectId}/locations/{location}/publishers/{publisher}/models/{model}",             GenerationConfig = new GenerationConfig             {                 Temperature = 0f             },             Contents =             {                 userPromptContent             },             Tools =             {                 new Tool                 {                     FunctionDeclarations = { getCurrentWeatherFunc }                 }             }         };          GenerateContentResponse response = await predictionServiceClient.GenerateContentAsync(generateContentRequest);          var functionCall = response.Candidates[0].Content.Parts[0].FunctionCall;         Console.WriteLine(functionCall);          string apiResponse = "";          // Check the function name that the model responded with, and make an API call to an external system         if (functionCall.Name == functionName)         {             // Extract the arguments to use in your API call             string locationCity = functionCall.Args.Fields["location"].StringValue;              // Here you can use your preferred method to make an API request to             // fetch the current weather              // In this example, we'll use synthetic data to simulate a response             // payload from an external API             apiResponse = @"{ ""location"": ""Boston, MA"",                     ""temperature"": 38, ""description"": ""Partly Cloudy""}";         }          // Return the API response to Gemini so it can generate a model response or request another function call         generateContentRequest = new GenerateContentRequest         {             Model = $"projects/{projectId}/locations/{location}/publishers/{publisher}/models/{model}",             Contents =             {                 userPromptContent, // User prompt                 response.Candidates[0].Content, // Function call response,                 new Content                 {                     Parts =                     {                         new Part                         {                             FunctionResponse = new()                             {                                 Name = functionName,                                 Response = new()                                 {                                     Fields =                                     {                                         { "content", new Value { StringValue = apiResponse } }                                     }                                 }                             }                         }                     }                 }             },             Tools =             {                 new Tool                 {                     FunctionDeclarations = { getCurrentWeatherFunc }                 }             }         };          response = await predictionServiceClient.GenerateContentAsync(generateContentRequest);          string responseText = response.Candidates[0].Content.Parts[0].Text;         Console.WriteLine(responseText);          return responseText;     } } 

Java

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Java Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

import com.google.cloud.vertexai.VertexAI; import com.google.cloud.vertexai.api.Content; import com.google.cloud.vertexai.api.FunctionDeclaration; import com.google.cloud.vertexai.api.GenerateContentResponse; import com.google.cloud.vertexai.api.Schema; import com.google.cloud.vertexai.api.Tool; import com.google.cloud.vertexai.api.Type; import com.google.cloud.vertexai.generativeai.ChatSession; import com.google.cloud.vertexai.generativeai.ContentMaker; import com.google.cloud.vertexai.generativeai.GenerativeModel; import com.google.cloud.vertexai.generativeai.PartMaker; import com.google.cloud.vertexai.generativeai.ResponseHandler; import java.io.IOException; import java.util.Arrays; import java.util.Collections;  public class FunctionCalling {   public static void main(String[] args) throws IOException {     // TODO(developer): Replace these variables before running the sample.     String projectId = "your-google-cloud-project-id";     String location = "us-central1";     String modelName = "gemini-2.0-flash-001";      String promptText = "What's the weather like in Paris?";      whatsTheWeatherLike(projectId, location, modelName, promptText);   }    // A request involving the interaction with an external tool   public static String whatsTheWeatherLike(String projectId, String location,                                            String modelName, String promptText)       throws IOException {     // Initialize client that will be used to send requests.     // This client only needs to be created once, and can be reused for multiple requests.     try (VertexAI vertexAI = new VertexAI(projectId, location)) {        FunctionDeclaration functionDeclaration = FunctionDeclaration.newBuilder()           .setName("getCurrentWeather")           .setDescription("Get the current weather in a given location")           .setParameters(               Schema.newBuilder()                   .setType(Type.OBJECT)                   .putProperties("location", Schema.newBuilder()                       .setType(Type.STRING)                       .setDescription("location")                       .build()                   )                   .addRequired("location")                   .build()           )           .build();        System.out.println("Function declaration:");       System.out.println(functionDeclaration);        // Add the function to a "tool"       Tool tool = Tool.newBuilder()           .addFunctionDeclarations(functionDeclaration)           .build();        // Start a chat session from a model, with the use of the declared function.       GenerativeModel model = new GenerativeModel(modelName, vertexAI)           .withTools(Arrays.asList(tool));       ChatSession chat = model.startChat();        System.out.println(String.format("Ask the question: %s", promptText));       GenerateContentResponse response = chat.sendMessage(promptText);        // The model will most likely return a function call to the declared       // function `getCurrentWeather` with "Paris" as the value for the       // argument `location`.       System.out.println("\nPrint response: ");       System.out.println(ResponseHandler.getContent(response));        // Provide an answer to the model so that it knows what the result       // of a "function call" is.       Content content =           ContentMaker.fromMultiModalData(               PartMaker.fromFunctionResponse(                   "getCurrentWeather",                   Collections.singletonMap("currentWeather", "sunny")));       System.out.println("Provide the function response: ");       System.out.println(content);       response = chat.sendMessage(content);        // See what the model replies now       System.out.println("Print response: ");       String finalAnswer = ResponseHandler.getText(response);       System.out.println(finalAnswer);        return finalAnswer;     }   } }

Jika model menentukan bahwa model memerlukan output dari fungsi tertentu, respons yang diterima aplikasi dari model berisi nama fungsi dan nilai parameter yang harus digunakan untuk memanggil fungsi.

Berikut adalah contoh respons model terhadap perintah pengguna "Bagaimana cuaca di Boston?". Model mengusulkan pemanggilan fungsi get_current_weather dengan parameter Boston, MA.

 candidates {   content {     role: "model"     parts {       function_call {         name: "get_current_weather"         args {           fields {             key: "location"             value {               string_value: "Boston, MA"             }           }         }       }     }   }   ... } 

Langkah 2: Berikan output API ke model

Panggil API eksternal dan teruskan output API kembali ke model.

Contoh berikut menggunakan data sintetis untuk menyimulasikan payload respons dari API eksternal dan mengirimkan output kembali ke model.

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) 

Untuk mengetahui praktik terbaik terkait pemanggilan API, lihat Praktik terbaik - Pemanggilan API.

Jika model telah mengusulkan beberapa panggilan fungsi paralel, aplikasi harus memberikan semua respons kembali ke model. Untuk mempelajari lebih lanjut, lihat Contoh pemanggilan fungsi paralel.

Model dapat menentukan bahwa output fungsi lain diperlukan untuk merespons perintah. Dalam hal ini, respons yang diterima aplikasi dari model berisi nama fungsi lain dan kumpulan nilai parameter lain.

Jika model menentukan bahwa respons API sudah cukup untuk merespons perintah pengguna, model akan membuat respons bahasa alami dan menampilkannya ke aplikasi. Dalam hal ini, aplikasi harus meneruskan respons kembali ke pengguna. Berikut adalah contoh respons bahasa alami:

 It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies. 

Panggilan fungsi dengan pemikiran

Saat memanggil fungsi dengan thinking diaktifkan, Anda harus mendapatkan thought_signature dari objek respons model dan menampilkannya saat Anda mengirimkan hasil eksekusi fungsi kembali ke model. Contoh:

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) 

Melihat tanda tangan pikiran tidak diperlukan, tetapi Anda harus menyesuaikan Langkah 2 untuk menampilkannya bersama hasil eksekusi fungsi sehingga dapat menggabungkan pikiran ke dalam respons akhirnya:

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) 

Saat menampilkan tanda tangan pemikiran, ikuti panduan berikut:

  • Model menampilkan tanda tangan dalam bagian lain dalam respons, misalnya, bagian panggilan fungsi atau teks, teks, atau ringkasan pemikiran. Mengembalikan seluruh respons dengan semua bagian kembali ke model pada giliran berikutnya.
  • Jangan menggabungkan bagian dengan satu tanda tangan dengan bagian lain yang juga berisi tanda tangan. Tanda tangan tidak dapat digabungkan.
  • Jangan menggabungkan satu bagian dengan tanda tangan dengan bagian lain tanpa tanda tangan. Hal ini akan merusak posisi yang benar dari pemikiran yang diwakili oleh tanda tangan.

Pelajari lebih lanjut batasan dan penggunaan tanda tangan pemikiran, serta model pemikiran secara umum, di halaman Pemikiran.

Panggilan fungsi paralel

Untuk perintah seperti "Dapatkan detail cuaca di Boston dan San Francisco?", model dapat menyarankan beberapa panggilan fungsi paralel. Untuk mengetahui daftar model yang mendukung panggilan fungsi paralel, lihat Model yang didukung.

REST

Contoh ini menunjukkan skenario dengan satu fungsi get_current_weather. Perintah pengguna adalah "Dapatkan detail cuaca di Boston dan San Francisco?". Model mengusulkan dua panggilan fungsi get_current_weather paralel: satu dengan parameter Boston dan yang lainnya dengan parameter San Francisco.

Untuk mempelajari parameter permintaan lebih lanjut, lihat Gemini API.

 { "candidates": [   {     "content": {       "role": "model",       "parts": [         {           "functionCall": {             "name": "get_current_weather",             "args": {               "location": "Boston"             }           }         },         {           "functionCall": {             "name": "get_current_weather",             "args": {               "location": "San Francisco"             }           }         }       ]     },     ...   } ], ... } 

Perintah berikut menunjukkan cara memberikan output fungsi ke model. Ganti my-project dengan nama project Google Cloud Anda.

Permintaan model

 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"         ]       }     }   ] } ] }'   

Respons bahasa alami yang dibuat oleh model mirip dengan berikut ini:

Respons model

 [ {     "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

Contoh ini menunjukkan skenario dengan satu fungsi get_current_weather. Perintah pengguna adalah "Bagaimana cuaca di Boston dan San Francisco?".

Ganti my-project dengan nama project Google Cloud Anda.

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],       )     ] ) 

Perintah berikut menunjukkan cara memberikan output fungsi ke model.

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

import ( 	"context" 	"encoding/json" 	"errors" 	"fmt" 	"io"  	"cloud.google.com/go/vertexai/genai" )  // parallelFunctionCalling shows how to execute multiple function calls in parallel // and return their results to the model for generating a complete response. func parallelFunctionCalling(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("failed to create GenAI client: %w", err) 	} 	defer client.Close()  	model := client.GenerativeModel(modelName) 	// Set temperature to 0.0 for maximum determinism in function calling. 	model.SetTemperature(0.0)  	funcName := "getCurrentWeather" 	funcDecl := &genai.FunctionDeclaration{ 		Name:        funcName, 		Description: "Get the current weather in a given location", 		Parameters: &genai.Schema{ 			Type: genai.TypeObject, 			Properties: map[string]*genai.Schema{ 				"location": { 					Type: genai.TypeString, 					Description: "The location for which to get the weather. " + 						"It can be a city name, a city name and state, or a zip code. " + 						"Examples: 'San Francisco', 'San Francisco, CA', '95616', etc.", 				}, 			}, 			Required: []string{"location"}, 		}, 	} 	// Add the weather function to our model toolbox. 	model.Tools = []*genai.Tool{ 		{ 			FunctionDeclarations: []*genai.FunctionDeclaration{funcDecl}, 		}, 	}  	prompt := genai.Text("Get weather details in New Delhi and San Francisco?") 	resp, err := model.GenerateContent(ctx, prompt)  	if err != nil { 		return fmt.Errorf("failed to generate content: %w", err) 	} 	if len(resp.Candidates) == 0 { 		return errors.New("got empty response from model") 	} else if len(resp.Candidates[0].FunctionCalls()) == 0 { 		return errors.New("got no function call suggestions from model") 	}  	// In a production environment, consider adding validations for function names and arguments. 	for _, fnCall := range resp.Candidates[0].FunctionCalls() { 		fmt.Fprintf(w, "The model suggests to call the function %q with args: %v\n", fnCall.Name, fnCall.Args) 		// Example response: 		// The model suggests to call the function "getCurrentWeather" with args: map[location:New Delhi] 		// The model suggests to call the function "getCurrentWeather" with args: map[location:San Francisco] 	}  	// Use synthetic data to simulate responses from the external API. 	// In a real application, this would come from an actual weather API. 	mockAPIResp1, err := json.Marshal(map[string]string{ 		"location":         "New Delhi", 		"temperature":      "42", 		"temperature_unit": "C", 		"description":      "Hot and humid", 		"humidity":         "65", 	}) 	if err != nil { 		return fmt.Errorf("failed to marshal function response to JSON: %w", err) 	}  	mockAPIResp2, err := json.Marshal(map[string]string{ 		"location":         "San Francisco", 		"temperature":      "36", 		"temperature_unit": "F", 		"description":      "Cold and cloudy", 		"humidity":         "N/A", 	}) 	if err != nil { 		return fmt.Errorf("failed to marshal function response to JSON: %w", err) 	}  	// Note, that the function calls don't have to be chained. We can obtain both responses in parallel 	// and return them to Gemini at once. 	funcResp1 := &genai.FunctionResponse{ 		Name: funcName, 		Response: map[string]any{ 			"content": mockAPIResp1, 		}, 	} 	funcResp2 := &genai.FunctionResponse{ 		Name: funcName, 		Response: map[string]any{ 			"content": mockAPIResp2, 		}, 	}  	// Return both API responses to the model allowing it to complete its response. 	resp, err = model.GenerateContent(ctx, prompt, funcResp1, funcResp2) 	if err != nil { 		return fmt.Errorf("failed to generate content: %w", err) 	} 	if len(resp.Candidates) == 0 || len(resp.Candidates[0].Content.Parts) == 0 { 		return errors.New("got empty response from model") 	}  	fmt.Fprintln(w, resp.Candidates[0].Content.Parts[0]) 	// Example response: 	// The weather in New Delhi is hot and humid with a humidity of 65 and a temperature of 42°C. The weather in San Francisco ...  	return nil } 

Pemanggilan fungsi paksa

Daripada mengizinkan model memilih antara respons bahasa alami dan panggilan fungsi, Anda dapat memaksanya untuk hanya memprediksi panggilan fungsi. Hal ini dikenal sebagai panggilan fungsi paksa. Anda juga dapat memilih untuk memberikan kumpulan lengkap deklarasi fungsi ke model, tetapi membatasi responsnya ke subset fungsi ini.

Mode Deskripsi
AUTO Perilaku model default. Model memutuskan apakah akan memprediksi panggilan fungsi atau respons bahasa alami.
ANY Model dibatasi untuk selalu memprediksi panggilan fungsi. Jika allowed_function_names tidak diberikan, model akan memilih dari semua deklarasi fungsi yang tersedia. Jika allowed_function_names disediakan, model akan memilih dari kumpulan fungsi yang diizinkan.
NONE Model tidak boleh memprediksi panggilan fungsi. Perilaku ini setara dengan permintaan model tanpa deklarasi fungsi terkait.

Contoh berikut dipaksa untuk memprediksi hanya panggilan fungsi 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"],         )     ) ) 

Contoh skema fungsi

Deklarasi fungsi kompatibel dengan skema OpenAPI. Kami mendukung atribut berikut: type, nullable, required, format, description, properties, items, enum, anyOf, $ref, dan $defs. Atribut yang tersisa tidak didukung.

Fungsi dengan parameter objek dan array

Contoh berikut menggunakan kamus Python untuk mendeklarasikan fungsi yang menggunakan parameter objek dan array:

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"],   }, )   

Fungsi dengan parameter enum

Contoh berikut menggunakan kamus Python untuk mendeklarasikan fungsi yang mengambil parameter bilangan bulat 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.         }       },   }, )   

Fungsi dengan ref dan def

Deklarasi fungsi JSON berikut menggunakan atribut ref dan 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" }             }           }         }       ]     }   ] }   

Catatan penggunaan:

  • Tidak seperti skema OpenAPI, tentukan ref dan defs tanpa simbol $.
  • ref harus merujuk ke turunan langsung dari defs; tidak ada referensi eksternal.
  • Kedalaman maksimum skema bertingkat adalah 32.
  • Kedalaman rekursi di defs (referensi mandiri) dibatasi hingga dua.

from_func dengan parameter array

Contoh kode berikut mendeklarasikan fungsi yang mengalikan array angka dan menggunakan from_func untuk menghasilkan skema 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'}} """   

Praktik terbaik untuk panggilan fungsi

Tulis nama fungsi, deskripsi parameter, dan petunjuk yang jelas dan mendetail

  • Nama fungsi harus diawali dengan huruf atau garis bawah dan hanya berisi karakter a-z, A-Z, 0-9, garis bawah, titik, atau tanda hubung dengan panjang maksimum 64.

  • Deskripsi fungsi harus jelas dan panjang. Misalnya, fungsi book_flight_ticket dapat memiliki deskripsi book flight tickets after confirming users' specific requirements, such as time, departure, destination, party size and preferred airline

Menggunakan parameter yang diketik dengan kuat

Jika nilai parameter berasal dari kumpulan terbatas, tambahkan kolom enum, bukan memasukkan kumpulan nilai ke dalam deskripsi. Jika nilai parameter selalu berupa bilangan bulat, tetapkan jenisnya ke integer, bukan number.

Menggunakan petunjuk sistem

Saat menggunakan fungsi dengan parameter tanggal, waktu, atau lokasi, sertakan tanggal, waktu, atau informasi lokasi yang relevan saat ini (misalnya, kota dan negara) dalam petunjuk sistem. Hal ini memberikan konteks yang diperlukan bagi model untuk memproses permintaan secara akurat, meskipun perintah pengguna tidak memiliki detail.

Perintah pembaruan pengguna

Untuk hasil terbaik, tambahkan detail berikut di awal perintah pengguna:

  • Konteks tambahan untuk model-misalnya, You are a flight API assistant to help with searching flights based on user preferences.
  • Detail atau petunjuk tentang cara dan waktu penggunaan fungsi-misalnya, Don't make assumptions on the departure or destination airports. Always use a future date for the departure or destination time.
  • Petunjuk untuk mengajukan pertanyaan klarifikasi jika kueri pengguna ambigu-misalnya, Ask clarifying questions if not enough information is available.

Menggunakan konfigurasi pembuatan

Untuk parameter suhu, gunakan 0 atau nilai rendah lainnya. Hal ini menginstruksikan model untuk menghasilkan hasil yang lebih meyakinkan dan mengurangi halusinasi.

Memvalidasi panggilan API

Jika model mengusulkan pemanggilan fungsi yang akan mengirimkan pesanan, memperbarui database, atau memiliki konsekuensi signifikan lainnya, validasi panggilan fungsi dengan pengguna sebelum mengeksekusinya.

Menggunakan tanda tangan pikiran

Tanda tangan pemikiran harus selalu digunakan dengan panggilan fungsi untuk hasil terbaik.

Harga

Harga untuk panggilan fungsi didasarkan pada jumlah karakter dalam input dan output teks. Untuk mempelajari lebih lanjut, lihat Harga Vertex AI.

Di sini, input teks (perintah) mengacu pada perintah pengguna untuk giliran percakapan saat ini, deklarasi fungsi untuk giliran percakapan saat ini, dan histori percakapan. Histori percakapan mencakup kueri, panggilan fungsi, dan respons fungsi dari pernyataan percakapan sebelumnya. Vertex AI memangkas histori percakapan pada 32.000 karakter.

Output teks (respons) mengacu pada panggilan fungsi dan respons teks untuk giliran percakapan saat ini.

Kasus penggunaan panggilan fungsi

Anda dapat menggunakan panggilan fungsi untuk tugas berikut:

Kasus Penggunaan Contoh deskripsi Contoh link
Mengintegrasikan dengan API eksternal Mendapatkan informasi cuaca menggunakan API meteorologi Tutorial notebook
Mengonversi alamat menjadi koordinat garis lintang/bujur Tutorial notebook
Mengonversi mata uang menggunakan API pertukaran mata uang Codelab
Membangun chatbot lanjutan Menjawab pertanyaan pelanggan tentang produk dan layanan Tutorial notebook
Membuat asisten untuk menjawab pertanyaan keuangan dan berita tentang perusahaan Tutorial notebook
Menyusun dan mengontrol panggilan fungsi Mengekstrak entity terstruktur dari data log mentah Tutorial notebook
Mengekstrak satu atau beberapa parameter dari input pengguna Tutorial notebook
Menangani daftar dan struktur data bertingkat dalam panggilan fungsi Tutorial notebook
Menangani perilaku panggilan fungsi Menangani panggilan dan respons fungsi paralel Tutorial notebook
Mengelola kapan dan fungsi mana yang dapat dipanggil oleh model Tutorial notebook
Membuat kueri database dengan bahasa alami Mengonversi pertanyaan dalam bahasa alami menjadi kueri SQL untuk BigQuery Aplikasi contoh
Panggilan fungsi multimodal Gunakan gambar, video, audio, dan PDF sebagai input untuk memicu panggilan fungsi Tutorial notebook

Berikut beberapa kasus penggunaan lainnya:

  • Menafsirkan perintah suara: Buat fungsi yang sesuai dengan tugas dalam kendaraan. Misalnya, Anda dapat membuat fungsi yang menyalakan radio atau mengaktifkan AC. Kirim file audio perintah suara pengguna ke model, lalu minta model untuk mengonversi audio menjadi teks dan mengidentifikasi fungsi yang ingin dipanggil pengguna.

  • Mengotomatiskan alur kerja berdasarkan pemicu lingkungan: Buat fungsi untuk merepresentasikan proses yang dapat diotomatiskan. Memberikan data dari sensor lingkungan ke model dan memintanya untuk mengurai dan memproses data guna menentukan apakah satu atau beberapa alur kerja harus diaktifkan. Misalnya, model dapat memproses data suhu di gudang dan memilih untuk mengaktifkan fungsi penyiram.

  • Mengotomatiskan penetapan tiket dukungan: Berikan model tiket dukungan, log, dan aturan yang sesuai konteks. Minta model untuk memproses semua informasi ini guna menentukan siapa yang harus diberi tiket. Panggil fungsi untuk menetapkan tiket kepada orang yang disarankan oleh model.

  • Mengambil informasi dari pusat informasi: Buat fungsi yang mengambil artikel akademis tentang subjek tertentu dan meringkasnya. Memungkinkan model menjawab pertanyaan tentang mata pelajaran akademis dan memberikan kutipan untuk jawabannya.

Langkah berikutnya