Domande frequenti sull'API Conversational Analytics

Questa pagina risponde alle domande frequenti sull'API Analisi conversazionale.

L'API Analisi conversazionale può modificare o eliminare i miei dati?

L'API Analisi conversazionale è progettata con misure di sicurezza per impedire la modifica o l'eliminazione dei 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). In particolare, il sistema esegue un'esecuzione di prova dell'SQL generato e consente solo le 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 rimozione.
  • 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 le query di tipo SELECT. Per impedire la modifica o l'eliminazione dei dati, assicurati che il account di servizio o l'utente che interagisce con l'API Analisi conversazionale disponga delle autorizzazioni di sola lettura per il tuo database.

L'API Analisi conversazionale è progettata per essere di sola lettura in queste origini dati. Per saperne di più sulla sicurezza dell'API Analisi conversazionale, consulta 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 quando utilizzi l'API Analisi conversazionale:

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

    • Causa probabile: questo messaggio spesso indica problemi con i ruoli Google Cloud IAM. L'utente o il account di servizio che tenta di utilizzare l'API non dispone delle autorizzazioni necessarie per il Google Cloud progetto.
    • Risoluzione dei problemi:
      • Il Google Cloud proprietario del progetto deve assicurarsi che all'utente o account di servizio siano assegnati i ruoli IAM corretti nel Google Cloud progetto. Per alcune operazioni, come l'attivazione dell'API o il test delle sue funzioni, potrebbero essere necessari ruoli come Project Editor.
      • Se si verifica 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 (ad esempio la libreria requests di Python) 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 lo stream si apre. Se l'agente di dati rileva un errore irreversibile durante lo stream (ad esempio un timeout per una query a lunga esecuzione o una negazione improvvisa delle autorizzazioni), 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 invece l'interruzione improvvisa come un arresto anomalo del socket.

Per gestire gli errori che si verificano durante uno stream, ti consigliamo vivamente di utilizzare lelibrerie 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 Analisi conversazionale?

Per utilizzare l'API Analisi conversazionale, 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 Google Cloud progetto per interagire con l'API geminidataanalytics.googleapis.com. I ruoli IAM configurati in modo errato spesso generano errori PERMISSION_DENIED.
    • I ruoli specifici richiesti possono dipendere dalle azioni, ma per alcune operazioni potrebbero essere necessari ruoli generali come Editor progetto.

  2. Autorizzazioni e ruoli 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'gemini_in_looker autorizzazione per i modelli con cui interagisce.

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

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

Per utilizzare l'API Analisi conversazionale con Data Studio Pro, l'abbonamento Pro deve essere al di fuori di un perimetro VPC-SC.

Quali sono i requisiti del database per l'utilizzo dell'API Analisi conversazionale?

Per utilizzare l'API Analisi conversazionale 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 ed eseguire query sul database specifico. In genere, si tratta di ruoli con accesso in lettura al database.

  2. Attivazione API:

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

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

Come faccio a eseguire la migrazione dall'API Data QnA all'API Analisi conversazionale?

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 Analisi conversazionale (geminidataanalytics.googleapis.com).

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

L'ID dell'agente di dati, definito come il valore di data_agent_id, è l'identificatore univoco dell'agente di dati. Il nome dell'agente di dati, data_agent.name, viene derivato automaticamente da data_agent_id come nome completo (FQN), con il formato 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, il data_agent.name completo viene trattato come identificatore univoco dell'agente di dati.

Quando utilizzi l'API Analisi conversazionale 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, perché 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é Analisi conversazionale lo identificherà automaticamente e lo sovrascriverà con {parent}/conversations/{conversation_id}.

Come faccio a utilizzare la maschera di aggiornamento?

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

  • Se updateMask è vuoto, viene generata un'eccezione BadRequestException e nessun campo viene aggiornato.
  • Se tutti i campi in updateMask sono campi dataAgent validi, verranno aggiornati solo questi campi.
  • Se viene fornita una combinazione di campi validi e non validi, i campi non validi vengono ignorati e vengono aggiornati solo quelli validi.

