Voraussetzungen für Anreicherungsaufgaben konfigurieren

Bevor Sie Anreicherungsaufgaben in Knowledge Studio erstellen können, müssen Sie je nach Sicherheitsarchitektur und Zieldatenquellen möglicherweise mehrere zugrunde liegende Infrastrukturkomponenten konfigurieren.

In diesem Leitfaden wird beschrieben, wie Sie vom Kunden verwaltete Dienstkonten, Drittanbieter-Authentifizierungsanbieter, Cloud Storage-Buckets und Cloud Logging-Ansichten konfigurieren.

In der folgenden Tabelle werden die erforderlichen Konfigurationen und der Zeitpunkt ihrer Konfiguration beschrieben:

Konfigurationsfunktion Wann Sie die Konfiguration vornehmen sollten
Google Cloud APIs Erforderlich. Sie müssen die zugrunde liegenden Google Cloud -APIs aktivieren, um Anreicherungsworkflows auszuführen.
Vom Kunden verwaltetes Dienstkonto Sie möchten den Lese- und Schreibzugriff auf Ihre Ziel-Datasets einschränken.
IAM-Rollen (Identity and Access Management) für Nutzer Sie müssen Workflow-Managern und ‑Prüfern Berechtigungen zum Generieren und Genehmigen von Metadaten erteilen.
Drittanbieter von Authentifizierungsdiensten Sie stellen eine Verbindung zu Wissensquellen von Drittanbietern her (z. B. Microsoft SharePoint, Atlassian Confluence oder GitHub).
Cloud Storage-Buckets Sie nehmen unstrukturierten Geschäftskontext (z. B. PDFs, Markdown und CSV) und Bewertungs-Datasets auf.
Bewertungs-Datasets Sie möchten Seed-Abfragen und Benchmark-Datasets bereitstellen, um die Genauigkeit des KI-Agenten aktiv zu verfolgen.
Agenten-Traces für selbstlernende KI Der Anreicherungs-Agent soll nachgelagerte Interaktionen des Gemini Enterprise-Agenten automatisch analysieren.
Datenprofilerstellung und Dateneinblicke Recommended. Sie möchten die Qualität der Anreicherung verbessern, indem Sie statistische Profile und grundlegende KI-Insights für häufig verwendete Tabellen generieren.

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

Details zu erforderlichen APIs

Die aktivierten APIs führen die folgenden Funktionen aus, um Anreicherungsaufgaben zu konfigurieren und auszuführen:

API-Name Servicebezeichner Zweck in Anreicherungsworkflows
Dataplex-API dataplex.googleapis.com Primäre API der Steuerungsebene. Verwaltet EnrichmentTask, EnrichmentRun, Kontextgruppen, Änderungsanfragen und den EnrichmentChatService.
BigQuery API bigquery.googleapis.com Erforderlich zum Scannen von Tabellenschemas, zum Aufnehmen des SQL-Ausführungsverlaufs und zum Abfragen von BigQuery Agent Analytics-Trace-Tabellen.
Cloud Storage API storage.googleapis.com Erforderlich für die Aufnahme von Bewertungs-Datasets und die Verwaltung von Bewertungs-Dataset-Stichproben.
IAM Service Account Credentials API iamcredentials.googleapis.com Erforderlich für die sichere Authentifizierung des Ausführungs-Agents und die Gewährung von kurzlebigen Anmeldedaten (Short-Lived Credentials, SLC) während Aufgaben.

Vom Kunden verwaltetes Dienstkonto konfigurieren

