Große Sprachmodelle (LLMs, Large Language Models) eignen sich hervorragend für die Lösung vieler Probleme. Sie sind jedoch durch folgende Einschränkungen eingeschränkt:
- Nach dem Training werden sie eingefroren, was zu veraltetem Wissen führt.
- Sie können keine externen Daten abfragen oder ändern.
Mit Funktionsaufrufen können diese Mängel behoben werden. Der Funktionsaufruf wird manchmal auch als Tool-Nutzung bezeichnet, da das Modell externe Tools wie APIs und Funktionen verwenden kann.
Wenn Sie einen Prompt an das LLM senden, stellen Sie dem Modell auch eine Reihe von Tools zur Verfügung, mit denen es auf den Prompt des Nutzers reagieren kann. Sie können beispielsweise eine Funktion get_weather angeben, die einen Standortparameter annimmt und Informationen zu den Wetterbedingungen an diesem Standort zurückgibt.
Bei der Verarbeitung eines Prompts kann das Modell bestimmte Aufgaben zur Datenverarbeitung an die von Ihnen angegebenen Funktionen delegieren. Die Funktionen werden vom Modell nicht direkt aufgerufen. Stattdessen liefert das Modell eine strukturierte Datenausgabe, die die aufzurufende Funktion und die zu verwendenden Parameterwerte enthält. Für einen Prompt What is the weather like in Boston? kann das Modell beispielsweise die Verarbeitung an die Funktion get_weather delegieren und den Standortparameterwert Boston, MA angeben.
Sie können die strukturierte Ausgabe des Modells verwenden, um externe APIs aufzurufen. Sie können beispielsweise eine Verbindung zu einer Wetterdienst-API herstellen, den Standort Boston, MA angeben und Informationen zu Temperatur, Bewölkung und Wind erhalten.
Sie können dann die API-Ausgabe für das Modell zurückgeben, damit es die Antwort auf den Prompt finalisieren kann. Im Beispiel für das Wetter könnte das Modell die folgende Antwort liefern: It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies.
Unterstützte Modelle
Die folgenden Modelle unterstützen Funktionsaufrufe:
| Modell | Version | Einführungsphase für Funktionsaufrufe | Unterstützung für parallele Funktionsaufrufe | Unterstützung für erzwungene Funktionsaufrufe |
|---|---|---|---|---|
| Gemini 1.0 Pro | all versions |
General Availability | Nein | Nein |
| Gemini 1.5 Flash | all versions |
General Availability | Ja | Ja |
| Gemini 1.5 Pro, | all versions |
General Availability | Ja | Ja |
Anwendungsfälle von Funktionsaufrufen
Sie können Funktionsaufrufe für die folgenden Aufgaben verwenden:
| Anwendungsfall | Beispielbeschreibung | Beispiellink |
|---|---|---|
| In externe APIs einbinden | Wetterinformationen mit einer meteorologischen API abrufen | Notebook-Anleitung |
| Adressen in Längen- und Breitengradangaben umwandeln | Notebook-Anleitung | |
| Währungen mit einer Währungsumrechnungs-API umrechnen | Codelab | |
| Erweiterte Chatbots erstellen | Kundenfragen zu Produkten und Dienstleistungen beantworten | Notebook-Anleitung |
| Einen Assistenten erstellen, der Finanz- und Nachrichtenfragen zu Unternehmen beantwortet | Notebook-Anleitung | |
| Funktionsaufrufe strukturieren und steuern | Strukturierte Entitäten aus Rohprotokolldaten extrahieren | Notebook-Anleitung |
| Einzelne oder mehrere Parameter aus der Nutzereingabe extrahieren | Notebook-Anleitung | |
| Listen und verschachtelte Datenstrukturen in Funktionsaufrufen verarbeiten | Notebook-Anleitung | |
| Verhalten von Funktionsaufrufen steuern | Parallele Funktionsaufrufe und ‑antworten verarbeiten | Notebook-Anleitung |
| Festlegen, wann und welche Funktionen das Modell aufrufen kann | Notebook-Anleitung | |
| Datenbanken mit natürlicher Sprache abfragen | Fragen in natürlicher Sprache in SQL-Abfragen für BigQuery umwandeln | Beispiel-App |
| Multimodale Funktionsaufrufe | Bilder, Videos, Audioinhalte und PDFs als Eingabe verwenden, um Funktionsaufrufe auszulösen | Notebook-Anleitung |
Hier sind einige weitere Anwendungsfälle:
Sprachbefehle interpretieren: Erstellen Sie Funktionen, die bestimmten Aufgaben im Fahrzeug entsprechen. Sie können beispielsweise Funktionen erstellen, mit denen das Radio eingeschaltet oder die Klimaanlage aktiviert wird. Senden Sie Audiodateien mit den Sprachbefehlen des Nutzers an das Modell und bitten Sie es, die Audiodaten in Text umzuwandeln und die Funktion zu identifizieren, die der Nutzer aufrufen möchte.
Workflows anhand von Umgebungstriggern automatisieren: Funktionen zur Darstellung von Prozessen erstellen, die automatisiert werden können. Stellen Sie dem Modell Daten von Umgebungssensoren bereit und bitten Sie es, die Daten zu parsen und zu verarbeiten, um festzustellen, ob einer oder mehrere Workflows aktiviert werden sollen. Ein Modell könnte zum Beispiel Temperaturdaten in einem Lager verarbeiten und eine Sprinklerfunktion aktivieren.
Zuweisung von Support-Tickets automatisieren: Stellen Sie dem Modell Support-Tickets, Protokolle und kontextsensitive Regeln zur Verfügung. Das Modell soll alle diese Informationen verarbeiten, um zu bestimmen, wem das Ticket zugewiesen werden soll. Rufen Sie eine Funktion auf, um das Ticket der vom Modell vorgeschlagenen Person zuzuweisen.
Informationen aus einer Wissensdatenbank abrufen: Erstellen Sie Funktionen, die akademische Artikel zu einem bestimmten Thema abrufen und zusammenfassen. Befähigen Sie das Modell, Fragen zu akademischen Themen zu beantworten und die Antworten mit Zitaten zu versehen.
Anwendung zum Aufrufen von Funktionen erstellen
Damit Nutzer mit dem Modell interagieren und Funktionsaufrufe verwenden können, müssen Sie Code erstellen, der die folgenden Aufgaben ausführt:
- Richten Sie die Umgebung ein.
- Definieren und beschreiben Sie mithilfe von Funktionsdeklarationen eine Reihe verfügbarer Funktionen.
- Senden Sie den Prompt eines Nutzers und die Funktionsdeklarationen an das Modell.
- Rufen Sie eine Funktion auf, wobei Sie die vom Modell ausgegebenen strukturierten Daten verwenden.
- Funktionsausgabe für das Modell übergeben.
Sie können eine Anwendung erstellen, die all diese Aufgaben verwaltet. Diese kann ein Text-Chatbot, ein Sprach-Agent, ein automatisierter Workflow oder ein anderes Programm sein.
Sie können Funktionsaufrufe verwenden, um eine einzelne Textantwort zu generieren oder eine Chatsitzung zu unterstützen. Ad-hoc-Textantworten sind nützlich für bestimmte Geschäftsaufgaben, einschließlich der Codegenerierung. Chatsitzungen sind nützlich in Freitextszenarien, in denen Nutzer wahrscheinlich Folgefragen stellen.
Wenn Sie einen Funktionsaufruf verwenden, um eine einzelne Antwort zu generieren, müssen Sie dem Modell den vollständigen Kontext der Interaktion zur Verfügung stellen. Wenn Sie hingegen Funktionsaufrufe im Kontext einer Chatsitzung verwenden, speichert die Sitzung den Kontext für Sie und nimmt ihn in jede Modellanfrage auf. In beiden Fällen speichert Vertex AI den Verlauf der Interaktion auf der Clientseite.
In diesem Leitfaden wird gezeigt, wie Sie mithilfe von Funktionsaufrufen eine einzelne Textantwort generieren können. Ein End-to-End-Beispiel finden Sie unter Textbeispiele. Weitere Informationen zur Verwendung von Funktionsaufrufen zur Unterstützung einer Chatsitzung finden Sie unter Chatbeispiele.
Schritt 1: Umgebung einrichten
Importieren Sie die erforderlichen Module und initialisieren Sie das Modell:
Python
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 = 'your-project-id'
vertexai.init(project=PROJECT_ID, location="us-central1")
# Initialize Gemini model
model = GenerativeModel(model_name="gemini-1.5-flash-002")
Schritt 2: Funktionen deklarieren
Die Anwendung muss eine Reihe von Funktionen deklarieren, die das Modell zur Verarbeitung des Prompts verwenden kann.
Die maximale Anzahl von Funktionsdeklarationen, die mit der Anfrage angegeben werden können, beträgt 128.
Sie müssen Funktionsdeklarationen in einem Schemaformat angeben, 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. Best Practices für Funktionsdeklarationen, einschließlich Tipps für Namen und Beschreibungen, finden Sie unter Best Practices.
Wenn Sie die REST API verwenden, geben Sie das Schema in JSON an. Wenn Sie das Vertex AI SDK für Python verwenden, können Sie das Schema entweder manuell mit einem Python-Wörterbuch oder automatisch mit der Hilfsfunktion from_func angeben.
JSON
{
"contents": ...,
"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"
]
}
}
]
}
]
}
Python-Wörterbuch
Die folgende Funktionsdeklaration verwendet einen einzelnen string-Parameter:
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 JSON schema format
parameters={
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city name of the location for which to get the weather."}
},
},
)
Die folgende Funktionsdeklaration nimmt sowohl Objekt- als auch Arrayparameter an:
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"],
},
)
Python aus Funktion
Im folgenden Codebeispiel wird eine Funktion deklariert, die ein Zahlenarray multipliziert, und from_func wird verwendet, um das FunctionDeclaration-Schema zu generieren.
# Define a function. Could be a local function or you can import the requests library to call an API
def multiply_numbers(numbers):
"""
Calculates the product of all numbers in an array.
Args:
numbers: An array of numbers to be multiplied.
Returns:
The product of all the numbers. If the array is empty, returns 1.
"""
if not numbers: # Handle empty array
return 1
product = 1
for num in numbers:
product *= num
return product
multiply_number_func = FunctionDeclaration.from_func(multiply_numbers)
'''
multiply_number_func contains the following schema:
name: "multiply_numbers"
description: "Calculates the product of all numbers in an array."
parameters {
type_: OBJECT
properties {
key: "numbers"
value {
description: "An array of numbers to be multiplied."
title: "Numbers"
}
}
required: "numbers"
description: "Calculates the product of all numbers in an array."
title: "multiply_numbers"
}
'''
Schritt 3: Prompt 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. Um zu konfigurieren, wie das Modell Ergebnisse generiert, kann die Anwendung das Modell mit einer Generierungskonfiguration bereitstellen. Um zu konfigurieren, wie das Modell die Funktionsdeklarationen verwendet, kann die Anwendung das Modell mit einer Toolkonfiguration bereitstellen.
Nutzeraufforderung definieren
Das folgende Beispiel zeigt einen Nutzer-Prompt: "Wie ist das Wetter in Boston?"
Im Folgenden finden Sie ein Beispiel für die Definition der Nutzeraufforderung:
Python
# 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?"),
],
)
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 bei 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 vielfältigere 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 einige Einschränkungen dafür festlegen, wie das Modell die von Ihnen bereitgestellten Funktionsdeklarationen verwenden soll. 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" oder "Funktionsaufruf mit gesteuerter Generierung"). Sie können dem Modell auch eine vollständige Funktionsdeklaration zur Verfügung stellen, die Antworten aber 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 |
|---|---|
AUTO |
Das Standardverhalten des Modells. Das Modell entscheidet, ob ein Funktionsaufruf oder eine Antwort in natürlicher Sprache vorhergesagt werden soll. |
ANY |
Das Modell ist darauf beschränkt, immer einen Funktionsaufruf vorherzusagen. Wenn allowed_function_names nicht angegeben ist, wählt das Modell eine der verfügbaren Funktionsdeklarationen aus. Wenn allowed_function_names angegeben wird, wählt das Modell eine der zulässigen Funktionen aus. |
NONE |
Das Modell darf keine Funktionsaufrufe vorhersagen. Dieses Verhalten entspricht einer Modellanfrage ohne zugehörige Funktionsdeklarationen. |
Eine Liste der Modelle, die den Modus ANY („erzwungener Funktionsaufruf“) unterstützen, finden Sie unter Unterstützte Modelle.
Weitere Informationen finden Sie unter Function Calling API.
Prompt und Funktionsdeklarationen senden
Das folgende Beispiel zeigt, wie Sie den Prompt und die Funktionsdeklarationen an das Modell senden und das Modell auf die Vorhersage von get_current_weather-Funktionsaufrufen beschränken können.
Python
# Define a tool that includes some of the functions that we declared earlier
tool = Tool(
function_declarations=[get_current_weather_func, extract_sale_records_func, multiply_number_func],
)
# 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=GenerationConfig(temperature=0),
tools=[tool],
tool_config=ToolConfig(
function_calling_config=ToolConfig.FunctionCallingConfig(
# ANY mode forces the model to predict only function calls
mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
# Allowed function calls to predict when the mode is ANY. If empty, any of
# the provided function calls will be predicted.
allowed_function_names=["get_current_weather"],
)
)
)
Wenn das Modell feststellt, dass die Ausgabe einer bestimmten Funktion erforderlich ist, 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 vor, die Funktion get_current_weather mit dem Parameter Boston, MA aufzurufen.
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. Weitere Informationen finden Sie unter Beispiel für parallele Funktionsaufrufe.
Schritt 4: Externe API aufrufen
Wenn die Anwendung einen Funktionsnamen und Parameterwerte vom Modell empfängt, muss sie eine Verbindung zu einer externen API herstellen und die Funktion aufrufen.
Im folgenden Beispiel werden synthetische Daten verwendet, um eine Antwortnutzlast aus einer externen API zu simulieren:
Python
# Check the function name that the model responded with, and make an API call to an external system
if (response.candidates[0].function_calls[0].name == "get_current_weather"):
# Extract the arguments to use in your API call
location = response.candidates[0].function_calls[0].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 den API-Aufruf finden Sie unter Best Practices – API-Aufruf.
Schritt 5: Ausgabe der Funktion an das Modell übergeben
Nachdem eine Anwendung eine Antwort von einer externen API erhalten hat, muss sie diese Antwort an das Modell weitergeben. Im folgenden Beispiel wird gezeigt, wie das mit Python funktioniert:
Python
response = model.generate_content(
[
user_prompt_content, # User prompt
response.candidates[0].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.text
Wenn das Modell mehrere parallele Funktionsaufrufe vorgeschlagen hat, muss die Anwendung alle Antworten an das Modell zurückgeben. Weitere Informationen finden Sie unter Beispiel für parallele Funktionsaufrufe.
Das Modell kann feststellen, dass die Ausgabe einer anderen Funktion zur Beantwortung des Prompts erforderlich ist. In diesem Fall enthält die Antwort, die die Anwendung vom Modell empfängt, einen anderen Funktionsnamen und einen anderen Satz von Parameterwerten.
Wenn das Modell feststellt, dass die API-Antwort ausreicht, um auf den Prompt des Nutzers zu reagieren, erstellt es eine Antwort in natürlicher Sprache und gibt sie an die Anwendung zurück. In diesem Fall muss die Anwendung die Antwort an den Nutzer zurückgeben. Hier ist ein Beispiel für eine Antwort:
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.
Beispiele für Funktionsaufrufe
Textbeispiele
Mit dem Funktionsaufruf können Sie eine einzelne Textantwort generieren. Ad-hoc-Textantworten sind nützlich für bestimmte Geschäftsaufgaben, einschließlich der Codegenerierung.
Wenn Sie einen Funktionsaufruf verwenden, um eine einzelne Antwort zu generieren, müssen Sie dem Modell den vollständigen Kontext der Interaktion zur Verfügung stellen. Vertex AI speichert den Verlauf der Interaktion auf der Clientseite.
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.
C#
Dieses Beispiel zeigt ein Textszenario mit einer Funktion und einem Prompt.
C#
Bevor Sie dieses Beispiel anwenden, folgen Sie den C#-Einrichtungsschritten in der Vertex AI-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Informationen finden Sie in der Referenzdokumentation zur Vertex AI C# 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.
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.
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 einen Prompt im Parameter text definieren. In diesem Beispiel wird die folgende Prompt-Definition verwendet: „In welchen Kinos 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_moviessucht Filmtitel, die im Kino gezeigt werden.find_theatressucht Kinos basierend auf dem Standort.get_showtimesermittelt 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):
name:AMC Mountain View 16,address:2000 W El Camino Real, Mountain View, CA 94040name: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
Sie können Funktionsaufrufe verwenden, um eine Chatsitzung zu unterstützen. Chatsitzungen sind nützlich in Freitextszenarien, in denen Nutzer wahrscheinlich Folgefragen stellen.
Wenn Sie Funktionsaufrufe im Kontext einer Chatsitzung verwenden, wird der Kontext für Sie in der Sitzung gespeichert und in jede Modellanfrage eingefügt. Vertex AI speichert den Verlauf der Interaktion auf der Clientseite.
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.
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.
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.
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.
Beispiel für parallele Funktionsaufrufe
Für Prompts wie „Wetterdetails in Neu-Delhi und San Francisco?“ kann das Modell mehrere parallele Funktionsaufrufe vorschlagen. Eine Liste der Modelle, die den parallelen Funktionsaufruf unterstützen, finden Sie unter Unterstützte Modelle.
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 Aufrufe der Funktion get_current_weather vor: einen mit dem Parameter New Delhi und einen mit dem Parameter San Francisco.
Weitere Informationen zu den Parametern der Modellanfrage finden Sie unter Gemini API.
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "New Delhi"
}
}
},
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "San Francisco"
}
}
}
]
},
...
}
],
...
}
Der folgende Befehl zeigt, wie Sie die Funktion an das Modell übergeben. Ersetzen Sie my-project durch den Namen des Google Cloud-Projekts.
Modellanfrage
PROJECT_ID=my-project
MODEL_ID=gemini-1.5-pro-002
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",
...
}
]
...
}
]
Python
Best Practices für Funktionsaufrufe
Funktionsname
Der Funktionsname muss mit einem Buchstaben oder einem Unterstrich beginnen und darf nur die Zeichen a–z, A–Z, 0–9, Unterstriche, Punkte oder Bindestriche enthalten. Die maximale Länge beträgt 64 Zeichen.
Funktionsbeschreibung
Verfassen 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 schlechte Funktionsbeschreibung:
book flight ticket
Funktionsparameter
Funktionsparameter und verschachtelte Attributnamen müssen mit einem Buchstaben oder einem Unterstrich beginnen und dürfen nur die Zeichen a–z, A–Z, 0–9 oder Unterstriche enthalten. Die maximale Länge beträgt 64 Zeichen. Verwenden Sie in den Namen von Funktionsparametern und verschachtelten Attributen keine Punkte (.), Bindestriche (-) oder Leerzeichen.
Verwenden Sie stattdessen Unterstriche (_) oder andere Zeichen.
Beschreibungen
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:
- Das folgende Beispiel ist 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 ist ein schlechtes Beispiel für eine
departure-Parameterbeschreibung:the departure airport
Typen
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, legen Sie den Typ auf integer statt auf number fest.
Systemanweisungen
Wenn Sie Funktionen mit Datums-, Uhrzeit- oder Standortparametern verwenden, geben Sie in der Systemanweisung das aktuelle Datum, die aktuelle Uhrzeit oder relevante Standortinformationen (z. B. Stadt und Land) an. So hat das Modell den erforderlichen Kontext, um die Anfrage korrekt zu verarbeiten, auch wenn der Prompt des Nutzers keine Details enthält.
Nutzer-Prompt
Für optimale Ergebnisse fügen Sie dem Nutzer-Prompt die folgenden Details hinzu:
- 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 Halluzinationen werden reduziert.
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 den Nutzerprompt 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.
Nächste Schritte
Weitere Informationen finden Sie in der API-Referenz für Funktionsaufrufe.