Ottenere approfondimenti con l'agente Data Insights

L'agente Data Insights è un agente Made by Google. Fornisce approfondimenti sui dati dai tuoi dati BigQuery. Con l'agente Data Insights, non hai bisogno di conoscenze pregresse di SQL. Ciò ti consente di prendere decisioni aziendali ben informate e basate sui dati e libera gli analisti di dati per concentrarsi su attività più complesse.

Questa pagina descrive in che modo un amministratore di progetto Google Cloud può autorizzare, creare ed eseguire il deployment dell'agente Data Insights utilizzando la Google Cloud console e l'API REST. Questa pagina mostra anche come un utente finale può utilizzare l'agente.

Panoramica

L'agente Data Insights è progettato per:

  • Comprendere l'intenzione dell'utente: analizza il contesto delle origini dati connesse e la query in linguaggio naturale dell'utente per comprendere il suo obiettivo
  • Genera SQL: in base a questa comprensione, converte la domanda dell'utente in una query SQL sintatticamente e semanticamente corretta.
  • Recupera i dati: quindi esegue l'SQL generato per recuperare i dati pertinenti direttamente dall'origine dati connessa, un set di dati BigQuery.
  • Fornisce approfondimenti: presenta i dati recuperati come visualizzazioni, ad esempio grafici e tabelle, o come riepiloghi basati su testo per rispondere alla query dell'utente.

Esempi di query che puoi porre all'agente Data Insights

Ecco alcuni esempi di query che puoi porre all'agente Data Insights:

  • Aggregazione e visualizzazione dei dati:
    • "Come si sono confrontate le vendite del secondo trimestre nella regione LATAM di quest'anno con quelle del secondo trimestre dell'anno scorso?"
    • "Traccia un grafico a barre che mostri il confronto per ciascuno dei primi 5 paesi della regione".
  • Analisi delle tendenze:
    • "Come è variato il volume delle chiamate in uscita negli ultimi 6 mesi, suddiviso per località?"
    • "Analizza i modelli di prenotazione per gli hotel di Lisbona con una valutazione superiore a 3 stelle"
  • Data mining:
    • "Quali fattori sono correlati al valore totale delle vendite quando un cliente acquista qualcosa? Mostrami una mappa termica che illustri la relazione."
  • Analisi e report:
    • "Riassumi la tabella delle opportunità e degli account e crea un breve report che metta in evidenza le tendenze chiave".

Prima di iniziare

Per iniziare a utilizzare l'agente Data Insights in Gemini Enterprise, segui questi passaggi:

Concedere l'accesso ai dati BigQuery

Per consentire all'agente Data Insights di visualizzare ed eseguire query sui dati BigQuery, concedi i ruoli Identity and Access Management (IAM) agli utenti dell'agente:

Flusso di lavoro

Il flusso di lavoro generale per configurare e utilizzare l'agente Data Insights è il seguente:

Ottenere i dettagli dell'autorizzazione

Segui questi passaggi per configurare l'autorizzazione. I dettagli che ottieni sono necessari per autorizzare l'agente Data Insights a connettersi ai dati BigQuery.

  1. Nella console Google Cloud , vai alla pagina Credenziali in API e servizi.

    Vai a credenziali

  2. Seleziona il progetto Google Cloud che contiene il set di dati BigQuery su cui vuoi che l'agente esegua query.

  3. Fai clic su Crea credenziali e seleziona ID client OAuth.

  4. In Tipo di applicazione, seleziona Applicazione web.

  5. Nella sezione URI di reindirizzamento autorizzati, aggiungi i seguenti URI:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. Fai clic su Crea.

  7. Nel riquadro OAuth client created (Client OAuth creato), fai clic su Download JSON (Scarica JSON). Il file JSON scaricato include i seguenti dettagli per il progettoGoogle Cloud selezionato. Questi dettagli sono necessari per creare una risorsa di autorizzazione:

    • ID client: CLIENT_ID
    • URI autorizzazione: 
      https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
    • URI del token: TOKEN_URI
    • Client secret: CLIENT_SECRET

Configura l'agente utilizzando la console Google Cloud

Questa sezione mostra come autorizzare, creare ed eseguire il deployment di un'istanza dell'agente Data Insights utilizzando la console Google Cloud . Puoi anche aggiungere autorizzazioni utente che determinano chi può accedere all'agente creato.

Autorizza e crea un'istanza dell'agente

