Использование API Genie Spaces

Интеграция Genie Spaces с собственным чат-ботом, агентом или приложением с API Genie Spaces. API включает API для диалогов, предназначенные для запросов к данным на естественном языке с сохранением состояния (с поддержкой уточняющих вопросов и сохранением истории), а также API управления для конвейеров CI/CD, которые создают, настраивают и развертывают Genie Spaces в разных рабочих пространствах.

Обзор

API Genie предоставляет два типа возможностей:

  • API для диалогов: обеспечение возможности выполнения запросов на естественном языке в приложениях, чат-ботах и платформах агентов ИИ. Эти API поддерживают беседы с отслеживанием состояния, в которых пользователи могут задавать вопросы и изучать данные естественным образом с течением времени.
  • API управления: обеспечивает программное управление созданием, настройкой и развертыванием Genie Spaces в рабочих пространствах. Используйте эти API для конвейеров CI/CD, управления версиями и автоматического управления пространствами.

На этой странице описаны API беседы и управления. Перед вызовом API беседы подготовьте хорошо курируемое пространство Genie. Пространство предоставляет контекст, который Genie использует для интерпретации вопросов и создания ответов. Если пространство не завершено или не протестировано, пользователи по-прежнему могут получать неправильные результаты даже при правильной интеграции API. В этом руководстве объясняется минимальная настройка, необходимая для создания пространства, которое эффективно работает с API Genie.

Примеры на этой странице используют REST API напрямую. Вы также можете вызвать эти API с помощью пакетов SDK Azure Databricks. См. Databricks SDK.

Предпосылки

Чтобы использовать API Genie, необходимо:

  • Доступ к рабочей области Azure Databricks с правами Databricks SQL.
  • По крайней мере, МОЖНО ИСПОЛЬЗОВАТЬ привилегии в хранилище SQL Pro или бессерверного хранилища SQL.

Начало работы

Настройка проверки подлинности Azure Databricks

В рабочих случаях использования, когда пользователь с доступом к браузеру присутствует, используйте OAuth для пользователей (OAuth U2M). В ситуациях, когда аутентификация через браузер невозможна, используйте учетную запись службы для аутентификации с помощью API. См. OAuth для служебных учетных записей (OAuth M2M). Субъекты-службы должны иметь разрешения на доступ к необходимым данным и хранилищам SQL.

Сбор сведений

  • Имя экземпляра рабочей области: найдите и скопируйте имя экземпляра рабочей области из URL-адреса рабочей области Databricks. Дополнительные сведения об идентификаторах рабочей области в URL-адресе см. в статье "Получение идентификаторов для объектов рабочей области".

    Пример: https://cust-success.cloud.databricks.com/

  • Идентификатор хранилища. Вам нужен идентификатор хранилища SQL, на который у вас есть по крайней мере права CAN USE. Чтобы найти идентификатор хранилища, выполните следующие действия.

    1. Перейдите в хранилища SQL в рабочей области.
    2. Выберите хранилище, которое вы хотите использовать.
    3. Скопируйте идентификатор хранилища из URL-адреса или страницы сведений о хранилище.

    Кроме того, используйте конечную точку "List warehouses"GET /api/2.0/sql/warehouses для программного получения списка всех SQL-складов, к которым у вас есть разрешения на доступ. Ответ содержит идентификатор хранилища.

Создание или выбор пространства Genie

Хорошо структурированное Пространство Genie имеет следующие характеристики:

  • Использует хорошо аннотированные данные: Genie использует метаданные таблицы и комментарии к столбцам. Убедитесь, что источники данных каталога Unity имеют четкие описательные комментарии.
  • Тестируется ли пользователь: проверьте пространство, задав вопросы, которые ожидаются от конечных пользователей. Используйте тестирование для создания и уточнения примеров запросов SQL.
  • Включает контекст для конкретной компании: добавление инструкций, примеры SQL и функций. См. примеры и инструкции по добавлению SQL. Стремитесь по крайней мере к пяти тестируемым примерам SQL-запросов.
  • Использует тесты для проверки точности: добавьте по крайней мере пять вопросов теста на основе ожидаемых вопросов пользователей. См. тесты производительности.

