Erste Schritte mit der Hybridsuche in AlloyDB

1. Einführung

In diesem Codelab erfahren Sie, wie Sie in AlloyDB mit der RUM-Erweiterung (Ranking Update Method) und dem ScaNN-Index (Scalable Nearest Neighbor) eine Hybridsuche durchführen. Dieses Lab ist Teil einer Lab-Sammlung, die sich mit AlloyDB AI-Funktionen befasst. Weitere Informationen

Voraussetzungen

Grundlegende Kenntnisse der Google Cloud Console
Grundkenntnisse in der Befehlszeile und Google Shell

Lerninhalte

AlloyDB-Cluster und primäre Instanz bereitstellen
Verbindung zu AlloyDB über eine Google Compute Engine-VM herstellen
Datenbank erstellen und AlloyDB AI aktivieren
Daten in die Datenbank laden
AlloyDB Studio verwenden
Einbettungen mit Vertex AI generieren
ScaNN-Vektorindex erstellen, um die Vektorsuche zu optimieren
RUM-Erweiterung für die Volltextsuche aktivieren und verwenden
Hybridsuche durchführen, indem Sie Volltextsuche, Vektorsuche und Reciprocal Rank Fusion (RRF) kombinieren

Voraussetzungen

Ein Google Cloud-Konto und ein Google Cloud-Projekt
Ein Webbrowser wie Chrome

2. Einrichtung und Anforderungen

Projekteinrichtung

Melden Sie sich in der Google Cloud Console an. Wenn Sie noch kein Gmail- oder Google Workspace-Konto haben, müssen Sie eines erstellen.

Verwenden Sie stattdessen ein privates Konto.

Google Cloud-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.

Abrechnung aktivieren

Sie haben zwei Möglichkeiten, die Abrechnung zu aktivieren. Sie können entweder Ihr privates Abrechnungskonto verwenden oder Guthaben mit den folgenden Schritten einlösen.

Privates Rechnungskonto einrichten

Wenn Sie die Abrechnung mit Google Cloud-Guthaben einrichten, können Sie diesen Schritt überspringen.

Hier können Sie die Abrechnung in der Cloud Console aktivieren, um ein privates Rechnungskonto einzurichten.

Hinweise:

Die Kosten für Cloud-Ressourcen für dieses Lab sollten weniger als 3 $betragen.
Sie können die Schritte am Ende dieses Labs ausführen, um Ressourcen zu löschen und so weitere Kosten zu vermeiden.
Neue Nutzer haben Anspruch auf den kostenlosen Testzeitraum mit einem Guthaben von 300$.

Cloud Shell starten

Während Sie Google Cloud von Ihrem Laptop aus per Fernzugriff nutzen können, wird in diesem Codelab Google Cloud Shell verwendet, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird.

Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und mit den erforderlichen Tools vorinstalliert ist.

Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
Prüfen Sie nach der Verbindung mit Cloud Shell Ihre Authentifizierung:
```
gcloud auth list
```
Prüfen Sie, ob Ihr Projekt konfiguriert ist:
```
gcloud config get project
```

Wenn Ihr Projekt nicht wie erwartet festgelegt ist, legen Sie es fest:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Diese virtuelle Maschine verfügt über sämtliche Entwicklertools, die Sie benötigen. Sie bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und läuft in Google Cloud, was die Netzwerkleistung und Authentifizierung erheblich verbessert. Alle Aufgaben in diesem Codelab können in einem Browser ausgeführt werden. Sie müssen nichts installieren.

3. Hinweis

API aktivieren

Ausgabe:

Wenn Sie AlloyDB, Compute Engine, Netzwerkdienste und Vertex AI verwenden möchten, müssen Sie die entsprechenden APIs in Ihrem Google Cloud-Projekt aktivieren.

APIs aktivieren

Prüfen Sie in Cloud Shell im Terminal, ob Ihre Projekt-ID eingerichtet ist:

gcloud config set project [YOUR-PROJECT-ID]

Legen Sie die Umgebungsvariable PROJECT_ID fest:

PROJECT_ID=$(gcloud config get-value project)

Aktivieren Sie alle erforderlichen APIs:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com

