API Conversational Analytics: crie agentes de dados e converse com os seus dados

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Importante: a API Data QnA foi descontinuada. Se estiver a migrar da API Data QnA, consulte o guia de migração para ver uma vista geral das principais diferenças e dos passos de migração necessários.

Os programadores podem usar a API Conversational Analytics, à qual se acede através de geminidataanalytics.googleapis.com, para criar uma interface de chat com tecnologia de inteligência artificial (IA) ou um agente de dados que usa a linguagem natural para responder a perguntas sobre dados estruturados no BigQuery, no Looker e no Looker Studio. Com a API Conversational Analytics, fornece ao seu agente de dados informações e dados da empresa (contexto), bem como acesso a ferramentas como SQL, Python e bibliotecas de visualização. Estas respostas do agente são apresentadas ao utilizador e podem ser registadas pela aplicação cliente, criando uma experiência de chat de dados integrada e auditável.

Saiba como e quando o Gemini para Google Cloud usa os seus dados.

Como tecnologia em fase inicial, o Gemini para produtos Google Cloud pode gerar resultados que parecem plausíveis, mas que estão factualmente incorretos. Recomendamos que valide todas as saídas do Gemini para Google Cloud produtos antes de as usar. Para mais informações, consulte o artigo Gemini para Google Cloud e IA responsável.

Nota: as ofertas de pré-DG em pré-visualização (1) destinam-se apenas a utilização em ambientes de teste e não devem ser utilizadas num ambiente de produção nem para processar dados pessoais ou outros dados sujeitos a requisitos de conformidade legal ou regulamentar e (2) estão sujeitas aos Termos das Ofertas de Pré-DG dos Termos Específicos do Serviço e ao Suplemento de Consentimento para o Gemini para o Google Cloud Programa de Testadores Fidedignos.

Comece a usar a API Conversational Analytics

Para começar a usar a API Conversational Analytics, pode primeiro rever a documentação sobre a arquitetura e os conceitos-chave para compreender como os agentes processam pedidos, os fluxos de trabalho para criadores e utilizadores de agentes, os modos de conversa e as funções de gestão de identidades e acessos (IAM). Em seguida, para começar a criar agentes de dados, pode escolher entre uma experiência guiada com inícios rápidos, codelabs e blocos de notas ou uma abordagem autónoma seguindo os passos em Configuração e pré-requisitos.

Inícios rápidos, codelabs e blocos de notas

Os seguintes recursos oferecem experiências guiadas para ajudar a começar a usar a API Conversational Analytics:

• App de início rápido: use esta aplicação de início rápido do Streamlit para integrar com a API Conversational Analytics num ambiente de teste local.
• Codelab da API Conversational Analytics: siga um tutorial passo a passo para saber como usar o SDK Python com dados do BigQuery.
• Notebooks do Colaboratory da API Conversational Analytics:
  • Bloco de notas do Colaboratory HTTP: fornece um guia interativo passo a passo para configurar o seu ambiente, criar um agente de dados e fazer chamadas API através de pedidos HTTP.
  • Bloco de notas do Colaboratory do SDK Python: oferece um guia interativo passo a passo para configurar o seu ambiente, criar um agente de dados e fazer chamadas API através do SDK Python.

Configuração e pré-requisitos

Antes de usar a API ou os exemplos, conclua os seguintes passos:

• Ative a API Conversational Analytics: descreve os pré-requisitos para ativar a API Conversational Analytics.
• Controlo de acesso à API Conversational Analytics com o IAM: descreve como usar a gestão de identidade e de acesso para partilhar e gerir o acesso a agentes de dados.
• Autentique e estabeleça ligação a uma origem de dados com a API Conversational Analytics: fornece instruções para autenticar a API e configurar ligações aos seus dados do BigQuery, Looker e Looker Studio.

Crie e interaja com um agente de dados

Depois de concluir os passos anteriores, use a API Conversational Analytics para criar e interagir com um agente de dados seguindo estes passos:

• Crie um agente de dados através de HTTP: fornece um exemplo completo de criação e interação com um agente de dados através de pedidos HTTP diretos com Python.
• Crie um agente de dados com o SDK Python: fornece um exemplo completo de criação e interação com um agente de dados através do SDK Python.
• Oriente o comportamento do agente com contexto criado: saiba como fornecer contexto criado para orientar o comportamento do agente e melhorar a precisão das respostas. Também pode ver exemplos de contexto criado com origens de dados do BigQuery e com origens de dados do Looker.
• Renderizar uma resposta do agente da API Conversational Analytics como uma visualização: fornece um exemplo de processamento de especificações de gráficos a partir de respostas da API e renderização das mesmas como visualizações através do SDK Python e da biblioteca Vega-Altair.

Práticas recomendadas

Reveja os seguintes guias para saber mais sobre as práticas recomendadas para usar a API Conversational Analytics:

• Faça a gestão dos custos do BigQuery para os seus agentes: saiba como monitorizar e gerir os custos do BigQuery para os seus agentes da API Conversational Analytics definindo limites de gastos ao nível do projeto, do utilizador e da consulta.
• Faça perguntas eficazes: saiba como criar perguntas eficazes para os seus agentes tirarem o máximo partido da API Conversational Analytics.
• Resolva problemas de erros da API Conversational Analytics: resolva problemas de erros comuns da API Conversational Analytics.
• Limitações conhecidas: fornece informações detalhadas sobre as limitações conhecidas da API Conversational Analytics, incluindo limitações de consultas, dados, visualizações e perguntas.

Operações da API principais

A API fornece os seguintes pontos finais principais para gerir agentes de dados e conversas:

Operação	Método HTTP	Ponto final	Descrição
Crie um agente	POST	/v1beta/projects/*/locations/*/dataAgents	Cria um novo agente de dados.
Obtenha um agente	GET	/v1beta/projects/*/locations/*/dataAgents/*	Obtém os detalhes de um agente de dados específico.
Obtenha a política de gestão de identidade e de acesso	POST	/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy	Obtém as autorizações de gestão de identidade e de acesso atribuídas a cada utilizador para um agente de dados específico. Os utilizadores com a função de proprietário do agente de dados podem chamar este ponto final para ver a política de gestão de identidades e acessos do agente de dados antes de usar o ponto final setIAMpolicy para partilhar um agente de dados com outros utilizadores.
Defina a política de gestão de identidade e de acesso	POST	/v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy	Define a política de gestão de identidade e de acesso para um agente de dados específico. Os utilizadores com uma função de proprietário do agente de dados devem chamar este ponto final para partilhar um agente de dados com outros utilizadores, o que atualiza efetivamente as autorizações de gestão de identidades e acessos desses utilizadores.
Atualize um agente	PATCH	/v1beta/projects/*/locations/*/dataAgents/*	Modifica um agente de dados existente.
Listar agentes	GET	/v1beta/projects/*/locations/*/dataAgents	Lista os agentes de dados disponíveis num projeto.
Apresentar agentes acessíveis	GET	/v1beta/projects/*/locations/*/dataAgents:listaccessible	Apresenta os agentes de dados acessíveis num projeto. Um agente de dados é considerado acessível se o utilizador que invoca esta API tiver a autorização get no agente. Pode usar o campo creator_filter para gerir os agentes que este método devolve: NONE (predefinição): devolve todos os agentes de dados acessíveis ao utilizador, independentemente de quem os criou. CREATOR_ONLY: devolve apenas os agentes de dados acessíveis ao utilizador e que foram criados por esse utilizador. NOT_CREATOR_ONLY: devolve apenas os agentes de dados acessíveis ao utilizador e que foram criados por outros.
Elimine um agente	DELETE	/v1beta/projects/*/locations/*/dataAgents/*	Remove um agente de dados.
Crie uma conversa	POST	/v1beta/projects/*/locations/*/conversations	Inicia uma nova conversa persistente.
Converse através de uma referência de conversa	POST	/v1beta/projects/*/locations/*:chat	Continua uma conversa com estado enviando uma mensagem de chat que faz referência a uma conversa existente e ao respetivo contexto do agente. Para conversas com várias interações,o Google Cloud armazena e gere o histórico de conversas.
Converse no chat usando uma referência de agente de dados	POST	/v1beta/projects/*/locations/*:chat	Envia uma mensagem de chat sem estado que faz referência a um agente de dados guardados para contexto. Para conversas com várias interações, a sua aplicação tem de gerir e fornecer o histórico de conversas com cada pedido.
Converse através do contexto inline	POST	/v1beta/projects/*/locations/*:chat	Envia uma mensagem de chat sem estado, fornecendo todo o contexto diretamente no pedido, sem usar um agente de dados guardados. Para conversas com várias interações, a sua aplicação tem de gerir e fornecer o histórico de conversas com cada pedido.
Receba uma conversa	GET	/v1beta/projects/*/locations/*/conversations/*	Obtém os detalhes de uma conversa específica.
Listar conversas	GET	/v1beta/projects/*/locations/*/conversations	Apresenta as conversas num projeto específico.
Liste mensagens numa conversa	GET	/v1beta/projects/*/locations/*/conversations/*/messages	Apresenta uma lista de mensagens numa conversa específica.

Enviar feedback

Use os seguintes links para registar um erro ou pedir uma funcionalidade.

• Envie um relatório de erro
• Envie um pedido de funcionalidade

Recursos adicionais

Os seguintes recursos fornecem documentação de referência, exemplos e ferramentas para ajudar a criar aplicações com a API Conversational Analytics:

• Referência REST da API Conversational Analytics: fornece descrições detalhadas de métodos, pontos finais e definições de tipos para estruturas de pedidos e respostas.
• Demonstrações e ferramentas de estatísticas de conversação: reveja demonstrações e ferramentas que apresentam as capacidades da API e fornecem padrões de integração práticos.
• Agent Development Kit (ADK): saiba como usar a função ask_data_insights no ADK para responder a perguntas sobre os seus dados em linguagem natural.