Дополнительные сведения о создании пространства см. в статьях Создание пространства Genie и управление им и Подготовка эффективного пространства Genie.

Вы можете создать новое пространство Genie или использовать существующий:

Создание нового пространства

Создайте пространство Genie программным способом с помощью API создания пространства Genie. В следующем примере демонстрируется хорошо структурированная структура, которая следует наилучшим практикам. Замените заполнители вашими данными.

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

Использование существующего пространства

Если у вас уже есть пространство Genie, вы можете найти идентификатор пространства с помощью API List Genie Spaces. Вы также можете найти и скопировать идентификатор пространства на вкладке "Параметры пространства 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>",
    }
  ]
}

Используйте space_id из ответа в последующих вызовах API.

Общие сведения о поле serialized_space

Поле serialized_space — это строка JSON, которая определяет конфигурацию и источники данных для пространства Genie. В запросе API этот КОД JSON должен быть экранирован в виде строки. Поле содержит следующее:

  • версия: номер версии схемы для обратной совместимости. Используйте 2 , как показано в приведенном ниже примере.
  • конфигурация: конфигурация пространства, в том числе:
    • sample_questions. Примеры вопросов, которые помогут пользователям. Для каждого вопроса требуется идентификатор (32-символьная шестнадцатеричная строка) и вопрос (массив строк).
  • data_sources: источники данных, доступные для пространства:
    • таблицы: массив объектов таблиц с идентификатором (трехуровневое пространство имен), необязательным описанием и необязательным column_configs.
    • metric_views: массив объектов представления метрик (та же структура, что и таблицы).
  • инструкции: структурированные инструкции для пространства:
    • text_instructions: общие рекомендации по LLM.
    • example_question_sqls. Примеры вопросов с ответами SQL, при необходимости с параметрами и usage_guidance.
    • sql_functions. Ссылки на функции SQL, доступные для пространства.
    • join_specs: предопределенные связи соединения между таблицами. Для sql поля требуются ровно два элемента: условие соединения, с использованием ссылок с алиасами, окружёнными обратными кавычками, а также аннотация типа связи, например "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--". См. формат спецификаций подключения.
    • sql_snippets: многократно используемые фильтры, выражения и меры.
  • контрольные показатели: вопросы по оценке качества пространства, каждый из которых содержит истинное значение SQL ответ.

Неискаченная версия serialized_space поля из примера создания пространства выглядит следующим образом:

{
  "version": 2,
  "config": {
    "sample_questions": [
      {
        "id": "a1b2c3d4e5f60000000000000000000a",
        "question": ["What were total sales last month?"]
      },
      {
        "id": "b2c3d4e5f6a70000000000000000000b",
        "question": ["Show top 10 customers by revenue"]
      }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.customers",
        "description": ["Customer master data including contact information and account details"],
        "column_configs": [
          {
            "column_name": "customer_id",
            "description": ["Unique identifier for each customer"],
            "synonyms": ["cust_id", "account_id"]
          },
          {
            "column_name": "customer_name",
            "enable_entity_matching": true
          },
          {
            "column_name": "internal_notes",
            "exclude": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.orders",
        "description": ["Transactional order data including order date, amount, and customer information"],
        "column_configs": [
          {
            "column_name": "order_date",
            "enable_format_assistance": true
          },
          {
            "column_name": "region",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          },
          {
            "column_name": "status",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.products"
      }
    ],
    "metric_views": [
      {
        "identifier": "sales.analytics.revenue_metrics",
        "description": ["Pre-aggregated revenue metrics by region and time period"],
        "column_configs": [
          {
            "column_name": "period",
            "description": ["Time period for the metric (monthly, quarterly, yearly)"],
            "enable_format_assistance": true
          }
        ]
      }
    ]
  },
  "instructions": {
    "text_instructions": [
      {
        "id": "01f0b37c378e1c9100000000000000a1",
        "content": [
          "When calculating revenue, sum the order_amount column. ",
          "When asked about 'last month', use the previous calendar month. ",
          "Round all monetary values to 2 decimal places."
        ]
      }
    ],
    "example_question_sqls": [
      {
        "id": "01f0821116d912db00000000000000b1",
        "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": "01f099751a3a1df300000000000000b2",
        "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)"
        ]
      },
      {
        "id": "01f099751a3a1df300000000000000b3",
        "question": ["Show sales for a specific region"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE region = :region_name"
        ],
        "parameters": [
          {
            "name": "region_name",
            "type_hint": "STRING",
            "description": ["The region to filter by (e.g., 'North America', 'Europe')"],
            "default_value": {
              "values": ["North America"]
            }
          }
        ],
        "usage_guidance": ["Use this example when the user asks about sales filtered by a specific geographic region"]
      }
    ],
    "sql_functions": [
      {
        "id": "01f0c0b4e815100000000000000000f1",
        "identifier": "sales.analytics.fiscal_quarter"
      }
    ],
    "join_specs": [
      {
        "id": "01f0c0b4e815100000000000000000c1",
        "left": {
          "identifier": "sales.analytics.orders",
          "alias": "orders"
        },
        "right": {
          "identifier": "sales.analytics.customers",
          "alias": "customers"
        },
        "sql": ["`orders`.`customer_id` = `customers`.`customer_id`", "--rt=FROM_RELATIONSHIP_TYPE_MANY_TO_ONE--"],
        "comment": ["Join orders to customers on customer_id"],
        "instruction": ["Use this join when you need customer details for order analysis"]
      }
    ],
    "sql_snippets": {
      "filters": [
        {
          "id": "01f09972e66d100000000000000000d1",
          "sql": ["orders.order_amount > 1000"],
          "display_name": "high value orders",
          "synonyms": ["large orders", "big purchases"],
          "comment": ["Filters to orders over $1000"],
          "instruction": ["Use when the user asks about high-value or large orders"]
        }
      ],
      "expressions": [
        {
          "id": "01f09974563a100000000000000000e1",
          "alias": "order_year",
          "sql": ["YEAR(orders.order_date)"],
          "display_name": "year",
          "synonyms": ["fiscal year", "calendar year"],
          "comment": ["Extracts the year from order date"],
          "instruction": ["Use for year-over-year analysis"]
        }
      ],
      "measures": [
        {
          "id": "01f09972611f100000000000000000f1",
          "alias": "total_revenue",
          "sql": ["SUM(orders.order_amount)"],
          "display_name": "total revenue",
          "synonyms": ["revenue", "total sales"],
          "comment": ["Sum of all order amounts"],
          "instruction": ["Use this measure for revenue calculations"]
        }
      ]
    }
  },
  "benchmarks": {
    "questions": [
      {
        "id": "01f0d0b4e815100000000000000000g1",
        "question": ["What is the average order value?"],
        "answer": [
          {
            "format": "SQL",
            "content": ["SELECT AVG(order_amount) as avg_order_value\n", "FROM sales.analytics.orders"]
          }
        ]
      }
    ]
  }
}

При создании пространства создайте эту структуру JSON и преобразуйте её в строку для запроса API. Для получения полных сведений о схеме см. справочник по API Create Genie Space.

Правила проверки для serialized_space

JSON serialized_space должен соответствовать следующим правилам проверки. Неверный JSON отклоняется при создании или обновлении пространства.

Версия

  • Поле версии: обязательно. Используйте 2 для новых пробелов. Номер версии существует для обратной совместимости.

Формат идентификатора

Все поля идентификатора должны быть 32-символьными шестнадцатеричными строками (формат UUID без дефисов).

  • Допустимо:a1b2c3d4e5f60000000000000000000a
  • Недопустимый: a1b2c3d4e5f6 (слишком короткий), A1B2C3D4E5F60000000000000000000A (верхний регистр), a1b2c3d4-e5f6-0000-0000-00000000000a (содержит дефисы)

Идентификаторы необходимы для:

  • config.sample_questions[].id
  • instructions.text_instructions[].id
  • instructions.example_question_sqls[].id
  • instructions.join_specs[].id
  • instructions.sql_snippets.filters[].id
  • instructions.sql_snippets.expressions[].id
  • instructions.sql_snippets.measures[].id
  • benchmarks.questions[].id (если бенчмарки включены)

Для создания допустимого идентификатора можно использовать следующую команду:

python3 -c "import random,datetime;t=int((datetime.datetime.now()-datetime.datetime(1582,10,15)).total_seconds()*1e7);print(f'{(t&0xFFFFFFFFFFFF0000)|(1<<12)|((t&0xFFFF)>>4):016x}{random.getrandbits(62)|0x8000000000000000:016x}')"

При этом создается упорядоченный по времени идентификатор UUID. Идентификаторы, созданные последовательно, автоматически сортируются в алфавитном порядке, что соответствует требованиям сортировки.

Требования к сортировке

Коллекции, содержащие ID или идентификаторы, должны быть предварительно отсортированы. Система проверяет, что массивы уже отсортированы и отклоняют несортированные входные данные.

Коллекция Ключ сортировки
data_sources.tables identifier (в алфавитном порядке)
data_sources.metric_views identifier (в алфавитном порядке)
data_sources.tables[].column_configs column_name (в алфавитном порядке)
data_sources.metric_views[].column_configs column_name (в алфавитном порядке)
config.sample_questions id (в алфавитном порядке)
instructions.text_instructions id (в алфавитном порядке)
instructions.example_question_sqls id (в алфавитном порядке)
instructions.sql_functions (id, identifier) кортеж (в алфавитном порядке)
instructions.join_specs id (в алфавитном порядке)
instructions.sql_snippets.filters id (в алфавитном порядке)
instructions.sql_snippets.expressions id (в алфавитном порядке)
instructions.sql_snippets.measures id (в алфавитном порядке)
benchmarks.questions id (в алфавитном порядке)

Ограничения уникальности

  • Идентификаторы вопросов: все идентификаторы в config.sample_questions и benchmarks.questions должны быть уникальными во всей совокупности обеих коллекций.
  • Идентификаторы инструкций: все идентификаторы среди text_instructions, example_question_sqls, sql_functions и join_specs и все типы sql_snippets должны быть уникальными.
  • Конфигурации столбцов: сочетание (table_identifier, column_name) должно быть уникальным в пространстве.

Ограничения размера и длины

  • Длина строки: отдельные строковые элементы ограничены 25 000 символами.
  • Размер массива: повторяющиеся поля ограничены 10 000 элементами.
  • Текстовые инструкции. Для каждого пространства допускается не более 1 текстовой инструкции.
  • Таблицы и представления метрик: при условии ограничений, относящихся к рабочей области.
  • Содержимое SQL: текст запроса в sql полях join_specs.sql зависит от ограничений длины.

Формат объединения спецификаций

Поле в каждой sql спецификации соединения должно содержать ровно два элемента:

  1. Условие соединения с использованием псевдонимов, заключенных в обратные кавычки.

    "`orders`.`customer_id` = `customers`.`customer_id`"

  2. Заметка типа связи в следующем формате:

    "--rt=FROM_RELATIONSHIP_TYPE_<CARDINALITY>--"

    Допустимые значения кратности:

    • FROM_RELATIONSHIP_TYPE_MANY_TO_ONE
    • FROM_RELATIONSHIP_TYPE_ONE_TO_MANY
    • FROM_RELATIONSHIP_TYPE_ONE_TO_ONE
    • FROM_RELATIONSHIP_TYPE_MANY_TO_MANY

Пропуская заметку типа связи, API отклоняет запрос с ошибкой синтаксического анализа. Для соединений с несколькими столбцами создайте отдельную спецификацию соединения для каждой связи.

Другие требования

  • Идентификаторы таблиц: необходимо использовать трехуровневый формат пространства имен (catalog.schema.table).
  • Ответы на тесты. Каждый вопрос теста должен иметь ровно один ответ с форматом, заданным в SQL.
  • Фрагменты КОДА SQL: фильтрация, выражение и измерение полей SQL не должны быть пустыми.

Использование API беседы

После настройки пространства Genie используйте конечные точки API бесед, чтобы задавать вопросы, получать результаты и поддерживать многоэтапные беседы с контекстом.

Запуск беседы

API-точка доступа Start conversationPOST /api/2.0/genie/spaces/{space_id}/start-conversation инициирует новую беседу в вашем пространстве Genie.

Замените заполнители экземпляром Databricks, идентификатором пространства Genie и маркером проверки подлинности. Пример успешного ответа приводится после запроса. В ней содержатся сведения, которые можно использовать для повторного доступа к этой беседе для дальнейших вопросов.

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

Получить созданный SQL

Используйте conversation_id и message_id в ответе, чтобы проверить статус генерации сообщения и получить созданный SQL от Genie. Подробные сведения о запросе и ответе см. в разделе GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} "Полный запрос и ответ".

Замечание

Только POST запросы учитываются для учета пропускной способности по запросам в минуту. Запросы GET, используемые для опроса результатов, не подлежат этому ограничению.

Подставьте свои значения в следующий запрос:

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

Следующий пример ответа сообщает сведения о сообщении:

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
}