Erwartete Ausgabe

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

Einführung der APIs

Mit der AlloyDB API (alloydb.googleapis.com) können Sie AlloyDB for PostgreSQL-Cluster erstellen, verwalten und skalieren. Er bietet einen vollständig verwalteten, PostgreSQL-kompatiblen Datenbankdienst für anspruchsvolle transaktionale und analytische Arbeitslasten in Unternehmen.
Mit der Compute Engine API (compute.googleapis.com) können Sie virtuelle Maschinen (VMs), nichtflüchtige Speicher und Netzwerkeinstellungen erstellen und verwalten. Sie bietet die erforderliche IaaS-Grundlage (Infrastructure-as-a-Service) für die Ausführung Ihrer Arbeitslasten und das Hosting der zugrunde liegenden Infrastruktur für viele verwaltete Dienste.
Mit der Cloud Resource Manager API (cloudresourcemanager.googleapis.com) können Sie die Metadaten und Konfiguration Ihres Google Cloud-Projekts programmatisch verwalten. Damit können Sie Ressourcen organisieren, IAM-Richtlinien (Identity and Access Management) verarbeiten und Berechtigungen in der gesamten Projekthierarchie validieren.
Mit der Service Networking API (servicenetworking.googleapis.com) können Sie die Einrichtung privater Verbindungen zwischen Ihrem VPC-Netzwerk (Virtual Private Cloud) und den verwalteten Diensten von Google automatisieren. Sie ist insbesondere erforderlich, um den Zugriff über private IP-Adressen für Dienste wie AlloyDB einzurichten, damit diese sicher mit Ihren anderen Ressourcen kommunizieren können.
Mit der Vertex AI API (aiplatform.googleapis.com) können Sie in Ihren Anwendungen Machine-Learning-Modelle erstellen, bereitstellen und skalieren. Sie bietet die einheitliche Schnittstelle für alle KI-Dienste von Google Cloud, einschließlich des Zugriffs auf generative KI-Modelle (wie Gemini) und des benutzerdefinierten Modelltrainings.

Optional können Sie Ihre Standardregion so konfigurieren, dass die Vertex AI-Einbettungsmodelle verwendet werden. Weitere Informationen zu verfügbaren Standorten für Vertex AI Im Beispiel wird die Region „us-central1“ verwendet.

gcloud config set compute/region us-central1

4. AlloyDB bereitstellen

Bevor wir einen AlloyDB-Cluster erstellen, benötigen wir einen verfügbaren privaten IP-Adressbereich in unserer VPC, der von der zukünftigen AlloyDB-Instanz verwendet werden soll. Wenn wir sie nicht haben, müssen wir sie erstellen, sie für die Verwendung durch interne Google-Dienste zuweisen und erst dann können wir den Cluster und die Instanz erstellen.

Privaten IP-Bereich erstellen

Wir müssen die Konfiguration für den Zugriff auf private Dienste in unserer VPC für AlloyDB konfigurieren. Wir gehen hier davon aus, dass das VPC-Standardnetzwerk im Projekt vorhanden ist und für alle Aktionen verwendet wird.

Erstellen Sie den privaten IP-Bereich:

gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default

Erstellen Sie eine private Verbindung mit dem zugewiesenen IP-Bereich:

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default
Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/global/addresses/psa-range].

student@cloudshell:~ (test-project-402417)$ gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default
Operation "operations/pssn.p24-4470404856-595e209f-19b7-4669-8a71-cbd45de8ba66" finished successfully.

student@cloudshell:~ (test-project-402417)$

AlloyDB-Cluster erstellen

In diesem Abschnitt erstellen wir einen AlloyDB-Cluster in der Region „us-central1“.

Legen Sie ein Passwort für den Postgres-Nutzer fest. Sie können ein eigenes Passwort definieren oder eine Zufallsfunktion verwenden, um eines zu generieren.

export PGPASSWORD=`openssl rand -hex 12`

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ export PGPASSWORD=`openssl rand -hex 12`

Notieren Sie sich das PostgreSQL-Passwort für die spätere Verwendung.

echo $PGPASSWORD

