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

Importante

Esse recurso está em Visualização Pública.

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

Visão geral

A API do Genie fornece dois tipos de recursos:

APIs de conversa: habilitar a consulta de dados de linguagem natural em aplicativos, chatbots e estruturas de agente de IA. Essas APIs dão suporte a conversas com estado em que os usuários podem fazer perguntas de acompanhamento e explorar dados naturalmente ao longo do tempo.
APIs de gerenciamento: Habilitam a criação, configuração e implantação programática de espaços do Genie em workspaces. Use essas APIs para pipelines de CI/CD, controle de versão e gerenciamento de espaço automatizado.

Esta página descreve as APIs de conversa e de gerenciamento. Antes de chamar as APIs de conversa, prepare um ambiente bem organizado do Genie. O espaço fornece o contexto que o 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 efetivamente com a API do Genie.

Pré-requisitos

Para usar a API do Genie, você deve ter:

Acesso a um workspace do Azure Databricks com o direito Databricks SQL.
Pelo menos privilégios CAN USE em um warehouse SQL Pro ou SQL sem servidor.

Como começar

Configurar a autenticação do Azure Databricks

Para casos de uso de produção em que um usuário com acesso a um navegador está presente, use OAuth para usuários (OAuth U2M). Em situações em que a autenticação baseada em navegador não é possível, use um principal de serviço para autenticar na API. Consulte o OAuth para entidades de serviço (OAuth M2M). As entidades de serviço devem ter permissões para acessar os dados necessários e os depósitos SQL.

Reunir detalhes

Nome da instância do workspace: Encontre e copie o nome da instância do workspace na URL do seu workspace do Databricks. Para obter detalhes sobre os identificadores do workspace em sua URL, consulte Obter identificadores para objetos de workspace.

Exemplo: https://cust-success.cloud.databricks.com/
ID do warehouse: você precisa da ID de um SQL Warehouse no qual você tenha pelo menos privilégios DE USO. Para localizar a ID do seu armazém:
1. Vá para SQL Warehouses em seu workspace.
2. Selecione o armazém que você deseja usar.
3. Copie o ID do armazém da URL ou da página de detalhes do armazém.
Como alternativa, use o endpoint de List warehousesGET /api/2.0/sql/warehouses para obter programaticamente uma lista de todos os SQL Warehouses que você tem permissões para acessar. A resposta inclui a identificação do armazém.

Criar ou selecionar um espaço Genie

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

Usa dados bem anotados: O Genie se baseia em metadados de tabela e comentários de coluna. Verifique se as fontes de dados do Catálogo do Unity têm comentários claros e descritivos.
É testado pelo usuário: Teste seu espaço fazendo perguntas que você espera dos usuários finais. Use o teste para criar e refinar consultas SQL de exemplo.
Inclui o contexto específico da empresa: Adicione instruções, exemplo de SQL e funções. Consulte Adicionar exemplos e instruções do SQL. Tenha como objetivo pelo menos cinco consultas SQL testadas como exemplo.
Usa parâmetros de comparação para testar a precisão: Adicione pelo menos cinco perguntas de parâmetro de comparação com base nas perguntas antecipadas do usuário. Veja Usar parâmetros de comparação em um espaço do Genie.

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

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

Criar um novo espaço

