Perguntas frequentes sobre a API Conversational Analytics

A API Conversational Analytics pode alterar ou eliminar os meus dados?

A API Conversational Analytics foi concebida com salvaguardas para evitar a alteração ou a eliminação dos seus dados.

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

  • BigQuery: a API bloqueia as declarações da linguagem de definição de dados (DDL) e da linguagem de manipulação de dados (DML). Especificamente, o sistema executa um teste no SQL gerado e só permite consultas do tipo SELECT.
  • Looker: a API interage com o Looker através de métodos como run_inline_query, que estão restritos a operações de leitura, como seleções, filtros e limites. Estes métodos não suportam operações DDL ou DML e não incluem operações de eliminação ou remoção.
  • Looker Studio (para ficheiros CSV e o Google Sheets): o Looker Studio usa um formato estruturado para definir e obter dados para visualizações e relatórios. Todas as consultas executadas com este método são só de leitura e não suportam mutações de dados.

A API Conversational Analytics foi concebida para ser só de leitura nestas origens de dados.

Como posso resolver erros de autenticação e autorização?

Seguem-se alguns erros comuns de autenticação e autorização que pode encontrar quando usa a API Conversational Analytics:

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

    • Causa provável: esta mensagem indica frequentemente problemas com as Google Cloud funções da IAM. O utilizador ou a conta de serviço que está a tentar usar a API não tem as autorizações necessárias no Google Cloud projeto.
    • Resolução de problemas:
      • O Google Cloud proprietário do projeto tem de garantir que o utilizador ou a conta de serviço tem as funções do IAM corretas atribuídas no Google Cloud projeto. Podem ser necessárias funções como Project Editor para determinadas operações, como ativar a API ou testar as respetivas funções.
      • Se encontrar um erro 403, como Write access to project 'us-gcp-project-name' was denied, ao mudar de região, verifique a configuração da IAM do seu projeto.

  2. Erro: 500 Internal Server Error quando um utilizador do Looker com uma função de Utilizador 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, precisa das autorizações adequadas no Google Cloud IAM e no Looker, consoante a origem de dados e as ações que quer realizar:

  1. Google Cloud Funções de IAM:

    • Precisa de funções do IAM suficientes no seu Google Cloud projeto para interagir com a API geminidataanalytics.googleapis.com. As funções IAM configuradas incorretamente originam frequentemente erros PERMISSION_DENIED.
    • As funções específicas necessárias podem depender das ações, mas as funções gerais, como Editor do projeto, podem ser necessárias para determinadas operações.

  2. Autorizações e funções do Looker:

    • Autorizações ao nível do modelo: para usar o Conversational Analytics e a API Conversational Analytics, tem de ser atribuída a um utilizador do Looker uma função que contenha a autorização gemini_in_looker para os modelos com os quais interage.

Para saber mais sobre as autorizações e as funções necessárias para usar a API Conversational Analytics, consulte a página de documentação Conceda funções e autorizações da IAM da API Conversational Analytics para mais informações.

Além disso, a sua instância do Looker tem de cumprir requisitos específicos:

Para usar a API Conversational Analytics com o Looker Studio Pro, a sua subscrição do Pro tem de estar fora de um perímetro de VPC-SC.

Como posso migrar da API Data QnA para a API Conversational Analytics?

Se 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 ponto final 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, que é definido como o valor de data_agent_id, é o identificador exclusivo do agente de dados. O nome do agente de dados, data_agent.name, é derivado automaticamente do data_agent_id como um nome totalmente qualificado (FQN), assumindo a forma projects/<project>/locations/<location>/dataAgents/<data_agent_id>.

Quando cria um agente de dados, qualquer valor que possa ter introduzido para data_agent.name é ignorado. Quando realizar operações get, update ou delete, o data_agent.name completo é tratado como o identificador exclusivo do agente de dados.

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

  • Se não definir data_agent_id, é gerado automaticamente um ID exclusivo.
  • Se definir data_agent_id como, por exemplo, TestID, qualquer valor que possa ter introduzido para data_agent.name é substituído por projects/<project>/locations/<location>/dataAgents/TestID.
  • Se definir data_agent_id com um FQN, recebe um erro de "nome com formato incorreto".

Qual é o formato aceite para um ID em Create Agent ou Create Conversation?

Para agentes de dados:

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

{data_agent} é o ID do recurso. Deve ter 63 carateres ou menos e corresponder ao formato descrito em https://google.aip.dev/122#resource-id-segments.

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

Recomendamos que ignore a definição deste campo durante a criação do agente, uma vez que 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 e deve ter 63 carateres ou menos, e corresponder ao formato descrito em https://google.aip.dev/122#resource-id-segments.

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

