Toolbox für Ihre Gen AI- und Agentic-Anwendungen in AlloyDB installieren und einrichten

1. Übersicht

Die Gen AI Toolbox for Databases ist ein Open-Source-Server von Google, mit dem sich Gen AI-Tools zum Interagieren 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 Tools für generative KI erstellen, mit denen Ihre Kundenservicemitarbeiter auf Daten in Ihrer Datenbank zugreifen können. Der Toolbox bietet folgende Vorteile:

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

Bessere Leistung:Best Practices wie Verbindungs-Pooling und Authentifizierung.

Erhöhte Sicherheit:Integrierte Authentifizierung für einen sicheren 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 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 bereitstellen zu müssen.

Aufgaben

In diesem Lab erstellen Sie eine Anwendung, mit der über ein Tool eine einfache Datenbankabfrage (AlloyDB) ausgeführt wird, die von Ihrem Bot oder der generativen KI-Anwendung aufgerufen werden kann. Dazu gehen Sie so vor:

  1. Toolbox installieren
  2. Tool, das eine Aufgabe in AlloyDB ausführen soll, auf dem Toolbox-Server einrichten
  3. Toolbox 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 Abrechnung (siehe Schritte im nächsten Abschnitt).

2. Hinweis

Projekt erstellen

  1. Wählen Sie in der Google Cloud Console auf der Seite der 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“.

Bild der Schaltfläche „Cloud Shell aktivieren“

  1. Nachdem 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
  1. 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
  1. Wenn Ihr Projekt nicht festgelegt ist, verwenden Sie den folgenden Befehl, um es festzulegen:
gcloud config set project <YOUR_PROJECT_ID>
  1. Aktivieren Sie die erforderlichen APIs, indem Sie die folgenden Befehle nacheinander in Ihrem Cloud Shell-Terminal ausführen:

Es gibt auch einen einzelnen Befehl, um die folgenden Schritte auszuführen. Wenn Sie jedoch ein Testkonto verwenden, kann es zu Kontingentproblemen kommen, wenn Sie diese Funktionen im Bulk-Verfahren aktivieren. Deshalb werden die Befehle einzeln pro Zeile eingegeben.

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

Als Alternative zum gcloud-Befehl können Sie ü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. Alle Ressourcen wie Datenbanken und Protokolle werden in Clustern gespeichert. Jeder Cluster hat eine primäre Instanz, die einen Zugriffspunkt auf die Daten bietet. Die tatsächlichen Daten werden in Tabellen gespeichert.

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

Cluster und Instanz erstellen

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

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

  1. Wählen Sie auf dieser Seite CLUSTER ERSTELLEN aus:

f76ff480c8c889aa.png

  1. Daraufhin wird ein Bildschirm wie der unten gezeigte 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“

538dba58908162fb.png

  1. Wenn Sie das Standardnetzwerk auswählen, wird ein Bildschirm wie der unten angezeigt. Wählen Sie VERKNÜPFUNG EINSTELLEN aus.
    7939bbb6802a91bf.png
  2. Wählen Sie dort „Automatisch zugewiesenen IP-Bereich verwenden“ aus und klicken Sie auf „Weiter“. Nachdem Sie sich die Informationen angesehen haben, wählen Sie VERBINDUNG ERSTELLEN aus. 768ff5210e79676f.png
  3. Sobald Ihr Netzwerk eingerichtet ist, können Sie mit dem Erstellen des Clusters fortfahren. Klicken Sie auf „CLUSTER ERSTEHEN“, um die Einrichtung des Clusters abzuschließen (siehe unten):

e06623e55195e16e.png

Ändern Sie die Instanz-ID in „

vector-instance"

.

Die Clustererstellung dauert etwa 10 Minuten. Wenn der Vorgang erfolgreich war, sollte ein Bildschirm mit einer Übersicht über den gerade erstellten Cluster angezeigt werden.

4. Datenaufnahme

Jetzt fügen Sie eine Tabelle mit den Daten zum Geschäft hinzu. Rufen Sie AlloyDB auf, wählen Sie den primären Cluster und dann AlloyDB Studio aus:

847e35f1bf8a8bd8.png