Für Anreicherungsaufgaben wird ein vom Kunden verwaltetes Dienstkonto verwendet, um Vorgänge auszuführen. So können Sie den Lese- und Schreibzugriff auf Ihre Ziel-Datasets einschränken.

  1. Erstellen Sie das Dienstkonto.

    Zum Erstellen eines Dienstkontos müssen Sie Project Owner (roles/owner) oder Editor (roles/editor) sein oder die Rolle Service Account Admin (roles/iam.serviceAccountAdmin) haben.

    Ein dediziertes Dienstkonto isoliert Ihre Anreicherungsvorgänge, sodass Sie nur die spezifischen Lese- und Schreibberechtigungen gewähren können, die für diese Aufgaben erforderlich sind, ohne andere Arbeitslasten zu beeinträchtigen.

    So erstellen Sie ein Dienstkonto:

    Google Cloud CLI

    Verwenden Sie den Befehl gcloud iam service-accounts create, um ein Dienstkonto zu erstellen:

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • SERVICE_ACCOUNT_NAME: der Name Ihres Dienstkontos

    Führen Sie folgenden Befehl aus:

    Linux, macOS oder Cloud Shell

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" \
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (PowerShell)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME `
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" `
    --display-name="Knowledge Catalog enrichment agent SA"

    Windows (cmd.exe)

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ^
    --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ^
    --display-name="Knowledge Catalog enrichment agent SA"

    REST

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • SERVICE_ACCOUNT_NAME: der Name Ihres Dienstkontos
    • TARGET_PROJECT_ID: Ihre Google Cloud-Projekt-ID

    HTTP-Methode und URL:

    POST https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts

    JSON-Text anfordern:

    {
   "accountId": "SERVICE_ACCOUNT_NAME",
   "serviceAccount": {
    "displayName": "Knowledge Catalog enrichment agent SA",
    "description": "Service Account for Dataplex Knowledge Catalog enrichment agent execution"
   }
  }

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Sie sollten einen erfolgreichen Statuscode (2xx) und eine leere Antwort als Ausgabe erhalten.

  2. Weisen Sie dem Ausführungsdienstkonto die erforderlichen IAM-Rollen auf Ressourcenebene für Ihre Zielbereiche zu:

    • Dataplex Catalog Editor (roles/dataplex.catalogEditor) und Dataplex Catalog Viewer (roles/dataplex.catalogViewer): Ermöglicht dem Agenten, Katalogmetadaten zu prüfen, gestaffelte Arbeitseinträge zu erstellen und genehmigte Anreicherungen manuell zu veröffentlichen.
    • (Optional) Dataplex Workflow Approver (roles/dataplex.workflowApprover): Nur erforderlich, wenn Sie für Ihre Aufgabe Automatisch veröffentlichen aktivieren. Ermöglicht dem KI-Agenten, seine eigenen Anfragen für Metadatenänderungen automatisch zu genehmigen und zu veröffentlichen.
    • BigQuery-Datenbetrachter (roles/bigquery.dataViewer): Ermöglicht dem Agenten, Tabellenschemas, Spaltenmetadaten und Agent-Analysetabellen zu lesen.

    Hinweis: In den folgenden Codebeispielen werden diese Rollen auf Projektebene zugewiesen, um die Einrichtung zu vereinfachen. Für Produktionssysteme empfehlen wir dringend, diese Rollen auf Ressourcenebene für Ihre spezifischen Ziel-Datasets zu gewähren.

    So weisen Sie diese Standardrollen zu:

    Verwenden Sie den Befehl gcloud projects add-iam-policy-binding, um einem Projekt eine IAM-Richtlinienbindung hinzuzufügen:

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • SERVICE_ACCOUNT_NAME: der Name Ihres Dienstkontos
    • TARGET_PROJECT_ID: Ihre Google Cloud-Projekt-ID

    Führen Sie folgenden Befehl aus:

    Linux, macOS oder Cloud Shell

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataViewer"

    Windows (PowerShell)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/bigquery.dataViewer"

    Windows (cmd.exe)

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/bigquery.dataViewer"

  3. Gewähren Sie Nutzern die Berechtigung, die Identität des Dienstkontos zu übernehmen, indem Sie ihnen die Rolle Dienstkontonutzer (roles/iam.serviceAccountUser) zuweisen:

    Nutzer, die die Anreicherungsaufgaben in der Console erstellen, müssen diese Berechtigung haben, damit sie dieses Dienstkonto für die Aufgabe angeben und anhängen können.

    So weisen Sie Nutzern die Rolle „Dienstkontonutzer“ zu:

    Verwenden Sie den Befehl gcloud iam service-accounts add-iam-policy-binding, um einem Dienstkonto eine IAM-Richtlinienbindung hinzuzufügen:

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • SERVICE_ACCOUNT_NAME: der Name Ihres Dienstkontos
    • TARGET_PROJECT_ID: Ihre Google Cloud-Projekt-ID
    • USER_EMAIL: die E-Mail-Adresse des Nutzers

    Führen Sie folgenden Befehl aus:

    Linux, macOS oder Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="user:USER_EMAIL@domain.com" \
    --role="roles/iam.serviceAccountUser"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="user:USER_EMAIL@domain.com" `
    --role="roles/iam.serviceAccountUser"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="user:USER_EMAIL@domain.com" ^
    --role="roles/iam.serviceAccountUser"

  4. Erlauben Sie dem internen Knowledge Catalog-Dienst-Agenten, die Identität dieses Dienstkontos zu übernehmen, indem Sie ihm die Rolle Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) zuweisen:

    Dadurch kann der zugrunde liegende Knowledge Catalog-Dienst die Identität dieses dedizierten Dienstkontos und seine eingeschränkten Berechtigungen übernehmen, wenn er die Hintergrundanreicherungsvorgänge in Ihrem Namen ausführt.

    So autorisieren Sie den Agent, die Identität des Dienstkontos zu übernehmen:

    Verwenden Sie den Befehl gcloud iam service-accounts add-iam-policy-binding, um einem Dienstkonto eine IAM-Richtlinienbindung hinzuzufügen:

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • SERVICE_ACCOUNT_NAME: der Name Ihres Dienstkontos
    • TARGET_PROJECT_ID: Ihre Google Cloud-Projekt-ID
    • TARGET_PROJECT_NUMBER: Ihre Google Cloud-Projektnummer.

    Führen Sie folgenden Befehl aus:

    Linux, macOS oder Cloud Shell

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (PowerShell)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" `
    --role="roles/iam.serviceAccountTokenCreator"

    Windows (cmd.exe)

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" ^
    --role="roles/iam.serviceAccountTokenCreator"