Autorizza e crea un'istanza dell'agente Data Insights seguendo questi passaggi:

  1. Nella console Google Cloud , vai a Gemini Enterprise.

    Vai a Gemini Enterprise

  2. Seleziona un'app in cui vuoi creare l'agente.

  3. Nel menu, fai clic su Agenti.

    La pagina Agenti mostra gli agenti esistenti.

  4. Fai clic su Aggiungi agente.

  5. Nel riquadro Crea agente, fai clic su Crea nella scheda Agente dati.

  6. In Autorizzazioni, fai clic su Aggiungi autorizzazione e inserisci i dettagli dell'autorizzazione. Per ulteriori informazioni, consulta Ottenere l'autorizzazione.

  7. Fai clic su Fine.

  8. Fai clic su Avanti.

  9. Configura l'agente nel seguente modo:

    1. Inserisci il nome e la descrizione dell'agente.
    2. In Set di dati BigQuery, fai clic su Sfoglia e svolgi una delle seguenti operazioni:
      • Seleziona un set di dati disponibile e fai clic su Seleziona.
      • Inserisci il percorso del set di dati BigQuery richiesto, fai clic su Cerca, selezionalo e poi seleziona Seleziona.

    3. (Facoltativo) Fai clic su Mostra altro per le opzioni avanzate.

    4. Seleziona le opzioni di accesso alla tabella corrette. Se vuoi imporre una lista consentita o una lista bloccata, specifica i percorsi delle tabelle con limitazioni.

    5. (Facoltativo) Definisci la configurazione della query in linguaggio naturale per fornire personalizzazioni specifiche per una traduzione in linguaggio naturale in codice SQL o Python. Puoi anche fornire un esempio di SQL utilizzando una query in linguaggio naturale, il relativo output SQL previsto e la relativa risposta prevista. Ciò migliora la qualità degli output dell'agente.

      • Descrizione dello schema: una stringa in linguaggio naturale che descrive lo schema del set di dati BigQuery.
      • Da query in linguaggio naturale a prompt SQL: una query in linguaggio naturale trasformata in un'istruzione SQL.
      • Da query in linguaggio naturale a prompt Python: una query in linguaggio naturale trasformata in un'istruzione Python.

    6. (Facoltativo) Aggiungi esempi di query in linguaggio naturale trasformate in query SQL:

      • Query: un esempio di query naturale che deve essere convertita in una query SQL. Ad esempio, "Quali sono i nomi e gli indirizzi email dei clienti con sede in California"
      • SQL previsto: una stringa che illustra un esempio di query SQL corrispondente alla query in linguaggio naturale. Ad esempio, supponiamo di avere una tabella BigQuery denominata customers. Quindi, la query SQL prevista può essere SELECT customer_name, email FROM customers WHERE state = 'California'.
      • Risposta prevista: una stringa che fornisce la risposta prevista per la query eseguendo la query SQL prevista. Ad esempio:
      Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

  10. Fai clic su Crea.

    L'istanza dell'agente Data Insights viene visualizzata nell'elenco Agenti.
    Per iniziare a utilizzare l'agente, attendi che la colonna Stato agente mostri Attivato per la tua istanza.

Configurare l'agente utilizzando l'API REST

Questa sezione descrive come autorizzare, creare e implementare un'istanza dell'agente Data Insights utilizzando l'API REST.

Autorizza l'agente

In qualità di amministratore, crea una risorsa di autorizzazione in Gemini Enterprise. In questo modo, l'agente Data Insights può accedere ai dati BigQuery.

  1. Crea la risorsa di autorizzazione.

    REST

    L'esempio seguente mostra come creare una risorsa di autorizzazione utilizzando il metodo authorizations.create.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTHORIZATION_ID" \
 -d '{
   "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTHORIZATION_ID",
   "serverSideOauth2": {
     "clientId": "CLIENT_ID",
     "clientSecret": "CLIENT_SECRET",
     "authorizationUri": "AUTHORIZATION_URI",
     "tokenUri": "TOKEN_URI"
}
}'

    Sostituisci quanto segue:

    • PROJECT_NUMBER: il numero del tuo Google Cloud progetto.
    • LOCATION: la posizione del tuo progetto Google Cloud .
    • AUTHORIZATION_ID: un ID che devi fornire per identificare la risorsa di autorizzazione.
    • CLIENT_ID: l'ID client ottenuto nel passaggio precedente.
    • CLIENT_SECRET: il client secret ottenuto nel passaggio precedente.
    • AUTHORIZATION_URI: l'URI di autorizzazione ottenuto nel passaggio precedente.
    • TOKEN_URI: l'URI del token ottenuto nel passaggio precedente.

Crea un'istanza dell'agente

In qualità di Google Cloud amministratore del progetto, puoi creare un'istanza dell'agente Data Insights. Per questa operazione sono necessari l'ID progetto e l'ID set di dati dei dati BigQuery su cui vuoi eseguire query utilizzando l'agente.

REST

