Obtenha estatísticas com o agente de estatísticas de dados

O agente Data Insights é um agente criado pela Google. Oferece-lhe estatísticas de dados dos seus dados do BigQuery. Com o agente Data Insights, não precisa de ter conhecimentos prévios de SQL. Isto permite-lhe tomar decisões empresariais bem informadas e orientadas por dados, e libertar os analistas de dados para se focarem em tarefas mais complexas.

Esta página descreve como um administrador do projeto pode autorizar, criar e implementar o agente Data Insights através da Google Cloud consola e da API REST. Google Cloud Esta página também mostra como um utilizador final pode usar o agente.

Vista geral

O agente Data Insights foi concebido para fazer o seguinte:

  • Compreender a intenção do utilizador: analisa o contexto das origens de dados ligadas e a consulta em linguagem natural do utilizador para compreender o objetivo do utilizador
  • Gerar SQL: com base nesta compreensão, converte a pergunta do utilizador numa consulta SQL sintática e semanticamente correta.
  • Obter dados: em seguida, executa o SQL gerado para obter os dados relevantes diretamente da origem de dados associada, um conjunto de dados do BigQuery.
  • Fornecer estatísticas: apresenta os dados obtidos como visualizações, como gráficos e tabelas, ou como resumos baseados em texto para responder à consulta do utilizador.

Exemplos de consultas que pode fazer ao agente de estatísticas de dados

Seguem-se alguns exemplos de consultas que pode fazer ao agente de estatísticas de dados:

  • Agregação e visualização de dados:
    • "Como se comparam as vendas do 2.º trimestre deste ano na região da América Latina com as do 2.º trimestre do ano passado?"
    • "Traça um gráfico de barras que mostre a comparação para cada um dos 5 principais países na região."
  • Análise de tendências:
    • "Como variou o volume de chamadas efetuadas nos últimos 6 meses, discriminado por localização?"
    • "Analisa os padrões de reserva dos hotéis em Lisboa com uma classificação superior a 3 estrelas"
  • Mineração de dados:
    • "Que fatores estão correlacionados com o valor total de vendas quando um cliente compra algo? Dá-me um mapa térmico que mostre a relação."
  • Análise e relatórios:
    • "Resume a tabela de oportunidades e contas e cria um breve relatório que realce as principais tendências."

Antes de começar

Para começar a usar o agente Data Insights no Gemini Enterprise, siga estes passos:

Conceda acesso aos dados do BigQuery

Para permitir que o agente Data Insights veja e consulte os dados do BigQuery, conceda as funções de gestão de identidades e acessos (IAM) aos utilizadores do agente:

Fluxo de trabalho

O fluxo de trabalho geral para configurar e usar o agente Data Insights é o seguinte:

Obtenha detalhes de autorização

Siga estes passos para configurar a autorização. Os detalhes que obtém são necessários para autorizar o agente Data Insights a estabelecer ligação aos dados do BigQuery.

  1. Na Google Cloud consola, aceda à página Credenciais em APIs e serviços.

    Aceder a Credenciais

  2. Selecione o Google Cloud projeto que contém o conjunto de dados do BigQuery que quer que o agente consulte.

  3. Clique em Criar credenciais e selecione ID de cliente OAuth.

  4. Em Tipo de aplicação, selecione Aplicação Web.

  5. Na secção URIs de redirecionamento autorizados, adicione os seguintes URIs:

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

  6. Clique em Criar.

  7. No painel Cliente OAuth criado, clique em Transferir JSON. O JSON transferido inclui os seguintes detalhes para oGoogle Cloud projeto selecionado. Precisa destes detalhes para criar um recurso de autorização:

    • ID de cliente: CLIENT_ID
    • URI de autorização: 
      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 do token: TOKEN_URI
    • Segredo do cliente: CLIENT_SECRET

Configure o agente através da Google Cloud consola

Esta secção mostra como autorizar, criar e implementar uma instância do agente Data Insights usando a consola. Google Cloud Também pode adicionar autorizações de utilizadores que determinam quem pode aceder ao agente criado.

