Configura i prerequisiti per le attività di arricchimento

Prima di poter creare attività di arricchimento in Knowledge Studio, potrebbe essere necessario configurare diversi componenti dell'infrastruttura sottostante, a seconda dell'architettura di sicurezza e delle origini dati di destinazione.

Questa guida descrive come configurare i service account gestiti dal cliente, i provider di autenticazione di terze parti, i bucket Cloud Storage e le visualizzazioni di Cloud Logging.

La tabella seguente descrive le configurazioni dei prerequisiti e quando devi configurarle:

Funzionalità di configurazione Quando configurare
API Google Cloud Obbligatorio. Devi abilitare le API Google Cloud sottostanti per eseguire i workflow di arricchimento.
Service account gestito dal cliente Vuoi limitare l'accesso in lettura e scrittura ai set di dati di destinazione.
Ruoli IAM (Identity and Access Management) degli utenti Devi concedere ai gestori e ai revisori del workflow le autorizzazioni per generare e approvare i metadati.
Provider di autenticazione di terze parti Ti stai connettendo a fonti di conoscenza di terze parti (come Microsoft SharePoint, Atlassian Confluence o GitHub).
Bucket Cloud Storage Stai importando un contesto aziendale non strutturato (ad esempio PDF, Markdown e CSV) e set di dati di valutazione.
Set di dati di valutazione Vuoi fornire query seed e set di dati di benchmark per monitorare attivamente l'accuratezza dell'agente.
Tracce degli agenti per l'autoapprendimento Vuoi che l'agente di arricchimento analizzi automaticamente le interazioni degli agenti Gemini Enterprise downstream.
Profilazione e insight sui dati Consigliata. Vuoi migliorare la qualità dell'arricchimento generando profili statistici e insight di base sull'AI sulle tabelle utilizzate di frequente.

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  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.

Dettagli delle API richieste

Per configurare ed eseguire le attività di arricchimento, le API abilitate eseguono le seguenti funzioni:

Nome API Identificatore servizio Scopo nei workflow di arricchimento
API Dataplex dataplex.googleapis.com API del control plane principale. Gestisce EnrichmentTask, EnrichmentRun, i set di contesto, le richieste di modifica e EnrichmentChatService.
API BigQuery bigquery.googleapis.com Obbligatorio per la scansione degli schemi delle tabelle, l'importazione della cronologia di esecuzione SQL e l'esecuzione di query sulle tabelle di traccia di BigQuery Agent Analytics.
API Cloud Storage storage.googleapis.com Obbligatorio per l'importazione dei set di valutazione e la gestione degli esempi di set di dati di valutazione.
API Service Account Credentials IAM iamcredentials.googleapis.com Obbligatorio per autenticare in modo sicuro l'agente di esecuzione e concedere credenziali di breve durata (SLC) durante le attività.

Configura un account di servizio gestito dal cliente

