将 Genie 空间资源添加到 Databricks 应用

将 AI/BI Genie 空间 添加为 Databricks Apps 资源，以便在应用程序中启用自然语言查询。 Genie spaces 提供用于数据探索的对话界面，允许用户以纯英语提问业务问题，并从特选数据集接收基于 SQL 的见解。

将 Genie 空间添加为资源时，应用可以：

• 将自然语言查询从用户转换为 SQL
• 访问预配置的业务上下文和元数据
• 使用特选的示例查询和数据定义
• 根据组织的数据集生成响应

添加 Genie 空间资源

在将 Genie 空间添加为应用资源之前，请查看 资源先决条件。

1. 在创建或编辑应用时，在 “应用资源 ”部分中，单击“ + 添加资源”。
2. 选择 Genie 空间 作为资源类型。
3. 从工作区中的可用空间列表中选择一个 Genie 空间。
4. 选择应用的权限级别：
   • 可以查看： 授予应用读取 Genie 空间配置和元数据的权限。
   • 可以运行： 授予应用将查询提交到 Genie 空间并接收响应的权限。
   • 可以编辑： 授予应用修改 Genie 空间配置的权限。
   • 可以管理： 授予应用对 Genie 空间的完全管理访问权限。
5. （可选）指定自定义资源密钥，即在应用配置中引用 Genie 空间的方式。 默认键为 genie-space.

添加 Genie 空间资源时：

• Azure Databricks 向应用 的服务主体 授予所选 Genie 空间的指定权限。
• 应用可以将自然语言查询提交到空间，并使用 SQL 查询和结果接收结构化响应。
• 应用访问空间的特选业务上下文，包括元数据、示例查询和数据定义。
• 访问权限仅限于所选空间。 除非将其他 Genie 空间添加为单独的资源，否则你的应用无法访问其他 Genie 空间。

环境变量

使用 Genie 空间资源部署应用时，Azure Databricks 通过可以使用配置中的valueFrom字段引用的app.yaml环境变量公开空间 ID。

示例配置：

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space # Use your custom resource key if different

在应用程序中使用空间 ID：

import os
from databricks.sdk import WorkspaceClient

# Access the Genie space using the injected environment variable
space_id = os.getenv("GENIE_SPACE_ID")

# Initialize the workspace client
w = WorkspaceClient()

# Start a conversation with a natural language query
response = w.genie.start_conversation_and_wait(
    space_id=space_id,
    content="What were our top-selling products last quarter?"
)

# Process the response (responses contain attachments with text, queries, and so on)
for attachment in response.attachments:
    print(f"Genie response: {attachment.text.content}")

# Continue the conversation with additional questions
follow_up = w.genie.create_message_and_wait(
    space_id=space_id,
    conversation_id=response.conversation_id,
    content="Can you break that down by product category?"
)

有关详细信息，请参阅从资源访问环境变量。

删除 Genie 空间资源

从应用中删除 Genie 空间资源时，应用的服务主体将失去对空间的访问权限。 Genie 空间本身保持不变，并继续可供具有适当权限的其他用户和应用程序使用。

将 Genie 空间与其他应用资源相结合

将 Genie 空间与其他 Databricks 应用资源相结合，以创建更复杂的数据应用程序。 常见的集成模式包括：

自然语言分析仪表板

结合使用以下资源来运行交互式分析：

• Genie 空间： 将用户问题转换为 SQL 查询
• SQL 仓库： 运行查询并返回用于可视化的结果
• 秘密： 存储外部可视化工具的 API 密钥

示例配置：

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space
  - name: SQL_WAREHOUSE_ID
    valueFrom: sql-warehouse
  - name: EXTERNAL_API_KEY
    valueFrom: viz-secret

AI 增强型商业智能

使用以下资源与 AI 模型集成：

• Genie 空间： 生成初始查询和数据上下文
• 模型服务终结点： 返回 AI 生成的摘要和建议
• SQL 仓库： 运行复杂的分析查询

服务主体权限

与其他应用资源集成时，向应用的服务主体授予以下权限：

• CAN RUN 在 Genie 空间上
• CAN USE 在 SQL 仓库（如果使用与 Genie 空间分开）
• CAN QUERY 在模型服务终结点上
• USE CATALOG 以及 USE SCHEMA 相关 Unity 目录对象
• SELECT 直接对应用查询的表

最佳做法

使用 Genie 空间资源时，请遵循以下最佳做法：

• 授予最小权限。 仅提供对应用需要运行的特定 Genie 空间的访问权限。
• 确保 Genie 空间包含精心策划的数据集和元数据，以提高自然语言查询响应的质量。
• 针对 Genie 空间测试应用的查询，以验证它是否可以为预期的用户问题生成准确的结果。
• 监视查询性能，并使用 Genie 空间调整应用的交互模式，以优化响应时间。
• 对于 Genie 空间无法有效解释或响应用户查询的情况，实现错误处理。