Möglicherweise müssen Sie warten, bis die Instanz erstellt wurde. Melden Sie sich anschließend mit den Anmeldedaten 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 in AlloyDB Studio authentifiziert haben, können Sie SQL-Befehle in den Editor eingeben. Über das Pluszeichen rechts neben dem letzten Fenster können Sie weitere Editorfenster hinzufügen.

91a86d9469d499c4.png

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

Erweiterungen aktivieren

Für diese App verwenden wir die Erweiterungen pgvector und google_ml_integration. Mit der pgvector-Erweiterung können Sie Vektoreinbettungen speichern und darin 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 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)) ;

Wenn der Befehl erfolgreich ausgeführt wurde, sollte die Tabelle in der Datenbank angezeigt werden.

Daten aufnehmen

Für dieses Lab haben wir Testdaten mit etwa 72 Einträgen 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/Einfügeanweisungen von dort, fügen Sie sie in einen leeren Editortab ein und wählen Sie „AUSFÜHREN“ aus.

Maximieren Sie den Bereich „Explorer“, bis Sie die Tabelle „apparels“ sehen, um den Tabelleninhalt zu sehen. Klicken Sie auf das Dreipunkt-Menü ⋮, um die Option „Tabelle abfragen“ zu sehen. Eine SELECT-Anweisung wird in einem neuen Editor-Tab geöffnet.

cfaa52b717f9aaed.png

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;

Dem 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 zu verarbeiten als Text. Ein Einbettungssystem wandelt Text in eine Reihe von Gleitkommazahlen um, die als Vektoreinbettungen bezeichnet werden. Diese sollen den Text unabhängig von der Formulierung und Sprache darstellen.

Ein Ort am Meer kann beispielsweise „am Wasser“, „Strand“, „Fußweg vom Zimmer zum Meer“, „sur la mer“ oder „на берегу океана“ heißen. 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 Daten und Kontext bereit sind, führen wir die SQL-Abfrage aus, um der Tabelle im Feld embedding die Einbettungen der Produktbeschreibung 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 Text-Embedding-Modells 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, der wie ein Array von Gleitkommazahlen aussieht, für die Spielzeugbeschreibung zurückgegeben werden, wie unten dargestellt:

7d32f7cd7204e1f3.png

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

6. Vektorsuche ausführen

Nachdem Tabelle, Daten und Einbettungen bereit sind, führen wir die Echtzeit-Vektorsuche für den Suchtext des Nutzers aus.

Angenommen, der Nutzer stellt folgende Frage:

„I want a white plush teddy bear toy with a floral pattern.“

Mit der folgenden Abfrage können Sie entsprechende Übereinstimmungen 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 Abfrage genauer an:

In dieser Abfrage:

  1. Der Suchbegriff des Nutzers lautet: „I want a white plush teddy bear toy with a floral pattern.“
  2. Wir konvertieren sie in der Methode embedding() mit dem Modell text-embedding-005 in Einbettungen. Dieser Schritt sollte Ihnen nach dem letzten Schritt bekannt vorkommen, in dem wir die Einbettungsfunktion auf alle Elemente in der Tabelle angewendet haben.
  3. „<=>“ steht für die Verwendung der Distanzmethode KOSINISCHE ÄHNLICHKEIT. Alle verfügbaren Ähnlichkeitsmaße 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. Mit LIMIT 5 geben wir an, dass wir 5 nächste Nachbarn für den Suchtext extrahieren möchten.

Das Ergebnis sieht so aus:

fa7f0fc3a4c68804.png

Wie Sie in den Ergebnissen sehen, stimmen die Übereinstimmungen ziemlich genau mit dem Suchtext überein. Ändern Sie den Text und sehen Sie, wie sich die Ergebnisse ändern.

7. AlloyDB für die Toolbox-Interaktion vorbereiten

Als Vorbereitung auf die Einrichtung der Toolbox aktivieren wir die öffentliche IP-Verbindung 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 Sie gelangen zur Seite „Primäre Instanz bearbeiten“.
  2. Gehen Sie zum Abschnitt „Öffentliche IP-Verbindung“, setzen Sie ein Häkchen in das Kästchen „Öffentliche IP-Adresse aktivieren“ und geben Sie die IP-Adresse Ihres Cloud Shell-Computers ein.
  3. Wenn Sie die IP-Adresse Ihres Cloud Shell-Rechners abrufen möchten, geben Sie im Cloud Shell-Terminal „ifconfig“ ein. Ermitteln Sie in den Ergebnissen die Inet-Adresse von eth0 und ersetzen Sie die letzten beiden Ziffern durch 0.0 mit einer Maskengröße von „/16“. Beispiel: „XX.XX.0.0/16“, wobei XX für Zahlen steht.
  4. Fügen Sie diese IP-Adresse in das Textfeld „Netzwerke“ auf der Seite „Instanz bearbeiten“ unter „Autorisierte externe Netzwerke“ ein.