Sie benötigen dieses Passwort später, um als Postgres-Nutzer eine Verbindung zur Instanz herzustellen. Schreiben Sie sie auf oder kopieren Sie sie an einen Ort, an dem Sie sie später verwenden können.

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-402417)$ echo $PGPASSWORD
bbefbfde7601985b0dee5723

AlloyDB-Cluster erstellen

Legen Sie die Region und den Namen des AlloyDB-Clusters fest. Wir verwenden die Region „us-central1“ und „alloydb-hybrid-search“ als Clusternamen:

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search

Führen Sie den folgenden Befehl aus, um den Cluster zu erstellen:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION

Erwartete Konsolenausgabe:

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION 
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.

Erstellen Sie in derselben Cloud Shell-Sitzung eine primäre AlloyDB-Instanz für unseren Cluster. Wenn die Verbindung getrennt wird, müssen Sie die Umgebungsvariablen für die Region und den Clusternamen noch einmal definieren.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

Erwartete Konsolenausgabe:

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.

5. Verbindung zu AlloyDB herstellen

AlloyDB wird über eine reine private Verbindung bereitgestellt. Daher benötigen wir eine VM mit installiertem PostgreSQL-Client, um mit der Datenbank zu arbeiten.

GCE-VM bereitstellen

Erstellen Sie eine GCE-VM in derselben Region und VPC wie der AlloyDB-Cluster.

Führen Sie in Cloud Shell Folgendes aus:

export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Erwartete Konsolenausgabe:

student@cloudshell:~ (alloydb-hybrid-search)$ export ZONE=us-central1-a
student@cloudshell:~ (talloydb-hybrid-search)$ export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/zones/us-central1-a/instances/instance-1].
NAME: instance-1
ZONE: us-central1-a
MACHINE_TYPE: n1-standard-1
PREEMPTIBLE: 
INTERNAL_IP: 10.128.0.2
EXTERNAL_IP: 34.71.192.233
STATUS: RUNNING

Postgres-Client installieren

PostgreSQL-Clientsoftware auf der bereitgestellten VM installieren

Stellen Sie eine Verbindung zur VM her.

gcloud compute ssh instance-1 --zone=us-central1-a

Erwartete Konsolenausgabe:

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/alloydb-hybrid-search].                                                                                                                                                         
Updating project ssh metadata...done.                                                                                                                                                                                                                                              
Waiting for SSH key to propagate.
Warning: Permanently added 'compute.5110295539541121102' (ECDSA) to the list of known hosts.
Linux instance-1.us-central1-a.c.gleb-test-short-001-418811.internal 6.1.0-18-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.76-1 (2024-02-01) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$

Installieren Sie den Befehl zum Ausführen der Software in der VM:

sudo apt-get update
sudo apt-get install --yes postgresql-client

Erwartete Konsolenausgabe:

student@instance-1:~$ sudo apt-get update
sudo apt-get install --yes postgresql-client
Get:1 https://packages.cloud.google.com/apt google-compute-engine-bullseye-stable InRelease [5146 B]
Get:2 https://packages.cloud.google.com/apt cloud-sdk-bullseye InRelease [6406 B]   
Hit:3 https://deb.debian.org/debian bullseye InRelease  
Get:4 https://deb.debian.org/debian-security bullseye-security InRelease [48.4 kB]
Get:5 https://packages.cloud.google.com/apt google-compute-engine-bullseye-stable/main amd64 Packages [1930 B]
Get:6 https://deb.debian.org/debian bullseye-updates InRelease [44.1 kB]
Get:7 https://deb.debian.org/debian bullseye-backports InRelease [49.0 kB]
...redacted...
update-alternatives: using /usr/share/postgresql/13/man/man1/psql.1.gz to provide /usr/share/man/man1/psql.1.gz (psql.1.gz) in auto mode
Setting up postgresql-client (13+225) ...
Processing triggers for man-db (2.9.4-2) ...
Processing triggers for libc-bin (2.31-13+deb11u7) ...

Verbindung zur Instanz herstellen

Stellen Sie mit psql eine Verbindung zur primären Instanz von der VM aus her.

Auf demselben Cloud Shell-Tab mit der geöffneten SSH-Sitzung zur VM „instance-1“.

