API Conversational Analytics: crea agenti dati e chatta con i tuoi dati

Questo prodotto o funzionalità è soggetto ai "Termini delle offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Importante:l'API Data QnA è obsoleta. Se esegui la migrazione dall'API Data QnA, consulta la guida alla migrazione per una panoramica delle principali differenze e dei passaggi di migrazione richiesti.

Gli sviluppatori possono utilizzare l'API Conversational Analytics, a cui si accede tramite geminidataanalytics.googleapis.com, per creare un'interfaccia di chat basata sull'intelligenza artificiale (AI) o un agente di dati che utilizza il linguaggio naturale per rispondere a domande sui dati strutturati in BigQuery, Looker e Looker Studio. Con l'API Conversational Analytics, fornisci all'agente di dati informazioni e dati aziendali (contesto), nonché l'accesso a strumenti come SQL, Python e librerie di visualizzazione. Queste risposte dell'agente vengono presentate all'utente e possono essere registrate dall'applicazione client, creando un'esperienza di chat con i dati fluida e verificabile.

Scopri come e quando Gemini per Google Cloud utilizza i tuoi dati.

Poiché si tratta di una tecnologia in fase iniziale, Gemini per i prodotti Google Cloud può generare output apparentemente plausibili, ma di fatto errati. Ti consigliamo di verificare tutti gli output di Gemini per i prodotti Google Cloud prima di utilizzarli. Per maggiori informazioni, consulta Gemini for Google Cloud e AI responsabile.

Nota: le offerte di anteprima pre-GA (1) sono destinate all'uso solo in ambienti di test e non devono essere utilizzate in un ambiente di produzione o per trattare dati personali o altri dati soggetti a requisiti di conformità legali o normativi e (2) sono soggette ai Termini delle offerte pre-GA dei Termini di servizio specifici e al Addendum al consenso per il programma Gemini for Google Cloud Trusted Tester.

Inizia a utilizzare l'API Conversational Analytics

Per iniziare a utilizzare l'API Conversational Analytics, puoi prima consultare la documentazione relativa all'architettura e ai concetti chiave per capire come gli agenti elaborano le richieste, i flussi di lavoro per i creatori e gli utenti degli agenti, le modalità di conversazione e i ruoli di Identity and Access Management (IAM). Per iniziare a creare agenti di dati, puoi scegliere tra un'esperienza guidata con guide rapide, codelab e blocchi note oppure un approccio autonomo seguendo i passaggi descritti in Configurazione e prerequisiti.

Guide rapide, codelab e blocchi note

Le seguenti risorse forniscono esperienze guidate per aiutarti a iniziare a utilizzare l'API Conversational Analytics:

• App di avvio rapido: utilizza questa applicazione di avvio rapido di Streamlit per l'integrazione con l'API Conversational Analytics in un ambiente di test locale.
• Codelab dell'API Conversational Analytics: segui un tutorial passo passo per scoprire come utilizzare l'SDK Python con i dati BigQuery.
• Notebook Colaboratory dell'API Conversational Analytics:
  • Notebook HTTP Colaboratory: fornisce una guida interattiva passo passo per configurare l'ambiente, creare un agente dati ed effettuare chiamate API utilizzando richieste HTTP.
  • Notebook Colaboratory dell'SDK Python: fornisce una guida interattiva passo passo per configurare l'ambiente, creare un agente dati ed effettuare chiamate API utilizzando l'SDK Python.

Configurazione e prerequisiti

Prima di utilizzare l'API o gli esempi, completa i seguenti passaggi:

• Abilitare l'API Conversational Analytics: descrive i prerequisiti per abilitare l'API Conversational Analytics.
• Controllo dell'accesso all'API Conversational Analytics con IAM: descrive come utilizzare Identity and Access Management per condividere e gestire l'accesso agli agenti di dati.
• Autenticarsi e connettersi a un'origine dati con l'API Conversational Analytics: fornisce istruzioni per l'autenticazione all'API e la configurazione delle connessioni ai dati di BigQuery, Looker e Looker Studio.

Creare e interagire con un agente di dati

Dopo aver completato i passaggi precedenti, utilizza l'API Conversational Analytics per creare un agente di dati e interagire con lui seguendo questi passaggi:

• Crea un agente dati utilizzando HTTP: fornisce un esempio completo di creazione e interazione con un agente dati utilizzando richieste HTTP dirette con Python.
• Crea un data agent utilizzando l'SDK Python: fornisce un esempio completo di creazione e interazione con un data agent utilizzando l'SDK Python.
• Guida il comportamento dell'agente con il contesto creato: scopri come fornire un contesto creato per guidare il comportamento dell'agente e migliorare l'accuratezza delle risposte. Puoi anche visualizzare esempi di contesto creato con origini dati BigQuery e con origini dati Looker.
• Visualizzare la risposta di un agente dell'API Conversational Analytics come visualizzazione: fornisce un esempio di elaborazione delle specifiche del grafico dalle risposte dell'API e di rendering come visualizzazioni utilizzando l'SDK Python e la libreria Vega-Altair.

Best practice

Consulta le seguenti guide per scoprire le best practice per l'utilizzo dell'API Conversational Analytics:

• Gestisci i costi di BigQuery per i tuoi agenti: scopri come monitorare e gestire i costi di BigQuery per gli agenti dell'API Conversational Analytics impostando limiti di spesa a livello di progetto, utente e query.
• Porre domande efficaci: scopri come formulare domande efficaci per i tuoi agenti per ottenere il massimo dall'API Conversational Analytics.
• Risolvi i problemi relativi agli errori dell'API Conversational Analytics: risolvi i problemi relativi agli errori comuni dell'API Conversational Analytics.
• Limitazioni note: fornisce informazioni dettagliate sulle limitazioni note dell'API Conversational Analytics, incluse quelle relative a query, dati, visualizzazioni e domande.

Operazioni API chiave

L'API fornisce i seguenti endpoint principali per la gestione degli agenti di dati e delle conversazioni:

Operazione	Metodo HTTP	Endpoint	Descrizione
Crea un agente	POST	/v1beta/projects/*/locations/*/dataAgents	Crea un nuovo agente dati.
Recuperare un agente	GET	/v1beta/projects/*/locations/*/dataAgents/*	Recupera i dettagli di un agente di dati specifico.
Recupera criterio Identity and Access Management	POST	/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy	Recupera le autorizzazioni di Identity and Access Management assegnate a ciascun utente per un agente dati specifico. Gli utenti con il ruolo Proprietario agente dati possono chiamare questo endpoint per visualizzare il criterio di Identity and Access Management dell'agente dati prima di utilizzare l'endpoint setIAMpolicy per condividere un agente dati con altri utenti.
Imposta il criterio Identity and Access Management	POST	/v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy	Imposta il criterio Identity and Access Management per un agente dati specifico. Gli utenti con un ruolo di proprietario dell'agente dati devono chiamare questo endpoint per condividere un agente dati con altri utenti, il che aggiorna effettivamente le autorizzazioni di Identity and Access Management di questi utenti.
Aggiorna un agente	PATCH	/v1beta/projects/*/locations/*/dataAgents/*	Modifica un agente dati esistente.
Elenca agenti	GET	/v1beta/projects/*/locations/*/dataAgents	Elenca gli agenti dati disponibili in un progetto.
Elenco degli agenti accessibili	GET	/v1beta/projects/*/locations/*/dataAgents:listaccessible	Elenca gli agenti dati accessibili in un progetto. Un agente dati è considerato accessibile se l'utente che richiama questa API dispone dell'autorizzazione get per l'agente. Puoi utilizzare il campo creator_filter per gestire gli agenti restituiti da questo metodo: NONE (impostazione predefinita): restituisce tutti gli agenti di dati accessibili all'utente, indipendentemente da chi li ha creati. CREATOR_ONLY: restituisce solo gli agenti di dati accessibili all'utente e creati da quest'ultimo. NOT_CREATOR_ONLY: restituisce solo gli agenti dati accessibili all'utente e creati da altri.
Eliminare un agente	DELETE	/v1beta/projects/*/locations/*/dataAgents/*	Rimuove un agente di dati.
Creare una conversazione	POST	/v1beta/projects/*/locations/*/conversations	Avvia una nuova conversazione persistente.
Chattare utilizzando un riferimento alla conversazione	POST	/v1beta/projects/*/locations/*:chat	Continua una conversazione con stato inviando un messaggio di chat che fa riferimento a una conversazione esistente e al relativo contesto dell'agente. Per le conversazioni multi-turno, Google Cloud memorizza e gestisce la cronologia della conversazione.
Chattare utilizzando un riferimento dell'agente di dati	POST	/v1beta/projects/*/locations/*:chat	Invia un messaggio di chat stateless che fa riferimento a un agente di dati salvato per il contesto. Per le conversazioni multi-turno, la tua applicazione deve gestire e fornire la cronologia della conversazione a ogni richiesta.
Chattare utilizzando il contesto in linea	POST	/v1beta/projects/*/locations/*:chat	Invia un messaggio di chat stateless fornendo tutto il contesto direttamente nella richiesta, senza utilizzare un agente dati salvato. Per le conversazioni multi-turno, la tua applicazione deve gestire e fornire la cronologia della conversazione a ogni richiesta.
Recuperare una conversazione	GET	/v1beta/projects/*/locations/*/conversations/*	Recupera i dettagli di una conversazione specifica.
Elenca conversazioni	GET	/v1beta/projects/*/locations/*/conversations	Elenca le conversazioni in un progetto specifico.
Elencare i messaggi in una conversazione	GET	/v1beta/projects/*/locations/*/conversations/*/messages	Elenca i messaggi all'interno di una conversazione specifica.

Invia feedback

Utilizza i seguenti link per segnalare un bug o richiedere una funzionalità.

• Inviare una segnalazione di bug
• Invia una richiesta di funzionalità

Risorse aggiuntive

Le seguenti risorse forniscono documentazione di riferimento, esempi e strumenti per aiutarti a creare applicazioni con l'API Conversational Analytics:

• Riferimento API REST Conversational Analytics: fornisce descrizioni dettagliate di metodi, endpoint e definizioni di tipo per le strutture di richiesta e risposta.
• Demo e strumenti di Conversational Analytics: esamina demo e strumenti che mostrano le funzionalità dell'API e forniscono pattern di integrazione pratici.
• Agent Development Kit (ADK): scopri come utilizzare la funzione ask_data_insights in ADK per rispondere a domande sui tuoi dati in linguaggio naturale.