Поле attachments постепенно заполняется во время обработки. Если состояние равно PENDING_WAREHOUSE или EXECUTING_QUERY, вы уже можете начать чтение attachments поля. Ответ заполняется постепенно, начиная с созданного SQL-запроса, за которым следует описание, дальнейшие вопросы и дополнительный контекст. Состояние COMPLETED указывает, что процесс ответа полностью завершен и опрос может остановиться, но понятное содержимое доступно ранее, если клиент проверяет ответ во время опроса, а не ожидает завершения.

Чтобы определить, был ли ответ создан с помощью доверенного ресурса, проверьте attachments поле в ответе на query.parameters объект. Его присутствие указывает, что ответ пришел из надежного источника.

Чтобы получить доступ к трассировкам вывода Genie, проверьте в attachments поле наличие query_attachments объекта типа GenieQueryAttachments. При наличии он содержит пошаговое обоснование, использованное Genie для создания ответа. Полные сведения о поле см. в справочнике по API по получению сообщений.

Получение результатов запроса

Массив attachments содержит ответ Genie. Он включает созданный текстовый ответ (), инструкцию запроса, если она существует (textquery), и идентификатор, который можно использовать для получения связанных результатов запроса (attachment_id). Замените заполнители в следующем примере, чтобы получить созданные результаты запроса:

Замечание

API бесед Genie возвращает табличные результаты запроса в виде структурированных данных. Она не возвращает отрисованные диаграммы или визуализации. Чтобы отобразить диаграммы, получите результаты запроса из attachment_id приложения и отрисуйте их в приложении с помощью выбранной библиотеки диаграмм. Поле query в вложении содержит SQL, созданный Genie, который вы можете также запустить прямо в вашем хранилище, чтобы получить результаты для визуализации.

Замечание

В отличие от пользовательского интерфейса Genie Spaces, API бесед Genie не поддерживает двухфазный шаблон ответа, где Genie отображает предварительный ответ, а затем обновляет его после проверки. Чтобы показывать пользователям промежуточный прогресс, проверяйте поле attachments при опросе в состояниях PENDING_WAREHOUSE или EXECUTING_QUERY вместо того, чтобы ждать COMPLETED.

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

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

Уточняйте вопросы

После получения ответа используйте conversation_id для продолжения беседы. Контекст из предыдущих сообщений сохраняется и используется в последующих ответах. Полные сведения о запросе и ответе см. в разделе 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?",
}

Добавление комментариев в сообщения

Вы можете добавлять текстовые примечания в сообщения и перечислять существующие комментарии с помощью конечных точек API комментариев сообщений.

Чтобы добавить комментарий к сообщению, используйте конечную точку API создания комментария к сообщениюPOST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments:

POST /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id}/comments
HOST= <DATABRICKS_INSTANCE>
Authorization: Bearer <your_authentication_token>
{
  "content": "<your comment text>"
}

Чтобы вывести список существующих комментариев в сообщении, используйте конечную точку комментариев списка сообщений.

Получение данных о пространстве и данных о беседе

API Genie предоставляет дополнительные точки доступа для получения конфигурации и исторических данных из существующих пространств и бесед.

Получение конфигурации пространства