Nutzern erforderliche IAM-Rollen zuweisen

Damit Ihr Team Anreicherungsworkflows verwalten und KI-generierte Vorschläge prüfen kann, müssen Sie Ihren Nutzern die entsprechenden IAM-Rollen zuweisen. Eine Anleitung zum Zuweisen dieser Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Workflow-Manager (z. B. Data Stewards), die Aufgaben erstellen, konfigurieren und überwachen, benötigen die folgenden Rollen:

  • Dataplex DataScan-Bearbeiter (roles/dataplex.dataScanEditor) oder Dataplex-Bearbeiter (roles/dataplex.editor): Ermöglicht Nutzern, Anreicherungsaufgaben zu erstellen, zu ändern, auszulösen und abzubrechen.
  • Dienstkontonutzer (roles/iam.serviceAccountUser) für das vom Kunden verwaltete Dienstkonto: Erforderlich, um das Dienstkonto als Ausführungsidentität der Aufgabe anzuhängen.

Änderungsprüfer (z. B. Domaininhaber oder Fachexperten), die KI-generierte Metadatenvorschläge prüfen, genehmigen und im Katalog veröffentlichen, benötigen die folgenden Rollen:

  • Dataplex Catalog Editor (roles/dataplex.catalogEditor) und Dataplex Catalog Viewer (roles/dataplex.catalogViewer): Erforderlich, um Änderungsanfragen zu öffnen, nebeneinander angezeigte Vorschlagsunterschiede zu prüfen und Beschreibungen inline zu bearbeiten.
  • Dataplex Workflow Approver (roles/dataplex.workflowApprover): Erforderlich, um Änderungsanfragen zu genehmigen und im Live-Katalog zu veröffentlichen.
  • Dataplex DataScan-Betrachter (roles/dataplex.dataScanViewer) oder Dataplex-Betrachter (roles/dataplex.viewer): Erforderlich, um Konfidenzwerte pro Vorschlag, Testfehlerdiagnosen und nachgelagerte Bewertungs-Scorecards zu prüfen.

Authentifizierungsanbieter von Drittanbietern konfigurieren

Wenn Sie den Anreicherungs-Agenten mit externen Wissensquellen (z. B. Microsoft SharePoint, Atlassian Confluence oder GitHub) verbinden, müssen Sie einen Authentifizierungsanbieter mit dem Agent Identity-Dienst von Google Cloudkonfigurieren.

Agent Identity fungiert als sicherer Sicherheitsanmeldedatenmanager, der Ihre Drittanbieter-Tokens in Ihrem Projekt verschlüsselt. So müssen menschliche Operatoren während der Aufgabenausführung nie mit unverschlüsselten Clientschlüsseln arbeiten.

Eine detaillierte Anleitung zum Generieren der erforderlichen Tokens und zum Konfigurieren des Authentifizierungsanbieters für bestimmte externe Plattformen finden Sie unter Externe Connectors für Anreicherungsaufgaben konfigurieren.