Recomendamos que ignore a definição deste campo durante a criação da conversa, uma vez que a análise conversacional o identifica automaticamente e, em seguida, substitui-o por {parent}/conversations/{conversation_id}.

Como uso a máscara de atualização?

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

  • Se updateMask estiver vazio, é gerado um BadRequestException e nenhum campo é atualizado.
  • Se todos os campos em updateMask forem campos válidos dataAgent, apenas esses campos são atualizados.
  • Se for fornecida uma combinação de campos válidos e inválidos, os campos inválidos são ignorados e apenas os válidos são atualizados.

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

  • Numa única sessão: a API Conversational Analytics suporta conversas com várias interações, o que significa que pode fazer referência a partes anteriores da conversa atual.
  • Em várias sessões: a API Conversational Analytics inclui funcionalidades para o histórico de conversas gerido, o que permite aos utilizadores conversar em várias sessões. Também suporta agentes com estado com conversas de várias interações geridas pela Google.
  • Memória a longo prazo: os agentes de dados da API Conversational Analytics não suportam capacidades de memória a longo prazo explícitas.

Um agente de dados da API Conversational Analytics dá-me sempre a mesma resposta quando faço a mesma pergunta?

  • As respostas em linguagem natural do agente de dados da API Conversational Analytics não são determinísticas, pelo que a resposta em linguagem natural fornecida pelo agente pode variar, mesmo para uma pergunta com a mesma redação.
  • Respostas a consultas de dados: no entanto, para uma pergunta específica que procure dados, espera-se que a consulta gerada subjacente (consulta SQL ou do Looker) seja determinística. Os dados obtidos devem ser os mesmos, partindo do princípio de que os dados subjacentes não foram alterados.

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

Uma forma de melhorar a precisão das respostas do agente de dados é fornecer-lhe informações contextuais robustas. Pode adicionar contexto das seguintes formas:

  • Na camada semântica do Looker, pode fornecer contexto nas definições do LookML. Para mais informações e exemplos, consulte a página de documentação Oriente o comportamento do agente com contexto criado no Looker.
  • Quando cria um agente de dados, pode fornecer instruções do sistema, que são orientações definidas pelo utilizador que podem moldar o comportamento de um agente de dados. Estas orientações incluem lógica específica da empresa, formatação de respostas ou apresentação de dados. Também pode fornecer "consultas de ouro", que são exemplos de perguntas em linguagem natural associadas às respetivas consultas SQL ou do Looker corretas. Para mais informações sobre as instruções do sistema, consulte a página de documentação Oriente o comportamento do agente com contexto criado.

Posso integrar a API Conversational Analytics com aplicações de terceiros?

A integração da API Conversational Analytics com aplicações de terceiros permite que os utilizadores interajam com os respetivos dados diretamente nas ferramentas que usam diariamente.

Qualquer aplicação de terceiros que interaja com os pontos finais da API geminidataanalytics.googleapis.com tem de conseguir enviar mensagens do utilizador da aplicação para o agente e apresentar as respostas.

Para criar uma integração, consulte o repositório de inícios rápidos de estatísticas de conversação para ver exemplos ou bibliotecas. Também pode visitar os fóruns de programadores da Google para procurar exemplos de outros utilizadores.

Quanto custa a API Conversational Analytics?

A API Conversational Analytics está numa fase de pré-visualização, e a Google não cobra pelos produtos em pré-visualização. Vamos enviar-lhe um aviso prévio de quaisquer alterações de preços no futuro.

Que origens de dados são suportadas pela API Conversational Analytics?

A API Conversational Analytics suporta as seguintes origens de dados:

  • BigQuery
  • Explorações do Looker
  • Looker Studio

Também pode estabelecer ligação a origens como a SAP e a Salesforce através do BigQuery, e a ficheiros CSV e ao Google Sheets através do 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.

Que quotas tenho de ter em atenção para os Google Cloud projetos?

Não existem restrições na Google Cloud seleção de projetos nem na localização. Pode criar agentes de dados para consultar origens de dados suportadas pertencentes a qualquer projeto ou região.

A API Conversational Analytics suporta a regionalização de dados?

Uma vez que a API Conversational Analytics ainda não suporta a residência de dados (DRZ) nem os perímetros de controlo de serviços (VPC-SC), ainda não pode alojar agentes em regiões geográficas específicas. A regionalização de dados não é suportada.

A API Conversational Analytics suporta outros idiomas além do inglês?

O único idioma oficialmente suportado para a API Conversational Analytics é o inglês. Embora os modelos Gemini subjacentes suportem muitos idiomas e alguns utilizadores tenham comunicado sucesso anedótico com consultas que não estão em inglês, a API Conversational Analytics não suporta oficialmente idiomas que não sejam o inglês.