メインコンテンツまでスキップ
に最終更新

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

備考

プレビュー

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

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

概要​

Genie API は次の 2 種類の機能を提供します。

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

このページでは、会話 API と管理APIs両方について説明します。 会話APIsを呼び出す前に、よく厳選されたGenieスペースを準備します。 このスペースは、Genie が質問を解釈して回答を生成するために使用するコンテキストを提供します。スペースが不完全またはテストされていない場合、正しい API 統合を行っても、ユーザーは誤った結果を受け取る可能性があります。このガイドでは、Genie API で効果的に機能するスペースを作成するために必要な最小限の設定について説明します。

前提 条件​

Genie API を使用するには、次のものが必要です。

  • Databricks SQL エンタイトルメントを持つ Databricks ワークスペースへのアクセス。
  • 少なくとも、 SQL Pro または サーバレス SQLウェアハウスに対する CAN USE 特権。

使い始める​

Databricks認証を構成する​

ブラウザにアクセスできるユーザーが存在する本番運用ユースケースでは、ユーザー向けOAuth ( OAuth U2M)を使用します。 ブラウザベースの認証ができない場合は、サービスプリンシパルを使用してAPIで認証します。 サービスプリンシパル ( OAuth M2M) については、 OAuth参照してください。 サービスシプリンパルには、必要なデータとSQLウェアハウスにアクセスするための権限が必要です。

詳細を収集する​

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

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

  • ウェアハウス ID : 少なくとも CAN USE 権限を持つSQLウェアハウスの ID が必要です。 ウェアハウス ID を確認するには:

    1. ワーク スペースのSQL に移動します。
    2. 使用したいウェアハウスを選択してください。
    3. URLまたはウェアハウス詳細ページからウェアハウスIDをコピーします。

    あるいは、リスト ウェアハウス エンドポイントGET /api/2.0/sql/warehousesを使用して、アクセス権限のあるすべてのSQLウェアハウスのリストをプログラムで取得します。 応答にはウェアハウス ID が含まれます。

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

適切に構造化されたGenieスペースには、次の特徴があります。

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

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

新しいGenieを作成することも、既存のものを使用することもできます。

Genieを使用して、GenieAPIスペースをプログラムで作成します。次の例は、ベスト プラクティスに従った適切に構造化されたスペースを示しています。プレースホルダーを実際の値に置き換えます。

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"
}

serialized_space フィールドの理解​

serialized_spaceフィールドは、 Genieスペースの構成とデータソースを定義するJSON文字列です。 API リクエストでは、この JSON を文字列としてエスケープする必要があります。このフィールドには次の内容が含まれます。

  • version : 下位互換性のためのスキーマバージョン番号。以下の例のように2使用します。

  • config : 次のスペース構成が含まれます:

    • sample_questions : ユーザーをガイドするためのサンプルの質問。各質問には ID (32 文字の 16 進文字列) と 質問 (文字列の配列) が必要です。

  • data_sources : スペースで利用可能なデータソース:

    • tables : 識別子 (3 レベルの名前空間)、オプションの 説明 、およびオプションの column_configs を持つテーブル オブジェクトの配列。
    • metric_views : メトリクス ビュー オブジェクトの配列 (テーブルと同じ構造)。

  • 指示 : スペースの構造化された指示:

    • text_instructions : LLM に関する高レベルのガイダンス。
    • example_question_sqls : SQL回答を含む質問の例。オプションで、問題および use_guidance が含まれ ます 。
    • sql_functions : スペースで使用可能な SQL 関数への参照。
    • join_specs : テーブル間の事前定義された結合関係。
    • sql_snippets : 再利用可能な フィルター 、 式 、 メジャー 。

  • ベンチマーク : 空間の品質を評価するための質問。それぞれに実際の SQL 回答が付いてい ます。

スペース作成例のserialized_spaceフィールドのエスケープされていないバージョンは次のようになります。

