Perguntas frequentes sobre a API Conversational Analytics

A API Conversational Analytics pode alterar ou excluir meus dados?

A API Conversational Analytics foi desenvolvida com proteções para evitar a alteração ou exclusão dos seus dados.

Veja como a segurança dos dados é processada para diferentes fontes:

  • BigQuery: a API bloqueia instruções da linguagem de definição de dados (DDL) e da linguagem de manipulação de dados (DML). Especificamente, o sistema faz um teste de execução no SQL gerado e permite apenas consultas do tipo SELECT.
  • Looker: a API interage com o Looker usando métodos como run_inline_query, que são restritos a operações de leitura, como seleções, filtros e limites. Esses métodos não são compatíveis com operações de DDL ou DML e não incluem operações de exclusão ou remoção.
  • Data Studio (para arquivos CSV e Google Planilhas): o Data Studio usa um formato estruturado para definir e buscar dados para visualizações e relatórios. Todas as consultas executadas com esse método são somente leitura e não são compatíveis com mutações de dados.
  • Bancos de dados: o sistema só permite consultas do tipo SELECT. Para evitar a alteração ou exclusão de dados, verifique se a conta de serviço ou o usuário que interage com a API Conversational Analytics tem permissões somente leitura para seu banco de dados.

A API Conversational Analytics foi projetada para ser somente leitura nessas fontes de dados. Para mais informações sobre a segurança da API Conversational Analytics, consulte a postagem do blog Converse com confiança: como funciona a segurança no recurso Análises de Conversação do Looker.

Como lidar com erros de autenticação e permissão?

Confira alguns erros comuns de autenticação e permissão que podem ocorrer ao usar a API Conversational Analytics:

  1. Erro: PERMISSION_DENIED ou 403 Write access to project ... was denied

    • Causa provável: essa mensagem geralmente indica problemas com os Google Cloud papéis do IAM. O usuário ou a conta de serviço que está tentando usar a API não tem as permissões necessárias no projeto Google Cloud .
    • Solução de problemas:
      • O proprietário do projeto Google Cloud precisa garantir que o usuário ou a conta de serviço tenha os papéis corretos do IAM atribuídos no projeto Google Cloud . Papéis como Project Editor podem ser necessários para determinadas operações, como ativar a API ou testar as funções dela.
      • Se você encontrar um erro 403, como Write access to project 'us-gcp-project-name' was denied, ao mudar de região, verifique a configuração do IAM do projeto.

  2. Erro: 500 Internal Server Error quando um usuário do Looker com o papel Usuário tenta conversar com um agente de dados.

Por que vejo erros 503 ou 500 ao transmitir respostas?

Se você usar um cliente HTTP ou REST básico (como a biblioteca requests do Python) para chamar o endpoint :chat de streaming, a API poderá retornar uma mensagem de erro genérica, como 503 Connection reset by peer ou 500 Internal error.

Esses erros genéricos ocorrem porque a API de streaming envia um cabeçalho HTTP 200 OK assim que o stream é aberto. Se o agente de dados encontrar um erro fatal durante o stream (como um tempo limite para uma consulta de longa duração ou uma negação repentina de permissão), ele vai encerrar o stream e incluir o código de erro específico nos trailers HTTP/2. Os clientes HTTP ou REST padrão não conseguem analisar esses cabeçalhos finais e interpretam o encerramento abrupto como uma falha de soquete.

Para processar erros que ocorrem durante um fluxo, recomendamos usar as bibliotecas de cliente (SDKs) oficiais do Google Cloud , como o SDK Python. Esses SDKs baseados em gRPC analisam trailers HTTP/2 e retornam o código de erro específico, como DEADLINE_EXCEEDED ou PERMISSION_DENIED, em vez de um erro de rede genérico.

Quais são os requisitos do Looker para usar a API Conversational Analytics?

