1. Übersicht
Was sind Funktionsaufrufe in Gemini?
Die Vertex AI Gemini API ist eine Reihe von generativen KI-Modellen, die von Google DeepMind entwickelt wurden und auf multimodale Anwendungsfälle ausgelegt sind. Funktionsaufrufe sind eine Funktion von Gemini-Modellen, die es Entwicklern erleichtert, strukturierte Datenausgaben von generativen Modellen zu erhalten.
Entwickler können diese Ausgaben dann verwenden, um andere APIs aufzurufen und die relevanten Antwortdaten an das Modell zurückzugeben. Mit Funktionsaufrufen können Sie Ihre generativen Modelle mit externen Systemen verbinden, damit die generierten Inhalte die aktuellsten und genauesten Informationen enthalten.
Funktionsweise von Funktionsaufrufen
Funktionen werden mithilfe von Funktionsdeklarationen beschrieben. So kann das generative Modell den Zweck und die Parameter einer Funktion besser verstehen. Nachdem Sie Funktionsdeklarationen in einer Abfrage an ein generatives Modell übergeben haben, gibt das Modell ein strukturiertes Objekt zurück, das die Namen relevanter Funktionen und deren Argumente basierend auf der Nutzeranfrage enthält. Hinweis: Beim Funktionsaufruf ruft das Modell die Funktion nicht tatsächlich auf. Stattdessen können Sie die zurückgegebene Funktion und die Parameter verwenden, um die Funktion in einer beliebigen Sprache, Bibliothek oder einem beliebigen Framework aufzurufen.
Aufgaben
In diesem Codelab erstellen Sie eine generative KI-Pipeline mit der Vertex AI Gemini API und Python. Nutzer können über Ihre App nach Wechselkursen fragen. Das System ruft dann die neuesten Daten von einer externen API ab und antwortet dem Nutzer.
Lerninhalte
- Mit dem Gemini-Modell über die Python-Clientbibliothek interagieren
- So definieren Sie eine Funktionsdeklaration und registrieren sie als Tool
- Gemini aufrufen und eine Antwort auf einen Funktionsaufruf erhalten
- Funktionsantwort an Gemini zurückgeben und auf den Nutzer reagieren
Voraussetzungen
- Google Cloud-Projekt
- Ein Browser wie Chrome
- Eine Python-Entwicklungsumgebung wie Colab oder Colab Enterprise
2. Einrichtung und Anforderungen
Bevor Sie Funktionsaufrufe in Gemini verwenden können, müssen Sie die Vertex AI API aktivieren und die neueste Version der Vertex AI-Python-Clientbibliothek installieren.
Vertex AI API aktivieren
So aktivieren Sie die Vertex AI API:
- Rufen Sie in Ihrem Browser die Seite mit den Dienstdetails zur Vertex AI API auf.
- Klicken Sie auf die Schaltfläche Aktivieren, um die Vertex AI API in Ihrem Google Cloud-Projekt zu aktivieren.
Python-Clientbibliothek für Vertex AI installieren
So installieren Sie die Python-Clientbibliotheken für Vertex AI:
- Öffnen Sie ein Terminal in Ihrer Entwicklungsumgebung.
- Prüfen Sie, ob Sie eine gültige Python-Entwicklungsumgebung haben, und sehen Sie sich bei Bedarf diese Richtlinien an.
- Führen Sie den folgenden Befehl aus, um die Python-Clientbibliothek für Vertex AI zu installieren:
pip install --upgrade google-cloud-aiplatform - Wenn Sie in einer Notebook-Umgebung arbeiten, müssen Sie möglicherweise die Laufzeit bzw. den Kernel neu starten, um die neu installierten Pakete verwenden zu können.
Jetzt können Sie die Vertex AI API verwenden.
3. Problem verstehen
Haben Sie schon einmal mit einem Large Language Model oder einem generativen KI-Modell interagiert und es nach Echtzeit- oder aktuellen Informationen gefragt, nur um eine Antwort mit veralteten oder ungenauen Informationen zu erhalten?
Probiert es doch gleich mal aus! Zuerst importieren wir die relevanten Python-Pakete und initialisieren das Gemini-Modell. Sie können den folgenden Code in einer Python-Entwicklungsumgebung wie Colab oder Colab Enterprise ausführen, indem Sie die neueste Version des Vertex AI SDK für Python installieren:
import vertexai
from vertexai.generative_models import GenerativeModel
model = GenerativeModel("gemini-1.5-pro-001")
Stellen wir nun eine Frage zum Wechselkurs für verschiedene Währungen heute:
response = model.generate_content(
"What's the exchange rate for euros to dollars today?"
)
print(response.text)
Das Modell sollte eine eingeschränkte oder veraltete Antwort ähnlich der folgenden generieren:
As an AI language model, I don't have access to real-time currency exchange rates. However, as of my last update in September 2021, the approximate exchange rate between euros (EUR) and US dollars (USD) was: 1 EUR ≈ 1.18 USD Please note that currency exchange rates constantly fluctuate and can vary depending on various factors such as economic conditions, supply and demand, political events, and more. To obtain the most up-to-date and accurate exchange rate, I recommend using a reliable currency converter or financial website that provides live rates. [...]
Wenn ein Endnutzer eine solche Antwort erhält, muss er den Kontext wechseln, um die gewünschten Währungen zu suchen, den aktuellen Wechselkurs abzurufen und alle erforderlichen Umrechnungen selbst vornehmen.
Im Idealfall kann eine Pipeline für generative Modelle einige oder alle dieser Aufgaben für den Nutzer übernehmen. Im nächsten Abschnitt probieren Sie einige gängige Workarounds aus, um strukturierte Antworten von generativen Modellen zu erhalten, damit Sie externe Systeme aufrufen können.
4. Häufige Problemumgehungen ausprobieren
Wenn Sie in Szenarien, in denen Sie aktuelle Informationen oder Daten aus externen Quellen benötigen, mit generativen Modellen arbeiten, können Sie eine externe API aufrufen und die Ergebnisse an das generative Modell zurückgeben, damit es sie in seiner Antwort verwenden kann.
Bevor Sie ein externes System aufrufen, müssen Sie die richtige Funktion ermitteln, die relevanten Parameter vom Nutzer extrahieren und die Parameter in ein strukturiertes Datenobjekt einfügen. Dazu ist in der Regel ein umfassendes Prompt Engineering erforderlich, um das generative Modell zur Ausgabe gültiger strukturierter Daten zu zwingen.
Sehen wir uns die Frage aus dem vorherigen Abschnitt noch einmal an und fügen wir dem Modell einige zusätzliche Anweisungen hinzu. Senden Sie die folgende Anfrage an das Gemini-Modell:
user_prompt = "What's the exchange rate from euros to US dollars today?"
response = model.generate_content("""
Your task is to extract parameters from the user's input and return it as a
structured JSON payload. The user will ask about the exchange rate and which
currency they are converting from and converting to.
User input: {user_prompt}
Please extract the currencies as parameters and put them in a JSON object.
""".format(user_prompt=user_prompt))
print(response.text)
Das Ergebnis ist die folgende Textantwort, die kein gültiges JSON ist und mit der wir nur schwer arbeiten können:
```json
{
"currency_from": "euros",
"currency_to": "US dollars"
}
```
Insbesondere die erste und letzte Zeile der Textantwort enthalten Backticks, um den Codeblock abzugrenzen. Die erste Zeile enthält einen Sprachbezeichner und die Werte im JSON-Objekt sind nicht die standardmäßigen dreistelligen Währungsabkürzungen, die eine Währungsumrechnungs-API als Eingabeparameter erwarten würde.
Wir könnten versuchen, diesen Text mit Python in gültiges JSON und ein Dictionary zu konvertieren, dem Prompt weitere Anweisungen hinzuzufügen, ein oder mehrere Beispiele für die gewünschte Ausgabe bereitzustellen, das Modell zu optimieren oder einen weiteren Aufruf an das generative Modell zu senden, um das JSON zu bereinigen.
Es gibt aber eine deterministischere Methode. Sehen wir uns an, wie Sie Funktionsaufrufe in Gemini verwenden können, um Informationen in externen Diensten abzufragen und relevante Antworten an Endnutzer zurückzugeben.
5. Funktionsweise von Funktionsaufrufen
Bevor wir mit der Parameterextrahierung und dem Funktionsaufruf beginnen, sehen wir uns die Schritte des Funktionsaufrufs und die Komponenten an, die zur Laufzeit verwendet werden.
Nutzereingabe für die Gemini API
Der Prompt des Nutzers wird an die Gemini API gesendet. In diesem API-Aufruf an das Gemini-Modell hat der Entwickler eine oder mehrere Funktionsdeklarationen in einem Tool definiert, damit das Gemini-Modell weiß, welche Funktionen es aufrufen kann und wie.
Die Gemini API gibt einen Funktionsaufruf zurück
Gemini gibt basierend auf dem Inhalt der Nutzereingabe und des Prompts eine Funktionsaufrufantwort mit strukturierten Daten zurück, die den Namen der aufzurufenden Funktion und die entsprechenden Parameter enthält.
API-Anfrage stellen
Anschließend verwenden Sie den Funktionsnamen und die Parameter, um eine API-Anfrage zu stellen und Informationen aus einem externen System oder einer externen API abzurufen. Diese API-Anfrage und ‑Antwort wird vom Entwickler im Anwendungscode implementiert und erfolgt außerhalb des Geltungsbereichs der Gemini API und des SDK. Sie können beispielsweise die requests-Bibliothek in Python verwenden, um eine REST API aufzurufen und eine JSON-Antwort zu erhalten. Alternativ können Sie die Funktion mit Ihrem bevorzugten Ansatz und Ihrer bevorzugten Clientbibliothek aufrufen.
API-Antwort an Gemini zurückgeben
Schließlich geben Sie die API-Antwort an das Gemini-Modell zurück, damit es eine Antwort auf den ursprünglichen Prompt des Endnutzers generieren oder eine andere Funktionsaufrufantwort aufrufen kann, wenn das Gemini-Modell feststellt, dass es zusätzliche Informationen benötigt.
6. API auswählen
Nachdem Sie nun den allgemeinen Ablauf und die einzelnen Schritte beim Funktionsaufruf kennen, erstellen Sie eine Pipeline für generative KI, um die aktuellen Währungskurse abzurufen. Zuerst müssen wir auswählen, welche API wir als Informationsquelle verwenden möchten.
Für unsere Währungsumrechnungs-App verwenden wir die REST API unter https://www.frankfurter.app/, um die neuesten Informationen zu globalen Wechselkursen abzurufen.
Um mit dieser REST API zu interagieren, können wir einen REST API-Aufruf mit requests in Python so ausführen:
import requests
url = "https://api.frankfurter.app/latest"
response = requests.get(url)
response.text
oder eine cURL-Anfrage wie:
curl https://api.frankfurter.app/latest
Dadurch wird eine Antwort ähnlich der folgenden zurückgegeben:
{
"amount": 1,
"base": "EUR",
"date": "2023-12-20",
"rates": {
"AUD": 1.6186, "BGN": 1.9558, "BRL": 5.3287,
"CAD": 1.4609, "CHF": 0.946, "CNY": 7.8121,
"CZK": 24.538, "DKK": 7.4565, "GBP": 0.86555,
"HKD": 8.5439, "HUF": 385.23, "IDR": 16994,
"ILS": 3.9983, "INR": 91.06, "ISK": 150.3,
"JPY": 157.12, "KRW": 1425.62, "MXN": 18.6867,
"MYR": 5.0977, "NOK": 11.2895, "NZD": 1.7421,
"PHP": 60.991, "PLN": 4.3413, "RON": 4.9699,
"SEK": 11.129, "SGD": 1.4562, "THB": 38.252,
"TRY": 31.883, "USD": 1.0944, "ZAR": 20.111
}
}
Da beim Funktionsaufruf in Gemini der externe API-Aufruf nicht tatsächlich für Sie erfolgt, gibt es keine Einschränkungen hinsichtlich des API-Typs, den Sie verwenden. Sie können einen Cloud Run-Dienst, eine Cloud-Funktion, eine API-Anfrage an einen Google Cloud-Dienst oder eine beliebige externe REST API verwenden.
7. Funktion und Tool definieren
Nachdem Sie eine REST API ausgewählt haben, können wir nun eine API-Spezifikation definieren und die Funktion in einem Tool registrieren.
Achten Sie darauf, dass Sie die neueste Version des Vertex AI SDK for Python installiert haben.
Importieren Sie dann die erforderlichen Module aus dem Python SDK und initialisieren Sie das Gemini-Modell:
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerativeModel,
Part,
Tool,
)
model = GenerativeModel("gemini-1.5-pro-001")
Wenn wir uns die REST API unter https://api.frankfurter.app/ noch einmal ansehen, stellen wir fest, dass sie die folgenden Eingabeparameter akzeptiert:
Parameter | Typ | Beschreibung |
| String | Währung für die Umrechnung |
| String | Währung, in die umgerechnet werden soll |
| String | Datum, für das der Wechselkurs abgerufen werden soll |
Mit diesen Parametern sieht eine partielle OpenAPI-Spezifikation für diese REST API im YAML-Format so aus:
openapi: 3.0.0
info:
title: Frankfurter Exchange Rate API
description: This API provides current and historical exchange rates
version: 1.0.0
servers:
- url: https://api.frankfurter.app
paths:
/{date}:
get:
summary: Get the latest currency exchange rates.
parameters:
- name: date
in: path
description: Get currency rates for a specific date or 'latest' if a date is not specified
required: true
schema:
type: string
- name: from
in: query
description: The currency to convert from.
required: true
schema:
type: string
- name: to
in: query
description: The currency to convert to.
schema:
type: string
Registrieren wir dies nun als FunctionDeclaration mit dem Python SDK für Gemini:
get_exchange_rate_func = FunctionDeclaration(
name="get_exchange_rate",
description="Get the exchange rate for currencies between countries",
parameters={
"type": "object",
"properties": {
"currency_date": {
"type": "string",
"description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
},
"currency_from": {
"type": "string",
"description": "The currency to convert from in ISO 4217 format"
},
"currency_to": {
"type": "string",
"description": "The currency to convert to in ISO 4217 format"
}
},
"required": [
"currency_from",
"currency_date",
]
},
)
Achten Sie darauf, dass die Funktions- und Parameterbeschreibungen so detailliert wie möglich sind, da das generative Modell anhand dieser Informationen bestimmt, welche Funktion ausgewählt und wie die Parameter im Funktionsaufruf ausgefüllt werden sollen.
Schließlich definieren Sie ein Tool, das die Funktionsdeklaration enthält:
exchange_rate_tool = Tool(
function_declarations=[get_exchange_rate_func],
)
Hier verwenden Sie eine Funktionsdeklaration in einem Tool. Sie können jedoch auch mehrere Funktionsdeklarationen in einem Tool registrieren. Das Modell wählt dann zur Laufzeit die passende Funktion aus. Weitere Informationen zu den Klassen FunctionDeclaration, Tool und den zugehörigen Klassen im Gemini SDK für Python finden Sie in der Dokumentation zu Funktionsaufrufen in der Gemini API.
Sie haben die Konfiguration Ihrer Funktions- und Tooldefinitionen abgeschlossen. Im nächsten Abschnitt rufen wir das generative Modell mit diesem Tool auf und erhalten einen Funktionsaufruf zurück, mit dem wir die REST API aufrufen können.
8. Funktionsaufruf generieren
Jetzt können Sie das generative Modell auffordern und die von Ihnen definierte tool einfügen:
prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""
response = model.generate_content(
prompt,
tools=[exchange_rate_tool],
)
Sehen wir uns das Antwortobjekt an:
print(response.candidates[0].content)
role: "model"
parts {
function_call {
name: "get_exchange_rate"
args {
fields {
key: "currency_to"
value {
string_value: "SEK"
}
}
fields {
key: "currency_from"
value {
string_value: "AUD"
}
}
fields {
key: "currency_date"
value {
string_value: "latest"
}
}
}
}
}
Das Modell hat die einzige verfügbare Funktion ausgewählt und einen Funktionsaufruf für die Funktion get_exchange_rate zusammen mit den Parametern zurückgegeben. Die Parameter haben das gewünschte Format. Strukturierte Antworten von generativen Modellen erhalten
Im nächsten Abschnitt verwenden Sie die Informationen in der Antwort, um eine API-Anfrage zu senden.
9. API-Anfrage stellen
Denken Sie daran, dass beim Funktionsaufruf in Gemini der externe API-Aufruf nicht automatisch erfolgt. Sie können jede beliebige Sprache, Bibliothek oder jedes beliebige Framework verwenden.
Hier verwenden Sie die requests-Bibliothek in Python, um die REST API für Wechselkurse aufzurufen.
Wir packen die Antwort in ein Python-Wörterbuch aus:
params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
params[key[9:]] = value
params
Jetzt können wir requests oder eine andere Methode aufrufen:
import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text
Das Ergebnis ist eine Antwort ähnlich der folgenden:
'{"amount":1.0,"base":"AUD","date":"2024-01-16","rates":{"SEK":6.8682}}'
Wir haben unsere Antwort von der REST API mit den aktuellen Wechselkursinformationen von heute. Im nächsten Abschnitt geben wir diese Informationen an das Modell zurück, damit es eine relevante Antwort für den Nutzer generieren kann.
10. Antwort generieren
Zum Schluss generieren wir eine Antwort für den Nutzer, indem wir die Funktionsantwort in der nächsten Unterhaltungsrunde an das Modell zurückgeben:
response = model.generate_content(
[
Content(role="user", parts=[
Part.from_text(prompt + """Give your answer in steps with lots of detail
and context, including the exchange rate and date."""),
]),
Content(role="function", parts=[
Part.from_dict({
"function_call": {
"name": "get_exchange_rate",
}
})
]),
Content(role="function", parts=[
Part.from_function_response(
name="get_exchange_rate",
response={
"content": api_response.text,
}
)
]),
],
tools=[exchange_rate_tool],
)
response.candidates[0].content.parts[0].text
Sobald wir die Funktionsantwort an das Modell zurückgeben, antwortet es auf den Prompt des Nutzers und gibt relevante Informationen aus der API-Antwort an.
The exchange rate from Australian dollars to Swedish krona on January 16, 2024, is 1 Australian dollar is equal to 6.8663 Swedish krona. So, 500 Australian dollars would be worth 500 * 6.8663 = 3,433.15 Swedish krona.
11. Vollständiges Codebeispiel ansehen
An diesem Punkt können Sie Ihren Python-Code in einer Backend-API mit einem Cloud Run-Dienst, einer Cloud-Funktion oder einem anderen Cloud-Dienst platzieren und eine Frontend-App bereitstellen, die diese Backend-API für Modellabfragen und API-Aufrufe verwendet.
Hier ist das vollständige Codebeispiel für unsere endgültige Lösung:
import requests
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerativeModel,
Part,
Tool,
)
model = GenerativeModel("gemini-1.5-pro-001")
get_exchange_rate_func = FunctionDeclaration(
name="get_exchange_rate",
description="Get the exchange rate for currencies between countries",
parameters={
"type": "object",
"properties": {
"currency_date": {
"type": "string",
"description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
},
"currency_from": {
"type": "string",
"description": "The currency to convert from in ISO 4217 format"
},
"currency_to": {
"type": "string",
"description": "The currency to convert to in ISO 4217 format"
}
},
"required": [
"currency_from",
"currency_date",
]
},
)
exchange_rate_tool = Tool(
function_declarations=[get_exchange_rate_func],
)
prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""
response = model.generate_content(
prompt,
tools=[exchange_rate_tool],
)
response.candidates[0].content
params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
params[key[9:]] = value
params
import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text
response = model.generate_content(
[
Content(role="user", parts=[
Part.from_text(prompt + """Give your answer in steps with lots of detail
and context, including the exchange rate and date."""),
]),
Content(role="function", parts=[
Part.from_dict({
"function_call": {
"name": "get_exchange_rate",
}
})
]),
Content(role="function", parts=[
Part.from_function_response(
name="get_exchange_rate",
response={
"content": api_response.text,
}
)
]),
],
tools=[exchange_rate_tool],
)
response.candidates[0].content.parts[0].text
In dieser Implementierung haben wir zwei Anfragen an das generative Modell gesendet: eine Anfrage zum Generieren eines Funktionsaufrufs und eine weitere Anfrage zum Zurückgeben der Funktionsantwort. Dies ist nur eine Methode zum Verarbeiten von Funktionsaufrufen und Funktionsantworten mit Gemini. Sie können auch zusätzliche Funktionsaufrufe ausführen, um weitere Informationen zu Ihrer Anfrage zu erhalten, oder Funktionsaufrufe mit Chat- und asynchronen Methoden verwenden.
Weitere Codebeispiele finden Sie im Beispiel-Notebook für Funktionsaufrufe in Gemini.
12. Glückwunsch
Sie haben erfolgreich eine Pipeline für generative KI mit Funktionsaufrufen in Gemini, der Vertex AI Gemini API und Python erstellt. Nutzer können nach Wechselkursen fragen. Das System ruft dann die neuesten Daten von einer externen API ab und gibt eine Antwort.
Bei einem Prompt von einem Endnutzer werden durch Funktionsaufrufe in Gemini die passende Funktion ausgewählt, Parameter aus dem Prompt extrahiert und ein strukturiertes Datenobjekt zurückgegeben, mit dem Sie einen externen API-Aufruf ausführen können.
Das Design des Funktionsaufrufs in Gemini soll Ihnen das Beste aus beiden Welten bieten: Parameter werden deterministisch extrahiert, während das generative Modell für die Zusammenfassung und die Erstellung von Inhalten zuständig ist. Sie können auch andere APIs und Prompts in Ihrer Pipeline ausprobieren und die anderen Funktionen der Vertex AI Gemini API nutzen.
Bereinigen
Mit den folgenden Schritten können Sie vermeiden, dass Ihrem Google Cloud-Konto die in diesem Codelab verwendeten Ressourcen in Rechnung gestellt werden:
- Löschen Sie das Projekt mit der Google Cloud Console, wenn Sie es nicht benötigen. Damit vermeiden Sie unnötige Kosten für Google Cloud.
- Wenn Sie die APIs für Vertex AI deaktivieren möchten, rufen Sie die Seite mit den Dienstdetails der Vertex AI API auf, klicken Sie auf API deaktivieren und bestätigen Sie die Aktion.
Weitere Informationen
In diesen Anleitungen und Ressourcen erfahren Sie mehr über konversationelle KI und generative KI:
- Übersicht über Gemini-Modelle
- Dokumentation zu Funktionsaufrufen in Gemini
- Beispiel-Notebook für Funktionsaufrufe in Gemini
- Beispielnotebooks für Gemini
- Generative KI in Google Cloud
Lizenz
Dieser Text ist mit einer Creative Commons Attribution 2.0 Generic License lizenziert.