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. O senhor também pode localizar e copiar o ID do espaço em Genie space Settings tab.

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.

Última atualização em