Funktionsaufruf

Ü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 dabei nicht aufgerufen. Stattdessen wird eine strukturierte Datenausgabe bereitgestellt, die den Namen einer ausgewählten Funktion und die Argumente enthält, die das Modell zum Aufruf der 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 finalisieren 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.

Modell Version Startphase für Funktionsaufrufe Unterstützung für parallelen Funktionsaufruf Unterstützung für erzwungene Funktionsaufrufe
Gemini 1.0 Pro gemini-1.0-pro-001 General Availability Nein Nein
Gemini 1.0 Pro gemini-1.0-pro-002 General Availability Nein Nein
Gemini 1.5 Flash gemini-1.5-flash-001 General Availability Ja Nein
Gemini 1.5 Pro gemini-1.5-pro-001 General Availability Ja Ja

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.

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

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. In diesem Fall sind die Antworten auf einen bestimmten Prompt größtenteils deterministisch, aber eine gewisse Variation ist dennoch möglich. Weitere Informationen finden Sie unter Gemini API.

Zum Festlegen dieses Parameters senden Sie eine Generierungskonfiguration (generation_config) zusammen mit dem Prompt und den Funktionsdeklarationen. Sie können den Parameter temperature während einer Chatunterhaltung mit der Vertex AI API und einem aktualisierten generation_config aktualisieren. Ein Beispiel für das Festlegen des temperature-Parameters siehe So reichen Sie den Prompt und die Funktionsdeklarationen ein.

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. Anstatt dem Modell beispielsweise zu erlauben, zwischen einer Antwort in natürlicher Sprache und einem Funktionsaufruf zu wählen, können Sie erzwingen, dass nur Funktionsaufrufe vorhergesagt werden ("erzwungener Funktionsaufruf"). 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 ANY-Modus der Toolkonfiguration ("erzwungener Funktionsaufruf") 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 auf den Nutzer-Prompt „Wie ist das Wetter in Boston?“. 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"
            }
          }
        }
      }
    }
  }
  ...
}

Für Prompts wie „Wetterdetails in Neu-Delhi und San Francisco?“ kann das Modell mehrere parallele Funktionsaufrufe vorschlagen. Parallele Funktionsaufrufe sind ein Vorschaufeature. Es wird von den Modellen Gemini 1.5 Pro und Gemini 1.5 Flash unterstützt. Weitere Informationen finden Sie unter Beispiel für parallele Funktionsaufrufe.

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 mehrere parallele Funktionsaufrufe vorgeschlagen hat, muss die Anwendung alle Antworten an das Modell zurückgeben. Parallele Funktionsaufrufe sind ein Vorschaufeature. Es wird von den Modellen Gemini 1.5 Pro und Gemini 1.5 Flash unterstützt. Weitere Informationen finden Sie unter Beispiel für parallele Funktionsaufrufe.

Die Modelle gemini-1.0-pro-001 und gemini-1.0-pro-002 können feststellen, dass die Ausgabe einer anderen Funktion zum Beantworten der Abfrage erforderlich ist. In diesem Fall enthält die Antwort, die die Anwendung vom Modell empfängt, einen anderen Funktionsnamen und einen weiteren Satz von Parameterwerten.

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.

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 Ihr bevorzugtes Format oder Ihre bevorzugte Werte. 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 Wertesatz 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 Funktionsaufrufe basieren auf der Anzahl der Zeichen in den Textein- 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 vorheriger Unterhaltungsrunden. Vertex AI kürzt den Verlauf der Unterhaltung auf 32.000 Zeichen.

Die 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 unter Chatbeispiele. Ein Beispiel für den parallelen Funktionsaufruf finden Sie unter Beispiel für parallele Funktionsaufrufe.

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

# Initialize Vertex AI
# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
vertexai.init(project=project_id, location="us-central1")

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

# 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("What is the weather like in Boston?"),
    ],
)

# Specify a function declaration and parameters for an API request
function_name = "get_current_weather"
get_current_weather_func = FunctionDeclaration(
    name=function_name,
    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],
)

# 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],
)
function_call = response.candidates[0].function_calls[0]
print(function_call)

