1. Übersicht
In diesem Codelab erstellen Sie eine skalierbare Suchanwendung für Wissensdatenbanken. Anstatt eine komplexe ETL-Pipeline mit Python-Skripts und Schleifen zu verwalten, um Vektoreinbettungen zu generieren, verwenden Sie AlloyDB AI, um die Einbettungsgenerierung nativ in der Datenbank mit einem einzigen SQL-Befehl zu verarbeiten.
Aufgaben
Eine leistungsstarke, „durchsuchbare“ Datenbankanwendung für Wissensdatenbanken.
Lerninhalte
Nach Abschluss können Sie:
- AlloyDB-Cluster bereitstellen und KI-Erweiterungen aktivieren
- Synthetische Daten (mehr als 50.000 Zeilen) mit SQL generieren
- Vektoreinbettungen für das gesamte Dataset mithilfe der Batchverarbeitung füllen.
- Richten Sie inkrementelle Echtzeit-Trigger ein, um neue Daten automatisch einzubetten.
- Führen Sie eine Hybridsuche (Vektor- und SQL-Filter) nach „Flexing Context“ durch.
Voraussetzungen
2. Hinweis
Projekt erstellen
- Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
- Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.
- Sie verwenden die Cloud Shell, eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird. Klicken Sie oben in der Google Cloud Console auf „Cloud Shell aktivieren“.
- Sobald die Verbindung mit der Cloud Shell hergestellt ist, prüfen Sie mit dem folgenden Befehl, ob Sie bereits authentifiziert sind und für das Projekt schon Ihre Projekt-ID eingestellt 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: Folgen Sie dem Link und aktivieren Sie die APIs.
Alternativ können Sie dafür den gcloud-Befehl verwenden. Informationen zu gcloud-Befehlen und ihrer Verwendung finden Sie in der Dokumentation.
gcloud services enable \
alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com
Fallstricke und Fehlerbehebung
Das „Ghost Project“-Syndrom | Sie haben |
Die Abrechnungsbarrikade | Sie haben das Projekt aktiviert, aber das Rechnungskonto vergessen. AlloyDB ist eine leistungsstarke Engine, die nicht startet, wenn der „Tank“ (Abrechnung) leer ist. |
API-Propagationsverzögerung | Sie haben auf „APIs aktivieren“ geklickt, aber in der Befehlszeile wird immer noch |
Quota Quags | Wenn Sie ein brandneues Testkonto verwenden, erreichen Sie möglicherweise ein regionales Kontingent für AlloyDB-Instanzen. Wenn |
„Versteckter“ Dienst-Agent | Manchmal wird dem AlloyDB-Dienst-Agent die Rolle |
3. Datenbank einrichten
In diesem Lab verwenden wir AlloyDB als Datenbank für die Testdaten. Es verwendet Cluster, 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 eigentlichen Daten.
Erstellen Sie einen AlloyDB-Cluster, eine AlloyDB-Instanz und eine AlloyDB-Tabelle, in die das Test-Dataset geladen wird.
- Klicken Sie auf den Button oder kopieren Sie den Link unten in den Browser, in dem Sie mit dem Google Cloud Console-Nutzer angemeldet sind.
- Sobald dieser Schritt abgeschlossen ist, wird das Repository in Ihren lokalen Cloud Shell-Editor geklont. Sie können dann den folgenden Befehl im Projektordner ausführen (achten Sie darauf, dass Sie sich im Projektverzeichnis befinden):
sh run.sh
- Verwenden Sie jetzt die Benutzeroberfläche, indem Sie auf den Link im Terminal oder auf den Link „Vorschau im Web“ im Terminal klicken.
- Geben Sie die Projekt-ID, den Cluster- und den Instanznamen ein, um loszulegen.
- Während die Logs durchlaufen, können Sie sich einen Kaffee holen und hier nachlesen, wie das im Hintergrund funktioniert. Das kann etwa 10–15 Minuten dauern.
Fallstricke und Fehlerbehebung
Das Problem mit der Geduld | Datenbankcluster sind eine komplexe Infrastruktur. Wenn Sie die Seite aktualisieren oder die Cloud Shell-Sitzung beenden, weil sie „hängt“, kann es sein, dass eine „Geisterinstanz“ entsteht, die nur teilweise bereitgestellt wurde und sich ohne manuelles Eingreifen nicht löschen lässt. |
Regionen stimmen nicht überein | Wenn Sie Ihre APIs in |
Zombie-Cluster | Wenn Sie zuvor denselben Namen für einen Cluster verwendet und ihn nicht gelöscht haben, wird im Script möglicherweise angezeigt, dass der Clustername bereits vorhanden ist. Clusternamen müssen innerhalb eines Projekts eindeutig sein. |
Cloud Shell-Zeitüberschreitung | Wenn Ihre Kaffeepause 30 Minuten dauert, wird Cloud Shell möglicherweise in den Ruhemodus versetzt und der |
4. Schemabereitstellung
In diesem Schritt behandeln wir Folgendes:
Sobald Ihr AlloyDB-Cluster und Ihre Instanz ausgeführt werden, rufen Sie den SQL-Editor von AlloyDB Studio auf, um die KI-Erweiterungen zu aktivieren und das Schema bereitzustellen.
Möglicherweise müssen Sie warten, bis die Instanz erstellt wurde. Melden Sie sich dann mit den Anmeldedaten, die Sie beim Erstellen des Clusters erstellt haben, in AlloyDB an. Verwenden Sie die folgenden Daten für die Authentifizierung bei PostgreSQL:
- Nutzername: „
postgres“ - Datenbank: „
postgres“ - Passwort: „
alloydb“ (oder das Passwort, das Sie beim Erstellen festgelegt haben)
Nachdem Sie sich erfolgreich in AlloyDB Studio authentifiziert haben, können Sie SQL-Befehle im Editor eingeben. Sie können mehrere Editor-Fenster hinzufügen, indem Sie auf das Pluszeichen rechts neben dem letzten Fenster klicken.
Sie geben Befehle für AlloyDB in Editorfenstern ein und verwenden nach Bedarf die Optionen „Ausführen“, „Formatieren“ und „Löschen“.
Erweiterungen aktivieren
Für die Erstellung 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 abzurufen. 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;
Tabelle erstellen
Wir benötigen ein Dataset, um die Skalierung zu demonstrieren. Anstatt eine CSV-Datei zu importieren, generieren wir mit SQL sofort 50.000 Zeilen synthetischer „Hilfeartikel“.
Sie können eine Tabelle mit der folgenden DDL-Anweisung in AlloyDB Studio erstellen:
-- 1. Create the table
CREATE TABLE help_articles (
id SERIAL PRIMARY KEY,
title TEXT,
category TEXT,
product_version TEXT,
content_body TEXT,
embedding vector(768) -- Dimension for text-embedding-005
);
-- 2. Generate 50,000 rows of synthetic data
INSERT INTO help_articles (title, category, product_version, content_body)
SELECT
'Help Article ' || i,
CASE
WHEN i % 3 = 0 THEN 'Billing'
WHEN i % 3 = 1 THEN 'Technical'
ELSE 'General'
END,
CASE
WHEN i % 2 = 0 THEN '2.0'
ELSE '1.0'
END,
'This article covers common issues regarding ' ||
CASE
WHEN i % 3 = 0 THEN 'payment failures, invoice disputes, and credit card updates.'
WHEN i % 3 = 1 THEN 'connection timeouts, latency issues, and API errors.'
ELSE 'account profile settings, password resets, and user roles.'
END
FROM generate_series(1, 50000) AS i;
In der Spalte item_vector werden die Vektorwerte des Texts gespeichert.
Daten überprüfen:
SELECT count(*) FROM help_articles;
-- Output: 50000
Datenbank-Flags aktivieren
Rufen Sie die Konsole für die Instanzkonfiguration auf, klicken Sie auf „Primäre Instanz bearbeiten“, rufen Sie „Erweiterte Konfiguration“ auf und klicken Sie auf „Datenbank-Flags hinzufügen“.
Wenn nicht, geben Sie sie im Drop-down-Menü „Flags“ ein, setzen Sie sie auf „EIN“ und aktualisieren Sie die Instanz.
Falls nicht, geben Sie sie im Drop-down-Menü „Flags“ ein, setzen Sie sie auf „EIN“ und aktualisieren Sie die Instanz.
Schritte zum Konfigurieren von Datenbank-Flags:
- Rufen Sie in der Google Cloud Console die Seite „Cluster“ auf.
- Klicken Sie in der Spalte Ressourcenname auf einen Cluster.
- Rufen Sie auf der Seite Übersicht den Abschnitt Instanzen in Ihrem Cluster auf, wählen Sie eine Instanz aus und klicken Sie dann auf Bearbeiten.
- Fügen Sie ein Datenbank-Flag zu Ihrer Instanz hinzu, ändern oder löschen Sie es:
Markierung hinzufügen
- Wenn Sie Ihrer Instanz ein Datenbank-Flag hinzufügen möchten, klicken Sie auf „Flag hinzufügen“.
- Wählen Sie ein Flag aus der Liste „Neues Datenbank-Flag“ aus.
- Geben Sie einen Wert für das Flag an.
- Klicken Sie auf "Fertig".
- Klicken Sie auf Instanz aktualisieren.
- Prüfen Sie, ob die Erweiterung „google_ml_integration“ die Version 1.5.2 oder höher hat:
Führen Sie den folgenden Befehl aus, um die Version Ihrer Erweiterung zu prüfen:
SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
Wenn Sie die Erweiterung auf eine höhere Version aktualisieren müssen, verwenden Sie den folgenden Befehl:
ALTER EXTENSION google_ml_integration UPDATE;
Berechtigung gewähren
- Wenn Sie einem Nutzer die Verwaltung der automatischen Einbettungsgenerierung ermöglichen möchten, gewähren Sie die Berechtigungen INSERT, UPDATE und DELETE für die Tabellen google_ml.embed_gen_progress und google_ml.embed_gen_settings:
GRANT INSERT, UPDATE, DELETE ON google_ml.embed_gen_progress TO postgres;
„postgres“ ist der NUTZERNAME, für den die Berechtigungen gewährt werden.
- Führen Sie die folgende Anweisung aus, um die Berechtigung zum Ausführen der Funktion „embedding“ zu gewähren:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Dem AlloyDB-Dienstkonto die Rolle „Vertex AI User“ gewähren
Gewähren Sie dem AlloyDB-Dienstkonto (das so aussieht: service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com) in der Google Cloud IAM-Konsole Zugriff auf die Rolle „Vertex AI-Nutzer“. PROJECT_NUMBER enthält Ihre Projektnummer.
Alternativ können Sie den folgenden Befehl im Cloud Shell-Terminal ausführen:
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"
Fallstricke und Fehlerbehebung
Die „Passwort-Amnesie“-Schleife | Wenn Sie die Einrichtung mit einem Klick verwendet haben und sich nicht mehr an Ihr Passwort erinnern, rufen Sie in der Console die Seite mit den grundlegenden Informationen zur Instanz auf und klicken Sie auf „Bearbeiten“, um das Passwort für |
Fehler „Erweiterung nicht gefunden“ | Wenn |
5. Die „One-Shot“-Vektorgenerierung
Das ist der Kern des Labs. Anstatt eine Python-Schleife zu schreiben,um diese 50.000 Zeilen zu verarbeiten, verwenden wir die Funktion ai.initialize_embeddings.
Dieser einzelne Befehl bewirkt zwei Dinge:
- Füllt alle vorhandenen Zeilen aus.
- Erstellt einen Trigger, um zukünftige Zeilen automatisch einzubetten.
Führen Sie die folgende SQL-Anweisung im AlloyDB-Abfrageeditor aus:
CALL ai.initialize_embeddings(
model_id => 'text-embedding-005',
table_name => 'help_articles',
content_column => 'content_body',
embedding_column => 'embedding',
incremental_refresh_mode => 'transactional'
);
Einbettungen prüfen
Prüfen Sie, ob die Spalte embedding jetzt ausgefüllt ist:
SELECT id, left(content_body, 30), substring(embedding::text, 1, 30) as vector_partial
FROM help_articles;
Das Ergebnis sollte in etwa so aussehen:
Was ist gerade passiert?
- Backfill im großen Maßstab: Die Funktion durchsucht automatisch Ihre vorhandenen 50.000 Zeilen und generiert Einbettungen über Vertex AI.
- Automatisierung: Wenn Sie „incremental_refresh_mode => 'transactional'“ festlegen, richtet AlloyDB die internen Trigger automatisch ein. Für jede neue Zeile, die in „help_articles“ eingefügt wird, wird sofort eine Einbettung generiert.
- Optional können Sie „incremental_refresh_mode => ‚None‘“ festlegen, damit die Anweisung nur Bulk-Updates ausführt und Sie „ai.refresh_embeddings()“ manuell aufrufen können, um die Einbettungen aller Zeilen zu aktualisieren.
Sie haben gerade eine Kafka-Warteschlange, einen Python-Worker und ein Migrationsskript durch sechs Zeilen SQL ersetzt. Eine detaillierte offizielle Dokumentation zu allen Attributen finden Sie hier.
Test des Echtzeit-Triggers
Prüfen wir, ob die Automatisierung „Zero Loop“ für neue Daten funktioniert.
- Neue Zeile einfügen:
INSERT INTO help_articles (title, category, product_version, content_body)
VALUES ('New Scaling Guide', 'Technical', '2.0', 'How to scale AlloyDB to millions of transactions.');
- Sofort prüfen:
SELECT embedding FROM help_articles WHERE title = 'New Scaling Guide';
Ergebnis:
Der Vektor sollte sofort generiert werden, ohne dass ein externes Script ausgeführt werden muss.
Batchgröße für die Abstimmung
Derzeit ist die Batchgröße in AlloyDB standardmäßig auf 50 festgelegt. Die Standardeinstellungen funktionieren zwar sofort, aber AlloyDB bietet Nutzern dennoch die Möglichkeit, die perfekte Konfiguration für ihr individuelles Modell und Dataset zu finden.
CALL ai.initialize_embeddings(
model_id => 'text-embedding-005',
table_name => 'help_articles',
content_column => 'content_body',
embedding_column => 'embedding',
incremental_refresh_mode => 'transactional',
batch_size => 20
);
Nutzer müssen sich jedoch der Kontingentlimits bewusst sein, die die Leistung einschränken können. Die empfohlenen AlloyDB-Kontingente finden Sie im Abschnitt „Vorbereitung“ in der Dokumentation.
Fallstricke und Fehlerbehebung
Die IAM-Propagationslücke | Sie haben den IAM-Befehl |
Abweichung bei Vektordimensionen | Die Tabelle |
6. Flexing Context Search
Jetzt führen wir eine Hybridsuche durch. Wir kombinieren semantisches Verständnis (Vektor) mit Geschäftslogik (SQL-Filter).
Führen Sie diese Abfrage aus, um Abrechnungsprobleme speziell für Produktversion 2.0 zu finden:
SELECT
title,
left(content_body, 100) as content_snippet,
1 - (embedding <=> embedding('text-embedding-005', 'Invoice did not go through')::vector) as relevance
FROM help_articles
WHERE category = 'Billing' -- Hard SQL Filter
AND product_version = '2.0' -- Hard SQL Filter
ORDER BY relevance DESC
LIMIT 5;
Das ist Flexing Context. Die Suche „passt sich an“, um die Absicht des Nutzers („Abrechnungsprobleme“) zu verstehen, während die starren Geschäftseinschränkungen (Version 2.0) berücksichtigt werden.
Warum dies für Start-ups und Migrationen von Vorteil ist
- Keine Infrastrukturschulden: Sie haben keine separate Vektordatenbank (Pinecone/Milvus) eingerichtet. Sie haben keinen separaten ETL-Job geschrieben. Alles ist in Postgres.
- Echtzeitaktualisierungen: Wenn Sie den Modus „transactional“ verwenden, ist Ihr Suchindex immer auf dem neuesten Stand. Sobald Daten festgeschrieben werden, sind sie vektorbereit.
- Skalierung: AlloyDB basiert auf der Infrastruktur von Google. Es kann Millionen von Vektoren schneller generieren, als es mit Ihrem Python-Script jemals möglich wäre.
Fallstricke und Fehlerbehebung
Leistungsproblem in der Produktion | Problem: Schnell für 50.000 Zeilen. Sehr langsam für 1 Million Zeilen, wenn der Kategoriefilter nicht selektiv genug ist.Lösung:Fügen Sie einen Vektorindex hinzu: Für die Produktion müssen Sie einen Index erstellen:CREATE INDEX ON help_articles USING hnsw (embedding vector_cosine_ops);Indexnutzung prüfen: Führen Sie |
Das „Modellkonflikt“-Desaster | Problem: Sie haben die Spalte mit text-embedding-005 in der CALL-Prozedur initialisiert. Wenn Sie versehentlich ein anderes Modell (z.B. text-embedding-004 oder ein OSS-Modell) in der SELECT-Abfragefunktion embedding('model-name', ...) verwenden, stimmen die Dimensionen möglicherweise überein (768), aber der Vektorraum ist völlig anders.Die Abfrage wird ohne Fehler ausgeführt, aber die Ergebnisse sind völlig irrelevant (Relevanzwerte sind unbrauchbar).Fehlerbehebung:Achten Sie darauf, dass die model_id in ai.initialize_embeddings genau mit der model_id in Ihrer SELECT-Abfrage übereinstimmt. |
Das Ergebnis „Silent Empty“ (Überfilterung) | Problem: Die Hybridsuche ist ein „AND“-Vorgang. Dafür sind Semantische Übereinstimmung UND SQL-Übereinstimmung erforderlich. Wenn ein Nutzer nach „Hilfe zur Abrechnung“ sucht, die Spalte
|
4. Berechtigungs-/Kontingentfehler (500-Fehler) | Problem:Die Funktion
|
5. Null-Einbettungen | Problem:Wenn Sie Daten einfügen, bevor das Modell vollständig initialisiert ist, oder wenn der Hintergrund-Worker fehlschlägt, enthalten einige Zeilen möglicherweise
|
7. Bereinigen
Vergessen Sie nicht, den AlloyDB-Cluster und die AlloyDB-Instanz zu löschen, wenn Sie dieses Lab abgeschlossen haben.
Der Cluster und seine Instanzen sollten bereinigt werden.
8. Glückwunsch
Sie haben erfolgreich eine skalierbare Suchanwendung für die Wissensdatenbank erstellt. Anstatt eine komplexe ETL-Pipeline mit Python-Skripts und Schleifen zu verwalten, um Vektoreinbettungen zu generieren, haben Sie AlloyDB AI verwendet, um die Einbettungsgenerierung nativ in der Datenbank mit einem einzigen SQL-Befehl zu verarbeiten.
Worüber haben wir gesprochen?
- Wir haben die „Python-For-Schleife“ für die Datenverarbeitung abgeschafft.
- Wir haben mit einem einzigen SQL-Befehl 50.000 Vektoren generiert.
- Wir haben die zukünftige Vektorgenerierung mit Triggern automatisiert.
- Wir haben eine hybride Suche durchgeführt.
Nächste Schritte
- Probieren Sie das mit Ihrem eigenen Dataset aus.
- AlloyDB AI-Dokumentation ansehen
- Weitere Workshops finden Sie auf der Website Code Vipassana.