Autorize e crie uma instância do agente

Autorize e crie uma instância do agente Data Insights através destes passos:

  1. Na Google Cloud consola, aceda ao Gemini Enterprise.

    Aceder ao Gemini Enterprise

  2. Selecione uma app na qual quer criar o agente.

  3. No menu, clique em Agentes.

    A página Agentes apresenta os agentes existentes.

  4. Clique em Adicionar agente.

  5. No painel Criar agente, clique em Criar no cartão Agente de dados.

  6. Em Autorizações, clique em Adicionar autorização e introduza os detalhes da autorização. Para mais informações, consulte o artigo Obtenha autorização.

  7. Clique em Concluído.

  8. Clicar em Seguinte.

  9. Configure o agente da seguinte forma:

    1. Introduza o nome e a descrição do agente.
    2. Em Conjunto de dados do BigQuery, clique em Procurar e faça uma das seguintes ações:
      • Selecione um conjunto de dados disponível e clique em Selecionar.
      • Introduza o caminho para o conjunto de dados do BigQuery necessário, clique em Pesquisar, selecione-o e, de seguida, selecione Selecionar.

    3. Opcional: clique em Mostrar mais para ver opções avançadas.

    4. Selecione as opções de acesso à tabela corretas. Se quiser impor uma lista de autorizações ou uma lista de bloqueios, especifique os caminhos para as tabelas restritas.

    5. Opcional: defina a configuração de consulta de linguagem natural para fornecer personalizações específicas de uma tradução de linguagem natural para código SQL ou Python. Também pode fornecer um exemplo de SQL com uma consulta de linguagem natural, o resultado de SQL esperado e a resposta esperada. Isto melhora a qualidade dos resultados do agente.

      • Descrição do esquema: uma string em linguagem natural que descreve o esquema do conjunto de dados do BigQuery.
      • Comando de consulta de linguagem natural para SQL: uma consulta em linguagem natural transformada numa instrução SQL.
      • Consulta de linguagem natural para comando Python: uma consulta em linguagem natural transformada numa instrução Python.

    6. Opcional: adicione exemplos de consultas de linguagem natural transformadas em consultas SQL:

      • Consulta: um exemplo de uma consulta natural que tem de ser convertida numa consulta SQL. Por exemplo, "Quais são os nomes e os endereços de email dos clientes residentes na Califórnia"
      • SQL esperado: uma string que ilustra uma consulta SQL de exemplo correspondente à consulta em linguagem natural. Por exemplo, suponha que tem uma tabela do BigQuery denominada customers. Em seguida, a consulta SQL esperada pode ser SELECT customer_name, email FROM customers WHERE state = 'California'.
      • Resposta esperada: uma string que fornece a resposta esperada para a consulta executando a consulta SQL esperada. Por exemplo:
      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. Clique em Criar.

    A instância do agente Data Insights é apresentada na lista Agentes.
    Para começar a trabalhar com o agente, aguarde até que a coluna Estado do agente apresente o estado Ativado para a sua instância.

Configure o agente através da API REST

Esta secção descreve como autorizar, criar e implementar uma instância do agente Data Insights através da API REST.

Autorize o agente

Como administrador, crie um recurso de autorização no Gemini Enterprise. Isto permite que o agente Data Insights aceda aos dados do BigQuery.

  1. Crie o recurso de autorização.

    REST

    O exemplo seguinte mostra como criar um recurso de autorização através do método 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"
}
}'

    Substitua o seguinte:

    • PROJECT_NUMBER: o número do seu projeto Google Cloud .
    • LOCATION: a localização do seu Google Cloud projeto.
    • AUTHORIZATION_ID: um ID que tem de fornecer para identificar o recurso de autorização.
    • CLIENT_ID: o ID de cliente que obteve no passo anterior.
    • CLIENT_SECRET: o segredo do cliente que obteve no passo anterior.
    • AUTHORIZATION_URI: o URI de autorização que obteve no passo anterior.
    • TOKEN_URI: o URI do token que obteve no passo anterior.