Come faccio a utilizzare getIAMPolicy e setIAMPolicy per impostare il criterio IAM per un agente di 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 il criterio IAM per un agente di dati:

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

Quali sono le funzionalità di memoria dell'agente di dati dell'API Analisi conversazionale?

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

Un agente di dati dell'API Analisi conversazionale mi darà la stessa risposta ogni volta che pongo la stessa domanda?

  • Le risposte in linguaggio naturale dell'agente di dati dell'API Analisi conversazionale 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 dei dati, la query sottostante generata (query SQL o Looker) dovrebbe essere deterministica. I dati recuperati dovrebbero essere gli stessi, a condizione che i dati sottostanti non siano cambiati.

Come posso migliorare l'accuratezza delle risposte di un agente di dati dell'API Analisi conversazionale?

Un modo per migliorare l'accuratezza delle risposte degli agenti di dati è fornire all'agente di dati informazioni contestuali solide. Puoi aggiungere 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 di Looker Comportamento dell'agente di guida con il contesto creato.
  • Per le origini dati BigQuery, puoi fornire il contesto creato tramite campi di contesto strutturati, come descrizioni a livello di tabella e colonna, sinonimi, tag ed esempi di query, e tramite istruzioni di sistema. Fornire questo contesto contribuisce anche a migliorare l'accuratezza delle risposte e può consentire agli agenti di citare le origini nelle loro risposte. Per saperne di più, consulta Definire il contesto dell'agente di 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, che sono indicazioni definite dall'utente che possono modellare il comportamento di un agente di dati. Queste indicazioni includono logica specifica per l'attività, formattazione delle risposte o presentazione dei dati.
    • Puoi fornire query verificate (chiamate anche query dorate a seconda dell'origine dati), che sono 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 Comportamento dell'agente di guida con il contesto creato.

Per indicazioni su come porre domande per ottenere risposte più efficaci e accurate, consulta la pagina Porre domande efficaci.

Come faccio a ispezionare e gestire in sicurezza il codice Python generato dall'agente?

Se hai attivato l'analisi avanzata con Python, l'agente di dati potrebbe restituire codice Python. Il codice Python restituito dagli agenti di dati è progettato per essere eseguito all'interno di una sandbox sicura e gestita da Google. L'esecuzione di questo codice in un ambiente locale o in un altro ambiente non verificato ignora 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 sicurezza 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 blocco note 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 linter sul codice per segnalare operazioni potenzialmente non sicure o pattern dannosi noti.

Posso integrare l'API Analisi conversazionale con applicazioni di terze parti?

L'integrazione dell'API Analisi conversazionale 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 dell'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 Analisi conversazionale?

L'API Analisi conversazionale è in disponibilità generale (GA). Per saperne di più sui prezzi, consulta la guida ai prezzi.

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

Quali origini dati sono supportate dall'API Analisi conversazionale?

L'API Analisi conversazionale supporta le seguenti origini dati:

  • BigQuery (incluse tabelle o un grafico)
  • Esplorazioni di Looker
  • Data Studio
  • AlloyDB per PostgreSQL
  • GoogleSQL per Spanner
  • Cloud SQL 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 Analisi conversazionale?

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

Quali quote devo conoscere per i Google Cloud progetti?

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

L'API Analisi conversazionale supporta la residenza dei dati?

Sì, l'API Analisi conversazionale supporta la residenza dei dati. Per controllare dove vengono trattati e archiviati i 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, consulta la sezione Residenza dei dati.

L'API Analisi conversazionale supporta lingue diverse dall'inglese?

L'unica lingua ufficialmente supportata per l'API Analisi conversazionale è l'inglese. Sebbene i modelli Gemini sottostanti supportino molte lingue e alcuni utenti abbiano segnalato aneddoticamente di aver avuto successo con le query in lingue diverse dall'inglese, l'API Analisi conversazionale non supporta ufficialmente lingue diverse dall'inglese.