Creare agenti di dati e chattare con i tuoi dati

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

Gli sviluppatori possono utilizzare l'API Analisi conversazionale, a cui si accede tramite geminidataanalytics.googleapis.com o endpoint regionali, per creare un'interfaccia di chat basata sull'intelligenza artificiale (AI) o un agente di dati. L'API utilizza il linguaggio naturale per rispondere alle domande sui dati strutturati in BigQuery, Looker e Data Studio e supporta anche l'esecuzione di query sui dati di AlloyDB, GoogleSQL per Spanner, Cloud SQL e Cloud SQL per PostgreSQL tramite il metodo QueryData.

Con l'API Analisi conversazionale, fornisci all'agente di dati informazioni sull'attività e dati (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 sui 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 Google Cloud i prodotti può generare risultati apparentemente plausibili, ma di fatto errati. Ti consigliamo di verificare tutti gli output di Gemini per i prodotti prima di utilizzarli. Google Cloud Per saperne di più, consulta Gemini per Google Cloud e l'AI responsabile.

Inizia a utilizzare l'API Analisi conversazionale

Per iniziare a utilizzare l'API Analisi conversazionale, consulta la seguente documentazione per comprendere gli approcci di integrazione disponibili e i concetti di base:

• Architettura e concetti chiave: scopri in che modo gli agenti di dati elaborano le richieste, i workflow per i creatori e gli utenti degli agenti, le modalità di conversazione e i ruoli Identity and Access Management (IAM) richiesti.
• Pattern di integrazione per gli agenti di dati: confronta gli approcci architetturali per determinare il metodo di connessione migliore per la tua applicazione.
• Gestione dello stato: scopri le modalità di conversazione con stato e senza stato, in che modo l'API gestisce la cronologia delle conversazioni e gli ambiti dello stato della sessione ADK.
• Sicurezza, privacy, rischio e conformità: scopri le opzioni di sicurezza e conformità per l'API Analisi conversazionale.
• Località dell'API Analisi conversazionale: fornisce una panoramica degli endpoint API regionali o multiregionali che ti consentono di controllare la posizione geografica delle risorse, della configurazione e dei dati del tuo agente.

Per iniziare a creare agenti di dati, completa i passaggi descritti nella documentazione relativa alla configurazione e ai prerequisiti. Per procedure guidate, applicazioni di esempio, SDK e altri strumenti di sviluppo, consulta Tutorial, demo e strumenti dell'API Analisi conversazionale.

Configurazione e prerequisiti

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

• Abilita l'API Analisi conversazionale: descrive i prerequisiti per abilitare l'API Analisi conversazionale.
• Controllo dell'accesso con IAM: descrive come utilizzare Identity and Access Management per condividere e gestire l'accesso agli agenti di dati.
• Autenticati e connettiti a un'origine dati: fornisce istruzioni per l'autenticazione all'API e la configurazione delle connessioni ai dati di BigQuery, Lakehouse, Looker, Data Studio e Cloud Databases (AlloyDB, GoogleSQL per Spanner, Cloud SQL e Cloud SQL per PostgreSQL).
• Chiavi di crittografia gestite dal cliente (CMEK): descrive come utilizzare le tue chiavi di crittografia in Cloud Key Management Service per proteggere gli agenti di dati e le conversazioni che utilizzano le origini dati di Looker.
• Vincoli dei criteri dell'organizzazione: descrive come utilizzare i vincoli dei criteri dell'organizzazione predefiniti per controllare le risorse a livello di organizzazione, cartella o progetto.

Crea un agente di dati e interagisci con lui

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

• Crea un agente di dati utilizzando HTTP: fornisce un esempio completo di creazione e interazione con un agente di dati utilizzando le richieste HTTP dirette con Python.
• Crea un agente di dati utilizzando l'SDK Python: fornisce un esempio completo di creazione e interazione con un agente di dati 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 le origini dati BigQuery e con le origini dati Looker.
• Esegui il rendering di una risposta dell'agente dell'API Analisi conversazionale come visualizzazione: fornisce un esempio di elaborazione delle specifiche dei grafici dalle risposte dell'API e di rendering come visualizzazioni utilizzando l'SDK Python e la libreria Vega-Altair.
  Nota: la creazione di agenti di dati utilizzando HTTP o l'SDK Python e il rendering delle visualizzazioni non sono supportati per le origini dati del database (AlloyDB, GoogleSQL per Spanner, Cloud SQL e Cloud SQL per PostgreSQL).

