Informationen zu diesem Codelab
1. Übersicht
MCP Toolbox for Databases ist ein Open-Source-Server von Google, mit dem sich generative KI-Tools für die Interaktion mit Datenbanken einfacher erstellen lassen. Sie können damit Tools einfacher, schneller und sicherer entwickeln, da komplexe Aufgaben wie Verbindungspooling und Authentifizierung übernommen werden. Sie können damit auf generativer KI basierende Tools erstellen, mit denen Ihre Agents auf Daten in Ihrer Datenbank zugreifen können. Der Toolbox bietet folgende Vorteile:
Vereinfachte Entwicklung:Sie können Tools mit weniger als 10 Zeilen Code in Ihren Agent einbinden, Tools für mehrere Agents oder Frameworks wiederverwenden und neue Versionen von Tools leichter bereitstellen.
Bessere Leistung:Best Practices wie Verbindungs-Pooling, Authentifizierung usw.
Erhöhte Sicherheit:Integrierte Authentifizierung für einen sichereren Zugriff auf Ihre Daten.
Durchgängige Beobachtbarkeit:Sofort einsatzbereite Messwerte und Tracing mit integrierter Unterstützung für OpenTelemetry.
Toolbox befindet sich zwischen dem Orchestration Framework Ihrer Anwendung und Ihrer Datenbank und bietet eine Steuerebene, mit der Tools geändert, verteilt oder aufgerufen werden. Sie vereinfacht die Verwaltung Ihrer Tools, da Sie Tools an einem zentralen Ort speichern und aktualisieren können. So können Sie Tools für Kundenservicemitarbeiter und Anwendungen freigeben und diese Tools aktualisieren, ohne Ihre Anwendung unbedingt neu bereitzustellen.
Aufgaben
Im Rahmen dieses Labs erstellen Sie eine Anwendung, die mit einem Tool eine einfache Datenbankabfrage (AlloyDB) ausführt, die von Ihrem Agent oder der generativen KI-Anwendung aufgerufen werden kann. Dazu erstellen Sie
- MCP Toolbox für Datenbanken installieren
- Richten Sie das Tool, das eine Aufgabe in AlloyDB ausführen soll, auf dem Toolbox-Server ein.
- MCP Toolbox für Datenbanken in Cloud Run bereitstellen
- Tool mit dem bereitgestellten Cloud Run-Endpunkt testen
- Cloud Run Functions-Funktion zum Aufrufen der Toolbox erstellen
Voraussetzungen
2. Hinweis
Projekt erstellen
- Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
- Die Abrechnung für das Cloud-Projekt muss aktiviert sein. Hier erfahren Sie, wie Sie prüfen, ob die Abrechnung für ein Projekt aktiviert ist.
- Sie verwenden Cloud Shell, eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird. Klicken Sie oben in der Google Cloud Console auf „Cloud Shell aktivieren“.
- Wenn Sie eine Verbindung zu Cloud Shell hergestellt haben, prüfen Sie mit dem folgenden Befehl, ob Sie bereits authentifiziert sind und ob für das Projekt die richtige Projekt-ID festgelegt ist:
gcloud auth list
- Führen Sie in Cloud Shell den folgenden Befehl aus, um zu prüfen, ob der gcloud-Befehl Ihr Projekt kennt.
gcloud config list project
- Wenn Ihr Projekt nicht festgelegt ist, verwenden Sie den folgenden Befehl, um es festzulegen:
gcloud config set project <YOUR_PROJECT_ID>
- Aktivieren Sie die erforderlichen APIs, indem Sie die folgenden Befehle nacheinander im Cloud Shell-Terminal ausführen:
Es gibt auch einen einzigen Befehl, um den unten stehenden Befehl auszuführen. Wenn Sie jedoch ein Testkonto sind, können Kontingentprobleme auftreten, wenn Sie versuchen, diese im Bulk zu aktivieren. Aus diesem Grund wird jeweils ein Befehl pro Zeile aufgeführt.
gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com
gcloud services enable servicenetworking.googleapis.com
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable cloudfunctions.googleapis.com
gcloud services enable aiplatform.googleapis.com
Alternativ zum gcloud-Befehl können Sie auch über die Console nach den einzelnen Produkten suchen oder diesen Link verwenden.
Wenn eine API fehlt, können Sie sie jederzeit während der Implementierung aktivieren.
Weitere Informationen zu gcloud-Befehlen und deren Verwendung finden Sie in der Dokumentation.
3. Datenbank einrichten
In diesem Lab verwenden wir AlloyDB als Datenbank für die Einzelhandelsdaten. Es verwendet Cluster, um alle Ressourcen wie Datenbanken und Logs zu speichern. Jeder Cluster hat eine primäre Instanz, die einen Zugangspunkt auf die Daten bietet. Die Tabellen enthalten die eigentlichen Daten.
Erstellen Sie nun einen AlloyDB-Cluster, eine AlloyDB-Instanz und eine AlloyDB-Tabelle, in die das E-Commerce-Dataset geladen wird.
Cluster und Instanz erstellen
- AlloyDB-Seite in der Cloud Console aufrufen
Die meisten Seiten in der Cloud Console lassen sich ganz einfach über die Suchleiste finden.
- Wählen Sie auf dieser Seite "CLUSTER ERSTELLEN" aus:
- Ein Bildschirm wie der unten abgebildete wird angezeigt. Erstellen Sie einen Cluster und eine Instanz mit den folgenden Werten. Achten Sie darauf, dass die Werte übereinstimmen, falls Sie den Anwendungscode aus dem Repository klonen:
- Cluster-ID: „
vector-cluster“ - Passwort: „
alloydb“ - Mit PostgreSQL 15 kompatibel
- Region: „
us-central1“ - Netzwerk: „
default“
- Wenn Sie das Standardnetzwerk auswählen, sehen Sie einen Bildschirm wie den folgenden. Klicken Sie auf VERBINDUNG EINRICHTEN.
- Wählen Sie „Automatisch zugewiesenen IP-Bereich verwenden“ aus und klicken Sie auf „Weiter“. Lesen Sie die Informationen und klicken Sie auf „VERBINDUNG ERSTELLEN“.
- Sobald Ihr Netzwerk eingerichtet ist, können Sie mit dem Erstellen des Clusters fortfahren. Klicken Sie auf CLUSTER ERSTELLEN, um die Einrichtung des Clusters wie unten dargestellt abzuschließen:
Achten Sie darauf, die Instanz-ID in „
vector-instance"
.
Die Erstellung des Clusters dauert etwa 10 Minuten. Anschließend wird ein Bildschirm mit einer Übersicht des soeben erstellten Clusters angezeigt.
4. Datenaufnahme
Jetzt ist es an der Zeit, eine Tabelle mit den Daten über den Speicher hinzuzufügen. Rufen Sie AlloyDB auf, wählen Sie den primären Cluster und dann AlloyDB Studio aus:
Möglicherweise müssen Sie warten, bis die Erstellung der Instanz abgeschlossen ist. Melden Sie sich danach mit den Anmeldedaten in AlloyDB an, die Sie bei der Clustererstellung erstellt haben. Verwenden Sie die folgenden Daten zur Authentifizierung bei PostgreSQL:
- Nutzername: "
postgres" - Datenbank: "
postgres" - Passwort: „
alloydb“
Nach der erfolgreichen Authentifizierung bei AlloyDB Studio können SQL-Befehle in den Editor eingegeben werden. Mit dem Pluszeichen rechts neben dem letzten Fenster können Sie mehrere Editor-Fenster hinzufügen.
Sie können Befehle für AlloyDB in Editorfenstern nach Bedarf mit den Optionen „Ausführen“, „Formatieren“ und „Löschen“ eingeben.
Erweiterungen aktivieren
Zum Erstellen dieser App verwenden wir die Erweiterungen pgvector und google_ml_integration. Mit der pgvector-Erweiterung können Sie Vektoreinbettungen speichern und suchen. Die Erweiterung google_ml_integration bietet Funktionen, mit denen Sie auf Vertex AI-Vorhersageendpunkte zugreifen und Vorhersagen in SQL abrufen können. Aktivieren Sie diese Erweiterungen, indem Sie die folgenden DDLs ausführen:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
Wenn Sie die in Ihrer Datenbank aktivierten Erweiterungen prüfen möchten, führen Sie den folgenden SQL-Befehl aus:
select extname, extversion from pg_extension;
Tabelle erstellen
Erstellen Sie mit der folgenden DDL-Anweisung eine Tabelle:
CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;
Nach erfolgreicher Ausführung des obigen Befehls sollte die Tabelle in der Datenbank angezeigt werden.
Daten aufnehmen
Für dieses Lab finden Sie in dieser SQL-Datei Testdaten mit etwa 72 Datensätzen. Es enthält die Felder id, name, description, quantity, price, image_url. Die anderen Felder werden später im Lab ausgefüllt.
Kopieren Sie dort die Zeilen/Anweisungen einfügen, fügen Sie diese Zeilen in einen leeren Editor-Tab ein und wählen Sie AUSFÜHREN aus.
Um den Inhalt der Tabelle zu sehen, erweitern Sie den Abschnitt „Explorer“, bis Sie die Tabelle mit dem Namen „wears“ (Bekleidung) sehen. Klicken Sie auf das Dreipunkt-Menü (⋮), um die Option zum Abfragen der Tabelle aufzurufen. Eine SELECT-Anweisung wird in einer neuen Editor-Registerkarte geöffnet.
Berechtigung gewähren
Führen Sie die folgende Anweisung aus, um dem Nutzer postgres Ausführungsrechte für die Funktion embedding zu gewähren:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Vertex AI-Nutzer ROLE für AlloyDB-Dienstkonto gewähren
Rufen Sie das Cloud Shell-Terminal auf und geben Sie den folgenden Befehl ein:
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
5. Einbettungen für den Kontext erstellen
Es ist für Computer viel einfacher, Zahlen zu verarbeiten als Text. Ein Einbettungssystem wandelt Text in eine Reihe von Gleitkommazahlen, sogenannten Vektoreinbettungen, um, die den Text darstellen sollten, unabhängig davon, wie er formuliert ist, welche Sprache er verwendet usw.
Ein Ort am Meer könnte zum Beispiel als „auf dem Wasser“, „Strand“, „vom Zimmer zum Meer gehen“, „sur la mer“, „kriminal“ bezeichnet werden. Diese Begriffe sehen zwar unterschiedlich aus, doch ihre semantische Bedeutung oder in der Terminologie des maschinellen Lernens sollten ihre Einbettungen sehr nah beieinander sein.
Die Daten und der Kontext sind nun bereit. Führen Sie nun den SQL-Code aus, um die Einbettungen der Produktbeschreibung in die Tabelle im Feld embedding einzufügen. Es gibt eine Vielzahl von Einbettungsmodellen, die Sie verwenden können. Wir verwenden text-embedding-005 aus Vertex AI. Achten Sie darauf, während des gesamten Projekts dasselbe Einbettungsmodell zu verwenden!
Hinweis: Wenn Sie ein altes Google Cloud-Projekt verwenden, müssen Sie möglicherweise weiterhin ältere Versionen des Texteinbettungsmodells wie „textembedding-gecko“ verwenden.
Kehren Sie zum AlloyDB Studio-Tab zurück und geben Sie die folgende DML ein:
UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);
Sehen Sie sich noch einmal die Tabelle toys an, um einige Einbettungen zu sehen. Achten Sie darauf, die SELECT-Anweisung erneut auszuführen, um die Änderungen zu sehen.
SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;
Dadurch sollte der Einbettungsvektor zurückgegeben werden, der wie ein Array von Gleitkommazahlen für die Spielzeugbeschreibung aussieht, wie unten gezeigt:
Hinweis:Bei neu erstellten Google Cloud-Projekten der kostenlosen Stufe können Kontingentprobleme auftreten, wenn es um die Anzahl der Einbettungsanfragen geht, die pro Sekunde für die Einbettungsmodelle zulässig sind. Wir empfehlen, eine Filterabfrage für die ID zu verwenden und dann selektiv 1 bis 5 Datensätze auszuwählen, während Sie die Einbettung generieren.
6. Vektorsuche durchführen
Nachdem die Tabelle, die Daten und die Einbettungen nun bereit sind, führen wir die Echtzeit-Vektorsuche für den Suchtext des Nutzers durch.
Angenommen, der Nutzer fragt:
„I want a white plush teddy bear toy with a floral pattern“
Sie können Übereinstimmungen dafür finden, indem Sie die folgende Abfrage ausführen:
select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;
Sehen wir uns diese Abfrage einmal genauer an:
In dieser Abfrage
- Der Suchtext des Nutzers lautet: „
I want a white plush teddy bear toy with a floral pattern.“ - Wir wandeln sie mithilfe des Modells
text-embedding-005in Einbettungen in dieembedding()-Methode um. Dieser Schritt sollte Ihnen nach dem letzten Schritt bekannt vorkommen, in dem wir die Einbettungsfunktion auf alle Elemente in der Tabelle angewendet haben. - "
<=>" steht für die Verwendung der Entfernungsmethode COSINE SIMILARITY. Sie finden alle verfügbaren Ähnlichkeitsmaße in der Dokumentation zu pgvector. - Wir wandeln das Ergebnis der Einbettungsmethode in einen Vektortyp um, damit sie mit den in der Datenbank gespeicherten Vektoren kompatibel ist.
- LIMIT 5 bedeutet, dass die 5 nächsten Nachbarn aus dem Suchtext extrahiert werden sollen.
Das Ergebnis sieht so aus:
Wie Sie in Ihren Ergebnissen sehen können, liegen die Übereinstimmungen ziemlich nah am Suchtext. Ändern Sie den Text, um zu sehen, wie sich die Ergebnisse ändern.
7. AlloyDB für die Toolbox-Interaktion vorbereiten
Als Vorbereitung auf die Einrichtung der Toolbox aktivieren wir nun die öffentliche IP-Verbindung in unserer AlloyDB-Instanz, damit das neue Tool auf die Datenbank zugreifen kann.
- Rufen Sie Ihre AlloyDB-Instanz auf, klicken Sie auf BEARBEITEN und landen Sie auf der Seite „Primäre Instanz bearbeiten“.
- Klicken Sie im Abschnitt „Öffentliche IP-Verbindung“ auf das Kästchen „Öffentliche IP-Adresse aktivieren“ und geben Sie die IP-Adresse Ihrer Cloud Shell-Maschine ein.
- Um die IP-Adresse Ihres Cloud Shell-Computers abzurufen, rufen Sie das Cloud Shell-Terminal auf und geben Sie "ifconfig" ein. Identifizieren Sie aus dem Ergebnis die inet-Adresse eth0 und ersetzen Sie die letzten beiden Ziffern durch 0.0 mit der Maskengröße "/16". Beispiel: „XX.XX.0.0/16“, wobei XX Zahlen sind.
- Fügen Sie diese IP-Adresse auf der Seite "Instanz bearbeiten" in das Textfeld "Netzwerke" für autorisierte externe Netzwerke ein.
- Klicken Sie abschließend auf INSTANZ AKTUALISIEREN.
Das wird einige Minuten dauern.
8. MCP Toolbox für die Datenbankinstallation
- Sie können einen Projektordner erstellen, um die Tooldetails zu speichern. Da wir in diesem Fall an Daten aus dem Spielzeugladen arbeiten, erstellen wir einen Ordner mit dem Namen „toystore“ und rufen ihn auf. Rufen Sie das Cloud Shell-Terminal auf und prüfen Sie, ob Ihr Projekt ausgewählt und in der Eingabeaufforderung des Terminals angezeigt wird. Führen Sie im Cloud Shell-Terminal den folgenden Befehl aus:
mkdir toystore
cd toystore
- Führen Sie den folgenden Befehl aus, um die Toolbox in Ihren neuen Ordner herunterzuladen und zu installieren:
# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
- Wechseln Sie zum Cloud Shell-Editor. Erweitern Sie den neu erstellten Ordner „toystore“ und erstellen Sie eine neue Datei mit dem Namen „tools.yaml“. Kopieren Sie den Inhalt unten. Ersetzen Sie YOUR_PROJECT_ID und prüfen Sie, ob alle anderen Verbindungsdetails korrekt sind.
sources:
alloydb-toys:
kind: "alloydb-postgres"
project: "YOUR_PROJECT_ID"
region: "us-central1"
cluster: "vector-cluster"
instance: "vector-instance"
database: "postgres"
user: "postgres"
password: "alloydb"
tools:
get-toy-price:
kind: postgres-sql
source: alloydb-toys
description: Get the price of a toy based on a description.
parameters:
- name: description
type: string
description: A description of the toy to search for.
statement: |
SELECT price FROM toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
LIMIT 1;
In diesem Tool finden wir die genaueste Übereinstimmung mit dem Suchtext des Nutzers (personalisierte Spielwarenbeschreibung) und geben den Preis zurück. Sie können ihn auch ändern, um den durchschnittlichen Preis der fünf am ehesten passenden Spielzeuge zu ermitteln:
select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;
Sie haben die Tool-Definition eingerichtet.
Weitere Informationen zur Konfiguration von Tools.yaml finden Sie in dieser Dokumentation.
- Wechseln Sie zum Cloud Shell-Terminal und geben Sie den folgenden Befehl ein, um den Toolbox-Server mit Ihrer Tools-Konfiguration zu starten:
./toolbox --tools_file "tools.yaml"
- Wenn Sie den Server jetzt im Webvorschaumodus in der Cloud öffnen, sollten Sie sehen können, wie der Toolbox-Server mit dem neuen Tool
get-toy-price.ausgeführt wird.
9. Cloud Run-Bereitstellung der MCP-Toolbox für Datenbanken
Stellen wir es nun in Cloud Run bereit, damit Sie das Tool tatsächlich nutzen können.
- Folgen Sie der Anleitung auf dieser Seite nacheinander, bis Sie den Befehl
gcloud run deploy toolboxerreichen, der sich am dritten Punkt im Abschnitt „In Cloud Run bereitstellen“ befindet. Sie benötigen die erste Option, nicht die zweite, wenn Sie eine VPC-Netzwerkmethode verwenden. - Nach der erfolgreichen Bereitstellung erhalten Sie einen von Cloud Run bereitgestellten Endpunkt Ihres Toolbox-Servers. Testen Sie es mit einem CURL-Befehl.
Tipps:
Folgen Sie der Anleitung auf der Seite genau und lassen Sie sich nichts entgehen.
Sie können das neu bereitgestellte Tool nun in Ihrer Agent-Anwendung verwenden.
10. Anwendung mit MCP Toolbox für Datenbanken verbinden
In diesem Teil erstellen wir eine kleine Anwendung, um die Interaktion Ihres Tools mit den Anforderungen der Anwendung zu testen und die Antwort abzurufen.
- Rufen Sie Google Colab auf und öffnen Sie ein neues Notebook.
- Führen Sie Folgendes in Ihrem Notebook aus
!pip install toolbox-core
from toolbox_core import ToolboxClient
# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")
# If there are multiple tools
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")
# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})
# Print result
print(result)
- Das Ergebnis sollte wie folgt aussehen:
Dies ist das Tool, das explizit in einer Python-Anwendung aufgerufen wird, die das Toolkit toolbox-langchain verwendet..
- Mit dem
langgraph-Toolkit können Sie dieses Tool verwenden und mit einem Agent in einer in LangGraph integrierten Anwendung verknüpfen. - Entsprechende Informationen finden Sie in den Code-Snippets.
11. Geh mit in die Cloud!!!
Wir packen dieses Python-Code-Snippet in eine Cloud Run Functions-Funktion, um es serverlos zu machen.
- Kopieren Sie die Quelle aus dem Code-Repository-Ordner, um sie an Cloud Functions abzurufen.
- Rufen Sie die Cloud Run Functions-Konsole auf und klicken Sie auf FUNKTION ERSTELLEN.
- Lassen Sie die Authentifizierung für die Demoanwendung nicht und wählen Sie auf der nächsten Seite die Python 3.11-Laufzeit aus.
- Kopieren Sie die Dateien
main.pyundrequirements.txtaus dem in Schritt 1 freigegebenen Quell-Repository und fügen Sie die entsprechenden Dateien ein. - Ersetzen Sie die Server-URL in "main.py" durch Ihre Server-URL.
- Stellen Sie die Funktion bereit und Sie erhalten einen REST-Endpunkt für das Preisprognosetool, auf den Sie in der Toystore-Webanwendung zugreifen können.
- Ihr Endpunkt sollte so aussehen:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- Sie können ihn direkt in der Cloud Functions-Konsole testen. Rufen Sie dazu den Tab TESTING auf und geben Sie Folgendes als Anfrageeingabe ein:
{
"search": "White plush toy"
}
- Klicken Sie auf FUNKTION TESTEN oder führen Sie die gewünschte Option im Cloud Shell-Terminal aus. Das Ergebnis sollte rechts unter dem Titel „Output“ angezeigt werden:
12. Glückwunsch
Glückwunsch! Sie haben erfolgreich ein robustes und wirklich modulares Tool entwickelt, das über Datenbanken, Plattformen und Frameworks zur generativen KI-Orchestrierung hinweg interagieren kann, um Ihre Agent-Anwendung zu erstellen.