# Check the function name that the model responded with, and make an API call to an external system
if function_call.name == function_name:
    # Extract the arguments to use in your API call
    location = function_call.args["location"]  # noqa: F841

    # 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.candidates[0].content,  # Function call response
        Content(
            parts=[
                Part.from_function_response(
                    name=function_name,
                    response={
                        "content": api_response,  # Return the API response to Gemini
                    },
                ),
            ],
        ),
    ],
    tools=[weather_tool],
)

# Get the model response
print(response.text)

Node.js

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

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

# Initialize Vertex AI
# project_id = "PROJECT_ID"
# TODO(developer): Update and un-comment below lines
vertexai.init(project=project_id, location="us-central1")

# Specify a function declaration and parameters for an API request
get_product_sku = "get_product_sku"
get_product_sku_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_sku_func,
        get_store_location_func,
    ],
)

# Initialize Gemini model
model = GenerativeModel(
    model_name="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
response = chat.send_message("Do you have the Pixel 8 Pro in stock?")

function_call = response.candidates[0].function_calls[0]
print(function_call)

# Check the function name that the model responded with, and make an API call to an external system
if function_call.name == get_product_sku:
    # Extract the arguments to use in your API call
    product_name = function_call.args["product_name"]  # noqa: F841

    # 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 model response
print(response.text)

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

function_call = response.candidates[0].function_calls[0]
print(function_call)

# Check the function name that the model responded with, and make an API call to an external system
if function_call.name == "get_store_location":
    # Extract the arguments to use in your API call
    location = function_call.args["location"]  # noqa: F841

    # 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 model response
print(response.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-002";

    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 = 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;
    }
  }
}

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"
)

// functionCallsChat opens a chat session and sends 4 messages to the model:
// - convert a first text question into a structured function call request
// - convert the first structured function call response into natural language
// - convert a second text question into a structured function call request
// - convert the second structured function call response into natural language
func functionCallsChat(w io.Writer, projectID, location, modelName string) error {
	// location := "us-central1"
	// modelName := "gemini-1.0-pro-002"
	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
	paramsProduct := &genai.Schema{
		Type: genai.TypeObject,
		Properties: map[string]*genai.Schema{
			"productName": {
				Type:        genai.TypeString,
				Description: "Product name",
			},
		},
	}
	fundeclProductInfo := &genai.FunctionDeclaration{
		Name:        "getProductSku",
		Description: "Get the SKU for a product",
		Parameters:  paramsProduct,
	}
	paramsStore := &genai.Schema{
		Type: genai.TypeObject,
		Properties: map[string]*genai.Schema{
			"location": {
				Type:        genai.TypeString,
				Description: "Location",
			},
		},
	}
	fundeclStoreLocation := &genai.FunctionDeclaration{
		Name:        "getStoreLocation",
		Description: "Get the location of the closest store",
		Parameters:  paramsStore,
	}
	model.Tools = []*genai.Tool{
		{FunctionDeclarations: []*genai.FunctionDeclaration{
			fundeclProductInfo,
			fundeclStoreLocation,
		}},
	}
	model.SetTemperature(0.0)

	chat := model.StartChat()

	// Send a prompt for the first conversation turn that should invoke the getProductSku function
	prompt := "Do you have the Pixel 8 Pro in stock?"
	fmt.Fprintf(w, "Question: %s\n", prompt)
	resp, err := chat.SendMessage(ctx, genai.Text(prompt))
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has returned a function call to the declared function `getProductSku`
	// with a value for the argument `productName`.
	jsondata, err := json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}
	fmt.Fprintf(w, "function call generated by the model:\n\t%s\n", string(jsondata))

	// Create a function call response, to simulate the result of a call to a
	// real service
	funresp := &genai.FunctionResponse{
		Name: "getProductSku",
		Response: map[string]any{
			"sku":      "GA04834-US",
			"in_stock": "yes",
		},
	}
	jsondata, err = json.MarshalIndent(funresp, "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}
	fmt.Fprintf(w, "function call response sent to the model:\n\t%s\n\n", string(jsondata))

	// And provide the function call response to the model
	resp, err = chat.SendMessage(ctx, funresp)
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has taken the function call response as input, and has
	// reformulated the response to the user.
	jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}
	fmt.Fprintf(w, "Answer generated by the model:\n\t%s\n\n", string(jsondata))

	// Send a prompt for the second conversation turn that should invoke the getStoreLocation function
	prompt2 := "Is there a store in Mountain View, CA that I can visit to try it out?"
	fmt.Fprintf(w, "Question: %s\n", prompt)

	resp, err = chat.SendMessage(ctx, genai.Text(prompt2))
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has returned a function call to the declared function `getStoreLocation`
	// with a value for the argument `store`.
	jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}
	fmt.Fprintf(w, "function call generated by the model:\n\t%s\n", string(jsondata))

	// Create a function call response, to simulate the result of a call to a
	// real service
	funresp = &genai.FunctionResponse{
		Name: "getStoreLocation",
		Response: map[string]any{
			"store": "2000 N Shoreline Blvd, Mountain View, CA 94043, US",
		},
	}
	jsondata, err = json.MarshalIndent(funresp, "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}
	fmt.Fprintf(w, "function call response sent to the model:\n\t%s\n\n", string(jsondata))

	// And provide the function call response to the model
	resp, err = chat.SendMessage(ctx, funresp)
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has taken the function call response as input, and has
	// reformulated the response to the user.
	jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.Marshal: %w", err)
	}
	fmt.Fprintf(w, "Answer generated by the model:\n\t%s\n\n", string(jsondata))
	return nil
}