Verwenden Sie den angegebenen AlloyDB-Passwortwert (PGPASSWORD) und die AlloyDB-Cluster-ID, um von der GCE-VM aus eine Verbindung zu AlloyDB herzustellen:

export PGPASSWORD=<Noted password>

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
export INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"

Erwartete Konsolenausgabe:

student@instance-1:~$ export PGPASSWORD=CQhOi5OygD4ps6ty
student@instance-1:~$ ADBCLUSTER=alloydb-aip-01
student@instance-1:~$ REGION=us-central1
student@instance-1:~$ INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
gleb@instance-1:~$ psql "host=$INSTANCE_IP user=postgres sslmode=require"
psql (15.6 (Debian 15.6-0+deb12u1), server 15.5)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=>

Schließen Sie die psql-Sitzung:

exit

6. Datenbank vorbereiten

Wir müssen eine Datenbank erstellen, die Vertex AI-Integration aktivieren, Datenbankobjekte erstellen und die Daten importieren.

Erforderliche Berechtigungen für AlloyDB erteilen

Fügen Sie dem AlloyDB-Dienst-Agent Vertex AI-Berechtigungen hinzu.

Öffnen Sie oben einen weiteren Cloud Shell-Tab, indem Sie auf das Pluszeichen (+) klicken.

Führen Sie im neuen Cloud Shell-Tab Folgendes aus:

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"

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ 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"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1

Schließen Sie den Tab, indem Sie entweder den Befehl „exit“ auf dem Tab ausführen:

exit

Datenbank erstellen

Erstellen Sie eine Datenbank mit dem Namen „quickstart“.

Führen Sie in der GCE-VM-Sitzung Folgendes aus:

Datenbank erstellen:

psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE quickstart_db"

Erwartete Konsolenausgabe:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE quickstart_db"
CREATE DATABASE
student@instance-1:~$

Vertex AI-Integration aktivieren

Aktivieren Sie die Vertex AI-Einbindung und die pgvector-Erweiterungen in der Datenbank.

Führen Sie auf der GCE-VM Folgendes aus:

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE"
psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS vector"

Erwartete Konsolenausgabe:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE"
psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS vector"
CREATE EXTENSION
CREATE EXTENSION
student@instance-1:~$

Daten importieren

Laden Sie die vorbereiteten Daten herunter und importieren Sie sie in die neue Datenbank.

Führen Sie auf der GCE-VM Folgendes aus:

gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_products from stdin csv header"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_inventory from stdin csv header"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_stores from stdin csv header"

Erwartete Konsolenausgabe:

student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"
SET
SET
SET
SET
SET
 set_config 
------------
 
(1 row)
SET
SET
SET
SET
SET
SET
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE SEQUENCE
ALTER TABLE
ALTER SEQUENCE
ALTER TABLE
ALTER TABLE
ALTER TABLE
student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_products from stdin csv header"
COPY 941
student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_inventory from stdin csv header"
COPY 263861
student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_stores from stdin csv header"
COPY 4654
student@instance-1:~$

7. Vektoreinbettungen generieren

Nach dem Import der Daten haben wir die folgenden Tabellen: cymbal_products mit Informationen zu Produkten, cymbal_inventory mit Informationen zum Artikelbestand in den einzelnen Geschäften und cymbal_stores mit einer Liste der Geschäfte. Um eine semantische Suche für unsere Produkte durchzuführen, müssen wir mit der Funktion initialize_embeddings Vektoreinbettungen unserer Produktbeschreibungen generieren. Wir verwenden die Vertex AI-Integration, um Vektordaten auf Grundlage unserer Produktbeschreibungen zu berechnen und der Tabelle hinzuzufügen. Weitere Informationen zur verwendeten Technologie finden Sie in der Dokumentation.

Um die Integration zu verwenden, stellen Sie mit psql von Ihrer VM aus eine Verbindung zur Datenbank her. Verwenden Sie dazu die IP-Adresse der AlloyDB-Instanz und das Postgres-Passwort:

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"

Prüfen Sie die Version der Erweiterung „google_ml_integration“.

SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

Die Version sollte 1.5.2 oder höher sein. Hier ein Beispiel für die Ausgabe:

quickstart_db=> SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
 extversion 
------------
 1.5.2
(1 row)

Die Standardversion sollte 1.5.2 oder höher sein. Wenn in Ihrer Instanz eine ältere Version angezeigt wird, muss sie wahrscheinlich aktualisiert werden. Prüfen Sie, ob die Wartung für die Instanz deaktiviert wurde.

Wir verwenden die Batch-Generierung von Einbettungen, um die Effizienz zu steigern. Weitere Informationen zu den verschiedenen Optionen und Techniken zum Generieren von Einbettungen finden Sie im Leitfaden. Um Batch-Einbettungen zu verwenden, müssen wir goole_ml_integration.enable_faster_embedding_generation aktivieren.

show google_ml_integration.enable_faster_embedding_generation;

Wenn das Flag an der richtigen Position ist, sieht die erwartete Ausgabe so aus:

quickstart_db=> show google_ml_integration.enable_faster_embedding_generation;                          
 google_ml_integration.enable_faster_embedding_generation 
----------------------------------------------------------
 on
(1 row)

Wenn „Aus“ angezeigt wird, muss die Instanz aktualisiert werden. Sie können dies über die Webkonsole oder mit dem gcloud-Befehl tun, wie in der Dokumentation beschrieben. Hier sehen Sie, wie Sie das mit dem gcloud-Befehl tun können:

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags google_ml_integration.enable_faster_embedding_generation=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Es kann einige Minuten dauern, bis der Flag-Wert auf „Ein“ gesetzt wird. Danach können Sie mit den nächsten Schritten fortfahren.

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"

Erstellen Sie in der mit der Datenbank verbundenen psql-Sitzung eine neue Spalte zum Speichern von Einbettungen in cymbal_products.

ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);

Erwartete Konsolenausgabe:

quickstart_db=> ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);
ALTER TABLE
quickstart_db=>

Schließlich sollen die Einbettungen auch aktualisiert werden, wenn sich die Spaltenwerte ändern. Dazu fügen wir das Argument incremental_refresh_mode in den Funktionsaufruf ein. Das führt zu einem Mehraufwand für unsere Datenbank, aber wir nehmen das in Kauf, um Einbettungen automatisch mit Inhalten zu synchronisieren. Wenn Sie Einbettungen manuell aktualisieren möchten, finden Sie eine Anleitung in der Dokumentation.

Wenn wir nun alles zusammenfügen und Einbettungen generieren, verwenden wir die Funktion initialize_embeddings und übergeben batch_size von 50 als Batch-Hinweis und setzen incremental_refresh_mode auf transactional.

CALL ai.initialize_embeddings(
    model_id => 'text-embedding-005',
    table_name => 'cymbal_products',
    content_column => 'product_description',
    embedding_column => 'product_embedding',
    batch_size => 50,
    incremental_refresh_mode => 'transactional'
);

Wenn wir jetzt eine neue Zeile in die Tabelle mit dem Wert NULL für die Spalte product_embedding einfügen,

INSERT INTO "cymbal_products" ("uniq_id", "crawl_timestamp", "product_url", "product_name", "product_description", "list_price", "sale_price", "brand", "item_number", "gtin", "package_size", "category", "postal_code", "available", "product_embedding") VALUES ('fd604542e04b470f9e6348e640cff794', NOW(), 'https://example.com/new_product', 'New Cymbal Product', 'This is a new cymbal product description.', 199.99, 149.99, 'Example Brand', 'EB123', '1234567890', 'Single', 'Cymbals', '12345', TRUE, NULL);

Wenn wir jetzt die gerade eingefügte Zeile abfragen, sehen wir, dass die Spalte product_embedding automatisch aktualisiert wurde.

SELECT uniq_id, (product_embedding::real[])[1:5] as product_embedding  FROM cymbal_products WHERE uniq_id='fd604542e04b470f9e6348e640cff794';

Die Ausgabe sollte so aussehen:

quickstart_db=> SELECT uniq_id,(product_embedding::real[])[1:5] as product_embedding  FROM cymbal_products WHERE uniq_id='fd604542e04b470f9e6348e640cff794';
             uniq_id              |                      product_embedding                       