Best practice

Consulta le seguenti guide per scoprire le best practice per l'utilizzo dell'API Analisi conversazionale:

• Gestisci i costi di BigQuery per i tuoi agenti: scopri come monitorare e gestire i costi di BigQuery per gli agenti dell'API Analisi conversazionale impostando limiti di spesa a livello di progetto, utente e query.
• Poni domande efficaci: scopri come creare domande efficaci per i tuoi agenti per sfruttare al meglio l'API Analisi conversazionale.
• Conservazione ed eliminazione dei dati: scopri la conservazione e l'eliminazione dei dati per gli agenti di dati e le conversazioni dell'API Analisi conversazionale.
• Quote e limiti: scopri le quote e i limiti per l'API Analisi conversazionale.
• Risolvi i problemi relativi agli errori dell'API Analisi conversazionale: risolvi i problemi relativi agli errori comuni dell'API Analisi conversazionale.
• Limitazioni note: fornisce informazioni dettagliate sulle limitazioni note dell'API Analisi conversazionale, incluse le limitazioni di query, dati, visualizzazioni e domande.
• Esegui il rendering delle risposte dell'agente per le origini dati di Looker: scopri le best practice per il rendering delle risposte dell'API Analisi conversazionale in un'interfaccia utente quando utilizzi le origini dati di Looker.

Riferimento API e librerie client

• Riferimento REST di Gemini Data Analytics: fornisce descrizioni dettagliate delle versioni, dei metodi, degli endpoint e delle definizioni dei tipi di API.
• SDK e strumenti di sviluppo: elenca le librerie client specifiche per lingua.

Operazioni API chiave

L'API fornisce i seguenti endpoint principali per la gestione degli agenti di dati e delle conversazioni. Quando crei questi percorsi (o i nomi delle risorse SDK corrispondenti), sostituisci i caratteri jolly (*) con l'ID progetto, l'identificatore della località (ad esempio global o us) e l'ID risorsa (ad esempio l'ID agente o l'ID conversazione), se applicabile.

Importante: la località nel percorso della richiesta deve corrispondere alla località dell'endpoint che stai chiamando. Ad esempio, se chiami l'endpoint geminidataanalytics.us.rep.googleapis.com, specifica us nel percorso della richiesta (ad esempio /locations/us). Per informazioni dettagliate sulla residenza dei dati e sulla configurazione degli endpoint, consulta Residenza dei dati.