JSON
{
  "version": 2,
  "config": {
    "sample_questions": [
      {
        "id": "a1b2c3d4e5f60000000000000000000a",
        "question": ["What were total sales last month?"]
      },
      {
        "id": "b2c3d4e5f6a70000000000000000000b",
        "question": ["Show top 10 customers by revenue"]
      }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.customers",
        "description": ["Customer master data including contact information and account details"],
        "column_configs": [
          {
            "column_name": "customer_id",
            "description": ["Unique identifier for each customer"],
            "synonyms": ["cust_id", "account_id"]
          },
          {
            "column_name": "customer_name",
            "enable_entity_matching": true
          },
          {
            "column_name": "internal_notes",
            "exclude": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.orders",
        "description": ["Transactional order data including order date, amount, and customer information"],
        "column_configs": [
          {
            "column_name": "order_date",
            "enable_format_assistance": true
          },
          {
            "column_name": "region",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          },
          {
            "column_name": "status",
            "enable_format_assistance": true,
            "enable_entity_matching": true
          }
        ]
      },
      {
        "identifier": "sales.analytics.products"
      }
    ],
    "metric_views": [
      {
        "identifier": "sales.analytics.revenue_metrics",
        "description": ["Pre-aggregated revenue metrics by region and time period"],
        "column_configs": [
          {
            "column_name": "period",
            "description": ["Time period for the metric (monthly, quarterly, yearly)"],
            "enable_format_assistance": true
          }
        ]
      }
    ]
  },
  "instructions": {
    "text_instructions": [
      {
        "id": "01f0b37c378e1c9100000000000000a1",
        "content": [
          "When calculating revenue, sum the order_amount column. ",
          "When asked about 'last month', use the previous calendar month. ",
          "Round all monetary values to 2 decimal places."
        ]
      }
    ],
    "example_question_sqls": [
      {
        "id": "01f0821116d912db00000000000000b1",
        "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": "01f099751a3a1df300000000000000b2",
        "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)"
        ]
      },
      {
        "id": "01f099751a3a1df300000000000000b3",
        "question": ["Show sales for a specific region"],
        "sql": [
          "SELECT SUM(order_amount) as total_sales\n",
          "FROM sales.analytics.orders\n",
          "WHERE region = :region_name"
        ],
        "parameters": [
          {
            "name": "region_name",
            "type_hint": "STRING",
            "description": ["The region to filter by (e.g., 'North America', 'Europe')"],
            "default_value": {
              "values": ["North America"]
            }
          }
        ],
        "usage_guidance": ["Use this example when the user asks about sales filtered by a specific geographic region"]
      }
    ],
    "sql_functions": [
      {
        "id": "01f0c0b4e815100000000000000000f1",
        "identifier": "sales.analytics.fiscal_quarter"
      }
    ],
    "join_specs": [
      {
        "id": "01f0c0b4e815100000000000000000c1",
        "left": {
          "identifier": "sales.analytics.orders",
          "alias": "orders"
        },
        "right": {
          "identifier": "sales.analytics.customers",
          "alias": "customers"
        },
        "sql": ["orders.customer_id = customers.customer_id"],
        "comment": ["Join orders to customers on customer_id"],
        "instruction": ["Use this join when you need customer details for order analysis"]
      }
    ],
    "sql_snippets": {
      "filters": [
        {
          "id": "01f09972e66d100000000000000000d1",
          "sql": ["orders.order_amount > 1000"],
          "display_name": "high value orders",
          "synonyms": ["large orders", "big purchases"],
          "comment": ["Filters to orders over $1000"],
          "instruction": ["Use when the user asks about high-value or large orders"]
        }
      ],
      "expressions": [
        {
          "id": "01f09974563a100000000000000000e1",
          "alias": "order_year",
          "sql": ["YEAR(orders.order_date)"],
          "display_name": "year",
          "synonyms": ["fiscal year", "calendar year"],
          "comment": ["Extracts the year from order date"],
          "instruction": ["Use for year-over-year analysis"]
        }
      ],
      "measures": [
        {
          "id": "01f09972611f100000000000000000f1",
          "alias": "total_revenue",
          "sql": ["SUM(orders.order_amount)"],
          "display_name": "total revenue",
          "synonyms": ["revenue", "total sales"],
          "comment": ["Sum of all order amounts"],
          "instruction": ["Use this measure for revenue calculations"]
        }
      ]
    }
  },
  "benchmarks": {
    "questions": [
      {
        "id": "01f0d0b4e815100000000000000000g1",
        "question": ["What is the average order value?"],
        "answer": [
          {
            "format": "SQL",
            "content": ["SELECT AVG(order_amount) as avg_order_value\n", "FROM sales.analytics.orders"]
          }
        ]
      }
    ]
  }
}

スペースを構築するときは、この JSON 構造を作成し、それを API リクエストの文字列としてエスケープします。完全なスキーマの詳細については、「 Create GenieリファレンスAPIを参照してください。

serialized_space の検証ルール​

serialized_space JSON は次の検証ルールに準拠する必要があります。有効でない JSON は、スペースの作成または更新中に拒否されます。