Crie um espaço do Genie programaticamente usando a API Criar espaço do Genie. O exemplo a seguir demonstra um espaço bem estruturado que segue as práticas recomendadas. 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\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
  "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          \"What were total sales last month?\"\n        ]\n      },\n      {\n        \"id\": \"b2c3d4e5f6g700000000000000000000\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ]\n      },\n      {\n        \"id\": \"c3d4e5f6g7h800000000000000000000\",\n        \"question\": [\n          \"Compare sales by region for Q1 vs Q2\"\n        ]\n      }\n    ]\n  },\n  \"data_sources\": {\n    \"tables\": [\n      {\n        \"identifier\": \"sales.analytics.orders\",\n        \"description\": [\n          \"Transactional order data including order date, amount, and customer information\"\n        ],\n        \"column_configs\": [\n          {\n            \"column_name\": \"order_date\",\n            \"get_example_values\": true\n          },\n          {\n            \"column_name\": \"status\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          },\n          {\n            \"column_name\": \"region\",\n            \"get_example_values\": true,\n            \"build_value_dictionary\": true\n          }\n        ]\n      },\n      {\n        \"identifier\": \"sales.analytics.customers\"\n      },\n      {\n        \"identifier\": \"sales.analytics.products\"\n      }\n    ]\n  },\n  \"instructions\": {\n    \"text_instructions\": [\n      {\n        \"id\": \"01f0b37c378e1c91\",\n        \"content\": [\n          \"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"\n        ]\n      }\n    ],\n    \"example_question_sqls\": [\n      {\n        \"id\": \"01f0821116d912db\",\n        \"question\": [\n          \"Show top 10 customers by revenue\"\n        ],\n        \"sql\": [\n          \"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\n          \"FROM sales.analytics.orders o\\n\",\n          \"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\n          \"GROUP BY customer_name\\n\",\n          \"ORDER BY total_revenue DESC\\n\",\n          \"LIMIT 10\"\n        ]\n      },\n      {\n        \"id\": \"01f099751a3a1df3\",\n        \"question\": [\n          \"What were total sales last month\"\n        ],\n        \"sql\": [\n          \"SELECT SUM(order_amount) as total_sales\\n\",\n          \"FROM sales.analytics.orders\\n\",\n          \"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\n          \"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"\n        ]\n      }\n    ],\n    \"join_specs\": [\n      {\n        \"id\": \"01f0c0b4e8151\",\n        \"left\": {\n          \"identifier\": \"sales.analytics.orders\",\n          \"alias\": \"orders\"\n        },\n        \"right\": {\n          \"identifier\": \"sales.analytics.customers\",\n          \"alias\": \"customers\"\n        },\n        \"sql\": [\n          \"orders.customer_id = customers.customer_id\"\n        ]\n      }\n    ],\n    \"sql_snippets\": {\n      \"filters\": [\n        {\n          \"id\": \"01f09972e66d1\",\n          \"sql\": [\"orders.order_amount > 1000\"],\n          \"display_name\": \"high value orders\",\n          \"synonyms\": [\"large orders\", \"big purchases\"]\n        }\n      ],\n      \"expressions\": [\n        {\n          \"id\": \"01f09974563a1\",\n          \"alias\": \"order_year\",\n          \"sql\": [\"YEAR(orders.order_date)\"],\n          \"display_name\": \"year\"\n        }\n      ],\n      \"measures\": [\n        {\n          \"id\": \"01f09972611f1\",\n          \"alias\": \"total_revenue\",\n          \"sql\": [\"SUM(orders.order_amount)\"],\n          \"display_name\": \"total revenue\",\n          \"synonyms\": [\"revenue\", \"total sales\"]\n        }\n      ]\n    }\n  }\n}\n"
}

Usar um espaço existente

Se você já tiver um espaço do Genie, poderá encontrar o ID do espaço usando a List Genie spaces API. Você também pode encontrar e copiar a ID do espaço na guia de Configurações do espaço Genie.

GET /api/2.0/genie/spaces
Host: <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>

Response:
{
  "spaces": [
    {
      "description": "Space for analyzing sales performance and trends",
      "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\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}",
      "space_id": "3c409c00b54a44c79f79da06b82460e2",
      "title": "Sales Analytics Space",
      "warehouse_id": "<warehouse-id>",
    },
    {
      "description": "Space for marketing campaign analysis",
      "serialized_space": "{\"version\":1,\"config\":{\"sample_questions\":[{\"id\":\"a1b2c3d4e5f6\",\"question\":[\"Show total revenue by state\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.gold.orders\"}]}}",
      "space_id": "7f8e9d0c1b2a3456789abcdef0123456",
      "title": "Marketing Analytics Space",
      "warehouse_id": "<warehouse-id>",
    }
  ]
}

Use o space_id da resposta em chamadas subsequentes de API.

