次の方法で共有

Genie API を使用して Genie をアプリケーションに統合する

Von Bedeutung

この機能は パブリック プレビュー段階です。

このページでは、Genie API を使用して、独自のチャットボット、エージェント、またはアプリケーションで Genie 機能を有効にする方法について説明します。

概要

Genie API には、次の 2 種類の機能があります。

  • 会話 API: アプリケーション、チャットボット、AI エージェント フレームワークで自然言語データクエリを有効にします。 これらの API は、ユーザーがフォローアップの質問をしたり、時間の経過と同時に自然にデータを探索したりできるステートフルな会話をサポートします。
  • 管理 API: ワークスペース間での Genie スペースのプログラムによる作成、構成、デプロイを有効にします。 CI/CD パイプライン、バージョン管理、および自動領域管理には、これらの API を使用します。

このページでは、会話 API と管理 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 ウェアハウスにアクセスするためのアクセス許可が必要です。

詳細を収集する

  • ワークスペース インスタンス名: Databricks ワークスペースの URL からワークスペース インスタンス名を検索してコピーします。 URL 内のワークスペース識別子の詳細については、「 ワークスペース オブジェクトの識別子を取得する」を参照してください。

    例: https://cust-success.cloud.databricks.com/

  • ウェアハウス ID: 少なくとも CAN USE 特権を持っている SQL ウェアハウスの ID が必要です。 倉庫 ID を検索するには:

    1. ワークスペースの SQL Warehouse に 移動します。
    2. 使用する倉庫を選択します。
    3. URL または倉庫の詳細ページから倉庫 ID をコピーします。

    または、List warehouses エンドポイントを使用してGET /api/2.0/sql/warehousesアクセス許可を持つすべての SQL ウェアハウスの一覧をプログラムで取得します。 応答にはウェアハウスIDが含まれています。

Genie スペースを作成または選択する

よく構造化された Genie 空間には、次の特性があります。

  • 適切に注釈が付けられたデータを使用します。 Genie は、テーブルメタデータと列コメントに依存します。 Unity カタログのデータ ソースに明確でわかりやすいコメントがあることを確認します。
  • ユーザー テストは次のとおりです。 エンド ユーザーに期待される質問をして、スペースをテストします。 テストを使用して、SQL クエリの例を作成および調整します。
  • 会社固有のコンテキストが含まれます。 手順、SQL の例、関数を追加します。 「SQL の例と手順を追加する」を参照してください。 少なくとも 5 つのテスト済みの SQL クエリ例を目指します。
  • ベンチマークを使用して精度をテストします。 予想されるユーザーの質問に基づいて、少なくとも 5 つのベンチマークの質問を追加します。 「Genie スペースでベンチマークを使用する」をご覧ください。

スペースの作成の詳細については、「AI/BI Genie 空間の設定と管理」および「効果的な Genie 空間のキュレーション」を参照してください。

新しい Genie 空間を作成するか、既存の Genie スペースを使用できます。

