Domande frequenti sull'API Conversational Analytics

Questa pagina risponde alle domande frequenti sull'API Conversational Analytics.

L'API Conversational Analytics può modificare o eliminare i miei dati?

L'API Conversational Analytics è progettata con misure di salvaguardia per impedire l'alterazione o l'eliminazione dei tuoi dati.

Ecco come viene gestita la sicurezza dei dati per le diverse origini dati:

  • BigQuery: l'API blocca le istruzioni DDL (Data Definition Language) e DML (Data Manipulation Language). Nello specifico, il sistema esegue un test run sull'SQL generato e consente solo query di tipo SELECT.
  • Looker: l'API interagisce con Looker utilizzando metodi come run_inline_query, che sono limitati alle operazioni di lettura come selezioni, filtri e limiti. Questi metodi non supportano le operazioni DDL o DML e non includono operazioni di eliminazione o eliminazione.
  • Data Studio (per file CSV e Fogli Google): Data Studio utilizza un formato strutturato per definire e recuperare i dati per visualizzazioni e report. Tutte le query eseguite con questo metodo sono di sola lettura e non supportano le mutazioni dei dati.
  • Database: il sistema consente solo query di tipo SELECT. Per impedire l'alterazione o l'eliminazione dei dati, assicurati che ilaccount di serviziot o l'utente che interagisce con l'API Conversational Analytics disponga delle autorizzazioni di sola lettura per il tuo database.

L'API Conversational Analytics è progettata per essere di sola lettura in queste origini dati. Per saperne di più sulla sicurezza dell'API Conversational Analytics, leggi il post del blog Chat with confidence: Unpacking security in Looker Conversational Analytics.

Come faccio a gestire gli errori di autenticazione e autorizzazione?

Di seguito sono riportati alcuni errori comuni di autenticazione e autorizzazione che potresti riscontrare durante l'utilizzo dell'API Conversational Analytics:

  1. Errore: PERMISSION_DENIED o 403 Write access to project ... was denied

    • Causa probabile: questo messaggio spesso indica problemi con i Google Cloud ruoli IAM. L'utente o il account di servizio che tenta di utilizzare l'API non dispone delle autorizzazioni necessarie per il progetto Google Cloud .
    • Risoluzione dei problemi:
      • Il proprietario del progetto Google Cloud deve assicurarsi che all'utente o al account di servizio siano assegnati i ruoli IAM corretti nel progetto Google Cloud . Per determinate operazioni, come l'abilitazione dell'API o il test delle sue funzioni, potrebbero essere necessari ruoli come Project Editor.
      • Se riscontri un errore 403 come Write access to project 'us-gcp-project-name' was denied quando cambi regione, verifica la configurazione IAM del progetto.

  2. Errore: 500 Internal Server Error quando un utente Looker con il ruolo Utente tenta di chattare con un agente di dati.

Perché visualizzo errori 503 o 500 durante lo streaming delle risposte?

Se utilizzi un client HTTP o REST di base (come la libreria Python requests) per chiamare l'endpoint di streaming :chat, l'API potrebbe restituire un messaggio di errore generico, ad esempio 503 Connection reset by peer o 500 Internal error.

Questi errori generici si verificano perché l'API di streaming invia un'intestazione HTTP 200 OK non appena si apre lo stream. Se l'agente dati rileva un errore irreversibile durante lo stream (ad esempio un timeout per una query a esecuzione prolungata o un'improvvisa negazione dell'autorizzazione), termina lo stream e include il codice di errore specifico nei trailer HTTP/2. I client HTTP o REST standard non possono analizzare queste intestazioni finali e interpretano l'interruzione improvvisa come un arresto anomalo del socket.

Per gestire gli errori che si verificano durante uno stream, ti consigliamo vivamente di utilizzare le librerie client (SDK) ufficiali Google Cloud , come l'SDK Python. Questi SDK basati su gRPC analizzano i trailer HTTP/2 e restituiscono il codice di errore specifico, ad esempio DEADLINE_EXCEEDED o PERMISSION_DENIED, anziché un errore di rete generico.

Quali sono i requisiti di Looker per l'utilizzo dell'API Conversational Analytics?