IAM-Berechtigungen für Authentifizierungsanbieter einrichten

Damit der Anreicherungs-Agent die Anmeldedaten Ihres Authentifizierungsanbieters während einer aktiven Ausführung dynamisch und sicher abrufen kann, müssen Sie dem verwalteten Knowledge Catalog-Dienst-Agent (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com) die Rolle Agent Identity Admin (roles/agentidentity.admin) zuweisen. Sie können diese Rolle entweder auf der Ressourcenebene des Authentifizierungsanbieters oder auf Projektebene zuweisen.

Außerdem muss der menschliche Nutzer, der den Authentifizierungsanbieter in derGoogle Cloud Console an die Aufgabe anhängt, die Berechtigung agentidentity.authProviders.get (enthalten in Agent Identity Viewer (roles/agentidentity.viewer)) für den Authentifizierungsanbieter haben.

Cloud Storage-Buckets vorbereiten

Cloud Storage dient als primäre dateibasierte Staging-, Kontextaufnahme- und Artefakt-Exportebene für Workflows zur Wissensanreicherung.

Sie können den KI-Agenten so konfigurieren, dass er Dateien aus einem oder mehreren Eingabe-Buckets aufnimmt, um seine Argumentation auf dem Fachwissen Ihres Unternehmens zu fundieren. Zu den unterstützten Kontexttypen gehören:

  • Domaindokumentation und Datenverzeichnisse: Markdown-, Nur-Text-, PDF-, HTML- oder CSV-Dateien mit Tabellendefinitionen, Unternehmensglossaren, Standardarbeitsanweisungen (SOPs), Datenpipeline-Architekturen oder Richtlinien für Spaltennamen.

  • Bewertungs-Datasets: JSONL- oder CSV-Dateien, in denen Seed-Abfragen und zurückgehaltene Validierungsabfragesätze gespeichert sind. Weitere Informationen finden Sie unter Bewertungs-Datasets formatieren.

  • Referenz-SQL- und Transformationsskripts: Gespeicherte SQL-Skripts, dbt-Modelldefinitionen oder ETL-Transformationslogik, die Kontextsignale zu Tabellenverknüpfungsmustern und Geschäftsberechnungen liefern.

Wenn der Anreicherungs-Agent konfiguriert ist, kann er auch strukturierte Bundles und Ausführungsartefakte in einen Ausgabe-Bucket exportieren. Zu den unterstützten Ausgabeartefakten gehören:

  • Detaillierte Bewertungsberichte: Umfassende Scorecards mit Genauigkeitsabweichungen pro Abfrage, Diagnose von Testfehlern und Messwerten zur Konfidenzverteilung.

Damit der Anreicherungs-Agent im Bucket arbeiten kann, muss Ihr Ausführungsdienstkonto die erforderlichen Berechtigungen haben.

  • Weisen Sie den Eingabe-Buckets die Rolle „Storage-Objekt-Betrachter“ (roles/storage.objectViewer) zu, damit der Agent Dokumente und Konfigurationsdateien lesen kann.
  • (Optional) Weisen Sie dem Ausgabe-Bucket die Rolle „Object Creator“ (roles/storage.objectCreator) zu, wenn der Agent Ausführungsartefakte und Validierungslogs speichern soll.

So gewähren Sie dem Dienstkonto Zugriff auf die Cloud Storage-Buckets:

Verwenden Sie den Befehl gcloud storage buckets add-iam-policy-binding, um einem Storage-Bucket eine IAM-Richtlinienbindung hinzuzufügen:

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • CUSTOMER_BUCKET: der Name Ihres Cloud Storage-Buckets
  • SERVICE_ACCOUNT_NAME: der Name Ihres Dienstkontos
  • TARGET_PROJECT_ID: Ihre Google Cloud-Projekt-ID

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Windows (PowerShell)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/storage.objectViewer"

Windows (cmd.exe)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/storage.objectViewer"

Bewertungs-Datasets formatieren

Anreicherungs-Workflows können Informationen automatisch ohne Beispiele extrahieren. Wenn Sie jedoch Bewertungs-Datasets bereitstellen, kann der Agent sich selbst testen und seine Accuracy verbessern.