Crie uma instância de agente

Enquanto Google Cloud administrador do projeto, pode criar uma instância do agente Data Insights. Isto requer o ID do projeto e o ID do conjunto de dados dos dados do BigQuery que quer consultar através do seu agente.

REST

O exemplo seguinte mostra como criar uma instância do agente Data Insights através do método agents.create. Para saber mais sobre os campos avançados que pode adicionar a este exemplo, consulte o artigo Adicione configurações avançadas para o 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"
      ]
    }
  }'

Substitua o seguinte:

  • PROJECT_NUMBER: o número do seu projeto Google Cloud .
  • LOCATION: a localização da sua app Gemini Enterprise.
  • APP_ID: o ID da app.
  • AGENT_DISPLAY_NAME: o nome da instância do agente Data Insights.
  • AGENT_ICON_URI: um campo opcional para fornecer um URI para o ícone do agente.
  • AGENT_DESCRIPTION: uma descrição da instância do agente Data Insights que indica a finalidade do agente ou os detalhes da origem dos dados do BigQuery.
  • BIGQUERY_PROJECT_ID: o ID do projeto do projeto que contém o conjunto de dados do BigQuery.Google Cloud
  • BIGQUERY_DATASET_ID: o ID do conjunto de dados do BigQuery que contém os dados a consultar.
  • AUTHORIZATION_RESOURCE_NAME: o nome do recurso de autorização que obteve na secção anterior.

Adicione configurações avançadas para o agente

Opcionalmente, pode definir o campo nlQueryConfig para fornecer personalizações específicas da tradução de linguagem natural para código SQL ou Python. Também pode fornecer um exemplo de SQL com uma consulta de linguagem natural, o resultado de SQL esperado e a resposta esperada. Isto melhora a qualidade dos resultados do agente. O seguinte fragmento do código mostra como pode configurar estes campos avançados:

"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"
  }
}

Substitua o seguinte:

  • NL_TO_SQL_INSTRUCTIONS: uma consulta em linguagem natural transformada numa instrução SQL.
  • NL_TO_PYTHON_INSTRUCTIONS: uma consulta em linguagem natural transformada numa instrução Python.
  • EXAMPLE_NL_QUERY: um exemplo de uma consulta de linguagem natural que tem de ser convertida numa consulta SQL. Por exemplo, "Quais são os nomes e os endereços de email dos clientes sediados na Califórnia"
  • EXPECTED_SQL_QUERY: uma string que ilustra uma consulta SQL de exemplo correspondente à consulta natural. Por exemplo, suponhamos que tem uma tabela do BigQuery denominada customers. Em seguida, a consulta SQL esperada pode ser "SELECT customer_name, email FROM customers WHERE state = 'California'".

  • EXPECTED_SQL_RESPONSE: uma string que fornece a resposta esperada para a consulta e a consulta SQL esperada. Por exemplo:

    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: uma string em linguagem natural que descreve o esquema do conjunto de dados do BigQuery.

Implemente a instância

Depois de criar a instância do agente Data Insights, como administrador, pode implementá-la para que os utilizadores finais a possam usar.

REST

  1. Implemente o agente. O exemplo seguinte mostra como implementar o agente criado através do método agents.deploy. A implementação do agente é uma operação de longa duração (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"
 }'

    Substitua o seguinte:

    • PROJECT_NUMBER: o número do seu projeto Google Cloud .
    • AGENT_RESOURCE_NAME: o nome do recurso do agente que obteve na secção anterior quando criou o agente.

  2. Obtenha o estado da operação de implementação. O exemplo seguinte mostra como obter o estado da operação de implementação do método operations.get.

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

    Substitua DEPLOY_OPERATION_NAME pelo nome do LRO que obteve no passo anterior quando implementou o agente.

    Na resposta, se o valor do campo done for true, a implementação está concluída. Se o valor do campo done for false, a implementação está em curso.