新しいスペースを作成する

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 スペースが既にある場合は、 Genie スペースの一覧表示 API を使用してスペース ID を見つけることができます。 また、[Genie space Settings]\(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 フィールドは、Genie 空間の構成とデータ ソースを定義する JSON 文字列です。 API 要求では、この JSON を文字列としてエスケープする必要があります。 フィールドには次のものが含まれます。

  • version: スキーマ のバージョン (現在 1)

  • config: 次のようなスペース構成:

    • sample_questions: ユーザーをガイドするための質問の例。 各質問には次のものが必要です。

      • id: 質問のユニークな識別子。 任意の一意の文字列 (短い英数字文字列や UUID など) を生成できます。 システムは、これらを 32 文字の識別子に正規化します。
      • question: 質問テキストを含む配列。

      一般的なユース ケースを表す、少なくとも 5 つの多様な質問を含めます。

  • data_sources: 次のような領域で使用できるデータ ソース。

    • tables: 3 レベルの名前空間形式 (catalog.schema.table) のテーブル オブジェクトの配列。 各テーブルには、次のものが含まれます。

      • 識別子: 必須。 完全なテーブル名。
      • description: 省略可能。 テーブルに関する説明テキストを含む配列。
      • column_configs: 省略可能。 列構成オブジェクトの配列。
        • column_name: 列名。
        • get_example_values: ブール値。 この列のサンプル値をサンプリングするかどうか。
        • build_value_dictionary: ブール値。 カテゴリ列の値ディクショナリを作成するかどうか。

  • instructions: 省略可能。 空間に関する構造化された指示:

    • text_instructions: スペースのテキスト命令。
    • example_question_sqls: SQL クエリ オブジェクトの例の配列。
    • join_specs: テーブル間の結合リレーションシップを定義する配列。
    • sql_snippets: フィルター、式、メジャーを含むオブジェクト。

作成スペースの例の 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 要求の文字列としてエスケープします。 スキーマの詳細については、 Genie 空間の作成 API リファレンスを参照してください。

会話 API の使用

Genie 空間を構成したら、会話 API エンドポイントを使用して質問し、結果を取得し、コンテキストを使用して複数ターンの会話を維持します。

会話を開始する

会話の開始エンドポイント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
  }
}

生成された SQL を取得する

応答で conversation_id と message_id を使用してメッセージの生成状態を確認し、Genie から生成された SQL を取得します。 要求と応答の詳細については、 GET /api/2.0/genie/spaces/{space_id}/conversations/{conversation_id}/messages/{message_id} を参照してください。

注

POST要求のみが、1 分あたりのクエリのスループット制限にカウントされます。 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 空間のシリアル化された文字列表現が含まれます。

このシリアル化された表現を 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 を使用して、特定の会話スレッドからすべてのメッセージを取得します。

分析のために会話データを取得する

スペース マネージャーは、分析のためにスペースのすべてのユーザーに対して要求されたすべての以前のメッセージをプログラムで取得できます。 このデータを取得するには:

  1. GET /api/2.0/genie/spaces/{space_id}/conversations エンドポイントを使用して、空間内のすべての既存の会話スレッドを取得します。
  2. 返される各会話 ID について、 GET /api/2.0/genie/spaces/{space_id}/conversations エンドポイントを使用して、その会話のメッセージの一覧を取得します。

ベスト プラクティスと制限

Genie API を使用するためのベスト プラクティス

Genie API を使用するときにパフォーマンスと信頼性を維持するには:

  • 指数バックオフを使用して再試行ロジックを実装します。 API は失敗した要求を再試行しないため、独自のキューと指数バックオフを追加します。 これにより、アプリケーションは一時的な障害を処理し、不要な繰り返し要求を回避し、増加に合わせてスループットの制限内に留まります。
  • ログ 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 行を返します。 データ分析でさらに多くの行が必要な場合は、データの特定のサブセットに焦点を当てるか、フィルターを使用して結果を絞り込むために質問を調整することを検討してください。

スループットの制限

パブリック プレビュー期間中、Genie API Free レベルのスループット レートはベスト エフォートであり、システム容量によって異なります。 通常またはトラフィックの少ない状況では、API はワークスペースごとに 1 分あたり 5 つのクエリに要求を制限します。 ピーク使用期間中、システムは使用可能な容量に基づいて要求を処理するため、スループットが低下する可能性があります。

領域を監視する

アプリケーションを設定したら、Databricks UI で質問と応答を監視できます。

ユーザーが質問する可能性がある質問の種類と受け取った回答について学習できるように、スペースをテストするようユーザーに勧めます。 ユーザーがスペースのテストを開始するのに役立つ ガイダンス を提供します。 [監視] タブを使用して、質問と回答を表示します。 「 領域の監視」を参照してください。

監査ログを使用して、Genie 空間のアクティビティを監視することもできます。 AI/BI Genie イベント を参照してください。

  • Last updated on