Pular para o conteúdo principal
Última atualização em

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​

A API Genie oferece dois tipos de funcionalidades:

  • APIsde Conversação : Permitem a consulta de dados em linguagem natural em aplicativos, chatbots e estruturas de agentes AI . Essas APIs suportam conversas com estado, onde os usuários podem fazer perguntas de acompanhamento e explorar os dados naturalmente ao longo do tempo.
  • APIsde gerenciamento : Permitem a criação, configuração e implantação programática de Genie spaces em todo o ambiente de trabalho. Utilize essas APIs para pipelines de CI/CD , controle de versão e gerenciamento automatizado de espaço.

Esta página descreve as APIs de conversação e de gerenciamento. Antes de chamar as APIs de conversação, prepare um espaço Genie bem organizado. O espaço fornece o contexto que Genie usa para interpretar perguntas e gerar respostas. Se o espaço estiver incompleto ou não testado, os usuários ainda poderão receber resultados incorretos mesmo com uma integração de API correta. Este guia explica a configuração mínima necessária para criar um espaço que funcione eficazmente com a API Genie.

Pré-requisitos​

Para usar a API Genie, você precisa 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.

Começando​

Configurar autenticação do Databricks​

Para casos de uso em produção onde um usuário com acesso a um navegador esteja presente, utilize OAuth para usuários (OAuth U2M). Em situações onde a autenticação baseada em navegador não é possível, utilize uma entidade de serviço para autenticar com a API. Consulte OAuth para entidade de serviço (OAuth M2M). A entidade de serviço deve ter permissões de acesso aos dados necessários e ao banco de dados SQL .

Reúna os detalhes​

  • Nome da instância do espaço de trabalho : Encontre e copie o nome da instância do seu workspace a partir do URL do seu workspace Databricks . Para obter detalhes sobre os identificadores workspace em seu URL, consulte Obter identificadores para objetos workspace.

    Exemplo: https://cust-success.cloud.databricks.com/

  • ID do Warehouse : Você precisa do ID de um SQL warehouse no qual você tenha pelo menos privilégios de CAN USE. Para encontrar o ID do seu armazém:

    1. Acesse o SQL Warehouse em seu workspace.
    2. Selecione o armazém que deseja utilizar.
    3. Copie o ID do armazém a partir do URL ou da página de detalhes do armazém.

    Alternativamente, use o endpointList warehouses GET /api/2.0/sql/warehouses para recuperar programaticamente uma lista de todos os warehouses SQL aos quais você tem permissão de acesso. A resposta inclui o ID do armazém.

Crie ou selecione um espaço Genie​

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

  • Utiliza dados bem anotados: Genie depende de metadados de tabelas e comentários de colunas. Verifique se sua fonte de dados Unity Catalog possui comentários claros e descritivos.
  • O ambiente foi testado pelos usuários? Teste seu espaço fazendo perguntas que você espera que os usuários finais façam. Utilize testes para criar e aprimorar exemplos de consultas SQL.
  • Inclui contexto específico da empresa: Adiciona instruções, exemplos de SQL e funções. Consulte os exemplos e instruções para adicionar SQL. Procure criar pelo menos cinco exemplos de consultas SQL testadas.
  • Utiliza parâmetros de referência para testar a precisão: Adicione pelo menos cinco perguntas de referência com base em perguntas previstas dos usuários. Consulte Usar benchmarks em um espaço Genie.

Para obter mais informações sobre como criar um espaço, consulte Configurar e gerenciar um espaço Genie AI/BI e Organizar um espaço Genie eficaz.

Você pode criar um novo espaço Genie ou usar um já existente:

Crie um espaço Genie programaticamente usando a API Criar espaço Genie. O exemplo a seguir demonstra um espaço bem estruturado que segue as melhores práticas. Substitua os espaços reservados pelos seus valores:

POST /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "description": "Space for analyzing sales performance and trends",
  "parent_path": "/Workspace/Users/<username>",
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g7\",\"question\":[\"Show top 10 customers by revenue\"]},{\"id\":\"c3d4e5f6g7h8\",\"question\":[\"Compare sales by region for Q1 vs Q2\"]},{\"id\":\"d4e5f6g7h8i9\",\"question\":[\"Which products have the highest return rate?\"]},{\"id\":\"e5f6g7h8i9j0\",\"question\":[\"Show monthly revenue trend for the past year\"]}],\"instructions\":\"This space analyzes sales data from our e-commerce platform. All monetary values are in USD. Use the orders and customers tables for transactional data.\"},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\"},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]}}",
  "title": "Sales Analytics Space",
  "warehouse_id": "<warehouse-id>"
}

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "serialized_space": "{\n  \"version\": 1,\n  \"config\": {\n    \"sample_questions\": [\n      {\n        \"id\": \"a1b2c3d4e5f600000000000000000000\",\n        \"question\": [\n          \"Show orders by date\"\n        ]\n      }\n    ]\n  },\n  \"data_sources\": {\n    \"tables\": [\n      {\n        \"identifier\": \"samples.tpch.orders\"\n      }\n    ]\n  }\n}\n"
}

Entendendo o campo serialized_space​

