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

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\"]},{\"id\":\"d4e5f6g7h8i9\",\"question\":[\"Which products have the highest return rate?\"]},{\"id\":\"e5f6g7h8i9j0\",\"question\":[\"Show monthly revenue trend for the past year\"]}],\"instructions\":\"This space analyzes sales data from our e-commerce platform. All monetary values are in USD. Use the orders and customers tables for transactional data.\"},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\"},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]}}",
  "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          \"Show orders by date\"\n        ]\n      }\n    ]\n  },\n  \"data_sources\": {\n    \"tables\": [\n      {\n        \"identifier\": \"samples.tpch.orders\"\n      }\n    ]\n  }\n}\n"
}

serialized_space フィールドの理解​

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

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

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

    • sample_questions : ユーザーをガイドするためのサンプルの質問。各質問には次の要件があります:

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

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

    • 指示 : データ、ビジネス ルール、および結果の解釈方法に関するコンテキスト。これにより、Genie はより正確な応答を提供できるようになります。

  • data_sources : 以下を含むスペースで利用可能なデータ ソース:

    • tables : 3 レベルの名前空間形式のテーブル識別子の配列 ( catalog.schema.table )。ユーザーがクエリするすべての関連テーブルを含めます。

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

JSON
{
  "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"]
      },
      {
        "id": "d4e5f6g7h8i9",
        "question": ["Which products have the highest return rate?"]
      },
      {
        "id": "e5f6g7h8i9j0",
        "question": ["Show monthly revenue trend for the past year"]
      }
    ],
    "instructions": "This space analyzes sales data from our e-commerce platform. All monetary values are in USD. Use the orders and customers tables for transactional data."
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "sales.analytics.orders"
      },
      {
        "identifier": "sales.analytics.customers"
      },
      {
        "identifier": "sales.analytics.products"
      }
    ]
  }
}

スペースを構築するときは、この JSON 構造を作成し、それを API リクエストの文字列としてエスケープします。完全なスキーマの詳細については、「 Create 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 を使用して、メッセージの生成ステータスを確認し、生成された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\"]}],\"instructions\":\"This space analyzes sales data from our e-commerce platform. All monetary values are in USD. Use the orders and customers tables for transactional data.\"},\"data_sources\":{\"tables\":[{\"identifier\":\"sales.analytics.orders\"},{\"identifier\":\"sales.analytics.customers\"},{\"identifier\":\"sales.analytics.products\"}]}}"
}

古い会話スレッドを参照する​

ユーザーが古い会話スレッドを参照できるようにするには、 会話メッセージの一覧表示エンドポイント 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 イベントを参照してください。