Adicione ou modifique utilizadores e as respetivas autorizações

Adicione ou modifique responsáveis na instância do agente Data Insights e atribua-lhes funções específicas de gestão de identidade e de acesso (IAM) através destes passos:

Consola

  1. Na Google Cloud consola, aceda ao Gemini Enterprise.

    Aceder ao Gemini Enterprise

  2. Selecione uma app que contenha a sua instância do agente Data Insights.

  3. No menu, clique em Agentes.

    A página Agentes apresenta os agentes existentes.

  4. Clique no agente para o qual quer adicionar ou modificar utilizadores.

    Por predefinição, um agente recém-criado não tem utilizadores.

  5. Na tabela Utilizadores com autorização, clique em Adicionar utilizador.

  6. Selecione um Tipo de membro na lista disponível.

  7. Introduza a identidade do membro consoante o tipo e atribua uma ou mais funções.

    • Para um utilizador, um grupo ou uma conta de serviço, a string de membro é um email.
    • Para um domínio, a string de membro é um nome de domínio válido.
    • Para um principal, a string de membro é um principal válido. Por exemplo, principal://iam.googleapis.com/locations/global/workforcePools/pool-1/subject/subject-1.
    • Para um conjunto de principais, a string de membro é um conjunto de principais válido. Por exemplo, principalSet://iam.googleapis.com/locations/global/workforcePools/pool-1/group/group-1.
    • Para domínios e conjuntos de entidades principais, todas as identidades e grupos de utilizadores nesses domínios e conjuntos de entidades principais têm as mesmas funções atribuídas. Para um acesso seguro ao agente, selecione grupos individuais e domínios ou conjuntos de principais controlados, e atribua-lhes funções de privilégio mínimo.

  8. Clique em Guardar.

    A política de IAM é atualizada e o utilizador é adicionado à lista de utilizadores autorizados.

  9. Para modificar as autorizações atribuídas, clique em Ações, selecione Modificar e faça uma das seguintes ações:

    • Modificar as funções atribuídas.
    • Adicione uma função diferente.
    • Clique em Eliminar para remover uma função. Tem de atribuir, pelo menos, uma função a um utilizador.

Altere o estado de funcionamento da instância

Depois de criar a instância do agente Data Insights, o agente é ativado por predefinição. Pode alterar o respetivo estado de funcionamento para Desativado, Suspenso, Ativado ou Eliminado através destes passos:

Consola

  1. Na Google Cloud consola, aceda ao Gemini Enterprise.

    Aceder ao Gemini Enterprise

  2. Selecione uma app que contenha a sua instância do agente Data Insights.

  3. No menu, clique em Agentes.

    A página Agentes apresenta os agentes existentes.

  4. Clique em Ações para os seus agentes e selecione uma das seguintes opções:

    • Suspenso: para tornar o agente temporariamente indisponível para utilização. No entanto, os utilizadores com qualquer grau de autorização para o agente de acesso continuam a poder ver o agente.
    • Desativado: para tornar o agente indisponível para todos os utilizadores, exceto o utilizador que o criou.
    • Ativado: para disponibilizar o agente a todos os utilizadores com qualquer grau de autorização para o agente de acesso.
    • Eliminar: para eliminar a instância do agente.

Use o agente

Siga estes passos para obter estatísticas de dados através do seu agente:

App

  1. No menu de navegação da app, clique em Agentes.

  2. Clique em Ver todos os agentes.

  3. Selecione a instância do agente Data Insights.

  4. Se o seu agente precisar de autorização adicional, clique em Autorizar e faculte os detalhes da autorização.

  5. Clique em Adicionar ficheiros para incluir ficheiros como origens de dados adicionais para o agente trabalhar.

  6. Clique em Fontes para selecionar as fontes que o agente tem de incluir para fornecer as estatísticas de dados mais relevantes.

  7. Introduza as suas perguntas ou comandos e prima Enter ou clique em Enviar.