Funktionsaufrufe

Überblick

Mit Funktionsaufrufen können Sie benutzerdefinierte Funktionen definieren und in einem generativen KI-Modell bereitstellen. Während der Verarbeitung einer Abfrage kann das Modell bestimmte Datenverarbeitungsaufgaben an diese Funktionen delegieren. Die Funktionen werden nicht aufgerufen. Stattdessen wird eine strukturierte Datenausgabe bereitgestellt, die den Namen einer ausgewählten Funktion und die Argumente enthält, mit denen das Modell die aufzurufende Funktion vorschlägt. Mit dieser Ausgabe können Sie externe APIs aufrufen. Sie können dann die API-Ausgabe für das Modell zurückgeben, damit es die Antwort auf die Abfrage abschließen kann. Auf diese Weise können durch Funktionsaufrufe LLMs auf Echtzeitinformationen zugreifen und mit verschiedenen Diensten wie SQL-Datenbanken, Customer-Relationship-Management-Systemen und Dokument-Repositories interagieren.

Das folgende Diagramm veranschaulicht die Funktionsweise von Funktionsaufrufen: Funktionsaufruf-Interaktion 

Weitere Informationen zu den Anwendungsfällen von Funktionsaufrufen finden Sie unter Anwendungsfälle für Funktionsaufrufe. Informationen zum Erstellen einer Funktionsaufrufanwendung finden Sie unter Funktionsaufrufanwendung erstellen. Best Practices finden Sie unter Best Practices.

Der Funktionsaufruf ist ein Feature des Modells gemini-1.0-pro-001 und ein Vorschaufeature des Modells gemini-1.0-pro-002.

Der Funktionsaufruf ist ein Feature des Modells Gemini 1.5 Pro (Vorschau).

Anwendungsfälle von Funktionsaufrufen

Sie können Funktionsaufrufe für die folgenden Aufgaben verwenden:

Funktionsaufrufanwendung erstellen

Damit eine Benutzeroberfläche mit dem Modell kommunizieren und Funktionsaufrufe verwenden kann, müssen Sie Code erstellen, der die folgenden Aufgaben ausführt:

Sie können eine Anwendung erstellen, die alle diese Aufgaben verwaltet. Diese kann ein Text-Chatbot, ein Sprach-Agent, ein automatisierter Workflow oder ein anderes Programm sein.

Eine Reihe verfügbarer Funktionen definieren und beschreiben

Die Anwendung muss eine Reihe von Funktionen deklarieren, die das Modell zur Verarbeitung der Abfrage verwenden kann. Jede Funktionsdeklaration muss einen Funktionsnamen und Funktionsparameter enthalten. Wir empfehlen dringend, in jede Funktionsdeklaration auch eine Funktionsbeschreibung aufzunehmen.

Funktionsname

Die Anwendung und das Modell identifizieren die Funktion anhand des Funktionsnamens.

Best Practices für den Funktionsnamen finden Sie unter Best Practices – Funktionsname.

Funktionsparameter

Funktionsparameter müssen in einem Format bereitgestellt werden, das mit dem OpenAPI-Schema kompatibel ist.

Vertex AI bietet eingeschränkte Unterstützung für das OpenAPI-Schema. Die folgenden Attribute sind zulässig: type, nullable, required, format, description, properties, items, enum. Die folgenden Attribute werden nicht unterstützt: default, optional, maximum, oneOf.

Wenn Sie curl verwenden, geben Sie das Schema mit JSON an. Wenn Sie das Vertex AI SDK für Python verwenden, geben Sie das Schema mit einem Python-Wörterbuch an.

Best Practices für Funktionsparameter finden Sie unter Best Practices – Funktionsparameter.

Funktionsbeschreibung

Das Modell verwendet Funktionsbeschreibungen, um den Zweck der Funktionen zu verstehen und zu bestimmen, ob diese Funktionen bei der Verarbeitung von Nutzerabfragen nützlich sind.

Best Practices zur Funktionsbeschreibung finden Sie unter Best Practices – Funktionsbeschreibung.

Beispiel für eine Funktionsdeklaration

Das folgende Beispiel zeigt eine einfache Funktionsdeklaration in Python:

get_current_weather_func = FunctionDeclaration(
    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."}},
    },
)

Das folgende Beispiel zeigt eine Funktionsdeklaration mit einem Array von Elementen:

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

Abfrage und Funktionsdeklarationen an das Modell senden

