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 DDL (Data Definition Language) e DML (Data Manipulation Language). Nello specifico, il sistema esegue un test di esecuzione 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.
  • Looker Studio (per file CSV e Fogli Google): Looker 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.

L'API Conversational Analytics è progettata per essere di sola lettura in queste origini dati.

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 indica spesso 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 alcune operazioni, come l'attivazione 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.

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'API geminidataanalytics.googleapis.com. 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 che contenga l'autorizzazione gemini_in_looker per i modelli con cui interagisce.

Per scoprire 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 Looker Studio Pro, l'abbonamento Pro deve trovarsi al di fuori di un perimetro VPC-SC.

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 il valore di data_agent_id, è l'identificatore univoco del data agent. Il nome dell'agente dati, data_agent.name, viene derivato automaticamente da data_agent_id come nome completo (FQN), con la forma projects/<project>/locations/<location>/dataAgents/<data_agent_id>.

Quando crei un agente 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 dell'agente 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".

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 di 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.
  • Quando crei un agente dati, puoi fornire 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 anche fornire "query dorate", ovvero domande di esempio in linguaggio naturale accoppiate alle query SQL o Looker corrette. Per saperne di più sulle istruzioni di sistema, consulta la pagina di documentazione Guida il comportamento dell'agente con il contesto creato.

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 Conversational Analytics 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, ti avviseremo in anticipo di eventuali modifiche dei prezzi.

Quali origini dati supporta l'API Conversational Analytics?

L'API Conversational Analytics supporta le seguenti origini dati:

  • BigQuery
  • Esplorazioni Looker
  • Looker Studio

Puoi anche connetterti a origini come SAP e Salesforce tramite BigQuery e a file CSV e Fogli Google tramite Looker 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 (DRZ) o i perimetri di controllo del servizio (VPC-SC), 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 positivi con query non in inglese, l'API Conversational Analytics non supporta ufficialmente lingue diverse dall'inglese.