Para usar a API Conversational Analytics, você precisa das permissões adequadas no Google Cloud IAM e no Looker, dependendo da fonte de dados e das ações que quer realizar:

  1. Google Cloud Papéis do IAM:

    • Você precisa ter papéis do IAM suficientes no projeto Google Cloud para interagir com a API geminidataanalytics.googleapis.com. Papéis do IAM configurados incorretamente geralmente levam a erros PERMISSION_DENIED.
    • Os papéis específicos necessários podem depender das ações, mas papéis gerais, como Editor de projetos, podem ser necessários para determinadas operações.

  2. Permissões e papéis do Looker:

    • Permissões no nível do modelo: para usar a API Conversational Analytics e o recurso de análise de conversação, um usuário do Looker precisa receber um papel do Looker que contenha a permissão gemini_in_looker para os modelos com que ele interage.

Para saber mais sobre as permissões e os papéis necessários para usar a API Conversational Analytics, consulte a página de documentação Conceder permissões e papéis do IAM da API Conversational Analytics.

Além disso, sua instância do Looker precisa atender a requisitos específicos:

Para usar a API Conversational Analytics com o Data Studio Pro, sua assinatura do Pro precisa estar fora de um perímetro do VPC-SC.

Quais são os requisitos de banco de dados para usar a API Conversational Analytics?

Para usar a API Conversational Analytics com bancos de dados como AlloyDB para PostgreSQL, GoogleSQL para Spanner, Cloud SQL para MySQL e Cloud SQL para PostgreSQL, verifique se a autenticação e a ativação do IAM estão corretas:

  1. Google Cloud Papéis do IAM:

    • A conta de serviço ou o usuário precisa ter os papéis do IAM necessários para se conectar e consultar o banco de dados específico. Isso geralmente envolve papéis com acesso de leitura ao banco de dados.

  2. Ativação da API:

    • Verifique se a API IA do Google Cloud Companion está ativada no seu Google Cloud projeto.

Para mais informações sobre como ativar a autenticação do IAM, consulte a documentação de cada banco de dados:

Como faço a migração da API Data QnA para a API Conversational Analytics?

Se você usou a versão experimental mais antiga da API Data QnA (dataqna.googleapis.com), consulte o guia de migração para saber como migrar para o novo endpoint oficial da API Conversational Analytics (geminidataanalytics.googleapis.com).

Qual é a diferença entre o nome e o ID de um agente de dados?

O ID do agente de dados, definido como o valor de data_agent_id, é o identificador exclusivo do agente. O nome do agente de dados, data_agent.name, é derivado automaticamente do data_agent_id como um nome totalmente qualificado (FQN), na forma projects/<project>/locations/<location>/dataAgents/<data_agent_id>.

Ao criar um agente de dados, qualquer valor inserido para data_agent.name é ignorado. Ao realizar operações get, update ou delete, o data_agent.name completo é tratado como o identificador exclusivo do agente de dados.

Ao usar a API Conversational Analytics para criar agentes de dados, os seguintes cenários se aplicam:

  • Se você não definir data_agent_id, um ID exclusivo será gerado automaticamente.
  • Se você definir data_agent_id como, por exemplo, TestID, qualquer valor inserido para data_agent.name será substituído por projects/<project>/locations/<location>/dataAgents/TestID.
  • Se você definir data_agent_id com um FQN, vai receber um erro de "nome malformado".

Qual é o formato aceito para um ID em "Criar agente" ou "Criar conversa"?

Para agentes de dados:

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

{data_agent} é o ID do recurso. Ele precisa ter 63 caracteres ou menos e seguir o formato descrito em https://google.aip.dev/122#resource-id-segments (link em inglês).

Exemplo: projects/1234567890/locations/us-central1/dataAgents/my-agent

Recomendamos pular a definição desse campo durante a criação do agente, porque ele será inferido automaticamente e substituído por {parent}/dataAgents/{data_agent_id}.

Para conversas:

projects/{project}/locations/{location}/conversations/{conversation_id}

{conversation_id} é o ID do recurso. Ele pode ter até 63 caracteres e precisa seguir o formato descrito em https://google.aip.dev/122#resource-id-segments (link em inglês).