Stellt der Nutzer einen Prompt bereit, muss die Anwendung das Modell mit dem Nutzer-Prompt und den Funktionsdeklarationen bereitstellen. Die Anwendung kann dem Modell eine Generierungskonfiguration zur Verfügung stellen, um zu konfigurieren, wie das Modell Ergebnisse generiert. Um zu konfigurieren, wie das Modell die Funktionsdeklarationen verwendet, kann die Anwendung das Modell mit einer Toolkonfiguration bereitstellen.

Nutzer-Prompt

Das folgende Beispiel zeigt einen Nutzer-Prompt: "Wie ist das Wetter in Boston?"

Best Practices für den Nutzer-Prompt finden Sie unter Best Practices – Nutzer-Prompt.

Generierungskonfiguration

Das Modell kann für verschiedene Parameterwerte unterschiedliche Ergebnisse generieren. Der Temperaturparameter steuert den Grad der Zufälligkeit in dieser Generierung. Niedrigere Temperaturen eignen sich für Funktionen, die deterministische Parameterwerte erfordern, während höhere Temperaturen für Funktionen mit Parametern geeignet sind, die unterschiedliche oder kreativere Parameterwerte akzeptieren. Eine Temperatur von 0 ist deterministisch, d. h., die Antwort mit der höchsten Wahrscheinlichkeit wird immer ausgewählt. Weitere Informationen finden Sie unter Gemini API.

Zum Festlegen dieses Parameters senden Sie eine Generierungskonfiguration (generation_config) zusammen mit dem Prompt und den Funktionsdeklarationen.

Best Practices für die Generierungskonfiguration finden Sie unter Best Practices – Generierungskonfiguration.

Toolkonfiguration

Sie können Einschränkungen für die Verwendung der von Ihnen bereitgestellten Funktionsdeklarationen durch das Modell festlegen. Beispielsweise können Sie erzwingen, dass das Modell nicht zwischen einer Antwort in natürlicher Sprache und einem Funktionsaufruf wählen kann, sondern nur Funktionsaufrufe vorhersagen kann. Sie können dem Modell auch einen vollständigen Satz von Funktionsdeklarationen bereitstellen, seine Antworten jedoch auf eine Teilmenge dieser Funktionen beschränken.

Reichen Sie eine Toolkonfiguration (tool_config) zusammen mit dem Prompt und den Funktionsdeklarationen ein, um diese Einschränkungen festzulegen. In der Konfiguration können Sie einen der folgenden Modi angeben:

Modus Beschreibung
AUTOMATISCH Das Standardverhalten des Modells. Das Modell entscheidet, ob ein Funktionsaufruf oder eine Antwort in natürlicher Sprache vorhergesagt werden soll.
ALLE Das Modell darf nur Funktionsaufrufe vorhersagen. Wenn Sie das Modell auf eine Teilmenge von Funktionen beschränken möchten, definieren Sie die zulässigen Funktionsnamen in allowed_function_names.
KEINE Das Modell darf Funktionsaufrufe nicht vorhersagen. Dieses Verhalten entspricht einer Modellanfrage ohne zugehörige Funktionsdeklarationen.

Der Modus ANY der Toolkonfiguration ist ein Vorschaufeature. Er wird nur für Gemini 1.5 Pro-Modelle unterstützt.

Weitere Informationen finden Sie unter Function Calling API.

Prompt und Funktionsdeklarationen senden

Das folgende Beispiel zeigt, wie Sie die Abfrage und die Funktionsdeklarationen an das Modell senden und das Modell auf die Vorhersage von get_current_weather-Funktionsaufrufen beschränken können.

# Initialize Vertex AI
from vertexai.preview.generative_models import ToolConfig

vertexai.init(project=project_id, location=location)

# Initialize Gemini model
model = GenerativeModel("Gemini 1.5 Pro")

# Define a tool that includes the function declaration get_current_weather_func
weather_tool = Tool(
    function_declarations=[get_current_weather_func],
)

# Define the user's prompt in a Content object that we can reuse in model calls
user_prompt_content = Content(
    role="user",
    parts=[
        Part.from_text(prompt),
    ],
)

# Send the prompt and instruct the model to generate content using the Tool object that you just created
response = model.generate_content(
    user_prompt_content,
    generation_config={"temperature": 0},
    tools=[weather_tool],
    tool_config=ToolConfig(
        function_calling_config=ToolConfig.FunctionCallingConfig(
            # ANY mode forces the model to predict a function call
            mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
            # Allowed functions to call when the mode is ANY. If empty, any one of
            # the provided functions are called.
            allowed_function_names=["get_current_weather"],
    ))
)
response_function_call_content = response.candidates[0].content

