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

Importante

Este recurso está no Public Preview.

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

Visão geral

A API Genie oferece dois tipos de capacidades:

APIs de conversação: Permitir a consulta de dados em linguagem natural em aplicações, chatbots e frameworks de agentes de IA. Estas APIs suportam conversas com estado onde os utilizadores podem fazer perguntas de seguimento e explorar dados de forma natural ao longo do tempo.
APIs de gestão: Permitir a criação, configuração e implementação programática de espaços Genie em vários espaços de trabalho. Use estas APIs para pipelines CI/CD, controlo de versões e gestão de espaço automatizada.

Esta página descreve tanto APIs de conversação como de gestão. Antes de chamar as APIs de conversação, prepare um espaço-Genie cuidadosamente preparado. O espaço fornece o contexto que o Génio usa para interpretar perguntas e gerar respostas. Se o espaço estiver incompleto ou não testado, os utilizadores podem ainda assim receber resultados incorretos mesmo com uma integração correta da API. Este guia explica a configuração mínima necessária para criar um espaço que funcione eficazmente com a API do Genie.

Pré-requisitos

Para usar a API do Genie, deve ter:

Acesso a um espaço de trabalho do Azure Databricks com a permissão Databricks SQL.
Pelo menos PODE USAR privilégios em um SQL pro ou SQL warehouse sem servidor.

Como Começar

Configurar autenticação 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, utilize um principal de serviço para autenticar com a API. Consulte 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 SQL warehouses.

Recolha detalhes

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

Exemplo: https://cust-success.cloud.databricks.com/
ID do armazém: Precisa do ID de um armazém SQL onde tem pelo menos privilégios de utilizar. Para encontrar o ID do seu armazém:
1. Vai a SQL Warehouses no teu espaço de trabalho.
2. Seleciona o armazém que queres usar.
3. Copie o ID do armazém a partir do URL ou da página de detalhes do armazém.
Alternativamente, usa o endpoint GET /api/2.0/sql/warehouses para recuperar programaticamente uma lista de todos os warehouses SQL aos quais tens permissões de acesso. A resposta inclui o ID do armazém.

Criar ou selecionar um espaço Génio

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

Utiliza dados bem anotados: O Genie baseia-se em metadados de tabelas e comentários nas colunas. Verifique se as suas fontes de dados do Unity Catalog têm comentários claros e descritivos.
É testado pelos utilizadores? Teste o seu espaço fazendo perguntas que espera dos utilizadores finais. Use testes para criar e refinar exemplos de consultas SQL.
Inclui contexto específico da empresa: Adicione instruções, exemplos de SQL e funções. Consulte Adicionar exemplos e instruções SQL. Procura pelo menos cinco consultas SQL de exemplo testadas.
Utiliza benchmarks para testar a precisão: Adicione pelo menos cinco perguntas de benchmark com base nas perguntas antecipadas dos utilizadores. Veja Utilizar benchmarks num espaço Genie.

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

Podes criar um novo espaço Genie ou usar um existente:

Criar um novo espaço

Crie um espaço Genie programaticamente usando a API Create Genie space. O exemplo seguinte 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\"]}]},\"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"
}

Utilizar um espaço existente

Se já tens um espaço Genie, podes encontrar o ID do espaço usando a API List Genie Spaces. Você também pode encontrar e copiar o ID do Espaço no separador 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>",
    }
  ]
}

Utilize a space_id da resposta em chamadas subsequentes à API.

Compreender o campo serialized_space

O serialized_space campo é uma string JSON que define a configuração e as fontes de dados para o seu espaço Genie. No pedido da API, este JSON deve ser convertido numa string. O campo contém:

versão: Versão Schema (atualmente 1)
config: Configuração de espaço incluindo:
- sample_questions: Perguntas de exemplo para orientar os utilizadores. Cada pergunta exige:
  - id: Um identificador único para a pergunta. Pode gerar qualquer cadeia única (como cadeias alfanuméricas curtas ou UUIDs). O sistema normaliza estes para identificadores de 32 caracteres.
  - pergunta: Um array contendo o texto da pergunta.
  Inclua pelo menos cinco perguntas diversas que representem casos de uso comuns.
data_sources: Fontes de dados disponíveis para o espaço, incluindo:
- tabelas: Array de objetos de tabela em 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 contendo texto de descrição da tabela.
  - column_configs: Opcional. Array de objetos de configuração de colunas com:
    - column_name: O nome da coluna.
    - get_example_values: Booleano. Se deve amostrar exemplos de valores desta coluna.
    - build_value_dictionary: Booleano. Se deve construir um dicionário de valores para colunas categóricas.
