MCP Toolbox für Datenbanken für generative KI und Agentenanwendungen in AlloyDB installieren und einrichten

1. Übersicht

Die MCP Toolbox for Databases ist ein Open-Source-Server von Google, der die Entwicklung von Gen AI-Tools für die Interaktion mit Datenbanken vereinfacht. Damit können Sie Tools einfacher, schneller und sicherer entwickeln, da Komplexitäten wie Connection Pooling und Authentifizierung abgedeckt werden. Damit können Sie Tools für generative KI erstellen, mit denen Ihre Agents auf Daten in Ihrer Datenbank zugreifen können. Der Werkzeugkasten bietet:

Vereinfachte Entwicklung:Sie können Tools mit weniger als 10 Zeilen Code in Ihren Agenten einbinden, Tools für mehrere Agenten oder Frameworks wiederverwenden und neue Versionen von Tools einfacher bereitstellen.

Bessere Leistung:Best Practices wie Verbindungs-Pooling, Authentifizierung usw.

Mehr Sicherheit:Integrierte Authentifizierung für einen sichereren Zugriff auf Ihre Daten.

End-to-End-Beobachtbarkeit:Sofort einsatzbereite Messwerte und Tracing mit integrierter Unterstützung für OpenTelemetry.

Toolbox befindet sich zwischen dem Orchestrierungs-Framework Ihrer Anwendung und Ihrer Datenbank und bietet eine Steuerungsebene, mit der Tools geändert, verteilt oder aufgerufen werden können. Sie vereinfacht die Verwaltung Ihrer Tools, da Sie Tools zentral speichern und aktualisieren können. So können Sie Tools für mehrere Agents und Anwendungen freigeben und aktualisieren, ohne Ihre Anwendung neu bereitstellen zu müssen.

Aufgaben

In diesem Lab erstellen Sie eine Anwendung, die ein Tool verwendet, um eine einfache Datenbankabfrage (AlloyDB) auszuführen, die von Ihrem Agenten oder der generativen KI-Anwendung aufgerufen werden kann. Dazu

1. MCP Toolbox for Databases installieren
2. Tool (für eine Aufgabe in AlloyDB) auf dem Toolbox-Server einrichten
3. MCP Toolbox für Datenbanken in Cloud Run bereitstellen
4. Tool mit dem bereitgestellten Cloud Run-Endpunkt testen
5. Cloud Run-Funktion zum Aufrufen der Toolbox erstellen

Voraussetzungen

• Ein Browser, z. B. Chrome oder Firefox
• Ein Google Cloud-Projekt mit aktivierter Abrechnungsfunktion (Schritte im nächsten Abschnitt).

2. Hinweis

Projekt erstellen

1. Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.
3. 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“.

4. Prüfen Sie nach der Verbindung mit Cloud Shell mit dem folgenden Befehl, ob Sie bereits authentifiziert sind und ob für das Projekt die richtige Projekt-ID eingestellt ist:

gcloud auth list

5. Führen Sie den folgenden Befehl in Cloud Shell aus, um zu bestätigen, dass der gcloud-Befehl Ihr Projekt kennt.

gcloud config list project

6. Wenn Ihr Projekt nicht festgelegt ist, verwenden Sie den folgenden Befehl, um es festzulegen:

gcloud config set project <YOUR_PROJECT_ID>

7. Aktivieren Sie die erforderlichen APIs, indem Sie die folgenden Befehle einzeln in Ihrem Cloud Shell-Terminal ausführen:

Es gibt auch einen einzelnen Befehl, mit dem Sie die unten aufgeführten Aktionen ausführen können. Wenn Sie jedoch ein Testkonto verwenden, kann es zu Kontingentproblemen kommen, wenn Sie versuchen, diese Aktionen im Bulk zu aktivieren. Deshalb werden die Befehle einzeln 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

Die Alternative zum gcloud-Befehl ist die Console. Suchen Sie dort nach den einzelnen Produkten oder verwenden Sie diesen Link.

Wenn eine API fehlt, können Sie sie jederzeit während der Implementierung aktivieren.

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. Darin werden Cluster verwendet, um alle Ressourcen wie Datenbanken und Logs zu speichern. Jeder Cluster hat eine primäre Instanz, die einen Zugriffspunkt auf die Daten bietet. Tabellen enthalten die tatsächlichen Daten.

Erstellen wir einen AlloyDB-Cluster, eine AlloyDB-Instanz und eine AlloyDB-Tabelle, in die das E-Commerce-Dataset geladen wird.

Cluster und Instanz erstellen

1. Rufen Sie in der Cloud Console die AlloyDB-Seite auf.

Die meisten Seiten in der Cloud Console lassen sich ganz einfach über die Suchleiste der Console finden.

2. Wählen Sie auf dieser Seite die Option CLUSTER ERSTELLEN aus:

3. Sie sehen einen Bildschirm wie den unten. Erstellen Sie einen Cluster und eine Instanz mit den folgenden Werten. Achten Sie darauf, dass die Werte übereinstimmen, wenn Sie den Anwendungscode aus dem Repository klonen:

• Cluster-ID: „vector-cluster“
• Passwort: „alloydb“
• Mit PostgreSQL 15 kompatibel
• Region: „us-central1“
• Netzwerk: „default“

4. Wenn Sie das Standardnetzwerk auswählen, wird ein Bildschirm wie der unten angezeigt. Wählen Sie VERBINDUNG EINRICHTEN aus.
   
5. Wählen Sie dort „Automatisch zugewiesenen IP-Bereich verwenden“ aus und klicken Sie auf „Weiter“. Nachdem Sie die Informationen geprüft haben, wählen Sie „VERBINDUNG ERSTELLEN“ aus.
6. Nachdem Sie Ihr Netzwerk eingerichtet haben, können Sie mit der Clustererstellung fortfahren. Klicken Sie auf CREATE CLUSTER (Cluster erstellen), um die Einrichtung des Clusters abzuschließen (siehe unten):

Achten Sie darauf, die Instanz-ID in „

vector-instance"

.

Die Clustererstellung dauert etwa 10 Minuten. Wenn die Einrichtung erfolgreich war, wird ein Bildschirm mit der Übersicht des gerade erstellten Clusters angezeigt.

4. Datenaufnahme

Jetzt ist es an der Zeit, eine Tabelle mit den Daten zum Geschäft 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 Instanz erstellt wurde. Melden Sie sich nach Abschluss des Vorgangs mit den Anmeldedaten bei AlloyDB an, die Sie beim Erstellen des Clusters erstellt haben. Verwenden Sie die folgenden Daten für die Authentifizierung bei PostgreSQL:

• Nutzername: „postgres“
• Datenbank: „postgres“
• Passwort: „alloydb“

Nachdem Sie sich erfolgreich in AlloyDB Studio authentifiziert haben, können Sie SQL-Befehle in den Editor eingeben. Sie können mehrere Editorfenster hinzufügen, indem Sie auf das Pluszeichen rechts neben dem letzten Fenster klicken.

Sie können Befehle für AlloyDB in Editorfenstern eingeben und die Optionen „Ausführen“, „Formatieren“ und „Löschen“ nach Bedarf verwenden.

Erweiterungen aktivieren

Für die Entwicklung dieser App verwenden wir die Erweiterungen pgvector und google_ml_integration. Mit der pgvector-Erweiterung können Sie Vektoreinbettungen speichern und durchsuchen. Die Erweiterung google_ml_integration bietet Funktionen, mit denen Sie auf Vertex AI-Vorhersageendpunkte zugreifen können, um Vorhersagen in SQL zu erhalten. 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 prüfen möchten, welche Erweiterungen für Ihre Datenbank aktiviert wurden, führen Sie diesen SQL-Befehl aus:

select extname, extversion from pg_extension;

Tabelle erstellen

Erstellen Sie eine Tabelle mit der folgenden DDL-Anweisung:

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 oben genannten Befehls sollte die Tabelle in der Datenbank zu sehen sein.

Daten aufnehmen

Für dieses Lab haben wir Testdaten mit etwa 72 Datensätzen in dieser SQL-Datei. Sie enthält die Felder id, name, description, quantity, price, image_url. Die anderen Felder werden später im Lab ausgefüllt.

Kopieren Sie die Zeilen/INSERT-Anweisungen und fügen Sie sie in einen leeren Editor-Tab ein. Wählen Sie dann „AUSFÜHREN“ aus.

Wenn Sie den Tabelleninhalt sehen möchten, maximieren Sie den Explorer-Bereich, bis Sie die Tabelle „apparels“ sehen. Wählen Sie das Dreipunkt-Menü (⋮) aus, um die Option zum Abfragen der Tabelle aufzurufen. Eine SELECT-Anweisung wird in einem neuen Editor-Tab 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;

AlloyDB-Dienstkonto die Rolle „Vertex AI User“ 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

Für Computer ist es viel einfacher, Zahlen als Text zu verarbeiten. Ein Einbettungssystem wandelt Text in eine Reihe von Gleitkommazahlen um, die als Vektoreinbettungen bezeichnet werden. Diese sollen den Text unabhängig von seiner Formulierung, der verwendeten Sprache usw. darstellen.

Ein Standort am Meer könnte beispielsweise als „am Wasser“, „direkt am Strand“, „vom Zimmer zum Meer laufen“, „sur la mer“, „на берегу океана“ usw. bezeichnet werden. Diese Begriffe sehen alle unterschiedlich aus, aber ihre semantische Bedeutung oder in der Terminologie des maschinellen Lernens ihre Einbettungen sollten sehr nah beieinander liegen.