Le attività di arricchimento utilizzano un account di servizio gestito dal cliente per eseguire le operazioni. In questo modo, puoi limitare l'accesso in lettura e scrittura ai set di dati di destinazione.

  1. Crea il service account.

    Per creare un account di servizio, devi essere un Project Owner (roles/owner) o un Editor (roles/editor) oppure devi disporre del ruolo Service Account Admin (roles/iam.serviceAccountAdmin).

    Un account di servizio dedicato isola le operazioni di arricchimento, consentendoti di concedere solo le autorizzazioni di lettura e autorizzazione in scrittura specifiche necessarie per queste attività senza influire su altri workload.

    Per creare un account di servizio, segui questi passaggi:

    Google Cloud CLI

    Per creare un account di servizio, utilizza il comando gcloud iam service-accounts create:

    Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

    • SERVICE_ACCOUNT_NAME: il nome del account di servizio

    Esegui questo comando:

    Linux, macOS o 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

    Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

    • SERVICE_ACCOUNT_NAME: il nome del account di servizio
    • TARGET_PROJECT_ID: l'ID del tuo progetto Google Cloud

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.

  2. Concedi i ruoli IAM a livello di risorsa necessari al account di servizio di esecuzione negli ambiti di destinazione:

    • Dataplex Catalog Editor (roles/dataplex.catalogEditor) e Dataplex Catalog Viewer (roles/dataplex.catalogViewer): consente all'agente di ispezionare i metadati del catalogo, creare voci di lavoro temporanee e pubblicare manualmente gli arricchimenti approvati.
    • (Facoltativo) Dataplex Workflow Approver (roles/dataplex.workflowApprover): richiesto solo se attivi la pubblicazione automatica per l'attività. Consente all'agente di approvare e pubblicare automaticamente le proprie richieste di modifica dei metadati.
    • Visualizzatore dati BigQuery (roles/bigquery.dataViewer): consente all'agente di leggere gli schemi delle tabelle, i metadati delle colonne e le tabelle di traccia di analisi dell'agente.

    Nota: i seguenti esempi di codice concedono questi ruoli a livello di progetto per semplificare la configurazione. Per i sistemi di produzione, ti consigliamo vivamente di concedere questi ruoli in modo sicuro a livello di risorsa sui tuoi set di dati di destinazione specifici.

    Per concedere questi ruoli standard, segui questi passaggi:

    Per aggiungere un'associazione di policy IAM a un progetto, utilizza il comando gcloud projects add-iam-policy-binding:

    Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

    • SERVICE_ACCOUNT_NAME: il nome del account di servizio
    • TARGET_PROJECT_ID: l'ID del tuo progetto Google Cloud

    Esegui questo comando:

    Linux, macOS o 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. Concedi agli utenti l'autorizzazione per simulare l'identità del account di servizio assegnando loro il ruolo Service Account User (roles/iam.serviceAccountUser):

    Gli utenti che creano le attività di arricchimento nella console devono disporre di questa autorizzazione per poter specificare e collegare questo account di servizio all'attività.

    Per concedere agli utenti il ruolo Service Account User, segui questi passaggi:

    Per aggiungere un'associazione della policy IAM a un account di servizio, utilizza il comando gcloud iam service-accounts add-iam-policy-binding:

    Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

    • SERVICE_ACCOUNT_NAME: il nome del account di servizio
    • TARGET_PROJECT_ID: l'ID del tuo progetto Google Cloud
    • USER_EMAIL: l'indirizzo email dell'utente

    Esegui questo comando:

    Linux, macOS o 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. Consenti all'agente di servizio Knowledge Catalog interno di impersonare questo service account concedendogli il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator):

    In questo modo, il servizio Knowledge Catalog sottostante può assumere l'identità di questo account di servizio dedicato e le relative autorizzazioni limitate quando esegue le operazioni di arricchimento in background per tuo conto.

    Per autorizzare l'agente ad assumere l'identità del account di servizio, segui questi passaggi:

    Per aggiungere un'associazione della policy IAM a un account di servizio, utilizza il comando gcloud iam service-accounts add-iam-policy-binding:

    Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

    • SERVICE_ACCOUNT_NAME: il nome del account di servizio
    • TARGET_PROJECT_ID: l'ID del tuo progetto Google Cloud
    • TARGET_PROJECT_NUMBER: il numero del tuo progetto Google Cloud

    Esegui questo comando:

    Linux, macOS o 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"

Concedi i ruoli IAM richiesti agli utenti

Per assicurarti che il tuo team possa gestire i workflow di arricchimento ed esaminare le proposte generate dall'AI, concedi i ruoli IAM appropriati ai tuoi utenti. Per istruzioni su come concedere questi ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