Wenn das Modell feststellt, dass es die Ausgabe einer bestimmten Funktion benötigt, enthält die Antwort, die die Anwendung vom Modell empfängt, den Funktionsnamen und die Parameterwerte, mit denen die Funktion aufgerufen werden soll.

Das folgende Beispiel zeigt eine Modellantwort. Das Modell schlägt den Aufruf der Funktion get_current_weather mit dem Parameter Boston, MA vor.

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

Externe API aufrufen

Wenn die Anwendung einen Funktionsnamen und Parameterwerte vom Modell empfängt, muss die Anwendung eine Verbindung zu einer externen API herstellen und die Funktion aufrufen.

Im folgenden Beispiel werden synthetische Daten verwendet, um eine Antwortnutzlast von einer externen API zu simulieren:

# Check the function name that the model responded with, and make an API call to an external system
if (
    response.candidates[0].content.parts[0].function_call.name
    == "get_current_weather"
):
    # Extract the arguments to use in your API call
    location = (
        response.candidates[0].content.parts[0].function_call.args["location"]
    )

    # Here you can use your preferred method to make an API request to fetch the current weather, for example:
    # api_response = requests.post(weather_api_url, data={"location": location})

    # In this example, we'll use synthetic data to simulate a response payload from an external API
    api_response = """{ "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy",
                    "icon": "partly-cloudy", "humidity": 65, "wind": { "speed": 10, "direction": "NW" } }"""

Best Practices für API-Aufrufe finden Sie unter Best Practices – API-Aufruf.

Funktionsausgabe für das Modell übergeben

Nachdem eine Anwendung eine Antwort von einer externen API erhalten hat, muss sie diese Antwort an das Modell senden. Im Folgenden finden Sie ein Beispiel dafür, wie Sie das mit Python tun können:

response = model.generate_content(
    [
        user_prompt_content,  # User prompt
        response_function_call_content,  # Function call response
        Content(
            parts=[
                Part.from_function_response(
                    name="get_current_weather",
                    response={
                        "content": api_response,  # Return the API response to Gemini
                    },
                )
            ],
        ),
    ],
    tools=[weather_tool],
)
# Get the model summary response
summary = response.candidates[0].content.parts[0].text

Wenn das Modell feststellt, dass die API-Antwort zur Beantwortung der Nutzeranfrage ausreicht, wird eine Antwort in natürlicher Sprache erstellt und an die Anwendung zurückgegeben. In diesem Fall muss die Anwendung die Antwort an den Nutzer zurückgeben. Das folgende Beispiel zeigt eine Abfrageantwort: It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies. The humidity is 65% and the wind is blowing at 10 mph from the northwest.

Wenn das Modell feststellt, dass die Ausgabe einer anderen Funktion zur Beantwortung der Abfrage erforderlich ist, enthält die Antwort, die die Anwendung vom Modell empfängt, einen anderen Funktionsnamen und einen anderen Satz von Parameterwerten.

Best Practices

Funktionsname

Verwenden Sie im Funktionsnamen keine Punkte (.), Bindestriche (-) oder Leerzeichen. Verwenden Sie stattdessen Unterstriche (_) oder andere Zeichen.

Funktionsparameter

Schreiben Sie klare und ausführliche Parameterbeschreibungen, einschließlich Details wie Ihrem bevorzugten Format oder Ihren bevorzugten Werten. Beispiel für eine book_flight_ticket-Funktion:

  • Hier ein gutes Beispiel für eine departure-Parameterbeschreibung: Use the 3 char airport code to represent the airport. For example, SJC or SFO. Don't use the city name.
  • Das folgende Beispiel zeigt eine departure-Parameterbeschreibung: the departure airport

Verwenden Sie nach Möglichkeit stark typisierte Parameter, um Modellhalluzinationen zu reduzieren. Wenn die Parameterwerte beispielsweise aus einem endlichen Set stammen, fügen Sie das Feld enum hinzu, anstatt den Satz von Werten in die Beschreibung einzufügen. Wenn der Parameterwert immer eine Ganzzahl ist, setzen Sie den Typ auf integer statt auf number.

Funktionsbeschreibung