Il seguente esempio mostra come creare un'istanza dell'agente Data Insights utilizzando il metodo agents.create. Per scoprire di più sui campi avanzati che puoi aggiungere a questo esempio, vedi Aggiungere configurazioni avanzate per l'agente.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
  -d '{
    "displayName": "AGENT_DISPLAY_NAME",
    "description": "AGENT_DESCRIPTION",
    "icon": {
       "uri": "AGENT_ICON_URI"
     },
    "managed_agent_definition": {
      "tool_settings": {
        "tool_description": "AGENT_DESCRIPTION"
      },
      "data_science_agent_config": {
        "bq_project_id": "BIGQUERY_PROJECT_ID",
        "bq_dataset_id": "BIGQUERY_DATASET_ID"
      }
    },
    "authorization_config": {
      "tool_authorizations" : [
        "AUTHORIZATION_RESOURCE_NAME"
      ]
    }
  }'

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero del tuo Google Cloud progetto.
  • LOCATION: la posizione dell'app Gemini Enterprise.
  • APP_ID: l'ID dell'app.
  • AGENT_DISPLAY_NAME: il nome dell'istanza dell'agente Data Insights.
  • AGENT_ICON_URI: un campo facoltativo per fornire un URI per l'icona dell'agente.
  • AGENT_DESCRIPTION: una descrizione dell'istanza dell'agente Data Insights che indica lo scopo dell'agente o i dettagli dell'origine dei dati BigQuery.
  • BIGQUERY_PROJECT_ID: l'ID progetto del progettoGoogle Cloud che contiene il set di dati BigQuery.
  • BIGQUERY_DATASET_ID: l'ID del set di dati BigQuery che contiene i dati su cui eseguire query.
  • AUTHORIZATION_RESOURCE_NAME: il nome della risorsa di autorizzazione ottenuto nella sezione precedente.

Aggiungere configurazioni avanzate per l'agente

Puoi definire facoltativamente il campo nlQueryConfig per fornire personalizzazioni specifiche per la traduzione dal linguaggio naturale al codice SQL o Python. Puoi anche fornire un esempio di SQL utilizzando una query in linguaggio naturale, il relativo output SQL previsto e la relativa risposta prevista. In questo modo, la qualità degli output dell'agente migliora. Il seguente snippet di codice mostra come configurare questi campi avanzati:

"dataScienceAgentConfig": {
  "nlQueryConfig": {
    "nl2sqlPrompt": "NL_TO_SQL_INSTRUCTIONS",
    "nl2pyPrompt": "NL_TO_PYTHON_INSTRUCTIONS",
    "nl2sqlExample": {
      "query": "EXAMPLE_NL_QUERY",
      "expectedSql": "EXPECTED_SQL_QUERY",
      "expectedResponse": "EXPECTED_SQL_RESPONSE"
    },
    "schemaDescription": "NL_DESCRIPTION_OF_BQ_DATASET"
  }
}

Sostituisci quanto segue:

  • NL_TO_SQL_INSTRUCTIONS: una query in linguaggio naturale trasformata in un'istruzione SQL.
  • NL_TO_PYTHON_INSTRUCTIONS: una query in linguaggio naturale trasformata in un'istruzione Python.
  • EXAMPLE_NL_QUERY: un esempio di query in linguaggio naturale che deve essere convertita in una query SQL. Ad esempio, "Quali sono i nomi e gli indirizzi email dei clienti che risiedono in California?"
  • EXPECTED_SQL_QUERY: una stringa che illustra una query SQL di esempio corrispondente alla query in linguaggio naturale. Ad esempio, supponiamo di avere una tabella BigQuery denominata customers. Quindi, la query SQL prevista può essere "SELECT customer_name, email FROM customers WHERE state = 'California'".

  • EXPECTED_SQL_RESPONSE: una stringa che fornisce la risposta prevista per la query e la query SQL prevista. Ad esempio:

    Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

  • NL_DESCRIPTION_OF_BQ_DATASET: una stringa in linguaggio naturale che descrive lo schema del set di dati BigQuery.

Esegui il deployment dell'istanza

Dopo aver creato l'istanza dell'agente Data Insights, in qualità di amministratore, puoi eseguirne il deployment in modo che gli utenti finali possano utilizzarla.

REST

  1. Esegui il deployment dell'agente. Il seguente esempio mostra come eseguire il deployment dell'agente creato utilizzando il metodo agents.deploy. Il deployment dell'agente è un'operazione a lunga esecuzione (LRO).

    curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME:deploy" \
 -d '{
   "name":"AGENT_RESOURCE_NAME"
 }'

    Sostituisci quanto segue:

    • PROJECT_NUMBER: il numero del tuo Google Cloud progetto.
    • AGENT_RESOURCE_NAME: il nome della risorsa agente ottenuto nella sezione precedente durante la creazione dell'agente.

  2. Recupera lo stato dell'operazione di deployment. Il seguente esempio mostra come ottenere lo stato dell'operazione di deployment operations.get metodo.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/DEPLOY_OPERATION_NAME"

    Sostituisci DEPLOY_OPERATION_NAME con il nome dell'operazione di lunga durata ottenuto nel passaggio precedente durante il deployment dell'agente.

    Nella risposta, se il valore del campo done è true, il deployment è completato. Se il valore del campo done è false, il deployment è in corso.

