使用 Genie API 将 Genie 集成到应用程序中

本页介绍如何使用 Genie API 在自己的聊天机器人、代理或应用程序中启用 Genie 功能。

概述

Genie API 提供两种类型的功能：

聊天 API：在应用程序、聊天机器人和 AI 代理框架中启用自然语言数据查询。这些 API 支持有状态对话，用户可在其中提问跟进问题并随时间推移自然地浏览数据。
管理 API：通过编程在跨工作区中创建、配置和部署 Genie Spaces。将这些 API 用于 CI/CD 管道、版本控制和自动化空间管理。

本页介绍聊天和管理 API。在调用对话 API 之前，请准备精心策划的 Genie Space。空间提供 Genie 用于解释问题和生成答案的上下文。如果空间不完整或未测试，用户仍可能会收到不正确的结果，即使 API 集成正确。本指南介绍了创建有效与 Genie API 配合使用的空间所需的最低设置。

此页上的示例直接使用 REST API。还可以使用 Azure Databricks SDK 调用这些 API。请参阅 Databricks SDK。

先决条件

若要使用 Genie API，必须具备：

使用 Databricks SQL 授权访问 Azure Databricks 工作区。
至少可以对 SQL 专业或无服务器 SQL 仓库使用特权。

入门指南

配置Azure Databricks身份验证

对于存在具有浏览器访问权限的用户的生产用例，请使用用户的 OAuth (OAuth U2M)。如果无法进行基于浏览器的身份验证，请使用服务主体通过 API 进行身份验证。请参阅适用于服务主体的 OAuth（OAuth M2M）。服务主体必须有权访问所需的数据和 SQL 仓库。

收集详细信息

工作区实例名称：从 Databricks 工作区 URL 查找和复制工作区实例名称。有关 URL 中工作区标识符的详细信息，请参阅获取工作区对象的标识符。

示例： https://cust-success.cloud.databricks.com/
仓库 ID：需要至少具有 CAN USE 权限的 SQL 仓库的 ID。要查找您的仓库 ID，请执行以下操作：
1. 转到工作区中的 SQL 仓库 。
2. 选择要使用的仓库。
3. 从 URL 或仓库详细信息页复制仓库 ID。
或者，使用列表仓库终结点GET /api/2.0/sql/warehouses 以编程方式检索你有权访问的所有 SQL 仓库的列表。响应包括仓库 ID。

创建或选择Genie Space

结构良好的 Genie Space 具有以下特征：

使用批注良好的数据：Genie 依赖于表元数据和列注释。验证 Unity 目录数据源是否具有明确的描述性注释。
用户是否经过测试：通过询问最终用户预期的问题来测试空间。使用测试创建和优化示例 SQL 查询。
包括特定于公司的上下文：添加说明、示例 SQL 和函数。请参阅 “添加 SQL 示例和说明”。力求确保至少有五个经过测试的示例 SQL 查询。
使用基准测试准确性：根据预期用户问题添加至少五个基准问题。请参阅 Genie Space 中的使用基准。

有关创建空间的详细信息，请参阅设置和管理 Genie Space 并建立有效的 Genie Space。

可以创建新的 Genie Space 或使用现有空间：

创建新空间

使用 Create Genie Space API 以编程方式创建 Genie Space。以下示例演示了一个结构良好的空间，该空间遵循最佳做法。将占位符替换为值：

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 Space，则可以使用列表 Genie Spaces API 找到空间 ID。还可以从“Genie 空间 设置” 选项卡查找和复制空间 ID。

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

在后续 API 调用中使用来自响应的space_id。

了解序列化空间字段

该 serialized_space 字段是一个 JSON 字符串，用于定义 Genie Space 的配置和数据源。在 API 请求中，此 JSON 必须转义为字符串形式。该字段包含：

版本：用于向后兼容性的架构版本号。使用 2，如以下示例所示。
配置：空间配置，包括：
- sample_questions：指导用户的示例问题。每个问题都需要 ID （32 个字符的十六进制字符串）和问题（字符串数组）。
data_sources：空间可用的数据源：
- 表：具有 标识符 （三级命名空间）、可选说明和可选 column_configs的表对象的数组。
- metric_views：指标视图对象的数组（与表相同）。
说明：空间的结构化说明：
- text_instructions：LLM 的高级指南。
- example_question_sqls：带有 SQL 答案的示例问题，可选参数和 使用指导。
- 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 请求的字符串。有关完整的架构详细信息，请参阅 “创建 Genie Space API 参考”。

serialized_space验证规则

serialized_space JSON 必须符合以下验证规则。创建或更新空间期间将拒绝不符合标准的 JSON。

版本

版本字段：必需。使用 2 用于新空间。版本号存在以实现向后兼容性。

ID 格式

所有 ID 字段必须是 32 个字符的小写十六进制字符串 （没有连字符的 UUID 格式）。

有效： a1b2c3d4e5f60000000000000000000a
无效： a1b2c3d4e5f6 （太短）、 A1B2C3D4E5F60000000000000000000A （大写）、 a1b2c3d4-e5f6-0000-0000-00000000000a （包含连字符）

ID 是必需的：

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 （如果包括基准）

可以使用以下命令生成有效的 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 按其创建的顺序自动排序，从而自动满足排序要求。