Schreiben Sie Funktionsbeschreibungen klar und ausführlich. Beispiel für eine book_flight_ticket-Funktion:

  • Das folgende Beispiel zeigt eine gute Funktionsbeschreibung: book flight tickets after confirming users' specific requirements, such as time, departure, destination, party size and preferred airline
  • Das folgende Beispiel zeigt eine fehlerhafte Funktionsbeschreibung: book flight ticket

Nutzer-Prompt

Die besten Ergebnisse erzielen Sie, wenn Sie der Nutzerabfrage die folgenden Details voranstellen:

  • Zusätzlicher Kontext für das Modell, z. B. You are a flight API assistant to help with searching flights based on user preferences.
  • Details oder Anleitungen zur Verwendung der Funktionen, z. B. Don't make assumptions on the departure or destination airports. Always use a future date for the departure or destination time.
  • Eine Anleitung, um klärende Fragen zu stellen, wenn Nutzerabfragen mehrdeutig sind, z. B. Ask clarifying questions if not enough information is available.

Generierungskonfiguration

Verwenden Sie für den Temperaturparameter 0 oder einen anderen niedrigen Wert. Dadurch wird das Modell angewiesen, zuverlässigere Ergebnisse zu generieren und KI-Halluzinationen zu reduzieren.

API-Aufruf

Wenn das Modell den Aufruf einer Funktion vorschlägt, die eine Bestellung senden, eine Datenbank aktualisieren oder anderweitig erhebliche Konsequenzen haben würde, validieren Sie den Funktionsaufruf vor der Ausführung mit dem Nutzer.

Preise

Die Preise für den Funktionsaufruf richten sich nach der Anzahl der Zeichen in den Texteingaben und -ausgaben. Weitere Informationen finden Sie unter Vertex AI-Preise.

Hier bezieht sich die Texteingabe (Prompt) auf die Nutzerabfrage für die aktuelle Unterhaltungsrunde, die Funktionsdeklarationen für die aktuelle Unterhaltungsrunde und den Verlauf der Unterhaltung. Der Verlauf der Unterhaltung umfasst die Abfragen, die Funktionsaufrufe und die Funktionsantworten der vorherigen Unterhaltungsrunden. Vertex AI kürzt den Verlauf der Unterhaltung auf 32.000 Zeichen.

Textausgabe (Antwort) bezieht sich auf die Funktionsaufrufe und die Textantworten für die aktuelle Unterhaltungsrunde.

Beispiele für Funktionsaufrufe

Sie können Funktionsaufrufe verwenden, um eine einzelne Textantwort zu generieren oder eine Chatsitzung zu unterstützen. Ad-hoc-Textantworten sind für bestimmte Geschäftsaufgaben nützlich, einschließlich der Codegenerierung. Chatsitzungen sind in freien, dialogorientierten Szenarien nützlich, in denen ein Nutzer wahrscheinlich Anschlussfragen stellt.

Wenn Sie Funktionsaufrufe verwenden, um eine einzelne Antwort zu generieren, müssen Sie dem Modell den vollständigen Kontext der Interaktion bereitstellen. Wenn Sie dagegen Funktionsaufrufe im Kontext einer Chatsitzung verwenden, speichert die Sitzung den Kontext für Sie und fügt ihn in jede Modellanfrage ein. In beiden Fällen speichert Vertex AI den Verlauf der Interaktion auf der Clientseite.

Informationen zum Generieren einer einzelnen Textantwort mithilfe von Funktionsaufrufen finden Sie unter Textbeispiele. Informationen zur Verwendung von Funktionsaufrufen zur Unterstützung einer Chatsitzung finden Sie in den Chatbeispielen.

Textbeispiele

Python

Dieses Beispiel zeigt ein Textszenario mit einer Funktion und einem Prompt. Es verwendet die Klasse GenerativeModel und ihre Methoden. Weitere Informationen zur Verwendung des Vertex AI SDK für Python mit multimodalen Modellen von Gemini finden Sie unter Einführung in multimodale Klassen in Vertex AI SDK für Python.

Python

Informationen zur Installation des Vertex AI SDK for Python finden Sie unter Vertex AI SDK for Python installieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Python API. 

import vertexai
from vertexai.generative_models import (
    Content,
    FunctionDeclaration,
    GenerationConfig,
    GenerativeModel,
    Part,
    Tool,
)

