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

重要

此功能目前以公共预览版提供。

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

概述

Genie API 使开发人员能够将自然语言数据查询集成到应用程序、聊天机器人和 AI 代理框架中。它支持有状态对话，允许用户在一段时间内提出跟进问题并更自然地浏览数据。使用 Genie API，可以将自然语言查询集成到工具和工作流中，使整个组织中的数据更易于访问。

使用 API 之前，必须准备好精心策划的 Genie 空间。空间定义 Genie 用来解释问题和返回结果的上下文。如果空间不完整或未经测试，则即使 API 集成本身成功，用户也可能会收到大量不正确的答案。本指南概述了创建有效使用 Genie API 的空间所需的最低设置。

先决条件

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

使用 Databricks SQL 权利访问 Azure Databricks 工作区。
至少可以对 SQL 专业或无服务器 SQL 仓库使用特权。
熟悉 Databricks REST API 参考。

步骤 1：创建并测试 Genie 空间

准备一个能够高度准确回答用户问题的Genie空间。

注释

即使计划使用 API 查询 Genie 空间，也必须使用 Azure Databricks UI 设置和优化空间。

使用以下资源，来帮助配置和管理“Genie 空间”。

设置 Genie 空间： 了解如何使用 Azure Databricks UI 创建 Genie 空间。本文包含有关使用 UI 工具创建工作 Genie 空间的分步指南。
查看最佳做法： 了解策展新 Genie 空间的最佳做法。本文提供了有关如何创建新 Genie 空间的方法建议，以及如何通过测试和反馈优化并反复改进空间。
设置基准： 准备可运行的基准测试问题，以衡量 Genie 的响应准确性。

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

使用带批注的数据： Genie 依赖于表元数据和列注释来生成响应。 Genie 空间的 Unity 目录数据源应包含清晰和描述性的注释。
是否经过用户测试：你应该是你空间的第一个用户。通过询问最终用户期望的问题来测试空间。使用测试创建和优化示例 SQL 查询。
包括特定于公司的上下文： 你需要包含上下文来教授 Genie 关于公司数据和行话的信息。请参阅添加 SQL 示例和说明，了解如何添加说明、示例 SQL 和函数以处理常见问题。旨在包含至少 5 个经过测试和优化的示例 SQL 查询。
使用基准测试准确性： 根据最终用户预期的问题添加至少 5 个基准问题。运行基准测试，验证 Genie 是否准确回答这些问题。

如果对 Genie 空间中的响应感到满意，并且已使用代表性问题对其进行了测试，则可以开始将其与应用程序集成。

步骤 2：配置 Azure Databricks 身份验证

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

步骤 3：收集详细信息

使用 Genie 空间 URL 查找工作区实例名称和 Genie 空间 ID。以下示例演示如何在 URL 中查找这些组件。有关 URL 中工作区标识符的详细信息，请参阅获取工作区对象的标识符。

https://<databricks-instance>/genie/rooms/<space-id>

复制 <databricks-instance> 和 <space-id> 到 Genie 空间。还可以从“Genie 空间 设置” 选项卡中查找和复制空间 ID。

列出 Genie 空间

可以使用 space-id以编程方式检索用户有权访问的工作区中所有 Genie 空间的列表，而不是在 URL 中查找GET /api/2.0/genie/spaces。返回的 spaces 数组列出了每个 Genie 空间的说明、空间 ID 和标题。

步骤 4：启动对话

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

将占位符替换为 Databricks 实例、Genie 空间 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
  }
}

步骤 5：检索生成的 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数组中。

步骤 6：检索查询结果

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

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。

步骤 7：提出后续问题

收到响应后，请使用 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?",
}

引用和检索历史数据

Genie API 提供了用于管理现有对话和检索历史数据进行分析的其他终结点。

引用旧会话线程

若要允许用户引用旧的会话线程，请使用 “列出对话消息”终结点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 不管理请求重试。使用自己的队列系统并实现增量退避，以避免超出吞吐量限制。
每隔 1 到 5 秒轮询状态更新一次：继续轮询，直到收到明确的消息状态，例如COMPLETED、FAILED或CANCELLED。将大多数查询的轮询限制为 10 分钟。如果在 10 分钟后没有最终响应，请停止轮询并返回超时错误，或提示用户稍后手动检查查询状态。
使用指数退避： 将指数退避应用于轮询频率，将轮询间隔增加到最多 1 分钟。此方法有助于缩短查询延迟，同时提高运行时间较长的查询的可靠性。
为每个会话启动一个新的对话： 避免跨会话重复使用会话线程，因为这样可以减少由于意外的上下文重用而的准确性。
维护聊天限制： 若要管理旧对话并保持在 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 行。如果数据分析需要更多行，请考虑优化问题以专注于特定数据子集，或使用筛选器缩小结果范围。

监控空间

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

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

还可以使用审核日志监视 Genie 空间中的活动。请参阅 AI/BI Genie 事件。

吞吐量限制

在公共预览期间，Genie API 免费层的吞吐量速率遵循尽力而为原则，具体取决于系统容量。在正常或低流量条件下，API 将请求限制为每个工作区每分钟 5 个查询。在高峰使用期间，系统会根据可用容量处理请求，这可能会导致吞吐量降低。

Last updated on 2025-12-15

通过