Kontextsets in AlloyDB Studio verwalten

Vorschau

Diese Funktion unterliegt den Bedingungen für Pre‑GA-Angebote im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen und den Zusatzbedingungen für Vorschauprodukte auf Basis von generativer KI. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Wenn Sie den Context-Engineering-Agenten verwenden, kann er Kontextsets automatisch über Ihre Befehlszeile erstellen und hochladen. In diesem Dokument wird beschrieben, wie Sie Kontextgruppen in AlloyDB for PostgreSQL Studio erstellen, bearbeiten und löschen, wenn Sie eine visuelle Oberfläche in der Google Cloud Console zum Verwalten von Kontextgruppendateien verwenden möchten. Wenn Sie in AlloyDB Studio einen Kontextsatz erstellen, wird er in der Kontextsatzgruppe default des Projekts für die ausgewählte Region gespeichert und mit der aktuellen Datenbank verknüpft. Kontextsatznamen (und die davon abgeleiteten Kontextsatz-IDs) müssen innerhalb der Kontextsatzgruppe default des Projekts für eine bestimmte Region über alle Datenbanken und Instanzen hinweg eindeutig sein. In AlloyDB Studio schlägt die Validierung fehl, wenn Sie ein Kontextset mit einem Namen erstellen, dessen abgeleitete ID bereits vorhanden ist. Wenn Sie den Inhalt überschreiben, aber die Datenbankzuordnungen beibehalten möchten, bearbeiten Sie stattdessen das vorhandene Kontextset. Wenn Sie Inhalte direkt über den Context Engineering-Agenten oder die Dataplex API mit einer vorhandenen Kontextsatz-ID hochladen, werden die Inhalte und, falls angegeben, die Datenbankzuordnungen ersetzt.

In der Liste Kontextsätze in AlloyDB Studio werden nur Kontextsätze in der Kontextsatzgruppe default in allen unterstützten Regionen angezeigt, die mit der aktuellen Datenbank verknüpft sind. Kontextsätze, die für eine andere Datenbank oder über die API erstellt wurden, ohne die Datenbankressource in databases (oder in einer benutzerdefinierten Kontextsatzgruppe) zu verknüpfen, werden nicht in der AlloyDB Studio-Liste angezeigt.

Weitere Informationen zu Kontextgruppen finden Sie unter Kontextgruppen – Übersicht.

Hinweis

Bevor Sie einen Kontextsatz erstellen oder hochladen, müssen Sie die folgenden Voraussetzungen erfüllen.

Kontextsätze können in den Regionen us-central1, us-east1, europe-west4 und asia-southeast1 erstellt werden.

Erforderliche Dienste aktivieren

Aktivieren Sie die folgenden Dienste für Ihr Projekt:

• Data Analytics API with Gemini
• Gemini for Google Cloud API
• Knowledge Catalog API

AlloyDB for PostgreSQL-Cluster, -Instanz und -Datenbank vorbereiten

Prüfen Sie, ob Sie Zugriff auf einen vorhandenen AlloyDB-Cluster und eine vorhandene AlloyDB-Instanz haben, oder erstellen Sie einen neuen Cluster und eine neue Instanz.
Für diese Anleitung benötigen Sie eine Datenbank in Ihrer AlloyDB-Instanz. Weitere Informationen finden Sie unter Datenbank erstellen.

Erforderliche Rollen und Berechtigungen