def generate_function_call(prompt: str, project_id: str, location: str) -> tuple:
    # Initialize Vertex AI
    vertexai.init(project=project_id, location=location)

    # Initialize Gemini model
    model = GenerativeModel("gemini-1.0-pro-001")

    # Specify a function declaration and parameters for an API request
    get_current_weather_func = FunctionDeclaration(
        name="get_current_weather",
        description="Get the current weather in a given location",
        # Function parameters are specified in OpenAPI JSON schema format
        parameters={
            "type": "object",
            "properties": {"location": {"type": "string", "description": "Location"}},
        },
    )

    # Define a tool that includes the above get_current_weather_func
    weather_tool = Tool(
        function_declarations=[get_current_weather_func],
    )

    # Define the user's prompt in a Content object that we can reuse in model calls
    user_prompt_content = Content(
        role="user",
        parts=[
            Part.from_text(prompt),
        ],
    )

    # Send the prompt and instruct the model to generate content using the Tool that you just created
    response = model.generate_content(
        user_prompt_content,
        generation_config=GenerationConfig(temperature=0),
        tools=[weather_tool],
    )
    response_function_call_content = response.candidates[0].content

    # Check the function name that the model responded with, and make an API call to an external system
    if (
        response.candidates[0].content.parts[0].function_call.name
        == "get_current_weather"
    ):
        # Extract the arguments to use in your API call
        location = (
            response.candidates[0].content.parts[0].function_call.args["location"]
        )

        # Here you can use your preferred method to make an API request to fetch the current weather, for example:
        # api_response = requests.post(weather_api_url, data={"location": location})

        # In this example, we'll use synthetic data to simulate a response payload from an external API
        api_response = """{ "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy",
                        "icon": "partly-cloudy", "humidity": 65, "wind": { "speed": 10, "direction": "NW" } }"""

    # Return the API response to Gemini so it can generate a model response or request another function call
    response = model.generate_content(
        [
            user_prompt_content,  # User prompt
            response_function_call_content,  # Function call response
            Content(
                parts=[
                    Part.from_function_response(
                        name="get_current_weather",
                        response={
                            "content": api_response,  # Return the API response to Gemini
                        },
                    )
                ],
            ),
        ],
        tools=[weather_tool],
    )
    # Get the model summary response
    summary = response.candidates[0].content.parts[0].text

    return summary, response

Node.js

Dieses Beispiel zeigt ein Textszenario mit einer Funktion und einem Prompt.

Node.js

Bevor Sie dieses Beispiel anwenden, folgen Sie den Node.js-Einrichtungsschritten in der Vertex AI-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Vertex AI Node.js API.

Richten Sie zur Authentifizierung bei Vertex AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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 functionCallingStreamChat(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.0-pro'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.preview.getGenerativeModel({
    model: model,
  });

  const request = {
    contents: [
      {role: 'user', parts: [{text: 'What is the weather in Boston?'}]},
      {
        role: 'model',
        parts: [
          {
            functionCall: {
              name: 'get_current_weather',
              args: {location: 'Boston'},
            },
          },
        ],
      },
      {role: 'function', 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);
  }
}

REST

Dieses Beispiel zeigt ein Textszenario mit drei Funktionen und einer Eingabeaufforderung.

In diesem Beispiel rufen Sie das generative KI-Modell zweimal auf.

  • In dem ersten Aufruf geben Sie das Modell mit dem Prompt und den Funktionsdeklarationen an.
  • In dem zweiten Aufruf geben Sie dem Modell die API-Antwort.

Erste Modellanfrage

Die Anfrage muss eine Abfrage im Parameter text definieren. In diesem Beispiel wird die folgende Abfrage definiert: "In welchen Theatern in Mountain View wird der Barbie-Film gezeigt?".

In der Anfrage muss auch ein Tool (tools) mit einer Reihe von Funktionsdeklarationen (functionDeclarations) definiert sein. Diese Funktionsdeklarationen müssen in einem Format angegeben werden, das mit dem OpenAPI-Schema kompatibel ist. In diesem Beispiel werden die folgenden Funktionen definiert:

  • find_movies sucht Filmtitel, die im Kino gezeigt werden.
  • find_theatres sucht Kinos basierend auf dem Standort.
  • get_showtimes ermittelt die Startzeiten von Filmen, die in einem bestimmten Kino laufen.

Weitere Informationen zu den Parametern der Modellanfrage finden Sie unter Gemini API.

Ersetzen Sie my-project durch den Namen des Google Cloud-Projekts.

Erste Modellanfrage