Nachdem die Daten und der Kontext bereit sind, führen wir den SQL-Code aus, um die Einbettungen der Produktbeschreibung in der Tabelle im Feld embedding hinzuzufügen. Es gibt verschiedene Einbettungsmodelle, die Sie verwenden können. Wir verwenden text-embedding-005 von Vertex AI. Achten Sie darauf, im gesamten Projekt dasselbe Einbettungsmodell zu verwenden.

Hinweis: Wenn Sie ein altes Google Cloud-Projekt verwenden, müssen Sie möglicherweise weiterhin ältere Versionen des Modelle für Texteinbettungen wie „textembedding-gecko“ verwenden.

Kehren Sie zum Tab „AlloyDB Studio“ 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. Führen Sie die SELECT-Anweisung noch einmal aus, um die Änderungen zu sehen.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

Dadurch sollte der Einbettungsvektor für die Spielzeugbeschreibung zurückgegeben werden, der wie ein Array von Gleitkommazahlen aussieht:

Hinweis:Bei neu erstellten Google Cloud-Projekten im Rahmen des kostenlosen Kontingents kann es zu Kontingentproblemen bei der Anzahl der Einbettungsanfragen pro Sekunde für die Einbettungsmodelle kommen. Wir empfehlen, eine Filterabfrage für die ID zu verwenden und dann beim Generieren des Einbettungsvektors selektiv 1–5 Datensätze auszuwählen.

6. Vektorsuche durchführen

Nachdem die Tabelle, die Daten und die Einbettungen 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.“

Mit der folgenden Abfrage können Sie Übereinstimmungen dafür finden:

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 Anfrage genauer an:

In dieser Abfrage

1. Der Suchtext des Nutzers lautet: „I want a white plush teddy bear toy with a floral pattern.“
2. Wir wandeln sie in der Methode embedding() mit dem Modell text-embedding-005 in Einbettungen um. Dieser Schritt sollte Ihnen nach dem letzten Schritt, in dem wir die Einbettungsfunktion auf alle Elemente in der Tabelle angewendet haben, bekannt vorkommen.
3. „<=>“ steht für die Verwendung der Distanzmethode KOSINUS-ÄHNLICHKEIT. Alle verfügbaren Ähnlichkeitsmessungen finden Sie in der Dokumentation von pgvector.
4. Wir konvertieren das Ergebnis der Einbettungsmethode in den Vektortyp, damit es mit den in der Datenbank gespeicherten Vektoren kompatibel ist.
5. LIMIT 5 gibt an, dass wir 5 nächste Nachbarn für den Suchtext extrahieren möchten.

Das Ergebnis sieht so aus:

Wie Sie in den Ergebnissen sehen können, sind die Übereinstimmungen sehr nah am Suchtext. Ändern Sie den Text, um zu sehen, wie sich die Ergebnisse ändern.

7. AlloyDB für die Toolbox-Interaktion vorbereiten

Bevor wir die Toolbox einrichten, aktivieren wir die öffentliche IP-Konnektivität in unserer AlloyDB-Instanz, damit das neue Tool auf die Datenbank zugreifen kann.

1. Rufen Sie Ihre AlloyDB-Instanz auf, klicken Sie auf „BEARBEITEN“ und rufen Sie die Seite „Primäre Instanz bearbeiten“ auf.
2. Rufen Sie den Bereich „Öffentliche IP-Adresse“ auf, setzen Sie ein Häkchen bei „Öffentliche IP-Adresse aktivieren“ und geben Sie die IP-Adresse Ihres Cloud Shell-Computers ein.
3. Wenn Sie die IP-Adresse Ihrer Cloud Shell-Maschine abrufen möchten, rufen Sie das Cloud Shell-Terminal auf und geben Sie „ifconfig“ ein. Suchen Sie im Ergebnis nach der eth0-Inet-Adresse und ersetzen Sie die letzten beiden Ziffern durch 0.0 mit einer Maskengröße von „/16“. Ein Beispiel wäre „XX.XX.0.0/16“, wobei XX für Zahlen steht.
4. Fügen Sie diese IP-Adresse auf der Seite zum Bearbeiten der Instanz in das Textfeld „Netzwerke“ unter „Autorisierte externe Netzwerke“ ein.

5. Klicken Sie anschließend auf „UPDATE INSTANCE“ (Instanz aktualisieren).

Das kann einige Minuten dauern.

8. Installation der MCP Toolbox for Databases

1. Sie können einen Projektordner erstellen, in dem die Tool-Details gespeichert werden. Da wir in diesem Fall mit Daten eines Spielzeuggeschäfts arbeiten, erstellen wir einen Ordner mit dem Namen „toystore“ und wechseln in diesen Ordner. Rufen Sie das Cloud Shell-Terminal auf und prüfen Sie, ob Ihr Projekt ausgewählt ist und im Prompt des Terminals angezeigt wird. Führen Sie den folgenden Befehl in Ihrem Cloud Shell-Terminal aus:

mkdir toystore

cd toystore

2. 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

3. Wechseln Sie zum Cloud Shell-Editor. Maximieren Sie den neu erstellten Ordner „toystore“ und erstellen Sie eine neue Datei namens „tools.yaml“. Kopieren Sie den folgenden Inhalt. 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 wird nur die beste Übereinstimmung mit dem Suchtext des Nutzers (Beschreibung des benutzerdefinierten Spielzeugs) ermittelt und der Preis zurückgegeben. Sie können die Abfrage auch so ändern, dass der Durchschnittspreis der fünf Spielzeuge mit der höchsten Übereinstimmung ermittelt wird:

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;

Die Tool-Definition ist abgeschlossen.

Weitere Informationen zum Konfigurieren von „tools.yaml“ finden Sie in dieser Dokumentation.

4. Wechseln Sie zum Cloud Shell-Terminal und geben Sie den folgenden Befehl ein, um den Toolbox-Server mit Ihrer Toolkonfiguration zu starten:

./toolbox --tools_file "tools.yaml"

5. Wenn Sie den Server jetzt in einem Webvorschau-Modus in der Cloud öffnen, sollte der Toolbox-Server mit Ihrem neuen Tool mit dem Namen get-toy-price. ausgeführt werden.

9. Cloud Run-Bereitstellung der MCP Toolbox for Databases

Wir stellen es in Cloud Run bereit, damit Sie es tatsächlich verwenden können.

1. Folgen Sie der Anleitung auf dieser Seite Schritt für Schritt, bis Sie den Befehl gcloud run deploy toolbox erreichen, der im Abschnitt „In Cloud Run bereitstellen“ im dritten Punkt aufgeführt ist. Sie benötigen die erste Option und nicht die zweite, die für die Verwendung einer VPC-Netzwerkmethode vorgesehen ist.
2. Nach erfolgreicher Bereitstellung erhalten Sie einen bereitgestellten Cloud Run-Endpunkt Ihres Toolbox-Servers. Testen Sie es mit einem CURL-Befehl.

Tipps:

Folgen Sie der Anleitung auf der Seite genau.

Sie können das neu bereitgestellte Tool jetzt in Ihrer Agent-Anwendung verwenden.

10. App mit der MCP-Toolbox für Datenbanken verbinden

In diesem Teil erstellen wir eine kleine Anwendung, um Ihr Tool zu testen und eine Antwort zu erhalten.

1. Rufen Sie Google Colab auf und öffnen Sie ein neues Notebook.
2. 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)

3. Das Ergebnis sollte so aussehen:

Das Tool wird explizit in einer Python-Anwendung aufgerufen, die das Toolkit verwendet. toolbox-langchain.

4. Wenn Sie dieses Tool verwenden und es an einen Agent in einer LangGraph-integrierten Anwendung binden möchten, können Sie das ganz einfach mit dem langgraph-Toolkit tun.
5. Code-Snippets

11. Ab in die Cloud!!!

Wir verpacken dieses Python-Code-Snippet in eine Cloud Run Functions-Funktion, um es serverlos zu machen.

1. Kopieren Sie den Quellcode aus dem Code-Repository-Ordner, um ihn in Cloud Functions zu verwenden.
2. Rufen Sie die Cloud Run Functions-Konsole auf und klicken Sie auf „FUNKTION ERSTELLEN“.
3. Lassen Sie die Demoanwendung nicht authentifiziert und wählen Sie auf der nächsten Seite die Python 3.11-Laufzeit aus.
4. Kopieren Sie die Dateien main.py und requirements.txt aus dem im ersten Schritt freigegebenen Quell-Repository und fügen Sie sie in die entsprechenden Dateien ein.
5. Ersetzen Sie die Server-URL in der Datei „main.py“ durch Ihre Server-URL.
6. Stellen Sie die Funktion bereit. Sie haben jetzt einen REST-Endpunkt, über den in der Webanwendung des Spielzeugladens auf das Tool für die Preisvorhersage zugegriffen werden kann.
7. Ihr Endpunkt sollte so aussehen:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

2. Sie können die Funktion 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"

}

3. Klicken Sie auf „FUNKTION TESTEN“ oder führen Sie die Funktion im Cloud Shell-Terminal aus. Das Ergebnis sollte rechts unter dem Titel „Ausgabe“ angezeigt werden:

12. Glückwunsch

Glückwunsch! Sie haben ein robustes und wirklich modulares Tool erstellt, das mit Datenbanken, Plattformen und Orchestrierungs-Frameworks für generative KI interagieren kann, um Ihre agentische Anwendung zu erstellen.