O campo serialized_space é uma string JSON que define a configuração e a fonte de dados para o seu espaço Genie . Na requisição API , este JSON deve ser convertido em uma string. O campo contém:

  • versão : Versão do esquema (atualmente 1)

  • Configuração : Configuração de espaço, incluindo:

    • sample_questions : Exemplos de perguntas para guiar os usuários. Cada questão exige:

      • id : Um identificador único para a pergunta. Você pode gerar qualquer sequência de caracteres única (como strings alfanuméricas curtas ou UUIDs). O sistema normaliza esses valores para identificadores de 32 caracteres.
      • pergunta : Uma matriz contendo o texto da pergunta.

      Inclua pelo menos cinco perguntas diversas que representem casos de uso comuns.

    • Instruções : Contexto sobre os dados, regras de negócio e como interpretar os resultados. Isso ajuda o Genie a fornecer respostas mais precisas.

  • data_sources : fonte de dados disponível para o espaço, incluindo:

    • tabelas : Matriz de identificadores de tabela no formato de namespace de três níveis (catalog.schema.table). Inclua todas as tabelas relevantes que os usuários irão consultar.

A versão sem escape do campo serialized_space do exemplo de criação de espaço se parece com:

JSON
{
  "version": 1,
  "config": {
    "sample_questions": [
      {
        "id": "a1b2c3d4e5f6",
        "question": ["What were total sales last month?"]
      },
      {
        "id": "b2c3d4e5f6g7",
        "question": ["Show top 10 customers by revenue"]
      },
      {
        "id": "c3d4e5f6g7h8",
        "question": ["Compare sales by region for Q1 vs Q2"]
      },
      {
        "id": "d4e5f6g7h8i9",
        "question": ["Which products have the highest return rate?"]
      },
      {
        "id": "e5f6g7h8i9j0",
        "question": ["Show monthly revenue trend for the past year"]
      }
    ],
    "instructions": "This space analyzes sales data from our e-commerce platform. All monetary values are in USD. Use the orders and customers tables for transactional data."
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.orders"
      },
      {
        "identifier": "sales.analytics.customers"
      },
      {
        "identifier": "sales.analytics.products"
      }
    ]
  }
}

Ao construir seu espaço, crie esta estrutura JSON e, em seguida, converta-a em strings para a solicitação API . Para obter detalhes completos do esquema, consulte a referência da API Create Genie space.

Usando a API de conversação​

Após configurar um espaço Genie , use o endpoint API de conversas para fazer perguntas, obter resultados e manter conversas com várias interações e contexto.

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
  }
}

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

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

Faça perguntas de acompanhamento.​

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?",
}

Recuperar dados de espaço e conversação​

A API Genie fornece um endpoint adicional para recuperar configurações e dados históricos de espaços e conversas existentes.

Recuperar configuração de espaço​

Ao recuperar informações de espaço usando a APIGet Genie Space, você pode incluir o campo serialized_space na resposta definindo o parâmetro include_serialized_space como true. O campo serialized_space contém a representação de strings serializadas do espaço Genie , incluindo instruções, benchmarks, junção e outros detalhes de configuração.

Utilize essa representação serializada com as APICriar Espaço Genie e APIEspaço Genie para promover Genie spaces entre áreas de trabalho ou criar backups das configurações de espaço.

Exemplo de solicitação GET:

GET /api/2.0/genie/spaces/{space_id}?include_serialized_space=true
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "space_id": "3c409c00b54a44c79f79da06b82460e2",
  "title": "Sales Analytics Space",
  "description": "Space for analyzing sales performance and trends",
  "warehouse_id": "<warehouse-id>",
  "created_timestamp": 1719769718,
  "last_updated_timestamp": 1719769718,
  "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f600000000000000000000\",\"question\":[\"What were total sales last month?\"]},{\"id\":\"b2c3d4e5f6g700000000000000000000\",\"question\":[\"Show top 10 customers by revenue\"]}],\"instructions\":\"This space analyzes sales data from our e-commerce platform. All monetary values are in USD. Use the orders and customers tables for transactional data.\"},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\"},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]}}"
}

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.

Melhores práticas e limites​

Melhores práticas para usar a API Genie​

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

  • Implemente uma lógica de repetição com recuo exponencial: A API não repete solicitações com falha automaticamente, portanto, adicione seu próprio sistema de filas e recuo exponencial. Isso ajuda sua aplicação a lidar com falhas transitórias, evitar solicitações repetidas desnecessárias e permanecer dentro dos limites de taxa de transferência à medida que cresce.

  • Registro de respostas API : Implemente um registro abrangente de solicitações e respostas API para ajudar na otimização do uso, monitorar padrões de utilização e acompanhar custos.

  • Verificar atualizações de status a cada 1 a 5 segundos: Continue verificando até receber uma mensagem de status conclusiva, como COMPLETED, FAILED ou CANCELLED. Limite o intervalo de consulta a 10 minutos para a maioria das solicitações. Se não houver uma resposta conclusiva após 10 minutos, interrompa a consulta e retorne um erro de tempo limite ou solicite ao usuário que verifique manualmente o status da consulta posteriormente.

  • Utilize o recuo exponencial para a verificação: aumente o intervalo entre as verificações até um máximo de um minuto. Isso reduz solicitações desnecessárias para consultas de longa duração, ao mesmo tempo que permite baixa latência para consultas rápidas.

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

  • Esteja ciente do limite de resultados da consulta : A API Genie retorna um máximo de 5.000 linhas por resultado de consulta. Se a sua análise de dados exigir mais linhas, considere refinar a sua pergunta para se concentrar num subconjunto específico de dados ou utilize filtros para restringir os resultados.

Taxa de transferência limit​

Durante o período de pré-visualização pública, as taxas de transferência da API Genie gratuita são calculadas da melhor forma possível e dependem da capacidade do sistema. Em condições normais ou de baixo tráfego, a API limita as solicitações a 5 consultas por minuto por workspace. Durante os períodos de pico de utilização, o sistema processa os pedidos com base na capacidade disponível, o que pode resultar numa taxa de transferência inferior.

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.