メインコンテンツまでスキップ

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

備考

プレビュー

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

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

概要​

Genie APIを使用すると、開発者は自然言語データのクエリをアプリケーション、チャットボット、およびAIエージェントフレームワークに統合できます。ステートフルな会話をサポートしているため、ユーザーはフォローアップの質問をしたり、時間の経過とともにデータをより自然に探索したりできます。Genie APIを使用すると、自然言語クエリをツールやワークフローに統合し、組織全体でデータにアクセスしやすくすることができます。

APIを使用する前に、厳選されたGenieスペースを準備する必要があります。スペースは、Genie が質問を解釈して結果を返すために使用するコンテキストを定義します。スペースが不完全または未テストの場合、API 統合自体が成功した場合でも、ユーザーは不正解を多く受け取る可能性があります。このガイドでは、Genie APIと効果的に連携するスペースを作成するために必要な最小限のセットアップについて概説します。

前提 条件​

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

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

ステップ 1: Genieスペースを作成してテストする​

ユーザーの質問に高い精度で確実に答えられる Genieスペースを用意します。

注記

Genieを使用して スペースをクエリする予定の場合でも、API DatabricksUI を使用してスペースを設定および調整する必要があります。

次のリソースを使用して、Genieスペースを構成およびキュレーションします。

  1. スペースを設定します 。 UI を使用してGenieスペースを作成する方法を学習します。 GenieDatabricksこの記事には、UI ツールを使用して作業 Genieスペースを作成するための詳細なガイダンスが含まれています。
  2. ベストプラクティスを確認します。 新しいGenieスペースをキュレーションするためのベストプラクティスを学びます。この記事では、新しいGenieスペース作成にアプローチする方法と、テストとフィードバックを通じてスペースを洗練および反復する方法に関する推奨事項を提供します。
  3. ベンチマークの設定: Genieの応答精度を測定するために実行できるベンチマークテストの質問を準備します。

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

  • 適切に注釈が付けられたデータを使用します。 Genieは、テーブルのメタデータと列のコメントに依存して応答を生成します。スペースの Unity Catalogデータソースには、明確で説明的なコメントを含める必要があります。Genie
  • ユーザーテスト済み: あなたはスペースの最初のユーザーである必要があります。エンドユーザーから予想される質問をして、スペースをテストします。テストを使用して、サンプル SQL クエリを作成および改良します。
  • 会社固有のコンテキストが含まれます。 Genieに会社のデータや専門用語について教えるには、コンテキストを含める必要があります。一般的な質問を処理するための命令、サンプル SQL、および関数を追加する方法については、「 コンテキストの追加 」を参照してください。テストと改良が行われた SQL クエリの例を少なくとも 5 つ含めることを目指します。
  • ベンチマークを使用して精度をテストします。 エンドユーザーから予想される質問に基づいて、少なくとも 5 つのベンチマーク質問を追加します。ベンチマークテストを実行して、Genieがこれらの質問に正確に答えていることを確認します。

Genieスペースのレスポンスに満足し、代表的な質問でテストしたら、アプリケーションとの統合を開始できます。

ステップ 2: Databricks 認証を構成する​

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

ステップ 3: 詳細を収集する​

Genieスペース URL を使用して、ワークスペース インスタンス名とGenieスペース ID を見つけます。次の例は、URL でこれらのコンポーネントを検索する方法を示しています。URL のワークスペース識別子の詳細については、「 ワークスペース オブジェクトの識別子を取得する」を参照してください。

https://<databricks-instance>/genie/rooms/<space-id>

Genieスペースの <databricks-instance> と <space-id> をコピーします。

ステップ 4: 会話を開始する​

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

ステップ 5: 生成された 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 配列に入力されます。

ステップ 6: クエリ結果を取得する​

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を参照してください。

ステップ 7: フォローアップの質問をする​

応答を受け取ったら、 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?",
}

Conversation API の使用に関するベスト プラクティス​

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

  • リクエストキューイングとバックオフを実装します。 API は要求の再試行を管理しません。独自のキューイングシステムを使用し、インクリメンタルバックオフを実装して、スループット制限を超えないようにします。
  • ステータスの更新を 5 秒から 10 秒ごとにポーリングします。 COMPLETED、FAILED、CANCELLEDなどの決定的なメッセージ状況が受信されるまで、ポーリングを続けます。ほとんどのクエリでポーリングを 10 分に制限します。10 分経っても決定的な応答がない場合は、ポーリングを停止してタイムアウト エラーを返すか、後でクエリの状態を手動で確認するようにユーザーに求めます。
  • 2 分後にエクスポネンシャル バックオフを使用します。 2 分以内に応答が受信されない場合は、エクスポネンシャル バックオフを適用して信頼性を向上させます。
  • セッションごとに新しい会話を開始します。 セッション間で会話スレッドを再利用すると、意図しないコンテキストの再利用により精度が低下する可能性があるため、使用しないでください。

スペースを監視する​

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

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

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

スループット制限​

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

に最終更新