Operazione	Metodo HTTP	Endpoint	Descrizione
Crea un agente	POST	/v1/projects/*/locations/*/dataAgents	Crea un nuovo agente di dati.
Crea un agente in modo sincrono	POST	/v1/projects/*/locations/*/dataAgents:createSync	Crea un nuovo agente di dati in modo sincrono.
Recupera un agente	GET	/v1/projects/*/locations/*/dataAgents/*	Recupera i dettagli di un agente di dati specifico.
Recupera i criteri Identity and Access Management	POST	/v1/projects/*/locations/*/dataAgents/*:getIamPolicy	Recupera le autorizzazioni Identity and Access Management assegnate a ogni utente per un agente di dati specifico. Gli utenti con il ruolo di proprietario dell'agente di dati possono chiamare questo endpoint per visualizzare i criteri Identity and Access Management dell'agente di dati prima di utilizzare l'endpoint setIAMpolicy per condividere un agente di dati con altri utenti.
Imposta i criteri Identity and Access Management	POST	/v1/projects/*/locations/*/dataAgents/*:setIamPolicy	Imposta i criteri Identity and Access Management per un agente di dati specifico. Gli utenti con il ruolo di proprietario dell'agente di dati devono chiamare questo endpoint per condividere un agente di dati con altri utenti, aggiornando di fatto le autorizzazioni Identity and Access Management di questi utenti.
Aggiorna un agente	PATCH	/v1/projects/*/locations/*/dataAgents/*	Modifica un agente di dati esistente.
Aggiorna un agente in modo sincrono	PATCH	/v1/projects/*/locations/*/dataAgents/*:updateSync	Modifica un agente di dati esistente in modo sincrono.
Elenca agenti	GET	/v1/projects/*/locations/*/dataAgents	Elenca gli agenti di dati disponibili in un progetto.
Elenca gli agenti accessibili	GET	/v1/projects/*/locations/*/dataAgents:listaccessible	Elenca gli agenti di dati accessibili in un progetto. Un agente di dati è considerato accessibile se l'utente che richiama questa API ha l'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 quell'utente. NOT_CREATOR_ONLY: restituisce solo gli agenti di dati accessibili all'utente e creati da altri.
Elimina un agente	DELETE	/v1/projects/*/locations/*/dataAgents/*	Rimuove un agente di dati.
Elimina un agente in modo sincrono	DELETE	/v1/projects/*/locations/*/dataAgents/*:deleteSync	Rimuove un agente di dati in modo sincrono.
Crea una conversazione	POST	/v1/projects/*/locations/*/conversations	Avvia una nuova conversazione persistente.
Chatta utilizzando un riferimento alla conversazione	POST	/v1/projects/*/locations/*:chat	Continua una conversazione con stato inviando un messaggio chat che fa riferimento a una conversazione esistente e al contesto dell'agente associato. Per le conversazioni multi-turno, Google Cloud memorizza e gestisce la cronologia delle conversazioni.
Chatta utilizzando un riferimento all'agente di dati	POST	/v1/projects/*/locations/*:chat	Invia un messaggio chat senza stato che fa riferimento a un agente di dati salvato per il contesto. Per le conversazioni multi-turno, l'applicazione deve gestire e fornire la cronologia delle conversazioni con ogni richiesta.
Chatta utilizzando il contesto in linea	POST	/v1/projects/*/locations/*:chat	Invia un messaggio di chat senza stato fornendo tutto il contesto direttamente nella richiesta, senza utilizzare un agente di dati salvato. Per le conversazioni multi-turno, l'applicazione deve gestire e fornire la cronologia delle conversazioni con ogni richiesta.
Recupera una conversazione	GET	/v1/projects/*/locations/*/conversations/*	Recupera i dettagli di una conversazione specifica.
Elenca conversazioni	GET	/v1/projects/*/locations/*/conversations	Elenca le conversazioni in un progetto specifico.
Elenca i messaggi in una conversazione	GET	/v1/projects/*/locations/*/conversations/*/messages	Elenca i messaggi all'interno di una conversazione specifica.
Elimina una conversazione	DELETE	/v1/projects/*/locations/*/conversations/*	Elimina una conversazione specifica. Per chiamare questo endpoint è necessario il ruolo Identity and Access Management di amministratore dell'argomento o almeno l'autorizzazione Identity and Access Management cloudaicompanion.topics.delete.
Esegui query sui dati	POST	/v1beta/projects/*/locations/*/conversations:queryData	Esegue query sui dati dei database AlloyDB, GoogleSQL per Spanner, Cloud SQL e Cloud SQL per PostgreSQL utilizzando il linguaggio naturale.

Assistenza e feedback

Per ricevere assistenza o segnalare un problema, contatta l'assistenza clienti. Segui le indicazioni riportate in Crea e gestisci le richieste di assistenza per aprire una richiesta di assistenza. Segui queste indicazioni quando crei la richiesta:

• Per l'assistenza per l'API Analisi conversazionale con BigQuery, nell'elenco Seleziona un prodotto , seleziona BigQuery e nel campo Funzionalità , seleziona AI e machine learning::API Analisi conversazionale in BigQuery.
• Per l'assistenza per l'API Analisi conversazionale con Looker, nell'elenco Seleziona un prodotto , seleziona Looker (originale) e nel campo Funzionalità , seleziona Gemini in Looker::API Analisi conversazionale.

Nota: l'assistenza per l'API Analisi conversazionale copre i problemi tecnici relativi all'utilizzo del servizio API. Il debug del codice generale e personalizzato non è incluso nell'ambito. I clienti sono responsabili del debug del proprio codice personalizzato.

Se hai feedback o domande generali sull'API Analisi conversazionale, invia un'email all'indirizzo [e-mail]. Non garantiamo una risposta alle comunicazioni via email, ma leggiamo le email e facciamo riferimento a questo feedback durante la pianificazione della roadmap.

Puoi anche presentare una richiesta di funzionalità per le nuove funzionalità dell'API Analisi conversazionale.