При получении сведений о пространстве с помощью API Get Genie Space можно включить serialized_space поле в ответ, установив параметр include_serialized_space в значение true. Поле serialized_space содержит сериализованное строковое представление пространства Genie, включая инструкции, тесты, соединения и другие сведения о конфигурации.

Используйте это сериализованное представление с API создания пространства Genie и API обновления пространства Genie, чтобы продвигать пространства Genie среди рабочих областей или создавать резервные копии конфигураций пространства.

Пример 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>",
  "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\"]}]}}}"
}

Ссылка на старые потоки беседы

Чтобы разрешить пользователям ссылаться на старые потоки беседы, используйте конечную точку списка сообщений беседыGET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages для получения всех сообщений из определенного потока беседы.

Получение данных беседы для анализа

Менеджеры пространства могут с помощью программного обеспечения получить все предыдущие сообщения, запрашиваемые всеми пользователями, для анализа. Чтобы получить эти данные, выполните указанные ниже действия.

  1. Используйте конечную точку GET /api/2.0/genie/spaces/{space_id}/conversations, чтобы получить все существующие темы бесед в пространстве.
  2. Для каждого возвращенного идентификатора беседы используйте GET /api/2.0/genie/spaces/{space_id}/conversations конечную точку, чтобы получить список сообщений для этой беседы.

Рекомендации и ограничения

Рекомендации по использованию API Genie

Чтобы обеспечить производительность и надежность при использовании API Genie:

  • Реализуйте логику повторных попыток с экспоненциальной задержкой: API не повторяет неудачные запросы за вас, поэтому добавьте свою очередь и экспоненциальную задержку. Это помогает приложению обрабатывать временные сбои, избегать ненужных повторных запросов и оставаться в пределах ограничений пропускной способности по мере роста.
  • Журналирование ответов API. Реализуйте комплексное журналирование запросов и ответов API, чтобы помочь в отладке, мониторинге шаблонов использования и отслеживанию затрат.
  • Выполняйте опрос обновлений состояния каждые 1–5 секунд: продолжайте опрос, пока не будет получено окончательное состояние сообщения, например COMPLETED, FAILED или CANCELLED. Ограничение опроса до 10 минут для большинства запросов. Если после 10 минут нет единого ответа, остановите опрос и верните ошибку времени ожидания или предложите пользователю вручную проверить состояние запроса позже.
  • Используйте экспоненциальный откат для опроса: увеличьте задержку между опросами не более одной минуты. Это сокращает ненужные запросы для длительных запросов, сохраняя низкую задержку для быстрых запросов.
  • Запустите новую беседу для каждого сеанса: избегайте повторного использования потоков бесед в сеансах, так как это может снизить точность из-за непреднамеренного повторного использования контекста.
  • Соблюдение лимитов бесед: чтобы управлять старыми беседами и не превышать лимит в 10 000 бесед:
    1. Используйте конечную точку GET /api/2.0/genie/spaces/{space_id}/conversations для просмотра всех существующих потоков бесед в пространстве.
    2. Определите беседы, которые больше не нужны, например старые беседы или тестовые беседы.
    3. Используйте конечную точку DELETE /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id} для программного удаления бесед.

Рекомендации по пропускной способности

Скорость обработки для бесплатного уровня API бесед Genie зависит от емкости системы и предоставляется в меру возможностей. Чтобы устранить неправильное использование и предотвратить злоупотребление во время пиковых периодов использования, система обрабатывает запросы на основе доступной емкости. В обычных или низких условиях трафика API поддерживает запросы на пять вопросов в минуту на рабочую область. Если вы ищете более высокую поддержку пропускной способности, обратитесь к группе учетной записи Databricks.

Мониторинг пространства

После настройки приложения вы можете отслеживать вопросы и ответы в пользовательском интерфейсе Databricks.

Попросите пользователей протестировать пространство, чтобы узнать о типах вопросов, которые они могут задавать и ответы, которые они получают. Предоставьте пользователям рекомендации , чтобы помочь им начать тестирование пространства. Используйте вкладку "Мониторинг" для просмотра вопросов и ответов. См. раздел "Мониторинг пространства".

Журналы аудита также можно использовать для мониторинга действий в пространстве Genie. См. события Genie Space.

  • Last updated on