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 do geminidataanalytics.googleapis.com, para criar uma interface de chat ou um agente de dados com tecnologia de inteligência artificial (IA) que responde a perguntas sobre dados estruturados no BigQuery, no Looker e no Looker Studio através da linguagem natural. Com a API Conversational Analytics, fornece ao seu agente de dados informações e dados empresariais ("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 orientada com os blocos de notas do Colaboratory ou uma abordagem autónoma seguindo os passos em Configuração e pré-requisitos.

Blocos de notas interativos do Colaboratory

Para um guia interativo passo a passo sobre como configurar o seu ambiente, criar um agente de dados e fazer chamadas API, consulte os seguintes blocos de notas do Colaboratory:

• Bloco de notas do Colaboratory HTTP da API Conversational Analytics
• Bloco de notas do Colaboratory do SDK da API Conversational Analytics

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.
• Conceda funções e autorizações de IAM da API Conversational Analytics: descreve as funções de IAM predefinidas para 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.
• Escreva instruções do sistema eficazes: saiba como estruturar o conteúdo YAML para o parâmetro system_instruction de modo a orientar o comportamento do agente e melhorar a precisão das respostas. Também pode ver exemplos de instruções do sistema em origens de dados do BigQuery e em 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

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

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

• Documentação de referência da API Conversational Analytics: fornece descrições detalhadas de métodos, pontos finais e definições de tipos para estruturas de pedidos e respostas.
• Resolva problemas de erros da API Conversation Analytics: resolva problemas de erros comuns da API Conversation Analytics.
• Limitações conhecidas: fornece informações detalhadas sobre as limitações conhecidas da API Conversation Analytics, incluindo limitações de consultas, limitações de dados, limitações de visualização e limitações de perguntas.