Perguntas frequentes sobre a API Conversational Analytics

A API Conversational Analytics pode alterar ou excluir meus dados?

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

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

  • 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 oferecem suporte a operações de DDL ou DML e não incluem operações de exclusão ou remoção.
  • Looker Studio (para arquivos CSV e Planilhas Google): o Looker 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 aceitam mutações de dados.

A API Conversational Analytics foi projetada para ser somente leitura nessas fontes de dados.

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 as Google Cloud funções 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 as funções corretas do IAM atribuídas no projeto Google Cloud . Funções como Project Editor podem ser necessárias 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 a função Usuário tenta conversar com um agente de dados.

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 suficientes do IAM no projeto Google Cloud para interagir com a API geminidataanalytics.googleapis.com. Funções do IAM configuradas 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 conversacional, um usuário do Looker precisa receber uma função 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 Looker Studio Pro, sua assinatura do Pro precisa estar fora de um perímetro do VPC-SC.

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

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. Ele 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 oferecem suporte a 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. Por isso, 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.
  • Ao criar um agente de dados, você pode fornecer 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ê também pode fornecer "consultas de ouro", que são exemplos de perguntas em linguagem natural combinadas com as consultas SQL ou do Looker corretas. Para mais informações sobre instruções do sistema, consulte a página de documentação Orientar o comportamento do agente com contexto criado.

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 de início rápido do 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évia, e o Google não cobra por produtos em prévia. 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
  • Looker Studio

Você também pode se conectar a fontes como SAP e Salesforce pelo BigQuery, e a CSVs e Planilhas Google pelo Looker 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 do Google Cloud ?

Não há restrições na Google Cloud seleção de projetos 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) ou os perímetros de controle de serviço (VPC-SC), 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 ofereçam suporte a muitos idiomas e alguns usuários tenham relatado sucesso com consultas em outros idiomas, a API Conversational Analytics não oferece suporte oficial a idiomas diferentes do inglês.