Per utilizzare l'API Conversational Analytics, devi disporre delle autorizzazioni appropriate sia in Google Cloud IAM sia in Looker, a seconda dell'origine dati e delle azioni che vuoi eseguire:

  1. Google Cloud Ruoli IAM:

    • Devi disporre di ruoli IAM sufficienti nel tuo progetto Google Cloud per interagire con l'APIgeminidataanalytics.googleapis.com. I ruoli IAM configurati in modo errato spesso causano errori PERMISSION_DENIED.
    • I ruoli specifici richiesti possono dipendere dalle azioni, ma per determinate operazioni potrebbero essere necessari ruoli generali come Project Editor.

  2. Ruoli e autorizzazioni di Looker:

    • Autorizzazioni a livello di modello: per utilizzare Analisi conversazionale e l'API Analisi conversazionale, a un utente Looker deve essere assegnato un ruolo Looker che contenga l'autorizzazione gemini_in_looker per i modelli con cui interagisce.

Per saperne di più sulle autorizzazioni e sui ruoli necessari per utilizzare l'API Conversational Analytics, consulta la pagina di documentazione Concedere ruoli e autorizzazioni IAM per l'API Conversational Analytics.

Inoltre, l'istanza di Looker deve soddisfare requisiti specifici:

Per utilizzare l'API Conversational Analytics con Data Studio Pro, l'abbonamento Pro deve trovarsi al di fuori di un perimetro VPC-SC.

Quali sono i requisiti del database per l'utilizzo dell'API Conversational Analytics?

Per utilizzare l'API Conversational Analytics con database come AlloyDB per PostgreSQL, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL, devi assicurarti che l'autenticazione e l'attivazione IAM siano corrette:

  1. Google Cloud Ruoli IAM:

    • Il account di servizio o l'utente deve disporre dei ruoli IAM necessari per connettersi al database specifico ed eseguire query. In genere, si tratta di ruoli con accesso in lettura al database.

  2. Abilitazione API:

    • Assicurati che l'API Cloud AI Companion sia abilitata nel tuo progetto Google Cloud .

Per saperne di più su come abilitare l'autenticazione IAM, consulta la documentazione di ogni database:

Come faccio a eseguire la migrazione dall'API Data QnA all'API Conversational Analytics?

Se hai utilizzato la versione sperimentale precedente dell'API Data QnA (dataqna.googleapis.com), consulta la guida alla migrazione per scoprire come eseguire la migrazione al nuovo endpoint ufficiale dell'API Conversational Analytics (geminidataanalytics.googleapis.com).

Qual è la differenza tra il nome e l'ID di un agente di dati?

L'ID del data agent, definito come valore di data_agent_id, è l'identificatore univoco del data agent. Il nome dell'agente di dati, data_agent.name, viene derivato automaticamente da data_agent_id come nome completo (FQN), assumendo la forma projects/<project>/locations/<location>/dataAgents/<data_agent_id>.

Quando crei un agente di dati, qualsiasi valore che potresti aver inserito per data_agent.name viene ignorato. Quando esegui operazioni get, update o delete, l'data_agent.name completo viene considerato l'identificatore univoco del data agent.

Quando utilizzi l'API Conversational Analytics per creare agenti di dati, si applicano i seguenti scenari:

  • Se non definisci data_agent_id, viene generato automaticamente un ID univoco.
  • Se definisci data_agent_id come, ad esempio, TestID, qualsiasi valore che potresti aver inserito per data_agent.name viene sovrascritto con projects/<project>/locations/<location>/dataAgents/TestID.
  • Se definisci data_agent_id con un FQN, ricevi un errore "Nome non valido".

Qual è il formato accettato per un ID in Crea agente o Crea conversazione?

Per gli agenti di dati:

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

{data_agent} è l'ID risorsa. Deve contenere al massimo 63 caratteri e deve corrispondere al formato descritto in https://google.aip.dev/122#resource-id-segments.

Esempio: projects/1234567890/locations/us-central1/dataAgents/my-agent

Ti consigliamo di saltare l'impostazione di questo campo durante la creazione dell'agente, in quanto verrà dedotto automaticamente e sovrascritto con {parent}/dataAgents/{data_agent_id}.

Per le conversazioni:

projects/{project}/locations/{location}/conversations/{conversation_id}

{conversation_id} è l'ID risorsa e deve contenere al massimo 63 caratteri e corrispondere al formato descritto in https://google.aip.dev/122#resource-id-segments.

Esempio: projects/1234567890/locations/us-central1/conversations/my-conversation.

Ti consigliamo di saltare l'impostazione di questo campo durante la creazione della conversazione perché l'Analisi conversazionale lo identificherà automaticamente e lo sovrascriverà con {parent}/conversations/{conversation_id}.