I gestori dei workflow (come i data steward) che creano, configurano e monitorano le attività richiedono i seguenti ruoli:

  • Dataplex DataScan Editor (roles/dataplex.dataScanEditor) o Dataplex Editor (roles/dataplex.editor): consente agli utenti di creare, modificare, attivare e annullare le attività di arricchimento.
  • Utente dell'account di servizio (roles/iam.serviceAccountUser) sul service account gestito dal cliente: richiesto per collegare il service account come identità di esecuzione dell'attività.

I revisori delle modifiche (ad esempio i proprietari di domini o gli esperti in materia) che ispezionano, approvano e pubblicano nel catalogo le proposte di metadati generate dall'AI richiedono i seguenti ruoli:

  • Dataplex Catalog Editor (roles/dataplex.catalogEditor) e Dataplex Catalog Viewer (roles/dataplex.catalogViewer): necessari per aprire le richieste di modifica, esaminare le differenze delle proposte affiancate e modificare le descrizioni incorporate.
  • Dataplex Workflow Approver (roles/dataplex.workflowApprover): richiesto per approvare e pubblicare le richieste di modifica nel catalogo attivo.
  • Dataplex DataScan Viewer (roles/dataplex.dataScanViewer) o Dataplex Viewer (roles/dataplex.viewer): richiesto per esaminare i punteggi di affidabilità per proposta, la diagnosi degli errori dei test e i prospetti di valutazione downstream.

Configura provider di autenticazione di terze parti

Quando connetti l'agente di arricchimento a fonti di conoscenza di terze parti (come Microsoft SharePoint, Atlassian Confluence o GitHub), devi configurare un provider di autenticazione utilizzando il servizio di identità dell'agente di Google Cloud.

Agent Identity funge da gestore delle credenziali di sicurezza che cripta i token di terze parti all'interno del progetto, garantendo che gli operatori umani non debbano mai gestire i client secret non elaborati durante l'esecuzione delle attività.

Per istruzioni passo passo su come generare i token richiesti e configurare il provider di autenticazione per piattaforme esterne specifiche, consulta Configura i connettori esterni per le attività di arricchimento.

Configura le autorizzazioni IAM per i provider di autenticazione

Per consentire all'agente di arricchimento di recuperare in modo sicuro le credenziali del provider di autenticazione in modo dinamico durante un'esecuzione attiva, devi concedere il ruolo Agent Identity Admin (roles/agentidentity.admin) all'agente di servizio Knowledge Catalog (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com) gestito. Puoi concedere questo ruolo a livello di risorsa del provider di autenticazione o a livello di progetto.

Inoltre, l'utente umano che collega il provider di autenticazione all'attività nella consoleGoogle Cloud deve disporre dell'autorizzazione agentidentity.authProviders.get (inclusa in Agent Identity Viewer (roles/agentidentity.viewer)) sul provider di autenticazione.

Prepara i bucket Cloud Storage

Cloud Storage funge da livello principale di gestione temporanea basata su file, importazione del contesto ed esportazione degli artefatti per i workflow di arricchimento delle conoscenze.

Puoi configurare l'agente in modo che importi i file da uno o più bucket di input per basare il suo ragionamento sulla conoscenza del dominio aziendale. I tipi di contesto supportati includono:

  • Documentazione del dominio e dizionari di dati: file Markdown, testo normale, PDF, HTML o CSV contenenti definizioni di tabelle, glossari aziendali, procedure operative standard (SOP), architetture di pipeline di dati o linee guida per la denominazione delle colonne.

  • Set di dati di valutazione: file JSONL o CSV che memorizzano le query seed e i set di query di convalida esclusi. Per saperne di più, consulta Formatta i set di dati di valutazione.

  • Script SQL e di trasformazione di riferimento: script SQL salvati, definizioni dei modelli dbt o logica di trasformazione ETL che forniscono indicatori di contesto relativi ai pattern di join delle tabelle e ai calcoli aziendali.

