Pular para o conteúdo principal

Use a API do Genie para integrar o Genie em seus aplicativos

info

Visualização

Esse recurso está em Public Preview.

Esta página explica como usar a API do Genie para ativar os recursos do Genie em seu próprio chatbot, agente ou aplicativo.

Visão geral

O Genie API permite que os desenvolvedores integrem a consulta de dados em linguagem natural a aplicativos, chatbots e estruturas de agentes AI. Ele suporta conversas com estado, permitindo que os usuários façam perguntas complementares e explorem os dados de forma mais natural ao longo do tempo. Usando o Genie API, o senhor pode integrar a consulta em linguagem natural às suas ferramentas e fluxo de trabalho, tornando os dados mais acessíveis em toda a organização.

Antes de usar a API, o senhor deve preparar um espaço Genie bem selecionado. O espaço define o contexto que o Genie usa para interpretar as perguntas e retornar os resultados. Se o espaço estiver incompleto ou não for testado, os usuários poderão receber uma alta taxa de respostas incorretas, mesmo que a integração da API em si seja bem-sucedida. Este guia descreve a configuração mínima necessária para criar um espaço que funcione efetivamente com a API do Genie.

Pré-requisitos

Para usar a API de conversação do Genie, o senhor deve ter:

  • Acesso a um Databricks workspace com o direito Databricks SQL.
  • Pelo menos os privilégios CAN USE em um SQL pro ou serverless SQL warehouse.
  • Familiaridade com a referência da API REST da Databricks.

Etapa 1: Criar e testar um espaço Genie

Prepare um espaço Genie que responda de forma confiável às perguntas dos usuários com um alto grau de precisão.

nota

Mesmo que planeje consultar o espaço do Genie usando a API, o senhor deve configurar e refinar o espaço usando a UI do Databricks.

Use o recurso a seguir para ajudá-lo a configurar e organizar seu espaço Genie:

  1. Configurar um espaço Genie: Saiba como criar um espaço Genie usando a interface do usuário do Databricks. Este artigo inclui orientações passo a passo sobre como usar as ferramentas da interface do usuário para criar um espaço Genie funcional.
  2. Analise as práticas recomendadas: Aprenda as práticas recomendadas para a organização de um novo espaço Genie. Este artigo oferece recomendações sobre como abordar a criação de novos espaços em Genie e como refinar e iterar um espaço por meio de testes e feedback.
  3. Estabeleça padrões de referência: Prepare perguntas de teste de referência que o senhor possa executar para medir a precisão das respostas do Genie.

Um espaço Genie bem estruturado tem as seguintes características:

  • Usa dados bem anotados: o site Genie se baseia em metadados de tabelas e comentários de colunas para gerar respostas. A Unity Catalog fonte de dados para seu espaço Genie deve incluir comentários claros e descritivos.
  • É testado pelo usuário: você deve ser o primeiro usuário do seu espaço. Teste seu espaço fazendo as perguntas que você espera dos usuários finais. Use seus testes para criar e refinar exemplos de consultas SQL.
  • Inclui contexto específico da empresa: é necessário incluir contexto para ensinar ao Genie sobre os dados e o jargão da sua empresa. Consulte Adicionar exemplos e instruções SQL para saber como adicionar instruções, exemplos SQL e funções para processar perguntas comuns. Procure incluir pelo menos cinco exemplos de consultas SQL que tenham sido testadas e aperfeiçoadas.
  • Usa benchmarks para testar a precisão: adicione pelo menos 5 perguntas de benchmark com base nas perguntas que você espera dos usuários finais. execução de testes de benchmark para verificar se o site Genie está respondendo a essas perguntas com precisão.

Quando estiver satisfeito com as respostas do seu espaço Genie e tiver testado o espaço com perguntas representativas, o senhor poderá começar a integrá-lo ao seu aplicativo.

Etapa 2: Configurar a autenticação do Databricks