----------------------------------+---------------------------------------------------------------
 fd604542e04b470f9e6348e640cff794 | {0.015003494,-0.005349732,-0.059790313,-0.0087091,-0.0271452}
(1 row)

Time: 3.295 ms

8. Vektorindex erstellen

Um die Leistung der Vektorsuche zu verbessern, fügen wir einen ScaNN-Index hinzu.

ScaNN-Index erstellen

Um den SCANN-Index zu erstellen, müssen wir eine weitere Erweiterung aktivieren. Die Erweiterung alloydb_scann bietet eine Schnittstelle für die Arbeit mit dem Vektorindex vom Typ „ANN“ mit dem ScaNN-Algorithmus von Google.

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

Erwartete Ausgabe:

quickstart_db=> CREATE EXTENSION IF NOT EXISTS alloydb_scann;
CREATE EXTENSION
Time: 27.468 ms
quickstart_db=>

Der Index kann im manuellen oder automatischen Modus erstellt werden. Der Modus „MANUAL“ ist standardmäßig aktiviert. Sie können einen Index erstellen und ihn wie jeden anderen Index verwalten. Wenn Sie den AUTO-Modus aktivieren, können Sie den Index erstellen, ohne dass Sie ihn warten müssen. Weitere Informationen zu allen Optionen In unserem Fall haben wir nicht genügend Zeilen, um den Index im AUTO-Modus zu erstellen. Daher erstellen wir ihn im MANUAL-Modus und fügen Optimierungsparameter ein. Weitere Informationen zum Optimieren von Indexparametern finden Sie in der Dokumentation.

Wir müssen das Flag scann.enable_preview_features aktivieren, damit wir die Optimierungsparameter ändern können. In Cloud Shell

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags scann.enable_preview_features=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

Es kann einige Minuten dauern, bis der Flag-Wert auf „Ein“ gesetzt wird. Nachdem das Flag festgelegt wurde, können wir zur psql-Sitzung auf der VM zurückkehren und den Index mit Optimierungsparametern erstellen.

CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (product_embedding cosine)
  WITH (mode='MANUAL', num_leaves=31, max_num_levels = 2);

Erwartete Ausgabe:

quickstart_db=> CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (product_embedding cosine)
  WITH (num_leaves=31, max_num_levels = 2);
CREATE INDEX
quickstart_db=>

Indexnutzung prüfen

Jetzt können wir die Vektorsuchanfrage im EXPLAIN-Modus ausführen und prüfen, ob der Index verwendet wird.