instruções: Opcionais. Instruções estruturadas para o espaço incluindo:
- text_instructions: Instruções de texto para o espaço.
- example_question_sqls: Array de exemplos de objetos de consulta SQL.
- join_specs: Array que define 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 criação de espaço é a seguinte:

{
  "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 o seu espaço, crie esta estrutura JSON e depois faça o escape dela como uma string para o pedido da API. Para detalhes completos do esquema, consulte a referência da API Create Genie Space.

Utilização da API de conversação

Depois de configurar um espaço Genie, usa os endpoints da API de conversas para colocar questões, recuperar resultados e manter conversações sustentadas com contexto.

Iniciem uma conversa

O endpoint Iniciar conversaPOST /api/2.0/genie/spaces/{space_id}/start-conversation inicia uma nova conversa no seu espaço Genie.

Substitua os marcadores de posição pela sua instância do Databricks, ID do espaço do Genie e 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 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} os detalhes completos da solicitação e da resposta.

Observação

Só POST as solicitações contam para o limite de consultas por minuto. GET Os pedidos utilizados para sondar os resultados não estão sujeitos a este 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 status campo é COMPLETED a resposta é preenchida attachments na matriz.

Recuperar resultados da consulta

A attachments matriz contém a resposta de 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 associados (attachment_id). Substitua os marcadores no exemplo a seguir para obter os resultados gerados da consulta.

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 seguimento

Depois de receber uma resposta, use o conversation_id para continuar a conversa. O contexto das mensagens anteriores é retido 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 espaço e dados de conversa

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

Obter configuração de espaço

Ao recuperar informação sobre o espaço usando a API Get Genie Space, pode incluir o campo serialized_space na resposta, definindo o parâmetro include_serialized_space para true. O serialized_space campo contém a representação em cadeia serializada do espaço Genie, incluindo instruções, benchmarks, joins e outros detalhes de configuração.

Utilize esta representação serializada com a API Create Genie Space e Update Genie Space API para promover espaços Genie entre espaços de trabalho ou criar cópias de segurança de configurações espaciais.

Exemplo GET de pedido:

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\"]}]}}}"
}

Fazer referência a tópicos de conversa antigos

Para permitir que os usuários façam referência a conversas antigas, use o ponto de extremidadeGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages Listar mensagens de conversa para recuperar todas as mensagens de um thread de conversa específico.

Recuperar dados de conversação para análise

Os gerentes 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 tópicos de conversa existentes em um espaço.
Para cada ID de conversa retornado, use o GET /api/2.0/genie/spaces/{space_id}/conversations ponto de extremidade para recuperar a lista de mensagens dessa conversa.

Boas práticas e limites

Boas práticas para usar a API do Genie

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

Implemente a lógica de nova tentativa com backoff exponencial: A API não repete pedidos falhados por si, por isso adicione a sua própria fila de espera e backoff exponencial. Isto ajuda a sua aplicação a lidar com falhas transitórias, evitar pedidos repetidos desnecessários e manter-se dentro dos limites de throughput à medida que cresce.
Registos das respostas da API: Implemente registos abrangentes dos pedidos e respostas da API para ajudar na resolução de problemas, monitorizar os padrões de utilização e acompanhar os custos.
Sondagem para atualizações de status a cada 1 a 5 segundos: Continue a sondagem até que um status de mensagem conclusivo, como COMPLETED, FAILEDou CANCELLED, seja recebido. Limite a sondagem a 10 minutos para a maioria das consultas. Se não houver uma resposta conclusiva após 10 minutos, pare 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 sondagens: Aumente o atraso entre sondagens até um máximo de um minuto. Isto reduz pedidos desnecessários para consultas de longa duração, permitindo ainda assim 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 não intencional do contexto.
Mantenha os limites de conversação: 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 tópicos 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.
Esteja atento ao limite de resultados de consulta: A API Genie devolve 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 focar num subconjunto específico de dados ou usar filtros para restringir os resultados.

Limite de taxa de transferência

Durante o período de Pré-visualização Pública, as taxas de rendimento para o nível gratuito 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 os pedidos a 5 consultas por minuto por espaço de trabalho. Durante os períodos de maior utilização, o sistema processa pedidos com base na capacidade disponível, o que pode resultar em menor rendimento.

Monitorize o espaço

Depois que seu 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 receberão. 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 Monitorizar o espaço.

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

Feedback

Esta página foi útil?

Last updated on 2025-12-19