Noções básicas sobre o campo serialized_space

O serialized_space campo é uma cadeia de caracteres JSON que define a configuração e as fontes de dados para o espaço do Genie. Na solicitação de API, esse JSON deve ser tratado como uma cadeia de caracteres. O campo contém:

versão: Versão do esquema (atualmente 1)
configuração: Configuração de espaço, incluindo:
- sample_questions: Perguntas de exemplo para orientar os usuários. Cada pergunta requer:
  - id: um identificador exclusivo para a pergunta. Você pode gerar qualquer cadeia de caracteres exclusiva (como cadeias de caracteres alfanuméricas curtas ou UUIDs). O sistema normaliza-os para identificadores de 32 caracteres.
  - pergunta: uma matriz que contém o texto da pergunta.
  Inclua pelo menos cinco perguntas diversas que representam casos de uso comuns.
data_sources: fontes de dados disponíveis para o espaço, incluindo:
- tabelas: Matriz de objetos de tabela no formato de namespace de três níveis (catalog.schema.table). Cada tabela pode incluir:
  - identificador: Obrigatório. O nome completo da tabela.
  - descrição: opcional. Array que contém o texto descritivo sobre a tabela.
  - column_configs: opcional. Matriz de objetos de configuração de coluna com:
    - column_name: o nome da coluna.
    - get_example_values: Booleano. Se os valores de exemplo devem ser amostrados da coluna.
    - build_value_dictionary: booleano. Se você deve criar um dicionário de valores para colunas categóricas.
instruções: opcional. Instruções estruturadas para o ambiente, incluindo:
- text_instructions: instruções textuais para o espaço.
- example_question_sqls: matriz de objetos de consulta SQL de exemplo.
- join_specs: Matriz definindo relações de junção entre tabelas.
- sql_snippets: objeto que contém filtros, expressões e medidas.

A versão sem escape do campo serialized_space do exemplo de criar espaço parece:

{
  "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"]
      }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.orders",
        "description": ["Transactional order data including order date, amount, and customer information"],
        "column_configs": [
          {
            "column_name": "order_date",
            "get_example_values": true
          },
          {
            "column_name": "status",
            "get_example_values": true,
            "build_value_dictionary": true
          },
          {
            "column_name": "region",
            "get_example_values": true,
            "build_value_dictionary": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.customers"
      },
      {
        "identifier": "sales.analytics.products"
      }
    ]
  },
  "instructions": {
    "text_instructions": [
      {
        "id": "01f0b37c378e1c91",
        "content": [
          "When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places."
        ]
      }
    ],
    "example_question_sqls": [
      {
        "id": "01f0821116d912db",
        "question": ["Show top 10 customers by revenue"],
        "sql": [
          "SELECT customer_name, SUM(order_amount) as total_revenue\n",
          "FROM sales.analytics.orders o\n",
          "JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\n",
          "GROUP BY customer_name\n",
          "ORDER BY total_revenue DESC\n",
          "LIMIT 10"
        ]
      },
      {
        "id": "01f099751a3a1df3",
        "question": ["What were total sales last month"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\n",
          "AND order_date < DATE_TRUNC('month', CURRENT_DATE)"
        ]
      }
    ],
    "join_specs": [
      {
        "id": "01f0c0b4e8151",
        "left": {
          "identifier": "sales.analytics.orders",
          "alias": "orders"
        },
        "right": {
          "identifier": "sales.analytics.customers",
          "alias": "customers"
        },
        "sql": ["orders.customer_id = customers.customer_id"]
      }
    ],
    "sql_snippets": {
      "filters": [
        {
          "id": "01f09972e66d1",
          "sql": ["orders.order_amount > 1000"],
          "display_name": "high value orders",
          "synonyms": ["large orders", "big purchases"]
        }
      ],
      "expressions": [
        {
          "id": "01f09974563a1",
          "alias": "order_year",
          "sql": ["YEAR(orders.order_date)"],
          "display_name": "year"
        }
      ],
      "measures": [
        {
          "id": "01f09972611f1",
          "alias": "total_revenue",
          "sql": ["SUM(orders.order_amount)"],
          "display_name": "total revenue",
          "synonyms": ["revenue", "total sales"]
        }
      ]
    }
  }
}