EXPLAIN (analyze) 
WITH trees as (
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        cp.uniq_id as product_id
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        (cp.product_embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

Erwartete Ausgabe (zur besseren Lesbarkeit gekürzt):

...
Aggregate (cost=16.59..16.60 rows=1 width=32) (actual time=2.875..2.877 rows=1 loops=1)
-> Subquery Scan on trees (cost=8.42..16.59 rows=1 width=142) (actual time=2.860..2.862 rows=1 loops=1)
-> Limit (cost=8.42..16.58 rows=1 width=158) (actual time=2.855..2.856 rows=1 loops=1)
-> Nested Loop (cost=8.42..6489.19 rows=794 width=158) (actual time=2.854..2.855 rows=1 loops=1)
-> Nested Loop (cost=8.13..6466.99 rows=794 width=938) (actual time=2.742..2.743 rows=1 loops=1)
-> Index Scan using cymbal_products_embeddings_scann on cymbal_products cp (cost=7.71..111.99 rows=876 width=934) (actual time=2.724..2.724 rows=1 loops=1)
Order By: (embedding <=> '[0.008864171,0.03693164,-0.024245683,-0.00355923,0.0055611245,0.015985578,...<redacted>...5685,-0.03914233,-0.018452475,0.00826032,-0.07372604]'::vector)
...

Aus der Ausgabe geht deutlich hervor, dass für die Abfrage „Index Scan using cymbal_products_embeddings_scann on cymbal_products“ verwendet wurde.

9. Volltextsuchindex

AlloyDB unterstützt alle Indextypen für die Volltextsuche, die von nativem PostgreSQL unterstützt werden. Die Wahl des Index hängt vom Gleichgewicht zwischen Suchgeschwindigkeit, Indexerstellungszeit, Aktualisierungsgeschwindigkeit und den erforderlichen spezifischen Suchfunktionen ab, z. B. Phrasensuche oder Relevanzranking.

In unserem Beispiel verwenden wir die RUM-Erweiterung für leistungsfähigere Volltextsuchvorgänge. RUM verbessert die Standard-GIN-Indizes, indem Positionsinformationen direkt im Index gespeichert werden. So können Sie schneller nach Begriffen suchen und die Relevanz einstufen, ohne auf die Tabellendaten zugreifen zu müssen.

Sie können die RUM-Erweiterung über AlloyDB Studio oder den psql-Client aktivieren.

RUM-Index erstellen

CREATE EXTENSION IF NOT EXISTS rum;

Wenn wir die Produktbeschreibungen in der Tabelle cymbal_products durchsuchen möchten, müssen wir eine Spalte erstellen, in der die Produktbeschreibung als tsvector gespeichert wird. In dieser Spalte wird der verarbeitete Text automatisch gespeichert, was die Abfrageleistung verbessert.

ALTER TABLE cymbal_products
ADD COLUMN product_search_vector tsvector
GENERATED ALWAYS AS (to_tsvector('english', product_description)) STORED;

Jetzt können wir einen neuen RUM-Index für die Spalte product_search_vector erstellen.

CREATE INDEX cymbal_products_rum
ON cymbal_products
USING rum (product_search_vector rum_tsvector_ops);

Führen Sie die folgende Abfrage aus, um die Tabelle mit dem Index abzufragen und nach Übereinstimmungen mit „Kirschbaum“ zu suchen. Der Operator <=> berechnet den Relevanzwert oder die Distanz zwischen dem Dokument und der Anfrage direkt aus dem Index.

SELECT product_name, product_description
FROM cymbal_products
WHERE product_search_vector @@ to_tsquery('english', 'cherry <-> tree')
ORDER BY product_search_vector <=> to_tsquery('english', 'cherry <-> tree');

10. Hybridsuche ausführen

Mit der Funktion google_vector_utils.hybrid_search() können Sie Ergebnisse aus verschiedenen Suchtypen wie Vektorsuche und Volltextsuche kombinieren. Die Funktion führt die gerankten Ergebnisse der einzelnen Suchkomponenten mithilfe des RRF-Algorithmus (Reciprocal Rank Fusion) in einer einzigen, einheitlichen Liste zusammen. Dieser Ansatz liefert relevantere Ergebnisse als ein einzelner Suchtyp.

Die Funktion hybrid_search() erstellt und führt dynamisch eine einzelne SQL-Abfrage aus. Für jede definierte Suchkomponente wird ein allgemeiner Tabellenausdruck (Common Table Expression, CTE) erstellt. Die Funktion führt dann die Ergebnisse aller CTEs zusammen und berechnet für jedes Dokument einen endgültigen RRF-Wert, um eine einheitliche, sortierte Liste zu erstellen.

Damit wir die Funktion verwenden können, müssen wir enable_preview_ai_functions in der primären Instanz aktivieren. Führen Sie den folgenden Befehl in Cloud Shell aus.

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags google_ml_integration.enable_preview_ai_functions=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

In der folgenden Abfrage wird unsere vorherige Frage zur Vektorsuche mit unserer Frage zur Volltextsuche kombiniert. Dies ist eine sehr einfache hybride Suchanfrage. Sie können auch komplexere Anfragen ausprobieren, z. B. „Bäume, die höher als ein Haus werden“ in der Vektorsuchkomponente und „Kalifornien“ in der FTS-Komponente.

SELECT score, id, p.product_name
FROM ai.hybrid_search(
  search_inputs => ARRAY[
      '{
        "data_type": "vector",
        "table_name": "cymbal_products",
        "key_column": "uniq_id",
        "vec_column": "product_embedding",
        "distance_operator": "public.<=>",
        "limit": 5,
        "query_vector": "ai.embedding(''text-embedding-005'', ''cherry'')::vector"
      }'::JSONB,
      '{
        "data_type": "text",
        "table_name": "cymbal_products",
        "key_column": "uniq_id",
        "text_column": "product_search_vector",
        "limit": 5,
        "ranking_function": "<=>",
        "query_text_input": "tree"
      }'::JSONB
  ]
) JOIN cymbal_products p ON id = p.uniq_id;