PROJECT_ID=my-project
MODEL_ID=gemini-1.0-pro
API=streamGenerateContent
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": {
  "role": "user",
  "parts": {
    "text": "Which theaters in Mountain View show the Barbie movie?"
  }
},
"tools": [
  {
    "function_declarations": [
      {
        "name": "find_movies",
        "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
            },
            "description": {
              "type": "string",
              "description": "Any kind of description including category or genre, title words, attributes, etc."
            }
          },
          "required": [
            "description"
          ]
        }
      },
      {
        "name": "find_theaters",
        "description": "find theaters based on location and optionally movie title which are is currently playing in theaters",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
            },
            "movie": {
              "type": "string",
              "description": "Any movie title"
            }
          },
          "required": [
            "location"
          ]
        }
      },
      {
        "name": "get_showtimes",
        "description": "Find the start times for movies playing in a specific theater",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
            },
            "movie": {
              "type": "string",
              "description": "Any movie title"
            },
            "theater": {
              "type": "string",
              "description": "Name of the theater"
            },
            "date": {
              "type": "string",
              "description": "Date for requested showtime"
            }
          },
          "required": [
            "location",
            "movie",
            "theater",
            "date"
          ]
        }
      }
    ]
  }
]
}'

Für die Eingabeaufforderung „In welchen Kinos in Mountain View wird der Barbie-Film gezeigt?“, gibt das Modell möglicherweise die Funktion find_theatres mit den Parametern Barbie und Mountain View, CA zurück.

Antwort auf die erste Modellanfrage

[{
"candidates": [
  {
    "content": {
      "parts": [
        {
          "functionCall": {
            "name": "find_theaters",
            "args": {
              "movie": "Barbie",
              "location": "Mountain View, CA"
            }
          }
        }
      ]
    },
    "finishReason": "STOP",
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
],
"usageMetadata": {
  "promptTokenCount": 9,
  "totalTokenCount": 9
}
}]

Zweite Modellanfrage

In diesem Beispiel werden synthetische Daten verwendet, anstatt die externe API aufzurufen. Es gibt zwei Ergebnisse mit jeweils zwei Parametern (name und address):

  1. name: AMC Mountain View 16, address: 2000 W El Camino Real, Mountain View, CA 94040
  2. name: Regal Edwards 14, address: 245 Castro St, Mountain View, CA 94040

Ersetzen Sie my-project durch den Namen des Google Cloud-Projekts.

Zweite Modellanfrage

PROJECT_ID=my-project
MODEL_ID=gemini-1.0-pro
API=streamGenerateContent
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-autopush-aiplatform.sandbox.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": [{
  "role": "user",
  "parts": [{
    "text": "Which theaters in Mountain View show the Barbie movie?"
  }]
}, {
  "role": "model",
  "parts": [{
    "functionCall": {
      "name": "find_theaters",
      "args": {
        "location": "Mountain View, CA",
        "movie": "Barbie"
      }
    }
  }]
}, {
  "parts": [{
    "functionResponse": {
      "name": "find_theaters",
      "response": {
        "name": "find_theaters",
        "content": {
          "movie": "Barbie",
          "theaters": [{
            "name": "AMC Mountain View 16",
            "address": "2000 W El Camino Real, Mountain View, CA 94040"
          }, {
            "name": "Regal Edwards 14",
            "address": "245 Castro St, Mountain View, CA 94040"
          }]
        }
      }
    }
  }]
}],
"tools": [{
  "functionDeclarations": [{
    "name": "find_movies",
    "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
    "parameters": {
      "type": "OBJECT",
      "properties": {
        "location": {
          "type": "STRING",
          "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
        },
        "description": {
          "type": "STRING",
          "description": "Any kind of description including category or genre, title words, attributes, etc."
        }
      },
      "required": ["description"]
    }
  }, {
    "name": "find_theaters",
    "description": "find theaters based on location and optionally movie title which are is currently playing in theaters",
    "parameters": {
      "type": "OBJECT",
      "properties": {
        "location": {
          "type": "STRING",
          "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
        },
        "movie": {
          "type": "STRING",
          "description": "Any movie title"
        }
      },
      "required": ["location"]
    }
  }, {
    "name": "get_showtimes",
    "description": "Find the start times for movies playing in a specific theater",
    "parameters": {
      "type": "OBJECT",
      "properties": {
        "location": {
          "type": "STRING",
          "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
        },
        "movie": {
          "type": "STRING",
          "description": "Any movie title"
        },
        "theater": {
          "type": "STRING",
          "description": "Name of the theater"
        },
        "date": {
          "type": "STRING",
          "description": "Date for requested showtime"
        }
      },
      "required": ["location", "movie", "theater", "date"]
    }
  }]
}]
}'