• Aktivieren Sie die IAM-Datenbankauthentifizierung (Identity and Access Management) auf der Instanz, indem Sie das Datenbank-Flag alloydb.iam_authentication auf on (alloydb.iam_authentication=on) setzen. Weitere Informationen finden Sie unter IAM-Authentifizierung aktivieren und deaktivieren.
• Fügen Sie dem Cluster auf Datenbankebene einen IAM-Nutzer oder ein Dienstkonto hinzu. Weitere Informationen finden Sie unter IAM-Authentifizierung verwalten.
• Weisen Sie dem IAM-Nutzer auf Projektebene die Rollen roles/alloydb.databaseUser, roles/serviceusage.serviceUsageConsumer und roles/geminidataanalytics.queryDataUser zu. Weitere Informationen finden Sie unter IAM-Richtlinienbindung für ein Projekt hinzufügen.
• Wenn Sie Kontextgruppen erstellen, hochladen und verwalten möchten, weisen Sie dem IAM-Nutzer auf Projektebene die Rolle „Dataplex Catalog Editor“ (roles/dataplex.catalogEditor) oder „Dataplex Catalog Admin“ (roles/dataplex.catalogAdmin) zu. Weitere Informationen finden Sie unter Berechtigungen für Kontextgruppen.
• Außerdem müssen Sie dem IAM-Nutzer oder -Dienstkonto Lesezugriff für die Datenbank gewähren.
  
  GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";
  
  Ersetzen Sie USER_NAME durch die E-Mail-Adresse eines Nutzers oder die Dienstkontoadresse ohne das Suffix . (z. B. [e-mail]). Sie müssen die Kennung in Anführungszeichen setzen, da sie Sonderzeichen (@ und .) enthält.
  
  Weitere Informationen finden Sie unter IAM-Nutzern die entsprechenden Datenbankberechtigungen gewähren.

Berechtigung executesql für AlloyDB for PostgreSQL-Instanz gewähren

Verwenden Sie den folgenden curl-Befehl, um der AlloyDB for PostgreSQL-Instanz die Berechtigung executesql zu gewähren und das Instanzfeld dataApiAccess auf ENABLED festzulegen (erforderlich für QueryData, obwohl die Standardeinstellung einige interne Google Cloud -Dienste wie AlloyDB Studio zulässt):

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
     -d '{
       "dataApiAccess": "ENABLED"
     }'

Ersetzen Sie Folgendes:

• PROJECT_ID: Die ID Ihres Google Cloud -Projekts.
• LOCATION: Die Region, in der sich Ihr AlloyDB-Cluster befindet.
• CLUSTER_ID: Die ID Ihres AlloyDB-Clusters.
• INSTANCE_ID: Die ID Ihrer AlloyDB-Instanz.

Melden Sie sich zum Ausführen der Schritte in dieser Anleitung bei Google Cloud an und authentifizieren Sie sich dann mit der IAM-Authentifizierung bei der Datenbank.

Kontextset erstellen

So erstellen Sie einen Kontextsatz:

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

   Zu AlloyDB

2. Wählen Sie einen Cluster aus der Liste aus.

3. Klicken Sie im Navigationsmenü auf AlloyDB Studio.

4. Melden Sie sich mit der IAM-Authentifizierung in AlloyDB Studio an.

5. Klicken Sie im Bereich Explorer neben Kontextsätze auf Aktionen ansehen.

6. Klicken Sie auf Kontextgruppe erstellen.

7. Geben Sie unter Name des Kontextsets einen eindeutigen Namen für das Kontextset ein. In AlloyDB Studio muss der Name 4 bis 30 Zeichen lang sein und darf nicht mit einem Leerzeichen beginnen. Studio leitet die Kontextsatz-ID ab, indem es den Namen in Kleinbuchstaben umwandelt und nicht alphanumerische Zeichen durch Bindestriche (-) ersetzt. Die abgeleitete Kontextsatz-ID muss innerhalb der Kontextsatzgruppe default des Projekts für die ausgewählte Region eindeutig sein. Der Kontextsatzname querydata_e2e_test hat beispielsweise die Kontextsatz-ID querydata-e2e-test. Wenn Sie einen Kontextsatz direkt mit dem Kontext-Engineering-Agenten oder der Dataplex API hochladen, wird bei der Kontextsatz-ID zwischen Groß- und Kleinschreibung unterschieden. Sie darf keine Schrägstriche (/) enthalten und ist nicht auf 4 bis 30 Zeichen oder alphanumerische Zeichen, Bindestriche und Unterstriche beschränkt.

