Generare contenuti utilizzando le chiamate di funzione

Questo esempio mostra come utilizzare le dichiarazioni di funzioni per influenzare i contenuti generati da Gemini Multimodal.

Per saperne di più

Per la documentazione dettagliata che include questo esempio di codice, vedi quanto segue:

Esempio di codice

Go

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Go.

Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

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
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Java.

Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 


import com.google.genai.Client;
import com.google.genai.types.FunctionDeclaration;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Schema;
import com.google.genai.types.Tool;
import com.google.genai.types.Type;
import java.util.Map;

public class ToolFunctionDescriptionWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    String contents =
        "At Stellar Sounds, a music label, 2024 was a rollercoaster. \"Echoes of the Night,\""
            + " a debut synth-pop album, \n surprisingly sold 350,000 copies, while veteran"
            + " rock band \"Crimson Tide's\" latest, \"Reckless Hearts,\" \n lagged at"
            + " 120,000. Their up-and-coming indie artist, \"Luna Bloom's\" EP, \"Whispers "
            + "of Dawn,\" \n secured 75,000 sales. The biggest disappointment was the "
            + "highly-anticipated rap album \"Street Symphony\" \n only reaching 100,000"
            + " units. Overall, Stellar Sounds moved over 645,000 units this year, revealing"
            + " unexpected \n trends in music consumption.";

    generateContent(modelId, contents);
  }

  // Generates content with text input and function declaration that
  // the model may use to retrieve external data for the response
  public static String generateContent(String modelId, String contents) {
    // 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 (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      FunctionDeclaration getAlbumSales =
          FunctionDeclaration.builder()
              .name("get_album_sales")
              .description("Gets the number of albums sold")
              // Function parameters are specified in schema format
              .parameters(
                  Schema.builder()
                      .type(Type.Known.OBJECT)
                      .properties(
                          Map.of(
                              "albums",
                              Schema.builder()
                                  .type(Type.Known.ARRAY)
                                  .description("List of albums")
                                  .items(
                                      Schema.builder()
                                          .description("Album and its sales")
                                          .type(Type.Known.OBJECT)
                                          .properties(
                                              Map.of(
                                                  "album_name",
                                                      Schema.builder()
                                                          .type(Type.Known.STRING)
                                                          .description("Name of the music album")
                                                          .build(),
                                                  "copies_sold",
                                                      Schema.builder()
                                                          .type(Type.Known.INTEGER)
                                                          .description("Number of copies sold")
                                                          .build()))
                                          .build()) // End items schema for albums
                                  .build() // End "albums" property schema
                              ))
                      .build()) // End parameters schema
              .build(); // End function declaration

      Tool salesTool = Tool.builder().functionDeclarations(getAlbumSales).build();

      GenerateContentConfig config =
          GenerateContentConfig.builder().tools(salesTool).temperature(0.0f).build();

      GenerateContentResponse response = client.models.generateContent(modelId, contents, config);

      // response.functionCalls() returns an Immutable<FunctionCall>.
      System.out.println(response.functionCalls().get(0));

      return response.functionCalls().toString();
      // Example response:
      // FunctionCall{id=Optional.empty, args=Optional[{albums=[{copies_sold=350000,
      // album_name=Echoes of the Night},
      // {copies_sold=120000, album_name=Reckless Hearts}, {copies_sold=75000, album_name=Whispers
      // of Dawn},
      // {album_name=Street Symphony, copies_sold=100000}]}], name=Optional[get_album_sales]}
    }
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Node.js.

Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

const {GoogleGenAI, Type} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateContent(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const get_album_sales = {
    name: 'get_album_sales',
    description: 'Gets the number of albums sold',
    parameters: {
      type: Type.OBJECT,
      properties: {
        albums: {
          type: Type.ARRAY,
          description: 'List of albums',
          items: {
            description: 'Album and its sales',
            type: Type.OBJECT,
            properties: {
              album_name: {
                type: Type.STRING,
                description: 'Name of the music album',
              },
              copies_sold: {
                type: Type.INTEGER,
                description: 'Number of copies sold',
              },
            },
          },
        },
      },
    },
  };

  const sales_tool = {
    functionDeclarations: [get_album_sales],
  };

  const prompt = `
    At Stellar Sounds, a music label, 2024 was a rollercoaster. "Echoes of the Night", a debut synth-pop album, 
    surprisingly sold 350,000 copies, while veteran rock band "Crimson Tide's" latest, "Reckless Hearts",
    lagged at 120,000. Their up-and-coming indie artist, "Luna Bloom's" EP, "Whispers of Dawn",
    secured 75,000 sales. The biggest disappointment was the highly-anticipated rap album "Street Symphony" 
    only reaching 100,000 units. Overall, Stellar Sounds moved over 645,000 units this year, revealing unexpected
    trends in music consumption.
  `;

  const MODEL_NAME = 'gemini-2.5-flash';

  const response = await client.models.generateContent({
    model: MODEL_NAME,
    contents: prompt,
    config: {
      tools: [sales_tool],
      temperature: 0,
    },
  });

  console.log(response.functionCalls);

  return response.functionCalls;
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Python.

Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale. 

from google import genai
from google.genai.types import (
    FunctionDeclaration,
    GenerateContentConfig,
    HttpOptions,
    Tool,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.5-flash"

get_album_sales = FunctionDeclaration(
    name="get_album_sales",
    description="Gets the number of albums sold",
    # Function parameters are specified in JSON schema format
    parameters={
        "type": "OBJECT",
        "properties": {
            "albums": {
                "type": "ARRAY",
                "description": "List of albums",
                "items": {
                    "description": "Album and its sales",
                    "type": "OBJECT",
                    "properties": {
                        "album_name": {
                            "type": "STRING",
                            "description": "Name of the music album",
                        },
                        "copies_sold": {
                            "type": "INTEGER",
                            "description": "Number of copies sold",
                        },
                    },
                },
            },
        },
    },
)

sales_tool = Tool(
    function_declarations=[get_album_sales],
)

response = client.models.generate_content(
    model=model_id,
    contents='At Stellar Sounds, a music label, 2024 was a rollercoaster. "Echoes of the Night," a debut synth-pop album, '
    'surprisingly sold 350,000 copies, while veteran rock band "Crimson Tide\'s" latest, "Reckless Hearts," '
    'lagged at 120,000. Their up-and-coming indie artist, "Luna Bloom\'s" EP, "Whispers of Dawn," '
    'secured 75,000 sales. The biggest disappointment was the highly-anticipated rap album "Street Symphony" '
    "only reaching 100,000 units. Overall, Stellar Sounds moved over 645,000 units this year, revealing unexpected "
    "trends in music consumption.",
    config=GenerateContentConfig(
        tools=[sales_tool],
        temperature=0,
    ),
)

print(response.function_calls)
# Example response:
# [FunctionCall(
#     id=None,
#     name="get_album_sales",
#     args={
#         "albums": [
#             {"album_name": "Echoes of the Night", "copies_sold": 350000},
#             {"copies_sold": 120000, "album_name": "Reckless Hearts"},
#             {"copies_sold": 75000, "album_name": "Whispers of Dawn"},
#             {"copies_sold": 100000, "album_name": "Street Symphony"},
#         ]
#     },
# )]

Passaggi successivi

Per cercare e filtrare gli esempi di codice per altri prodotti Google Cloud , consulta il browser degli esempi diGoogle Cloud .