Para casos de uso de produção em que um usuário com acesso a um navegador está presente, use o OAuth para usuários (OAuth U2M). Em situações em que a autenticação baseada no navegador não é possível, o senhor pode usar uma entidade de serviço para se autenticar na API. Consulte OAuth para entidade de serviço (OAuth M2M). A entidade de serviço deve ter permissões para acessar os dados necessários e o armazém SQL.

Etapa 3: reunir detalhes

Use o URL do espaço Genie para encontrar o nome da instância workspace e o ID do espaço Genie. O exemplo a seguir demonstra como localizar esses componentes na URL. Para obter detalhes sobre os identificadores workspace em seu URL, consulte Obter identificadores para objetos workspace.

https://<databricks-instance>/genie/rooms/<space-id>

Copie o <databricks-instance> e o <space-id> para seu espaço Genie.

Lista Genie spaces

Em vez de encontrar o space-id no URL, o senhor pode usar a opção List Genie spaces endpoint GET /api/2.0/genie/spaces para recuperar programaticamente uma lista de todos os Genie spaces em um workspace ao qual o usuário tem acesso. A matriz spaces retornada lista a descrição, o ID do espaço e o título de cada espaço Genie.

Etapa 4: iniciar uma conversa

A conversa começar endpoint POST /api/2.0/genie/spaces/{space_id}/start-conversation iniciará uma nova conversa em seu espaço Genie.

Substitua os espaços reservados por sua instância Databricks, ID do espaço Genie e tokens de autenticação. Um exemplo de resposta bem-sucedida segue a solicitação. Ele inclui detalhes que você pode usar para acessar essa conversa novamente para fazer perguntas complementares.

POST /api/2.0/genie/spaces/{space_id}/start-conversation

HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
"content": "<your question>",
}


Response:

{
"conversation": {
"created_timestamp": 1719769718,
"id": "6a64adad2e664ee58de08488f986af3e",
"last_updated_timestamp": 1719769718,
"space_id": "3c409c00b54a44c79f79da06b82460e2",
"title": "Give me top sales for last month",
"user_id": 12345
},
"message": {
"attachments": null,
"content": "Give me top sales for last month",
"conversation_id": "6a64adad2e664ee58de08488f986af3e",
"created_timestamp": 1719769718,
"error": null,
"id": "e1ef34712a29169db030324fd0e1df5f",
"last_updated_timestamp": 1719769718,
"query_result": null,
"space_id": "3c409c00b54a44c79f79da06b82460e2",
"status": "IN_PROGRESS",
"user_id": 12345
}
}

Etapa 5: Recuperar o SQL gerado

Use os endereços conversation_id e message_id na resposta à pesquisa para verificar o status de geração da mensagem e recuperar o SQL gerado do Genie. Consulte GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} para obter detalhes completos da solicitação e da resposta.

nota

Somente as solicitações do site POST contam para o limite de consultas por minuto da Taxa de transferência. As solicitações GET usadas para pesquisar os resultados não estão sujeitas a esse limite.

Substitua seus valores na seguinte solicitação:

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

O exemplo de resposta a seguir relata os detalhes da mensagem:

Response:

{
"attachments": null,
"content": "Give me top sales for last month",
"conversation_id": "6a64adad2e664ee58de08488f986af3e",
"created_timestamp": 1719769718,
"error": null,
"id": "e1ef34712a29169db030324fd0e1df5f",
"last_updated_timestamp": 1719769718,
"query_result": null,
"space_id": "3c409c00b54a44c79f79da06b82460e2",
"status": "IN_PROGRESS",
"user_id": 12345
}

Quando o campo status é COMPLETED, a resposta é preenchida na matriz attachments.

Etapa 6: recuperar os resultados da consulta

A matriz attachments contém a resposta do Genie. Ela inclui a resposta de texto gerada (text), a instrução de consulta, se existir (query), e um identificador que você pode usar para obter os resultados da consulta associada (attachment_id). Substitua os espaços reservados no exemplo a seguir para recuperar os resultados da consulta gerada:

GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/query-result/{attachment_id}
Authorization: Bearer <your_authentication_token>