Aggiungere o modificare utenti e relative autorizzazioni

Aggiungi o modifica le entità nell'istanza dell'agente Data Insights e assegna loro ruoli IAM (Identity and Access Management) specifici seguendo questi passaggi:

Console

  1. Nella console Google Cloud , vai a Gemini Enterprise.

    Vai a Gemini Enterprise

  2. Seleziona un'app che contenga l'istanza dell'agente Data Insights.

  3. Nel menu, fai clic su Agenti.

    La pagina Agenti mostra gli agenti esistenti.

  4. Fai clic sull'agente per il quale vuoi aggiungere o modificare gli utenti.

    Per impostazione predefinita, un agente appena creato non ha utenti.

  5. Nella tabella Utenti con autorizzazione, fai clic su Aggiungi utente.

  6. Seleziona un Tipo di membro dall'elenco disponibile.

  7. Inserisci l'identità del membro a seconda del tipo e assegna uno o più ruoli.

    • Per un utente, un gruppo o un account di servizio, la stringa membro è un'email.
    • Per un dominio, la stringa del membro è un nome di dominio valido.
    • Per un'entità, la stringa membro è un'entità valida. Ad esempio: principal://iam.googleapis.com/locations/global/workforcePools/pool-1/subject/subject-1.
    • Per un insieme di entità, la stringa membro è un insieme di entità valido. Ad esempio: principalSet://iam.googleapis.com/locations/global/workforcePools/pool-1/group/group-1.
    • Per i domini e i set di entità, a tutte le identità e i gruppi di utenti all'interno di questi domini e set di entità vengono assegnati gli stessi ruoli. Per un accesso sicuro all'agente, seleziona singoli gruppi e domini controllati o insiemi di entità e assegna loro ruoli con privilegi minimi.

  8. Fai clic su Salva.

    Il criterio IAM viene aggiornato e l'utente viene aggiunto all'elenco degli utenti con autorizzazione.

  9. Per modificare le autorizzazioni assegnate, fai clic su Azioni, seleziona Modifica ed esegui una delle seguenti operazioni:

    • Modifica i ruoli assegnati.
    • Aggiungi un altro ruolo.
    • Fai clic su Elimina per rimuovere un ruolo. Devi assegnare almeno un ruolo a un utente.

Modificare lo stato di funzionamento dell'istanza

Dopo aver creato l'istanza dell'agente Data Insights, l'agente viene abilitato per impostazione predefinita. Puoi modificare il suo stato di funzionamento in Disattivato, Sospeso, Attivato o Eliminato seguendo questi passaggi:

Console

  1. Nella console Google Cloud , vai a Gemini Enterprise.

    Vai a Gemini Enterprise

  2. Seleziona un'app che contenga l'istanza dell'agente Data Insights.

  3. Nel menu, fai clic su Agenti.

    La pagina Agenti mostra gli agenti esistenti.

  4. Fai clic su Azioni per i tuoi agenti e seleziona una delle seguenti opzioni:

    • Sospeso: per rendere l'agente temporaneamente non disponibile per l'utilizzo. Tuttavia, gli utenti con qualsiasi livello di autorizzazione per l'agente di accesso possono comunque visualizzarlo.
    • Disabilitato: per rendere l'agente non disponibile per tutti gli utenti, ad eccezione di quello che lo ha creato.
    • Attivato: per rendere l'agente disponibile a tutti gli utenti con qualsiasi livello di autorizzazione per l'agente di accesso.
    • Elimina: per eliminare l'istanza dell'agente.

Utilizzare l'agente

Per ottenere approfondimenti sui dati utilizzando l'agente:

App

  1. Nel menu di navigazione dell'app, fai clic su Agenti.

  2. Fai clic su Visualizza tutti gli agenti.

  3. Seleziona l'istanza dell'agente Data Insights.

  4. Se l'agente richiede un'autorizzazione aggiuntiva, fai clic su Autorizza e fornisci i dettagli dell'autorizzazione.

  5. Fai clic su Aggiungi file per includere i file come origini dati aggiuntive con cui l'agente può lavorare.

  6. Fai clic su Origini per selezionare le origini che l'agente deve includere per fornire le informazioni più pertinenti sui dati.

  7. Inserisci le domande o i prompt e premi Invio o fai clic su Invia.