バージョン​

  • バージョン フィールド : 必須。新しいスペースには2使用します。バージョン番号は下位互換性のために存在します。

IDフォーマット​

すべての ID フィールドは 、32 文字の小文字の 16 進文字列 (ハイフンなしの UUID 形式) である必要があります。

  • 有効 ： a1b2c3d4e5f60000000000000000000a
  • 無効 : a1b2c3d4e5f6 (短すぎる)、 A1B2C3D4E5F60000000000000000000A (大文字)、 a1b2c3d4-e5f6-0000-0000-00000000000a (ハイフンを含む)

以下の場合にはIDが必要です:

  • config.sample_questions[].id
  • instructions.text_instructions[].id
  • instructions.example_question_sqls[].id
  • instructions.join_specs[].id
  • instructions.sql_snippets.filters[].id
  • instructions.sql_snippets.expressions[].id
  • instructions.sql_snippets.measures[].id
  • benchmarks.questions[].id （ベンチマークが含まれている場合）

ソート要件​

ID または識別子を含むコレクションは事前にソートする必要があります。システムは配列がすでにソートされていることを検証し、ソートされていない入力を拒否します。

コレクション

ソートキー

data_sources.tables

identifier （アルファベット順）

data_sources.metric_views

identifier （アルファベット順）

data_sources.tables[].column_configs

column_name （アルファベット順）

data_sources.metric_views[].column_configs

column_name （アルファベット順）

config.sample_questions

id （アルファベット順）

instructions.text_instructions

id （アルファベット順）

instructions.example_question_sqls

id （アルファベット順）

instructions.sql_functions

(id, identifier) タプル（アルファベット順）

instructions.join_specs

id （アルファベット順）

instructions.sql_snippets.filters

id （アルファベット順）

instructions.sql_snippets.expressions

id （アルファベット順）

instructions.sql_snippets.measures

id （アルファベット順）

benchmarks.questions

id （アルファベット順）

一意性制約​

  • 質問 ID : config.sample_questionsとbenchmarks.questions内のすべての ID は、両方のコレクション間で一意である必要があります。
  • 命令 ID : text_instructions 、 example_question_sqls 、 sql_functions 、 join_specs 、およびすべてのsql_snippetsタイプにわたるすべての ID は一意である必要があります。
  • 列構成 : (table_identifier, column_name)の組み合わせはスペース内で一意である必要があります。

サイズと長さの制限​

  • 文字列の長さ : 個々の文字列要素は 25,000 文字に制限されます。
  • 配列サイズ : 繰り返しフィールドは 10,000 項目に制限されます。
  • テキスト指示 : スペースごとに最大 1 つのテキスト指示が許可されます。
  • テーブルとメトリクス ビュー : ワークスペース固有の制限に従います。
  • SQL コンテンツ : sqlおよびjoin_specs.sqlフィールドのクエリ テキストには長さ制限があります。

その他の要件​

  • テーブル識別子 : 3 レベルの名前空間形式 ( catalog.schema.table ) を使用する必要があります。
  • ベンチマーク回答 : 各ベンチマーク質問には、形式が SQL に設定された回答が 1 つだけ必要です。
  • SQL スニペット : フィルター、式、メジャーの SQL フィールドは空にできません。

会話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 を使用して、メッセージの生成ステータスを確認し、生成されたSQLをGenieから取得します。要求と応答の詳細については、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使用してスペース情報を取得する場合、 include_serialized_spaceをtrueに設定することで、応答にserialized_spaceフィールドを含めることができます。 serialized_spaceフィールドには、命令、ベンチマーク、結合、その他の構成の詳細を含む、 Genieスペースのシリアル化された文字列表現が含まれます。

このシリアル化された表現をCreate Genie Space APIおよびUpdate Genie Space APIと組み合わせて使用することで、ワークスペース 全体でGenie spacesプロモートしたり、スペース構成のバックアップを作成したりできます。

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 無料レベルのスループット レートはベストエフォートであり、システム容量によって異なります。通常またはトラフィックの少ない状況では、API はワークスペースごとに 1 分あたり 5 クエリまでのリクエストを制限します。使用率がピークになる時間帯には、システムは利用可能な容量に基づいてリクエストを処理するため、スループットが低下する可能性があります。

スペースを監視する​

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

スペースをテストするようユーザーに促し、ユーザーが尋ねる可能性のある質問の種類と受け取る回答について理解できるようにします。ユーザーがスペースのテストを開始するのに役立つ ガイダンス を提供します。 モニタリング タブを使用して、質問と回答を表示します。「スペースの監視」を参照してください。

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