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 dati.

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

  • BigQuery: l'API blocca le istruzioni Data Definition Language (DDL) e Data Manipulation Language (DML). In particolare, il sistema esegue un test di esecuzione dell'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 Chatta in tutta sicurezza: analisi della sicurezza 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 Conversational Analytics:

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

    • Causa probabile: questo messaggio spesso indica problemi con i ruoli IAM Google Cloud . 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 ruolo Utente tenta di chattare con un agente 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 improvviso rifiuto 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:

    • Per interagire con l'API geminidataanalytics.googleapis.com, devi disporre di ruoli IAM sufficienti nel tuo progetto Google Cloud . 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 Editor progetto.

  2. Ruoli e autorizzazioni di Looker:

    • Autorizzazioni a livello di modello: per utilizzare Conversational Analytics e l'API Conversational Analytics, 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 dell'agente dati, definito come valore di data_agent_id, è l'identificatore univoco dell'agente dati. Il nome dell'agente 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 le operazioni get, update o delete, l'intero data_agent.name viene considerato l'identificatore univoco dell'agente di trattamento dei dati.

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 nome di dominio completo, 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 faccio a utilizzare la maschera di aggiornamento?

Nel flusso Aggiorna agente di trasferimento dei 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, 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 il criterio 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 dati dell'API Conversational Analytics?

  • All'interno di una singola sessione: l'API Conversational Analytics supporta le conversazioni multi-turn, 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 (query SQL o Looker) deve essere deterministica. I dati recuperati devono essere gli stessi, supponendo che i dati sottostanti non siano cambiati.

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

Un modo per migliorare l'accuratezza delle risposte dell'agente di dati è fornire all'agente di 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.
  • 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 su come interpretarli.

  • 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 accoppiate 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 e 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, ad esempio richieste di rete impreviste (ad es. socket, requests o urllib), comandi a livello di sistema (ad es. os.system o subprocess) o variabili e stringhe letterali fortemente offuscate.
  • Non eseguire mai codice non verificato direttamente su una macchina 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 fase di anteprima e Google non addebita costi per i prodotti in anteprima. In futuro, forniremo un preavviso in caso di modifiche ai prezzi.

Quali origini dati supporta l'API Conversational Analytics?

L'API Conversational Analytics supporta le seguenti origini dati:

  • BigQuery
  • Esplorazioni 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 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 sono presenti limitazioni alla Google Cloud selezione del progetto o della località. Puoi creare agenti dati per eseguire query sulle origini dati supportate che appartengono a qualsiasi progetto o regione.

L'API Conversational Analytics supporta la regionalizzazione dei dati?

Poiché l'API Conversational Analytics non supporta ancora la residenza dei dati, non puoi ancora ospitare agenti in regioni geografiche specifiche. La regionalizzazione dei dati non è supportata.

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.