Se configurato, l'agente di arricchimento può anche esportare bundle strutturati ed eseguire artefatti in un bucket di output. Gli artefatti di output supportati includono:

  • Report di valutazione dettagliati: scorecard complete che mostrano i delta di accuratezza per query, la diagnosi degli errori dei test e le metriche di distribuzione della confidenza.

Per assicurarti che l'agente di arricchimento possa operare all'esterno del bucket, assicurati che il tuo account di servizio di esecuzione disponga delle autorizzazioni necessarie.

  • Concedi il ruolo Visualizzatore oggetti (roles/storage.objectViewer) sui bucket di input in modo che l'agente possa leggere i documenti e i file di configurazione delle fasi.
  • (Facoltativo) Concedi il ruolo Object Creator (roles/storage.objectCreator) sul bucket di output se vuoi che l'agente salvi gli artefatti di esecuzione e i log di convalida.

Per concedere al account di servizio l'accesso ai bucket Cloud Storage, segui questi passaggi:

Per aggiungere un'associazione di policy IAM a un bucket di archiviazione, utilizza il comando gcloud storage buckets add-iam-policy-binding:

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • CUSTOMER_BUCKET: il nome del bucket Cloud Storage
  • SERVICE_ACCOUNT_NAME: il nome del account di servizio
  • TARGET_PROJECT_ID: l'ID del tuo progetto Google Cloud

Esegui questo comando:

Linux, macOS o 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"

Formatta i set di dati di valutazione

I workflow di arricchimento possono estrarre automaticamente le informazioni senza esempi. Tuttavia, fornire set di dati di valutazione consente all'agente di testarsi e migliorare la sua accuratezza.

Puoi fornire due tipi di set di dati:

  • Set di selezione: un elenco di domande degli utenti di esempio e delle query SQL previste. L'agente utilizza questo elenco per esercitarsi e scrivere riepiloghi delle tabelle migliori.

  • Set di valutazione: un elenco separato di domande utilizzate per valutare le prestazioni dell'agente. Se l'agente ha un rendimento scarso, questo set di valutazione impedisce la pubblicazione di aggiornamenti scadenti nel tuo catalogo.

In alternativa, puoi fornire un unico set di dati consolidato. Il servizio di arricchimento suddivide automaticamente i dati in un set di selezione e un set di valutazione.

Requisiti dello schema del set di dati

I set di dati di valutazione devono essere formattati come file JSONL e archiviati in Cloud Storage. Ogni riga del file deve contenere una domanda in linguaggio naturale associata alla query SQL di dati di fatto prevista.

Assicurati che il file corrisponda allo schema del set di dati di valutazione prescritto da Gemini Enterprise Agent Platform. La tabella seguente mostra i campi di formattazione accettati:

Nome campo Tipo Descrizione
display_name STRING Facoltativo. Un identificatore o un nome per la richiesta di valutazione.
evaluation_request.prompt.text STRING La domanda in linguaggio naturale o il prompt dell'utente.
evaluation_request.golden_response.candidate STRING Identifica la risposta di riferimento. Da impostare su golden.
evaluation_request.golden_response.text STRING La query SQL convalidata, che rappresenta il dato di fatto, che risponde alla domanda. Il sistema di punteggio esegue questo SQL sui dati.

Il seguente snippet mostra un file di valutazione .jsonl valido:

{"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';"}}}

Per indicazioni dettagliate sulla creazione di set di dati di valutazione di alta qualità, consulta la documentazione di Gemini Enterprise Agent Platform.

Configura le tracce dell'agente per l'autoapprendimento

Per consentire all'agente di arricchimento di analizzare automaticamente le interazioni degli agenti Gemini Enterprise downstream (o delle applicazioni Gemini Enterprise Agent Platform personalizzate), puoi facoltativamente fornirgli l'accesso in lettura alle tracce di interazione della tua applicazione.