Beispiel für parallelen Funktionsaufruf

REST

Dieses Beispiel zeigt ein Szenario mit einer get_current_weather-Funktion. Die Eingabeaufforderung lautet „Wetterdetails für Neu-Delhi und San Francisco?“. Das Modell schlägt zwei parallele get_current_weather-Funktionsaufrufe vor: einen mit dem Parameter New Delhi und einen mit dem Parameter San Francisco. Der parallele Funktionsaufruf ist eine Vorschaufunktion. Es wird von den Modellen Gemini 1.5 Pro und Gemini 1.5 Flash unterstützt.

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

candidates {
content {
  role: "model"
  parts: [
    {
      function_call {
        name: "get_current_weather"
        args {
          fields {
            key: "location"
            value {
              string_value: "New Delhi"
            }
          }
        }
      }
    },
    {
      function_call {
        name: "get_current_weather"
        args {
          fields {
            key: "location"
            value {
              string_value: "San Francisco"
            }
          }
        }
      }
    }
  ]
}
...
}

Der folgende Befehl zeigt, wie Sie dem Modell die Funktionsausgabe bereitstellen. Ersetzen Sie my-project durch den Namen des Google Cloud-Projekts.

Modellanfrage

PROJECT_ID=my-project
MODEL_ID=gemini-1.5-pro-001
VERSION="v1"
LOCATION="us-central1"
ENDPOINT=${LOCATION}-aiplatform.googleapis.com
API="generateContent"
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://${ENDPOINT}/${VERSION}/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": [
    {
        "role": "user",
        "parts": {
            "text": "What is difference in temperature in New Delhi and San Francisco?"
        }
    },
    {
        "role": "model",
        "parts": [
            {
                "functionCall": {
                    "name": "get_current_weather",
                    "args": {
                        "location": "New Delhi"
                    }
                }
            },
            {
                "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 and state, e.g. San Francisco, CA or a zip code e.g. 95616"
                        }
                    },
                    "required": [
                        "location"
                    ]
                }
            }
        ]
    }
]
}'

Die vom Modell erstellte Antwort in natürlicher Sprache sieht in etwa so aus:

Modellantwort

[
{
    "candidates": [
        {
            "content": {
                "parts": [
                    {
                        "text": "The temperature in New Delhi is 30.5C and the temperature in San Francisco is 20C. The difference is 10.5C. \n"
                    }
                ]
            },
            "finishReason": "STOP",
            ...
        }
    ]
    ...
}
]