Come si usa updateMask?

Nel metodo dell'agente dati patch, il parametro updateMask accetta una stringa di formato FieldMask che specifica quali campi dataAgent verranno sovrascritti nella risorsa dataAgent con l'aggiornamento. Il parametro updateMask è un campo obbligatorio e viene convalidato nel seguente modo:

  • Se updateMask è vuoto, verrà generato un BadRequestException e nessun campo verrà aggiornato.
  • Se tutti i campi in updateMask sono campi dataAgent validi, verranno aggiornati solo questi campi.
  • Se viene fornito un mix di campi validi e non validi, i campi non validi verranno ignorati e verranno aggiornati solo quelli validi.

Come faccio a utilizzare getIAMPolicy e setIAMPolicy per impostare il criterio IAM per un agente dati?

Puoi utilizzare il metodo getIamPolicy e il metodo setIamPolicy per assegnare ruoli IAM agli utenti per un agente specifico.

I seguenti esempi di codice mostrano come recuperare la policy IAM per un agente dati:

I seguenti esempi di codice mostrano come assegnare IAM a un agente dati:

Quali sono le capacità di memoria dell'agente di dati dell'API Conversational Analytics?

  • All'interno di una singola sessione: l'API Conversational Analytics supporta le conversazioni a più turni, il che significa che può fare riferimento a parti precedenti della conversazione corrente.
  • In più sessioni: l'API Conversational Analytics include funzionalità per la cronologia delle conversazioni gestita, che consente agli utenti di chattare in più sessioni. Supporta anche agenti stateful con conversazioni multi-turn gestite da Google.
  • Memoria a lungo termine: gli agenti di dati dell'API Conversational Analytics non supportano funzionalità esplicite di memoria a lungo termine.

Un agente dati dell'API Conversational Analytics mi darà la stessa risposta ogni volta che pongo la stessa domanda?

  • Le risposte in linguaggio naturale dell'agente dati dell'API Conversational Analytics non sono deterministiche, quindi la risposta in linguaggio naturale fornita dall'agente può variare anche per una domanda formulata in modo identico.
  • Risposte alle query sui dati: tuttavia, per una domanda specifica di ricerca di dati, la query generata sottostante (SQL o Looker) deve essere deterministica. I dati recuperati devono essere gli stessi, supponendo che i dati sottostanti non siano cambiati.

Come posso migliorare l'accuratezza delle risposte di un agente dati dell'API Conversational Analytics?