Sie können zwei Arten von Datasets bereitstellen:

  • Kuratierungssatz: Eine Liste mit Beispielfragen von Nutzern und den erwarteten SQL-Abfragen. Der Agent verwendet diese Liste, um zu üben und bessere Tabellenzusammenfassungen zu schreiben.

  • Bewertungsset: Eine separate Liste von Fragen, die zur Bewertung der Leistung des Agenten verwendet werden. Wenn der Agent schlecht abschneidet, verhindert dieser Bewertungssatz, dass schlechte Updates in Ihrem Katalog veröffentlicht werden.

Alternativ können Sie einen einzelnen konsolidierten Datensatz bereitstellen. Der Anreicherungsdienst partitioniert die Daten automatisch in ein Kuratierungs- und ein Bewertungs-Dataset.

Anforderungen an das Dataset-Schema

Bewertungs-Datasets müssen als JSONL-Dateien formatiert und in Cloud Storage gespeichert werden. Jede Zeile in der Datei muss eine Frage in natürlicher Sprache enthalten, die mit der erwarteten Ground-Truth-SQL-Abfrage verknüpft ist.

Achten Sie darauf, dass Ihre Datei dem von der Gemini Enterprise Agent Platform vorgegebenen Schema für das Bewertungs-Dataset entspricht. In der folgenden Tabelle sind die zulässigen Formatierungsfelder aufgeführt:

Feldname Typ Beschreibung
display_name STRING Optional. Eine Kennung oder ein Name für die Bewertungsanfrage.
evaluation_request.prompt.text STRING Die Frage in natürlicher Sprache oder der Nutzer-Prompt.
evaluation_request.golden_response.candidate STRING Identifiziert die Golden Response. Legen Sie golden fest.
evaluation_request.golden_response.text STRING Die Grundwahrheit, die validierte SQL-Abfrage, die die Frage beantwortet. Der Scorer führt diese SQL-Abfrage für die Daten aus.

Das folgende Snippet zeigt eine gültige .jsonl-Bewertungsdatei:

{"display_name": "revenue-2026", "evaluation_request": {"prompt": {"text": "What is total revenue for customer C100 in 2026?"}, "golden_response": {"candidate": "golden", "text": "SELECT SUM(amount) FROM `project.dataset.orders` WHERE customer_id = 'C100' AND EXTRACT(YEAR FROM order_date) = 2026;"}}}
{"display_name": "monthly-subscribers", "evaluation_request": {"prompt": {"text": "List active subscribers on monthly billing"}, "golden_response": {"candidate": "golden", "text": "SELECT user_id, email FROM `project.dataset.subscriptions` WHERE status = 'ACTIVE' AND plan_type = 'MONTHLY';"}}}

Eine ausführliche Anleitung zum Erstellen hochwertiger Bewertungs-Datasets finden Sie in der Dokumentation zur Gemini Enterprise Agent Platform.

Agent-Traces für selbstständiges Lernen konfigurieren

Damit der Anreicherungs-Agent nachgelagerte Interaktionen mit Gemini Enterprise-Agenten (oder benutzerdefinierten Gemini Enterprise Agent Platform-Anwendungen) automatisch analysieren kann, können Sie ihm optional Lesezugriff auf die Interaktions-Traces Ihrer Anwendung gewähren.

Durch die Aufnahme dieser Traces kann der Agent Trajectory Mining durchführen. Der Agent erkennt, wo nachgelagerte Agenten aufgrund fehlenden Kontexts Probleme hatten, fasst häufige Nutzerfragen in Abfrageklassen mit hoher Auswirkung zusammen und stellt automatisch die genauen Tabellenzusammenfassungen, Spaltensemantiken und Unternehmensglossarbegriffe zusammen, die zum Schließen dieser Lücken erforderlich sind.

Wählen Sie je nach Unternehmensarchitektur eine der folgenden beiden Einrichtungsmethoden aus:

Direktes Logging mit Logansichten mit eingeschränktem Bereich (empfohlen)