排序要求

必须预先排序包含 ID 或标识符的集合。系统验证数组是否已排序并拒绝未排序的输入。

Collection	排序键
`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` （按字母顺序）

唯一性约束

问题 ID：config.sample_questions 和 benchmarks.questions 中的所有 ID 必须在两个集合中都是唯一的。
指令 ID：跨 text_instructions、 example_question_sqls、 sql_functions、 join_specs和所有类型的 sql_snippets ID 必须是唯一的。
列配置：所组合的 (table_identifier, column_name) 在空间中必须是唯一的。

大小和长度限制

字符串长度：单个字符串元素限制为 25,000 个字符。
数组大小：重复字段限制为 10,000 个项。
文本说明：每个空间最多允许 1 个文本指令。
表和指标视图：受工作区特定限制的影响。
SQL 内容：sql 和 join_specs.sql 字段中的查询文本受长度限制。

联接规范格式

sql每个联接规范中的字段必须正好包含两个元素：

使用带反引号的别名引用作为联接条件：

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

关于关系类型的注释，格式如下：
```
"--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 Space 后，使用会话 API 终结点提问、检索结果，以及使用上下文维护多轮次对话。

启动对话

“开始对话”终结点POST /api/2.0/genie/spaces/{space_id}/start-conversation将在 Genie Space 中启动一个新的对话。

将占位符替换为 Databricks 实例、Genie Space ID 和身份验证令牌。在请求之后，是一个成功响应的示例。其中包括可用于再次访问此对话的详细信息，以便跟进问题。

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 以轮询消息的生成状态，并从 Genie 检索生成的 SQL。请参阅 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
}

当status字段是COMPLETED时，响应被填充到attachments数组中。

若要确定是否使用受信任的资产生成了响应，请在响应中检查 attachments 字段是否有 query.parameters 对象。其存在表明答案来自受信任的资产。

若要访问 Genie 的推理跟踪，请检查attachments字段中query_attachments类型的GenieQueryAttachments对象。在存在的情况下，它包含 Genie 用于生成响应的逐步推理过程。有关完整的字段详细信息，请参阅获取消息 API 参考。

检索查询结果

数组 attachments 包含 Genie 的响应。它包括生成的文本响应（text）、查询语句（如果存在query）以及可用于获取关联查询结果的标识符（attachment_id）。替换以下示例中的占位符以检索生成的查询结果：

注释

Genie 对话 API 将表格查询结果作为结构化数据返回。它不返回呈现的图表或可视化效果。若要显示图表，请使用所选图表库从 attachment_id 应用程序中检索查询结果并将其呈现在应用程序中。 query附件中的字段包含 Genie 生成的 SQL，还可以直接针对仓库运行，以检索结果以供可视化。

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 终结点向消息添加文本注释并列出现有注释。

若要向消息添加注释，请使用 “创建消息注释”终结点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>
{
  "comment": "<your comment text>"
}

若要列出消息上的现有注释，请使用列表消息注释终结点。

检索空间和对话数据

Genie API 提供了额外的端点，用于从已有空间和对话中检索配置和历史数据。

检索空间配置

使用 Get Genie Space API 检索空间信息时，可以通过将serialized_space参数设置为include_serialized_space来在响应中包含true字段。该 serialized_space 字段包含 Genie Space 的序列化字符串表示形式，包括说明、基准测试、联接和其他配置详细信息。

将此序列化表示形式与 Create Genie Space API 和 Update Genie Space API 配合使用，以跨工作区提升 Genie Spaces 或创建空间配置的备份。

示例 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 从特定会话线程检索所有消息。

检索对话数据进行分析

空间管理器可以以编程方式检索空间中所有用户所请求的所有历史消息进行分析。检索此数据：

使用 GET /api/2.0/genie/spaces/{space_id}/conversations 终结点获取空间中的所有现有会话线程。
对于返回的每个会话 ID，请使用 GET /api/2.0/genie/spaces/{space_id}/conversations 终结点检索该会话的消息列表。

最佳做法和限制

使用 Genie API 的最佳做法

在使用 Genie API 时保持性能和可靠性：

使用指数退避实现重试逻辑：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} 终结点以编程方式删除对话。
请注意查询结果限制：Genie API 为每个查询结果返回最多 5,000 行。如果数据分析需要更多行，请考虑优化问题以专注于特定数据子集，或使用筛选器缩小结果范围。

吞吐量注意事项

Genie 会话 API 免费层的吞吐量速率是尽力而为的，取决于系统容量。为了缓解滥用并在高峰使用期间防止滥用，系统会根据可用容量处理请求。在正常或低流量条件下，API 支持每个工作区每分钟请求 5 个问题。如果要寻求更高的吞吐量支持，请联系 Databricks 帐户团队。

监视空间

设置应用程序后，可以在 Databricks UI 中监视问题和响应。

鼓励用户测试空间，以便了解他们可能提出的问题类型以及他们收到的回复。为用户提供指导，帮助他们开始测试空间。使用“ 监视 ”选项卡查看问题和答复。请参阅监视空间。

还可以使用审核日志监视 Genie Space 中的活动。请参阅 Genie Space 事件。

反馈

此页面是否有帮助？

Last updated on 2026-05-03