Consulte GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/attachments/{attachment_id}/query-result.

Etapa 7: faça perguntas complementares

Depois de receber uma resposta, use o conversation_id para continuar a conversa. O contexto das mensagens anteriores é mantido e usado nas respostas de acompanhamento. Para obter detalhes completos da solicitação e da resposta, consulte POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages.

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages
HOST= <DATABRICKS_INSTANCE>
Authorization: <your_authentication_token>
{
"content": "Which of these customers opened and forwarded the email?",
}

Referência e recuperação de dados históricos

O site Genie API oferece um ponto de extremidade adicional para gerenciar as conversas existentes e recuperar dados históricos para análise.

Consulte tópicos de conversa antigos

Para permitir que os usuários consultem tópicos de conversa antigos, use o endpoint List conversation messages GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages para recuperar todas as mensagens de um tópico de conversa específico.

Recuperar dados de conversas para análise

Os gerentes de espaço podem recuperar programaticamente todas as mensagens anteriores solicitadas por todos os usuários de um espaço para análise. Para recuperar esses dados:

  1. Use o botão GET /api/2.0/genie/spaces/{space_id}/conversations endpoint para obter todos os tópicos de conversa existentes em um espaço.
  2. Para cada ID de conversa retornada, use o comando GET /api/2.0/genie/spaces/{space_id}/conversations endpoint para recuperar a lista de mensagens dessa conversa.

Práticas recomendadas para usar a API do Genie

Para manter o desempenho e a confiabilidade ao usar a API do Genie:

  • Implementar enfileiramento de solicitações e backoff: O site API não gerencia novas tentativas de solicitação. Use seu próprio sistema de filas e implemente um backoff incremental para evitar exceder os limites da Taxa de transferência.
  • Pesquise atualizações de status a cada 5 a 10 segundos: continue pesquisando até que um status de mensagem conclusivo, como COMPLETED, FAILED ou CANCELLED, seja recebido. Limite a enquete a 10 minutos para a maioria das consultas. Se não houver uma resposta conclusiva após 10 minutos, interrompa a pesquisa e retorne um erro de tempo limite ou solicite que o usuário verifique manualmente o status da consulta posteriormente.
  • Use o recuo exponencial após 2 minutos: se nenhuma resposta for recebida em 2 minutos, aplique o recuo exponencial para melhorar a confiabilidade.
  • Iniciar uma nova conversa para cada sessão: Evite reutilizar threads de conversas entre sessões, pois isso pode reduzir a precisão devido à reutilização não intencional do contexto.
  • Manter os limites de conversas: Para gerenciar conversas antigas e ficar abaixo do limite de 10.000 conversas:
    1. Use o botão GET /api/2.0/genie/spaces/{space_id}/conversations endpoint para ver todos os tópicos de conversa existentes em um espaço.
    2. Identifique conversas que não são mais necessárias, como conversas antigas ou conversas de teste.
    3. Use o botão DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} endpoint para remover conversas de forma programática.

Monitore o espaço

Depois que o aplicativo estiver configurado, o senhor poderá monitorar as perguntas e respostas na interface do usuário do Databricks.

Incentive os usuários a testarem o espaço para que você saiba mais sobre os tipos de perguntas que eles provavelmente farão e as respostas que receberão. Forneça aos usuários orientações para ajudá-los a começar a testar o espaço. Use o monitoramento tab para view perguntas e respostas. Consulte Monitorar o espaço.

O senhor também pode usar logs de auditoria para monitorar a atividade em um espaço Genie. Veja os eventos do AI/BI Genie.

Taxa de transferência limit

Durante o período de Public Preview, as taxas de transferência para o site Genie API são de melhor esforço e dependem da capacidade do sistema. Em condições normais ou de baixo tráfego, as solicitações são limitadas a 5 consultas por minuto por workspace. Durante os períodos de pico de uso, a Taxa de transferência real pode ser menor, pois as solicitações são processadas com base na capacidade disponível.