5f6e60e8dec2cea1.png

  1. Klicken Sie auf AKTUALISIEREN.

Das kann einige Minuten dauern.

8. Toolbox installieren

  1. Sie können einen Projektordner zum Speichern der Tooldetails erstellen. Da wir in diesem Fall mit Daten eines Spielzeuggeschäfts arbeiten, erstellen wir einen Ordner mit dem Namen „Spielzeuggeschäft“ und wechseln zu ihm. Rufen Sie das Cloud Shell-Terminal auf und prüfen Sie, ob Ihr Projekt ausgewählt und im Prompt des Terminals angezeigt wird. Führen Sie in Ihrem Cloud Shell-Terminal den folgenden Befehl aus:
mkdir toystore

cd toystore
  1. Führen Sie den folgenden Befehl aus, um die Toolbox in Ihrem 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
  1. 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 der am besten passende Treffer für den Suchtext des Nutzers (Beschreibung des benutzerdefinierten Spielzeugs) ermittelt und der Preis zurückgegeben. Sie können sie auch so ändern, dass der Durchschnittspreis der fünf am besten passenden Spielzeuge 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 Tooldefinition ist fertig.

Weitere Informationen zur Konfiguration von tools.yaml finden Sie in dieser Dokumentation.

  1. 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"
  1. Wenn Sie den Server jetzt in der Cloud im Webvorschaumodus öffnen, sollte der Toolbox-Server mit Ihrem neuen Tool namens get-toy-price. angezeigt werden.

9. Cloud Run-Bereitstellung der Toolbox

Stellen wir es in Cloud Run bereit, damit Sie es verwenden können.

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

Sie können das neu bereitgestellte Tool jetzt in Ihrer Agenturanwendung verwenden.

10. App mit Toolbox verbinden

In diesem Teil erstellen wir eine kleine Anwendung, um Ihr Tool zu testen, um mit den Anforderungen der Anwendung zu interagieren und eine Antwort abzurufen.

  1. Rufen Sie Google Colab auf und öffnen Sie ein neues Notebook.
  2. Führen Sie in Ihrem Notebook Folgendes aus:
pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)
  1. Das Ergebnis sollte in etwa so aussehen:

5074f209a86c4f15.png

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

  1. Wenn Sie dieses Tool verwenden und in einer in LangGraph integrierten Anwendung an einen Kundenservicemitarbeiter binden möchten, können Sie das ganz einfach mit dem langgraph-Toolkit tun.
  2. Weitere Informationen finden Sie in den Code-Snippets.

11. In die Cloud!

Um diesen Python-Code in eine serverlose Cloud Run-Funktion einzubetten, gehen wir so vor:

  1. Kopieren Sie den Code aus dem Ordner des Code-Repositorys, um ihn in Cloud Functions hochzuladen.
  2. Rufen Sie die Console für Cloud Run-Funktionen auf und klicken Sie auf „FUNKTION ERSTELLEN“.
  3. Lassen Sie die Authentifizierung für die Demoanwendung deaktiviert 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 in Schritt 1 freigegebenen Quell-Repository und fügen Sie sie in die entsprechenden Dateien ein.
  5. Wenn Sie die Funktion bereitstellen, haben Sie einen REST-Endpunkt für das Preisvorhersagetool, auf den in der Webanwendung des Spielzeuggeschäfts zugegriffen werden kann.
  6. Der Endpunkt sollte so aussehen:

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

  1. Sie können sie direkt in der Cloud Functions-Konsole testen. Rufen Sie dazu den Tab „TESTEN“ auf und geben Sie Folgendes als Anfrageeingabe ein:

{

               "`search`"`:` "`White plush toy`"

}

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

d7ba57cf5e5ca553.png

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.