使用 Genie API 將 Genie 整合到您的應用程式中

這很重要

這項功能目前處於公開預覽版。

本頁說明如何使用 Genie API 在您自己的聊天機器人、客服專員或應用程式中啟用 Genie 功能。

概觀

Genie API 提供兩種功能：

對話 API：在應用程式、聊天機器人及 AI 代理框架中啟用自然語言資料查詢。這些 API 支援有狀態的對話，使用者可以隨時提出後續問題並自然探索資料。
管理 API：允許跨工作空間的程式化建立、配置與部署 Genie 空間。使用這些 API 進行 CI/CD 管線、版本控制及自動化空間管理。

本頁介紹了對話與管理 API。在呼叫對話 API 之前，先準備一個精心策劃的 Genie 空間。這個空間提供了Genie用來解讀問題並產生答案的脈絡。如果空間不完整或未經測試，即使有正確的 API 整合，使用者仍可能收到錯誤結果。本指南說明建立一個能有效使用 Genie API 的空間所需的最低設定。

先決條件

要使用 Genie API，您必須具備：

使用 Databricks SQL 權利存取 Azure Databricks 工作區。
至少可以在 SQL Pro 或無伺服器 SQL 倉儲上使用許可權。

入門指南

配置 Azure Databricks 驗證

針對具有瀏覽器存取權的使用者在生產環境中的使用案例，請使用 OAuth 用戶 (OAuth U2M)。在無法進行瀏覽器認證的情況下，使用服務主體與 API 進行認證。請參閱服務主體的 OAuth（OAuth M2M）。服務主體必須具有存取必要數據和 SQL 倉儲的許可權。

蒐集細節

Workspace 實例名稱：從你的 Databricks workspace URL 找到並複製你的 workspace 實例名稱。如需 URL 中工作區標識碼的詳細資訊，請參閱取得工作區對象的標識碼。

範例：https://cust-success.cloud.databricks.com/
倉庫 ID：你需要一個至少擁有 CAN USE 權限的 SQL 倉庫的 ID。要找到你的倉庫編號：
1. 在你工作區使用 SQL Warehouses 。
2. 選擇你想使用的倉庫。
3. 從網址或倉庫詳情頁面複製倉庫 ID。
或者，使用 List warehouses 端GET /api/2.0/sql/warehouses 點，程式化地取得你有權限存取的所有 SQL 倉庫清單。回應中會附上倉庫識別碼。

建立或選擇精靈空間

結構良好的 Genie 空間具有下列特性：

使用詳盡註解的資料： Genie 依賴表格元資料和欄位註解。請確認你的 Unity Catalog 資料來源是否有明確且具描述性的註解。
是否經過使用者測試： 透過提出你預期會從目標使用者那裡得到的問題，來測試你的系統。利用測試來建立並精煉範例 SQL 查詢。
包含公司特定的背景說明： 新增指令、範例SQL和函式。請參閱新增 SQL 範例和指示。目標是至少五個經過測試的 SQL 範例查詢。
使用基準測試準確度： 根據預期的用戶問題，至少加入五題基準問題。請參閱在 Genie 空間中使用基準測試。

欲了解更多如何創建空間的資訊，請參閱「設置與管理 AI/BI Genie 空間」及「策劃一個有效的 Genie 空間」。

你可以創建新的精靈空間，或使用現有的空間：

創造一個新空間

使用 Create 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 空間，可以使用 List 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 欄位

這個 serialized_space 欄位是一個 JSON 字串，用來定義你的 Genie 空間的配置和資料來源。在 API 請求中，這個 JSON 必須以字串形式轉義。該油田包括：

版本：架構版本（目前 1）
config：空間配置，包括：
- sample_questions：指導使用者的範例問題。每個問題需要：
  - ID：問題的唯一識別碼。你可以產生任何獨特的字串（例如短的字母數字字串或 UUID）。系統會將這些標識標準化為 32 字元的識別碼。
  - 問題：包含問題文本的陣列。
  請包含至少五個代表常見使用案例的多元問題。
data_sources：本領域可取得的資料來源，包括：
- tables：以三層命名空間格式（）排列的表格物件陣列（catalog.schema.table）。每張表格可包含：
  - 識別碼：必填。完整的資料表名稱。
  - 描述：選擇性。包含關於表格描述文字的陣列。
  - column_configs：可選。欄位配置物件陣列，包含：
    - column_name：專欄名稱。
    - get_example_values：布林值。是否從此欄取樣範例數值。
    - build_value_dictionary：布林值。是否要為類別欄位建立值字典。
說明：可選。空間結構化說明包括：
- text_instructions：空間的文字說明。
- example_question_sqls：範例 SQL 查詢物件陣列。
- join_specs：陣列定義資料表間的連接關係。
- sql_snippets：包含過濾器、表達式與度量的物件。

create space 範例中未脫逸的版本 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"]
        }
      ]
    }
  }
}

建構空間時，先建立一個與此類似的 JSON 結構，然後將其轉換為字串形式以用於 API 請求。完整架構細節請參閱 Create Genie 空間 API 參考資料。

使用對話 API

設定 Genie 空間後，使用對話 API 端點提問、檢索結果，並維持多回合對話與上下文對話。

開始對話

開始交談端點POST /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 在回應中進行輪詢，以檢查訊息的生成狀態，並從 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 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。

提出後續問題

收到回應之後，請使用 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 Genie Space API 取得空間資訊時，可以透過將serialized_space參數設置為include_serialized_space來包含true欄位在回應中。該 serialized_space 欄位包含 Genie 空間的序列化字串表示，包括指令、基準測試、連接及其他配置細節。

使用此序列化表示法搭配 Create Genie Space API 及 Update Genie Space API 來推廣 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>",
  "created_timestamp": 1719769718,
  "last_updated_timestamp": 1719769718,
  "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 取得空間中所有現有的交談執行緒。
針對傳回的每個交談識別碼，請使用 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 UI 中監視問題和回應。

鼓勵用戶測試空間，讓您了解他們可能詢問的問題類型，以及他們收到的回應。為使用者提供指引，以協助他們開始測試空間。使用 [ 監視] 索引標籤來檢視問題和回應。請參閱監視空間。

您也可以使用稽核記錄來監視 Genie 空間中的活動。請參閱 AI/BI Genie 事件。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-19