Exemplo: projects/1234567890/locations/us-central1/conversations/my-conversation.

Recomendamos que você pule a definição desse campo durante a criação da conversa, porque a Análise Conversacional o identificará e substituirá automaticamente por {parent}/conversations/{conversation_id}.

Como faço para usar a máscara de atualização?

No fluxo de atualização do agente de dados, o parâmetro updateMask usa uma string de formato FieldMask que especifica quais campos dataAgent serão substituídos no recurso dataAgent pela atualização. O parâmetro updateMask é um campo obrigatório e é validado da seguinte maneira:

  • Se updateMask estiver vazio, uma BadRequestException será gerada e nenhum campo será atualizado.
  • Se todos os campos no updateMask forem campos dataAgent válidos, somente eles serão atualizados.
  • Se houver uma mistura de campos válidos e inválidos, os inválidos serão ignorados, e apenas os válidos serão atualizados.

Como usar getIAMPolicy e setIAMPolicy para definir a política do IAM de um agente de dados?

É possível usar o método getIamPolicy e o método setIamPolicy para atribuir papéis do IAM a usuários de um agente específico.

Os exemplos de código a seguir demonstram como buscar a política do IAM de um agente de dados:

Os exemplos de código a seguir demonstram como atribuir o IAM a um agente de dados:

Quais são as capacidades de memória do agente de dados da API Conversational Analytics?

  • Em uma única sessão: a API Conversational Analytics é compatível com conversas multiturno, ou seja, ela pode fazer referência a partes anteriores da conversa atual.
  • Em várias sessões: a API Conversational Analytics inclui recursos para histórico de conversas gerenciado, permitindo que os usuários conversem em várias sessões. Ela também é compatível com agentes com estado e conversas multiturno gerenciadas pelo Google.
  • Memória de longo prazo: os agentes de dados da API Conversational Analytics não são compatíveis com recursos explícitos de memória de longo prazo.

Um agente de dados da API Conversational Analytics vai me dar a mesma resposta sempre que eu fizer a mesma pergunta?

  • As respostas em linguagem natural do agente de dados da API Conversational Analytics não são deterministas. Portanto, a resposta em linguagem natural fornecida pelo agente pode variar mesmo para uma pergunta com a mesma redação.
  • Respostas de consultas de dados: no entanto, para uma pergunta específica de busca de dados, espera-se que a consulta gerada (SQL ou do Looker) seja determinista. Os dados recuperados devem ser os mesmos, supondo que os dados subjacentes não tenham mudado.

Como posso melhorar a precisão das respostas de um agente de dados da API Conversational Analytics?

Uma maneira de melhorar a precisão das respostas do agente de dados é fornecer informações contextuais robustas. É possível adicionar contexto das seguintes maneiras:

  • Na camada semântica do Looker, é possível fornecer contexto nas definições do LookML. Para mais informações e exemplos, consulte a página de documentação Orientar o comportamento do agente com contexto criado no Looker.
  • Nas fontes de dados do AlloyDB para PostgreSQL, do Cloud SQL para MySQL, do Cloud SQL para PostgreSQL e do Spanner, é possível fornecer contexto adicionando descrições e restrições de tabelas, colunas e esquemas como orientação para os dados e como interpretá-los.

  • Ao criar um agente de dados, é possível fornecer instruções do sistema, consultas verificadas e contexto avançado:

    • Instruções do sistema, que são orientações definidas pelo usuário que podem moldar o comportamento de um agente de dados. Isso inclui lógica específica da empresa, formatação de respostas ou apresentação de dados.
    • Você pode fornecer consultas verificadas (também chamadas de consultas de ouro, dependendo da fonte de dados), que são exemplos de perguntas em linguagem natural combinadas com as consultas SQL ou do Looker corretas.
    • Para fontes de dados do AlloyDB, do Cloud SQL para MySQL, do Cloud SQL para PostgreSQL e do Spanner, é possível fornecer contexto avançado, o que ajuda a otimizar a compreensão e a precisão dos dados dos seus agentes.

    Para mais informações, consulte Orientar o comportamento do agente com contexto criado.

