將 Genie Space 資源加入 Databricks 應用程式

將 Genie Spaces 加入 Databricks Apps 資源，以啟用應用程式中的自然語言查詢功能。 Genie Spaces 提供對話式介面，讓使用者能用淺顯英文提出商業問題，並從您精心策劃的資料集中獲得基於 SQL 的洞見。

當你新增 Genie Space 作為資源時，你的應用程式可以：

  • 將使用者的自然語言查詢轉換為 SQL
  • 存取預先設定的商業脈絡和中繼資料
  • 使用策劃的範例查詢和資料定義
  • 根據組織的資料集產生回應

新增一個精靈空間資源

在新增 Genie Space 作為資源之前，請先檢視 應用程式資源的先決條件。

  1. 在 應用程式資源 區塊中，當你建立或編輯應用程式時，點擊 + 新增資源>Genie Space。
  2. 從你工作空間的可用空間清單中選擇一個精靈空間。
  3. 選取應用程式的權限層級：
    • 可查看： 授權應用程式讀取 Genie Space 的設定與元資料。
    • 可執行： 授予應用程式提交查詢到 Genie Space 並接收回應的權限。
    • 可以編輯： 授權應用程式修改 Genie Space 設定。
    • 可管理： 賦予應用程式對 Genie 空間的完整管理權限。
  4. （可選）指定一個自訂的資源鍵，這就是你在應用程式設定中引用 Genie Space 的方式。 預設索引鍵是 genie-space。

當你新增 Genie Space 資源時：

  • Azure Databricks會授予你應用程式的 service principal 在所選 Genie 空間上的指定權限。
  • 該應用程序可以向空間提交自然語言查詢，並接收帶有 SQL 查詢和結果的結構化響應。
  • 該應用程式存取空間的精選業務上下文，包括元資料、範例查詢和資料定義。
  • 存取範圍僅限於選取的空間。 除非你把其他 Genie Spaces 加入獨立資源，否則你的應用程式無法存取它們。

備註

應用程式的服務主體也需要對 Genie Space 查詢的底層資料來源擁有適當的權限。 這通常包括USE CATALOGUSE SCHEMASELECT相關 Unity Catalog 資料表和檢視的權限。

環境變數

當你部署使用 Genie Space 資源的應用程式時，Azure Databricks 會透過環境變數暴露空間 ID，你可以在 valueFrom 設定中使用 app.yaml 欄位來參考。

設定範例：

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 Space 資源時，該應用程式的服務主體會失去對該空間的存取權。 Genie Space 本身保持不變，並持續對擁有適當權限的其他使用者及應用程式開放。

將 Genie Spaces 與其他應用程式資源結合

將 Genie Spaces 與其他 Databricks 應用程式資源結合，打造更複雜的資料應用程式。 常見的整合模式包括：

自然語言分析儀表板

一起使用下列資源來執行互動式分析：

  • 精靈空間： 將使用者問題轉換為 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 模型整合：

  • 精靈空間： 產生初始查詢與資料上下文
  • 模型服務端點： 返回 AI 生成的摘要和建議
  • SQL 倉儲： 執行複雜的分析查詢

服務主體權限

與其他應用程式資源整合時，將下列權限授與應用程式的服務主體：

  • CAN RUN 在精靈空間
  • CAN USE 在 SQL 倉庫（若使用與 Genie 空間不同的倉庫）
  • CAN QUERY 在模型服務端點上
  • USE CATALOG 以及 USE SCHEMA 相關的 Unity 目錄物件
  • SELECT 在資料表中，應用程式直接查詢

最佳實務

使用Genie Space資源時，請遵循以下最佳實務：

  • 授予最低權限。 只提供應用程式功能所需的特定 Genie Spaces 存取權。
  • 確保 Genie 空間包含精心策劃的資料集與元資料，以提升自然語言查詢回應的品質。
  • 將你的應用程式查詢與 Genie Space 測試，以驗證它是否能為預期的使用者問題產生準確結果。
  • 監控查詢效能，並調整應用程式與 Genie Space 的互動模式，以優化回應時間。
  • 在 Genie Space 無法有效解讀或回應使用者查詢的情況下，實作錯誤處理功能。
  • Last updated on