Wenn das Interaktions-Logging für eine Anwendung aktiviert ist, werden Ausführungslogs direkt in Logging gestreamt. Um das Prinzip der geringsten Berechtigung zu befolgen, erstellen Sie eine dedizierte Logansicht, die auf die jeweilige Anwendung beschränkt ist, und gewähren Sie dem Ausführungsdienstkonto ausschließlich Lesezugriff auf diese Ansicht.

  1. Erstellen Sie eine Logansicht mit eingeschränktem Bereich, um die Logs zu isolieren. So wird sichergestellt, dass der Anreicherungsdienst nur Telemetriedaten von bestimmten konfigurierten Anwendungen liest (z. B. durch Filtern nach resource.type="aiplatform.googleapis.com/Agent"). Dadurch wird ein nicht autorisierter Zugriff auf Ihre allgemeinen Cloud-Logs verhindert.

    gcloud-CLI

    Verwenden Sie den Befehl gcloud logging views create, um eine Logansicht für einen Bereich zu erstellen:

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • LOG_VIEW_NAME: der Name Ihrer Logansicht
    • YOUR_GEMINI_ENTERPRISE_APP_ID: die Anwendungs-ID Ihrer Gemini Enterprise-Anwendung

    Führen Sie folgenden Befehl aus:

    Linux, macOS oder Cloud Shell

    gcloud logging views create LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (PowerShell)

    gcloud logging views create LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    Windows (cmd.exe)

    gcloud logging views create LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --log-filter='resource.type="aiplatform.googleapis.com/Agent" AND resource.labels.agent_id="YOUR_GEMINI_ENTERPRISE_APP_ID"'

    REST

    Ersetzen Sie diese Werte in den folgenden Anfragedaten:

    • LOG_VIEW_NAME: der Name Ihrer Logansicht
    • TARGET_PROJECT_ID: Ihre Google Cloud-Projekt-ID
    • YOUR_GEMINI_ENTERPRISE_APP_ID: die Anwendungs-ID Ihrer Gemini Enterprise-Anwendung

    HTTP-Methode und URL: 

    POST https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME

    JSON-Text anfordern:

    {
 "filter": "resource.type=\"aiplatform.googleapis.com/Agent\" AND resource.labels.agent_id=\"YOUR_GEMINI_ENTERPRISE_APP_ID\""
}

    Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

    Sie sollten einen erfolgreichen Statuscode (2xx) und eine leere Antwort als Ausgabe erhalten.

  2. Nachdem Sie die Logansicht erstellt haben, gewähren Sie dem Ausführungsdienstkonto Lesezugriff darauf. Dadurch wird der Anreicherungsjob autorisiert, die Anwendungstelemetrie abzurufen, die er während der selbstlernenden Phase benötigt.

    Verwenden Sie den Befehl gcloud logging views add-iam-policy-binding, um einer Logansicht eine IAM-Richtlinienbindung hinzuzufügen:

    Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

    • LOG_VIEW_NAME: der Name Ihrer Logansicht
    • SERVICE_ACCOUNT_NAME: der Name Ihres Dienstkontos
    • TARGET_PROJECT_ID: Ihre Google Cloud-Projekt-ID

    Führen Sie folgenden Befehl aus:

    Linux, macOS oder Cloud Shell

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/logging.viewAccessor"

    Windows (PowerShell)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/logging.viewAccessor"

    Windows (cmd.exe)

    gcloud logging views add-iam-policy-binding LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/logging.viewAccessor"

Weitere Informationen finden Sie unter Logansichten für einen Log-Bucket konfigurieren.

BigQuery Agent Analytics

Wenn Ihre Organisation Interaktionslogs mithilfe einer Logging-Logsenke in BigQuery streamt oder direkt in BigQuery-Agent-Analysetabellen schreibt, können Sie stattdessen Zugriff auf das Dataset gewähren.

Achten Sie darauf, dass die Interaktionslogs so konfiguriert sind, dass sie in ein bestimmtes BigQuery-Dataset gestreamt werden, und prüfen Sie, ob dem Ausführungsdienstkonto die Rolle „BigQuery-Datenbetrachter“ (roles/bigquery.dataViewer) für dieses Dataset zugewiesen ist. So kann der Agent die exportierten Telemetriedaten direkt aus BigQuery lesen.

Weitere Informationen zum Exportieren von Logs finden Sie unter Logs an unterstützte Ziele weiterleiten.

Datenprofilerstellung und Dateneinblicke aktivieren

Bevor Sie eine Anreicherungsaufgabe ausführen, sollten Sie das Datenprofiling und die KI-Dateneinblicke für Ihre häufig verwendeten Zieltabellen aktivieren. Das Datenprofiling liefert statistische Merkmale wie häufige Werte, Datenverteilungen und Nullwerte, während Dateneinblicke grundlegende Tabellenbeschreibungen und Beispielabfragen generieren. Wenn Sie diese Signale bereitstellen, kann der Anreicherungs-Agent genauere Metadatenvorschläge generieren.

Nächste Schritte