L'importazione di queste tracce consente all'agente di eseguire il mining delle traiettorie. L'agente scopre dove gli agenti downstream hanno avuto difficoltà a causa della mancanza di contesto, raggruppa le domande frequenti degli utenti in classi di query ad alto impatto e cura automaticamente i riepiloghi esatti delle tabelle, la semantica delle colonne e i termini del glossario aziendale necessari per risolvere queste lacune.

A seconda dell'architettura aziendale, scegli uno dei seguenti due metodi di configurazione:

Logging diretto utilizzando visualizzazioni dei log con ambito (consigliato)

Quando il logging delle interazioni è abilitato per un'applicazione, i log di esecuzione vengono trasmessi direttamente in flussi in Logging. Per seguire il principio del privilegio minimo, crea una visualizzazione log dedicata limitata all'applicazione specifica e concedi al account di servizio di esecuzione l'accesso in lettura esclusivamente a quella visualizzazione.

  1. Creare una visualizzazione log mirata per isolare i log. In questo modo, il servizio di arricchimento legge la telemetria solo da applicazioni configurate specifiche (ad esempio, filtrando in base a resource.type="aiplatform.googleapis.com/Agent"), impedendo l'accesso non autorizzato ai log di Cloud più ampi.

    gcloud CLI

    Per creare una visualizzazione log con ambito, utilizza il comando gcloud logging views create:

    Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

    • LOG_VIEW_NAME: il nome della visualizzazione log
    • YOUR_GEMINI_ENTERPRISE_APP_ID: l'ID applicazione Gemini Enterprise

    Esegui questo comando:

    Linux, macOS o 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

    Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

    • LOG_VIEW_NAME: il nome della visualizzazione log
    • TARGET_PROJECT_ID: l'ID del tuo progetto Google Cloud
    • YOUR_GEMINI_ENTERPRISE_APP_ID: l'ID applicazione Gemini Enterprise

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.

  2. Dopo aver creato la visualizzazione dei log, concedi l'accesso in lettura al account di servizio di esecuzione. In questo modo, il job di arricchimento è autorizzato a estrarre la telemetria dell'applicazione di cui ha bisogno durante la fase di autoapprendimento.

    Per aggiungere un'associazione della policy IAM a una visualizzazione log, utilizza il comando gcloud logging views add-iam-policy-binding:

    Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

    • LOG_VIEW_NAME: il nome della visualizzazione log
    • SERVICE_ACCOUNT_NAME: il nome del account di servizio
    • TARGET_PROJECT_ID: l'ID del tuo progetto Google Cloud

    Esegui questo comando:

    Linux, macOS o 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"

Per saperne di più, consulta Configura le visualizzazioni dei log su un bucket di log.

BigQuery Agent Analytics

Se la tua organizzazione trasmette in streaming i log delle interazioni in BigQuery utilizzando un sink di log di Logging o scrive direttamente nelle tabelle di analisi degli agenti di BigQuery, puoi concedere l'accesso al set di dati.

Assicurati che i log delle interazioni siano configurati per lo streaming in un set di dati BigQuery designato e verifica che al account di servizio di esecuzione sia concesso il ruolo BigQuery Data Viewer (roles/bigquery.dataViewer) su quel set di dati specifico. In questo modo, l'agente può leggere la telemetria esportata direttamente da BigQuery.

Per saperne di più sull'esportazione dei log, consulta Instrada i log verso destinazioni supportate.

Abilita la profilazione e gli insight sui dati

Prima di eseguire un'attività di arricchimento, ti consigliamo di attivare la profilazione dei dati e gli insight sui dati AI sulle tabelle di destinazione utilizzate di frequente. La profilazione dei dati fornisce caratteristiche statistiche, come valori comuni, distribuzioni dei dati e conteggi di valori nulli, mentre gli insight sui dati generano descrizioni delle tabelle di base e query di esempio. Fornire questi indicatori aiuta l'agente di arricchimento a generare proposte di metadati più accurate.

Passaggi successivi