Die Antwort des Modells sieht in etwa so aus:

Antwort auf die zweite Modellanfrage

{
"candidates": [
  {
    "content": {
      "parts": [
        {
          "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
        }
      ]
    }
  }
],
"usageMetadata": {
  "promptTokenCount": 9,
  "candidatesTokenCount": 27,
  "totalTokenCount": 36
}
}

Chatbeispiele

Python

Dieses Beispiel zeigt ein Chatszenario mit zwei Funktionen und zwei aufeinanderfolgenden Eingabeaufforderungen. Es verwendet die Klasse GenerativeModel und ihre Methoden. Weitere Informationen zur Verwendung des Vertex AI SDK für Python mit multimodalen Modellen finden Sie unter Einführung in multimodale Klassen in Vertex AI SDK für Python.

Informationen zum Installieren oder Aktualisieren von Python finden Sie unter Vertex AI SDK für Python installieren. Weitere Informationen finden Sie in der Referenzdokumentation zur Python API.

import vertexai
from vertexai.generative_models import (
    FunctionDeclaration,
    GenerationConfig,
    GenerativeModel,
    Part,
    Tool,
)

def generate_function_call_chat(project_id: str, location: str) -> tuple:
    prompts = []
    summaries = []

    # Initialize Vertex AI
    vertexai.init(project=project_id, location=location)

    # Specify a function declaration and parameters for an API request
    get_product_info_func = FunctionDeclaration(
        name="get_product_sku",
        description="Get the SKU for a product",
        # Function parameters are specified in OpenAPI JSON schema format
        parameters={
            "type": "object",
            "properties": {
                "product_name": {"type": "string", "description": "Product name"}
            },
        },
    )

    # Specify another function declaration and parameters for an API request
    get_store_location_func = FunctionDeclaration(
        name="get_store_location",
        description="Get the location of the closest store",
        # Function parameters are specified in OpenAPI JSON schema format
        parameters={
            "type": "object",
            "properties": {"location": {"type": "string", "description": "Location"}},
        },
    )

    # Define a tool that includes the above functions
    retail_tool = Tool(
        function_declarations=[
            get_product_info_func,
            get_store_location_func,
        ],
    )

    # Initialize Gemini model
    model = GenerativeModel(
        "gemini-1.0-pro-001",
        generation_config=GenerationConfig(temperature=0),
        tools=[retail_tool],
    )

    # Start a chat session
    chat = model.start_chat()

    # Send a prompt for the first conversation turn that should invoke the get_product_sku function
    prompt = "Do you have the Pixel 8 Pro in stock?"
    response = chat.send_message(prompt)
    prompts.append(prompt)

    # Check the function name that the model responded with, and make an API call to an external system
    if response.candidates[0].content.parts[0].function_call.name == "get_product_sku":
        # Extract the arguments to use in your API call
        product_name = (
            response.candidates[0].content.parts[0].function_call.args["product_name"]
        )
        product_name

        # Here you can use your preferred method to make an API request to retrieve the product SKU, as in:
        # api_response = requests.post(product_api_url, data={"product_name": product_name})

        # In this example, we'll use synthetic data to simulate a response payload from an external API
        api_response = {"sku": "GA04834-US", "in_stock": "yes"}

    # Return the API response to Gemini so it can generate a model response or request another function call
    response = chat.send_message(
        Part.from_function_response(
            name="get_product_sku",
            response={
                "content": api_response,
            },
        ),
    )

    # Extract the text from the summary response
    summary = response.candidates[0].content.parts[0].text
    summaries.append(summary)

    # Send a prompt for the second conversation turn that should invoke the get_store_location function
    prompt = "Is there a store in Mountain View, CA that I can visit to try it out?"
    response = chat.send_message(prompt)
    prompts.append(prompt)

    # Check the function name that the model responded with, and make an API call to an external system
    if (
        response.candidates[0].content.parts[0].function_call.name
        == "get_store_location"
    ):
        # Extract the arguments to use in your API call
        location = (
            response.candidates[0].content.parts[0].function_call.args["location"]
        )
        location

        # Here you can use your preferred method to make an API request to retrieve store location closest to the user, as in:
        # api_response = requests.post(store_api_url, data={"location": location})

        # In this example, we'll use synthetic data to simulate a response payload from an external API
        api_response = {"store": "2000 N Shoreline Blvd, Mountain View, CA 94043, US"}

    # Return the API response to Gemini so it can generate a model response or request another function call
    response = chat.send_message(
        Part.from_function_response(
            name="get_store_location",
            response={
                "content": api_response,
            },
        ),
    )

    # Extract the text from the summary response
    summary = response.candidates[0].content.parts[0].text
    summaries.append(summary)

    return prompts, summaries