Un modo per migliorare l'accuratezza delle risposte dell'agente dati è fornire all'agente dati informazioni contestuali solide. Puoi aggiungere il contesto nei seguenti modi:

  • Nel livello semantico di Looker, puoi fornire il contesto all'interno delle definizioni LookML. Per ulteriori informazioni ed esempi, consulta la pagina della documentazione Guida il comportamento dell'agente con il contesto creato in Looker.
  • Per le origini dati BigQuery, puoi fornire un contesto creato tramite campi di contesto strutturati, come descrizioni a livello di tabella e colonna, sinonimi, tag e query di esempio, e tramite istruzioni di sistema. Fornire questo contesto contribuisce anche a migliorare l'accuratezza delle risposte e può consentire agli agenti di citare le fonti nelle loro risposte. Per saperne di più, consulta Definire il contesto dell'agente dati per le origini dati BigQuery.
  • Nelle origini dati AlloyDB per PostgreSQL, Cloud SQL per MySQL, Cloud SQL per PostgreSQL e Spanner, puoi fornire il contesto aggiungendo descrizioni e vincoli di tabelle, colonne e schemi come indicazioni per i dati e per la loro interpretazione.

  • Quando crei un agente di dati, puoi fornire istruzioni di sistema, query verificate e contesto avanzato:

    • Istruzioni di sistema, ovvero indicazioni definite dall'utente che possono modellare il comportamento di un agente dati. Queste indicazioni includono logica specifica per l'attività, formattazione della risposta o presentazione dei dati.
    • Puoi fornire query verificate (chiamate anche query dorate a seconda dell'origine dati), ovvero domande di esempio in linguaggio naturale abbinate alle query SQL o Looker corrette.
    • Per le origini dati AlloyDB, Cloud SQL per MySQL, Cloud SQL per PostgreSQL e Spanner, puoi fornire un contesto avanzato, che ti aiuta a ottimizzare la comprensione e l'accuratezza dei dati degli agenti.

    Per saperne di più, consulta Guida il comportamento dell'agente con il contesto creato.

Consulta la pagina Fare domande efficaci per indicazioni su come porre domande per ricevere risposte più efficaci e accurate.

Come posso ispezionare e gestire in modo sicuro il codice Python generato dall'agente?

Se hai attivato l'analisi avanzata con Python, il tuo agente di dati potrebbe restituire codice Python. Il codice Python restituito dagli agenti dati è progettato per essere eseguito all'interno di una sandbox sicura gestita da Google. L'esecuzione di questo codice in un ambiente locale o non verificato aggira le protezioni di sicurezza della sandbox e può esporre il sistema a rischi per la sicurezza, ad esempio l'esecuzione di codice dannoso.

Per ispezionare e gestire in modo sicuro il codice Python generato dall'agente, segui queste linee guida:

  • Ispeziona manualmente il codice generato prima di eseguirlo. Cerca pattern sospetti come richieste di rete impreviste (ad esempio socket, requests o urllib), comandi a livello di sistema (ad esempio os.system o subprocess) o variabili e stringhe letterali fortemente offuscate.
  • Non eseguire mai codice non verificato direttamente su un computer locale o in un ambiente di produzione. Utilizza una sandbox sicura e isolata, ad esempio un notebook Colaboratory, un container Docker temporaneo o una macchina virtuale, che non abbia accesso a credenziali sensibili, reti interne o file system locali.
  • Se possibile, prima di eseguire il codice, esegui strumenti di analisi statica o linters sul codice per segnalare operazioni potenzialmente non sicure o pattern dannosi noti.

Posso integrare l'API Conversational Analytics con applicazioni di terze parti?

L'integrazione dell'API Conversational Analytics con applicazioni di terze parti consente agli utenti di interagire con i propri dati direttamente negli strumenti che utilizzano quotidianamente.

Qualsiasi applicazione di terze parti che interagisce con gli endpoint API geminidataanalytics.googleapis.com deve essere in grado di inviare messaggi utente dall'applicazione all'agente e visualizzare le risposte.

Per creare un'integrazione, consulta il repository delle guide rapide di Analisi conversazionale per esempi o librerie. Puoi anche visitare i forum per sviluppatori Google per cercare esempi di altri utenti.

Quanto costa l'API Conversational Analytics?

L'API Conversational Analytics è in disponibilità generale (GA). Per ulteriori informazioni sui prezzi, consulta la guida ai prezzi.

Inoltre, le query eseguite dagli agenti dati sulle origini dati come BigQuery potrebbero comportare costi per questi servizi. Per BigQuery, puoi gestire i costi impostando quote o limitando i byte fatturati per query utilizzando il parametro bigquery_max_billed_bytes.

Quali origini dati supporta l'API Conversational Analytics?

L'API Conversational Analytics supporta le seguenti origini dati:

  • BigQuery (incluse tabelle e grafici con BigQuery Graph)
  • Esplorazioni Looker
  • Data Studio
  • AlloyDB per PostgreSQL
  • GoogleSQL per Spanner
  • Cloud SQL per MySQL e Cloud SQL per PostgreSQL

Puoi anche connetterti a origini come SAP e Salesforce tramite BigQuery e a file CSV e Fogli Google tramite Data Studio.

Quali sono le limitazioni note dell'API Conversational Analytics?

Per saperne di più sulle limitazioni note dell'API Conversational Analytics, consulta la pagina della documentazione Limitazioni note dell'API Conversational Analytics.

Quali quote devo conoscere per i progetti Google Cloud ?

Non esistono limitazioni alla Google Cloud selezione del progetto o della località. Puoi creare agenti dati per eseguire query sulle origini dati supportate appartenenti a qualsiasi progetto o regione.

L'API Conversational Analytics supporta la residenza dei dati?

Sì, l'API Conversational Analytics supporta la residenza dei dati. Per controllare dove vengono trattati e archiviati i tuoi dati, specifica un endpoint di servizio regionale o multiregionale quando effettui richieste API. Per informazioni dettagliate sul supporto di località specifiche e sui dettagli di configurazione, vedi Residenza dei dati.

L'API Conversational Analytics supporta lingue diverse dall'inglese?

L'unica lingua supportata ufficialmente per l'API Conversational Analytics è l'inglese. Sebbene i modelli Gemini sottostanti supportino molte lingue e alcuni utenti abbiano segnalato risultati aneddotici con query non in inglese, l'API Conversational Analytics non supporta ufficialmente lingue diverse dall'inglese.