Ao construir seu espaço, crie essa estrutura JSON e escape-a como uma cadeia de caracteres para a solicitação de API. Para obter detalhes completos do esquema, consulte a referência da API de espaço Create Genie.

Usando a API de conversa

Depois de configurar um espaço Genie, use os endpoints da API de conversação para fazer perguntas, recuperar resultados e manter conversas em múltiplos turnos com contexto.

Iniciar uma conversa

A opção Iniciar ponto de extremidade de conversaPOST /api/2.0/genie/spaces/{space_id}/start-conversation inicia uma nova conversa no seu espaço do Genie.

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

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 o conversation_id e o message_id na resposta para verificar o estado 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} os detalhes completos da solicitação e da resposta.

Observação

Somente as solicitações POST contam para o limite de produtividade de consultas por minuto. GET as solicitações usadas para sondar 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>

A resposta de exemplo 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 status campo é COMPLETED a resposta é preenchida na attachments matriz.

Recuperar resultados da consulta

A attachments matriz contém a resposta do Genie. Ele inclui a resposta de texto gerada (text), a instrução de consulta se ela 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 obter 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.

Fazer perguntas de acompanhamento

Depois de receber uma resposta, use a conversation_id para continuar a conversa. O contexto das mensagens anteriores é mantido e usado em respostas de acompanhamento. Para obter detalhes completos de solicitação e 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ços e conversas

A API do Genie fornece endpoints adicionais para recuperar dados de configuração e históricos de conversas e espaços existentes.

Recuperar configuração de espaço

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

Use essa representação serializada com a API do Create Genie Space e a API do Update Genie Space para promover espaços Genie em espaços de trabalho ou criar backups das configurações de espaço.

Solicitação de exemplo 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\"]}]},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\",\"description\":[\"Transactional order data including order date, amount, and customer information\"],\"column_configs\":[{\"column_name\":\"order_date\",\"get_example_values\":true},{\"column_name\":\"status\",\"get_example_values\":true,\"build_value_dictionary\":true},{\"column_name\":\"region\",\"get_example_values\":true,\"build_value_dictionary\":true}]},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]},\"instructions\":{\"text_instructions\":[{\"id\":\"01f0b37c378e1c91\",\"content\":[\"When calculating revenue, sum the order_amount column. When asked about 'last month', use the previous calendar month (not the last 30 days). Round all monetary values to 2 decimal places.\"]}],\"example_question_sqls\":[{\"id\":\"01f0821116d912db\",\"question\":[\"Show top 10 customers by revenue\"],\"sql\":[\"SELECT customer_name, SUM(order_amount) as total_revenue\\n\",\"FROM sales.analytics.orders o\\n\",\"JOIN sales.analytics.customers c ON o.customer_id = c.customer_id\\n\",\"GROUP BY customer_name\\n\",\"ORDER BY total_revenue DESC\\n\",\"LIMIT 10\"]},{\"id\":\"01f099751a3a1df3\",\"question\":[\"What were total sales last month\"],\"sql\":[\"SELECT SUM(order_amount) as total_sales\\n\",\"FROM sales.analytics.orders\\n\",\"WHERE order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH)\\n\",\"AND order_date < DATE_TRUNC('month', CURRENT_DATE)\"]}],\"join_specs\":[{\"id\":\"01f0c0b4e8151\",\"left\":{\"identifier\":\"sales.analytics.orders\",\"alias\":\"orders\"},\"right\":{\"identifier\":\"sales.analytics.customers\",\"alias\":\"customers\"},\"sql\":[\"orders.customer_id = customers.customer_id\"]}],\"sql_snippets\":{\"filters\":[{\"id\":\"01f09972e66d1\",\"sql\":[\"orders.order_amount > 1000\"],\"display_name\":\"high value orders\",\"synonyms\":[\"large orders\",\"big purchases\"]}],\"expressions\":[{\"id\":\"01f09974563a1\",\"alias\":\"order_year\",\"sql\":[\"YEAR(orders.order_date)\"],\"display_name\":\"year\"}],\"measures\":[{\"id\":\"01f09972611f1\",\"alias\":\"total_revenue\",\"sql\":[\"SUM(orders.order_amount)\"],\"display_name\":\"total revenue\",\"synonyms\":[\"revenue\",\"total sales\"]}]}}}"
}