Node.js

Bevor Sie dieses Beispiel anwenden, folgen Sie den Node.js-Einrichtungsschritten in der Vertex AI-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Vertex AI Node.js API.

Richten Sie zur Authentifizierung bei Vertex AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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 functionCallingStreamChat(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.0-pro'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.preview.getGenerativeModel({
    model: model,
  });

  // Create a chat session and pass your function declarations
  const chat = generativeModel.startChat({
    tools: functionDeclarations,
  });

  const chatInput1 = 'What is the weather in Boston?';

  // This should include a functionCall response from the model
  const result1 = await chat.sendMessageStream(chatInput1);
  for await (const item of result1.stream) {
    console.log(item.candidates[0]);
  }
  await result1.response;

  // Send a follow up message with a FunctionResponse
  const result2 = await chat.sendMessageStream(functionResponseParts);
  for await (const item of result2.stream) {
    console.log(item.candidates[0]);
  }

  // This should include a text response from the model using the response content
  // provided above
  const response2 = await result2.response;
  console.log(response2.candidates[0].content.parts[0].text);
}

Java

Bevor Sie dieses Beispiel anwenden, folgen Sie den Java-Einrichtungsschritten in der Vertex AI-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Vertex AI Java API.

Richten Sie zur Authentifizierung bei Vertex AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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-1.0-pro";

    String promptText = "What's the weather like in Paris?";

    whatsTheWeatherLike(projectId, location, modelName, promptText);
  }

  public static String whatsTheWeatherLike(String projectId, String location,
                                           String modelName, String promptText)
      throws IOException {

    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 =
          GenerativeModel.newBuilder()
              .setModelName(modelName)
              .setVertexAi(vertexAI)
              .setTools(Arrays.asList(tool))
              .build();
      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;
    }
  }
}

Go

Bevor Sie dieses Beispiel anwenden, folgen Sie den Go-Einrichtungsschritten in der Vertex AI-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Vertex AI Go API.

Richten Sie zur Authentifizierung bei Vertex AI Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"

	"cloud.google.com/go/vertexai/genai"
)

// functionCalls opens a chat session and sends 2 messages to the model:
// - first, to convert a text into a structured function call request
// - second, to convert a structured function call response into natural language
func functionCalls(w io.Writer, prompt, projectID, location, modelName string) error {
	// prompt := "What's the weather like in Paris?"
	// location := "us-central1"
	// modelName := "gemini-1.0-pro"
	ctx := context.Background()
	client, err := genai.NewClient(ctx, projectID, location)
	if err != nil {
		return fmt.Errorf("unable to create client: %v", err)
	}
	defer client.Close()

	model := client.GenerativeModel(modelName)

	// Build an OpenAPI schema, in memory
	params := &genai.Schema{
		Type: genai.TypeObject,
		Properties: map[string]*genai.Schema{
			"location": {
				Type:        genai.TypeString,
				Description: "location",
			},
		},
	}
	fundecl := &genai.FunctionDeclaration{
		Name:        "getCurrentWeather",
		Description: "Get the current weather in a given location",
		Parameters:  params,
	}
	model.Tools = []*genai.Tool{
		{FunctionDeclarations: []*genai.FunctionDeclaration{fundecl}},
	}

	chat := model.StartChat()

	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 `getCurrentWeather`
	// with a value for the argument `location`.
	jsondata, err := json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "", "  ")
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}
	fmt.Fprintf(w, "function call generated by the model:\n%s\n\n", string(jsondata))

	// Create a function call response, to simulate the result of a call to a
	// real service
	funresp := &genai.FunctionResponse{
		Name: "getCurrentWeather",
		Response: map[string]any{
			"currentWeather": "sunny",
		},
	}
	jsondata, err = json.MarshalIndent(funresp, "", "  ")
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}
	fmt.Fprintf(w, "function call response sent to the model:\n%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], "", "  ")
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}
	fmt.Fprintf(w, "Answer generated by the model:\n%s\n", string(jsondata))

	return nil
}