Erwartete Ausgabe

"score","id","product_name"
"0.00819672631147241","d536e9e823296a2eba198e52dd23e712","Cherry Tree"
"0.015873015873015872","23e41a71d63d8bbc9bdfa1d118cfddc5","Apple Tree"
"0.00819672631147241","dc789a2f87b142e94e6e325689482af9","Oak Tree"
"0.008064521129029258","f5c70d62ccf3118d73863bf3b17edcbe","Cypress Tree"
"0.008064521129029258","b70c44b1a38c0a2329fa583c9109a80f","Peach Tree"

In den Ergebnissen finden Sie id, das die angegebene key_column ist, und score, den endgültigen Wert, der von RRF berechnet wurde. Reciprocal Rank Fusion (RRF) ist ein rangbasierter Algorithmus, mit dem mehrere sortierte Listen von Suchergebnissen in einer einzigen sortierten Liste zusammengeführt werden. Dazu wird jedem Dokument ein Wert zugewiesen. Dieser Wert basiert auf dem reziproken Rang von RRF in allen beitragenden Listen. Dokumente mit einem höheren Rang erhalten einen größeren Beitrag. Wenn Sie include_json_output => true im Parameter verwenden, wird eine detail_json-Spalte zurückgegeben, die eine Aufschlüsselung der Berechnung der Punktzahl für jede Komponente enthält.

Die Volltextsuche eignet sich am besten, um bestimmte Begriffe oder genaue Übereinstimmungen zu finden. Die Vektorsuche ist ideal, um Synonyme und Absichten zu finden, auch wenn die Wörter nicht übereinstimmen. Durch die Kombination dieser beiden Methoden sorgt die hybride Suche dafür, dass Nutzer eine robuste Reihe von Ergebnissen erhalten, die sowohl wörtlich korrekt als auch semantisch relevant sind.

11. Umgebung bereinigen

Löschen Sie die AlloyDB-Instanzen und den Cluster, wenn Sie mit dem Lab fertig sind.

AlloyDB-Cluster und alle Instanzen löschen

Wenn Sie die Testversion von AlloyDB verwendet haben. Löschen Sie den Testcluster nicht, wenn Sie planen, andere Labs und Ressourcen damit zu testen. Sie können keinen weiteren Testcluster im selben Projekt erstellen.

Der Cluster wird mit der Option „force“ zerstört, wodurch auch alle zum Cluster gehörenden Instanzen gelöscht werden.

Definieren Sie in Cloud Shell die Projekt- und Umgebungsvariablen, wenn die Verbindung getrennt wurde und alle vorherigen Einstellungen verloren gegangen sind:

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
export PROJECT_ID=$(gcloud config get-value project)

Löschen Sie den Cluster:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.

AlloyDB-Sicherungen löschen

Löschen Sie alle AlloyDB-Sicherungen für den Cluster:

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.

Jetzt können wir unsere VM löschen.

GCE-VM löschen

Führen Sie in Cloud Shell Folgendes aus:

export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet

Erwartete Konsolenausgabe:

student@cloudshell:~ (test-project-001-402417)$ export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet
Deleted

12. Glückwunsch

Herzlichen Glückwunsch zum Abschluss des Codelabs.

Behandelte Themen

AlloyDB-Cluster und primäre Instanz bereitstellen
Verbindung zu AlloyDB über eine Google Compute Engine-VM herstellen
Datenbank erstellen und AlloyDB AI aktivieren
Daten in die Datenbank laden
AlloyDB Studio verwenden
Einbettungen mit Vertex AI generieren
ScaNN-Vektorindex erstellen, um die Vektorsuche zu optimieren
RUM-Erweiterung für die Volltextsuche aktivieren und verwenden
Hybridsuche durchführen, indem Sie Volltextsuche, Vektorsuche und Reciprocal Rank Fusion (RRF) kombinieren