Referenciar threads de conversa antigos

Para permitir que os usuários se refiram a threads de conversa antigos, use o ponto de GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages para recuperar todas as mensagens de um thread de conversa específico.

Recuperar dados de conversa para análise

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

Use o GET /api/2.0/genie/spaces/{space_id}/conversations ponto de extremidade para obter todos os threads de conversa existentes em um espaço.
Para cada ID de conversa retornada, use o GET /api/2.0/genie/spaces/{space_id}/conversations ponto de extremidade para recuperar a lista de mensagens dessa conversa.

Melhores práticas e limites

Práticas recomendadas para usar a API do Genie

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

Implementar lógica de repetição com recuo exponencial: A API não faz tentativas automáticas de requisições falhadas para você, portanto, adicione sua própria fila e recuo exponencial. Isso ajuda seu aplicativo a lidar com falhas transitórias, evitar solicitações de repetição desnecessárias e permanecer dentro dos limites de taxa de transferência à medida que ele aumenta.
Registrar respostas da API: Implemente o registro abrangente de solicitações e respostas de API para ajudar na depuração, no monitoramento de padrões de uso e no acompanhamento de custos.
Sondagem para atualizações de status a cada 1 a 5 segundos: Continue sondando até que um status de mensagem conclusivo, como COMPLETED, FAILEDou CANCELLED, seja recebido. Limite a sondagem para 10 minutos para a maioria das consultas. Se não houver resposta conclusiva após 10 minutos, interrompa a sondagem e retorne um erro de tempo limite ou solicite que o usuário verifique manualmente o status da consulta mais tarde.
Use o recuo exponencial para polling: Aumente o atraso entre as consultas até um máximo de um minuto. Isso reduz solicitações desnecessárias para consultas de longa execução, permitindo ainda baixa latência para consultas rápidas.
Inicie uma nova conversa para cada sessão: Evite reutilizar threads de conversa entre sessões, pois isso pode reduzir a precisão devido à reutilização de contexto não intencional.
Manter limites de conversa: Para gerenciar conversas antigas e ficar abaixo do limite de 10.000 conversas:
1. Use o GET /api/2.0/genie/spaces/{space_id}/conversations ponto de extremidade para ver todos os threads de conversa existentes em um espaço.
2. Identifique conversas que não são mais necessárias, como conversas mais antigas ou conversas de teste.
3. Use o DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} ponto de extremidade para remover conversas programaticamente.
Lembre-se do limite de resultados da consulta: a API do Genie retorna um máximo de 5.000 linhas por resultado da consulta. Se a análise de dados exigir mais linhas, considere refinar sua pergunta para se concentrar em um subconjunto específico de dados ou usar filtros para restringir os resultados.

Limite de desempenho

Durante o período de Visualização Pública, as taxas de transferência da camada gratuita da API Genie são baseadas em melhor esforço 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 uso, o sistema processa solicitações com base na capacidade disponível, o que pode resultar em menor taxa de transferência.

Monitorar o espaço

Depois que o aplicativo for configurado, você poderá monitorar perguntas e respostas na interface do usuário do Databricks.

Incentive os usuários a testar o espaço para que você aprenda sobre os tipos de perguntas que eles provavelmente farão e as respostas que recebem. Forneça aos usuários orientações para ajudá-los a começar a testar o espaço. Use a guia Monitoramento para exibir perguntas e respostas. Veja Monitorar o espaço.

Você também pode usar logs de auditoria para monitorar a atividade em um espaço do Genie. Veja Eventos de AI/BI do Genie.

Comentários

Esta página foi útil?

Last updated on 2025-12-19