8. Optional. Fügen Sie unter Beschreibung des Kontextsets eine Beschreibung für Ihr Kontextset hinzu.

9. Optional. Wenn Sie eine Kontextsatzdatei hochladen möchten, klicken Sie im Bereich Kontextsatzdatei hochladen auf Durchsuchen und wählen Sie die Kontextsatzdatei aus.

10. Optional. Wenn Sie eine Region für den Kontextsatz auswählen möchten, klicken Sie auf Erweiterte Optionen einblenden und wählen Sie unter Standort auswählen eine Region aus. Standardmäßig wird bei jeder Erstellung us-east1 verwendet. Wenn Sie eine andere Region als us-east1 auswählen, wählen Sie die Region aus, bevor Sie den Namen des Kontextsets eingeben, damit AlloyDB Studio die Eindeutigkeit des Namens in dieser Region prüft.

11. Klicken Sie auf Erstellen.

Hinweis: Das Erstellen eines Kontextsets in AlloyDB Studio kann einige Minuten dauern, während AlloyDB Studio das Kontextset verarbeitet. Das Erstellen oder Hochladen eines Kontextsets über den Context-Engineering-Agenten oder die Dataplex API dauert in der Regel nur wenige Sekunden.

Kontextsets erstellen

Wenn Sie in Studio einen leeren Kontextsatz erstellt haben oder einen vorhandenen aktualisieren möchten, folgen Sie der Anleitung unter Kontextsätze mit dem Kontext-Engineering-Agenten erstellen und optimieren, um eine Kontextsatzdatei zu generieren und zu optimieren. Der Kontext-Engineering-Agent kann Ihr Kontextset direkt über die Befehlszeile erstellen und hochladen. Alternativ können Sie Ihr Kontextset in Studio bearbeiten, um die Kontextset-Datei manuell hochzuladen.

Kontextset bearbeiten

So bearbeiten Sie einen Kontextsatz:

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

   Zu AlloyDB

2. Wählen Sie einen Cluster aus der Liste aus.

3. Klicken Sie im Navigationsmenü auf AlloyDB Studio.

4. Melden Sie sich mit der IAM-Authentifizierung in AlloyDB Studio an.

5. Klicken Sie neben dem Kontextsatz, den Sie bearbeiten möchten, auf Aktionen ansehen.

6. Klicken Sie auf Kontextgruppe bearbeiten.

7. Optional. Bearbeiten Sie die Beschreibung des Kontextsets.

8. Klicken Sie im Abschnitt Kontextset-Datei hochladen auf Durchsuchen und wählen Sie die Kontextset-Datei aus.

9. Klicken Sie auf Speichern.

Kontextset löschen

So löschen Sie einen Kontextsatz:

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

   Zu AlloyDB

2. Wählen Sie einen Cluster aus der Liste aus.

3. Klicken Sie im Navigationsmenü auf AlloyDB Studio.

4. Melden Sie sich mit der IAM-Authentifizierung in AlloyDB Studio an.

5. Klicken Sie neben dem Kontextset, das Sie löschen möchten, auf Aktionen ansehen.

6. Klicken Sie auf Kontextset löschen.

7. Geben Sie im Bestätigungsdialogfeld Kontextgruppe löschen die ID der Kontextgruppe ein.

8. Klicken Sie auf Bestätigen, um den Kontextsatz zu löschen.

Hinweis: Durch das Löschen einer Datenbank werden die zugehörigen Kontextgruppen nicht gelöscht. Löschen Sie sie, bevor Sie die Datenbank löschen, um verwaiste Kontextgruppen zu vermeiden, die weiterhin Schemadetails preisgeben.

Nächste Schritte

• Weitere Informationen zu Kontextgruppen
• Informationen zum Testen von QueryData in AlloyDB Studio
• Kontextsätze mit dem Context Engineering-Agenten erstellen und optimieren
• QueryData in eine Anwendung einbinden