Consulte a página Faça perguntas úteis para saber como fazer perguntas e receber respostas mais eficazes e precisas.

Como posso inspecionar e processar com segurança o código Python gerado pelo agente?

Se você ativou a análise avançada com Python, seu agente de dados pode retornar código Python. O código Python retornado pelos agentes de dados é projetado para ser executado em um sandbox seguro gerenciado pelo Google. Executar esse código em um ambiente local ou não verificado ignora as proteções de segurança do sandbox e pode expor seu sistema a riscos de segurança, como a execução de código malicioso.

Para inspecionar e processar com segurança o código Python gerado pelo agente, siga estas diretrizes:

  • Inspecione manualmente o código gerado antes de executá-lo. Procure padrões suspeitos, como solicitações de rede inesperadas (por exemplo, socket, requests ou urllib), comandos no nível do sistema (por exemplo, os.system ou subprocess) ou variáveis e literais de string muito ofuscados.
  • Nunca execute código não verificado diretamente em uma máquina local ou em um ambiente de produção. Use um sandbox seguro e isolado, como um notebook do Colaboratory, um contêiner efêmero do Docker ou uma máquina virtual, que não tenha acesso a credenciais sensíveis, redes internas ou sistemas de arquivos locais.
  • Sempre que possível, antes de executar o código, use ferramentas de análise estática ou linters para sinalizar operações potencialmente não seguras ou padrões maliciosos conhecidos.

Posso integrar a API Conversational Analytics com aplicativos de terceiros?

Ao integrar a API Conversational Analytics com aplicativos de terceiros, os usuários podem interagir com os dados diretamente nas ferramentas que usam diariamente.

Qualquer aplicativo de terceiros que interaja com os endpoints da API geminidataanalytics.googleapis.com precisa enviar mensagens do usuário do aplicativo para o agente e mostrar as respostas.

Para criar uma integração, consulte o repositório do guia de início rápido da Conversational Analytics para exemplos ou bibliotecas. Você também pode acessar os fóruns de desenvolvedores do Google para pesquisar exemplos de outros usuários.

Quanto custa a API Conversational Analytics?

A API Conversational Analytics está em fase de pré-lançamento, e o Google não cobra por produtos em pré-lançamento. Vamos avisar com antecedência sobre qualquer mudança de preço no futuro.

Quais fontes de dados são compatíveis com a API Conversational Analytics?

A API Conversational Analytics é compatível com as seguintes fontes de dados:

  • BigQuery
  • Análises do Looker
  • Data Studio
  • AlloyDB para PostgreSQL
  • GoogleSQL para Spanner
  • Cloud SQL e Cloud SQL para PostgreSQL

Você também pode se conectar a fontes como SAP e Salesforce pelo BigQuery, e a CSVs e Planilhas Google pelo Data Studio.

Quais são as limitações conhecidas da API Conversational Analytics?

Para saber mais sobre as limitações conhecidas da API Conversational Analytics, consulte a página de documentação Limitações conhecidas da API Conversational Analytics.

Quais cotas preciso conhecer para projetos Google Cloud ?

Não há restrições na seleção de projetos Google Cloud ou locais. É possível criar agentes de dados para consultar fontes de dados compatíveis que pertencem a qualquer projeto ou região.

A API Conversational Analytics é compatível com a regionalização de dados?

Como a API Conversational Analytics ainda não é compatível com a residência de dados (DRZ), ainda não é possível hospedar agentes em regiões geográficas específicas. A regionalização de dados não é compatível.

A API Conversational Analytics é compatível com outros idiomas além do inglês?

O único idioma oficialmente compatível com a API Conversational Analytics é o inglês. Embora os modelos do Gemini sejam compatíveis com muitos idiomas e alguns usuários tenham relatado sucesso com consultas em outros idiomas, a API Conversational Analytics não é compatível oficialmente com idiomas diferentes do inglês.