Genie plugin

Databricks AI/BI Genie の space を AppKit アプリケーションに統合し、チャット形式のインターフェースから自然言語でデータをクエリできるようにします。

主な機能:

複数の Genie space を名前付きエイリアスで指定可能
リアルタイムのステータス更新に対応した SSE ストリーミング
自動再接続による会話履歴の再生
クエリ結果のアタッチメント取得
On-behalf-of (OBO) によるユーザー権限での実行

基本的な使い方

import { createApp, genie, server } from "@databricks/appkit";

await createApp({
  plugins: [
    server(),
    genie(),
  ],
});

設定オプション

オプション	型	デフォルト	説明
`spaces`	`Record<string, string>`	`{ default: DATABRICKS_GENIE_SPACE_ID }`	エイリアス名と Genie Space ID の対応マップ
`timeout`	`number`	`120000`	ポーリングのタイムアウト (ミリ秒) 。`0` を指定すると無制限

スペースエイリアス

スペースエイリアスを使うと、複数の Genie space を名前で参照できます。エイリアスは API ルートおよびフロントエンドの <GenieChat> コンポーネントで使用します。

genie({
  spaces: {
    sales: "01ABCDEF12345678",
    support: "01GHIJKL87654321",
  },
});

spaces を省略した場合、pluginは環境変数から DATABRICKS_GENIE_SPACE_ID を読み取り、default エイリアスで登録します。

Genie Space ID の確認方法

Space ID は、Databricks の Genie space ページにある About タブで確認できます。

About タブに表示される Genie Space ID

環境変数

変数	説明
`DATABRICKS_GENIE_SPACE_ID`	デフォルトの Genie Space ID (`spaces` 設定を省略した場合に使用されます)

HTTP endpoint

genie plugin は次の endpoint を公開します (/api/genie 配下にマウント) :

POST /api/genie/:alias/messages — Genie space にメッセージを送信 (SSE stream)
GET /api/genie/:alias/conversations/:conversationId — 会話履歴を再生 (SSE stream)

メッセージを送信する

POST /api/genie/:alias/messages
Content-Type: application/json

{
  "content": "What were total sales last quarter?",
  "conversationId": "optional-existing-conversation-id"
}

レスポンスは SSE ストリームで、次のイベントタイプを送出します:

イベントタイプ	説明
`message_start`	会話 ID とメッセージ ID の割り当て
`status`	処理ステータスの更新 (例: `ASKING_AI`、`EXECUTING_QUERY`)
`message_result`	テキストとクエリ添付を含む最終メッセージ
`query_result`	クエリ添付の表形式データ
`error`	エラーの詳細

会話履歴を取得する

GET /api/genie/:alias/conversations/:conversationId

会話内のすべてのメッセージについて、message_result イベントと query_result イベントの SSE ストリームを返します。

プログラムによるアクセス

この plugin は、サーバーサイドで利用する sendMessage と getConversation をエクスポートします。

const AppKit = await createApp({
  plugins: [server(), genie({ spaces: { demo: "space-id" } })],
});

// イベントをストリーミング
for await (const event of AppKit.genie.sendMessage("demo", "Show revenue by region")) {
  console.log(event.type, event);
}

// 会話全体を取得
const history = await AppKit.genie.getConversation("demo", "conversation-id");

フロントエンドコンポーネント

@databricks/appkit-ui パッケージには、Genie 向けにすぐ使える React コンポーネントが用意されています。

GenieChat

ストリーミング、履歴、再接続に対応したフル機能のチャットインターフェイスです。

GenieChat コンポーネント

import { GenieChat } from "@databricks/appkit-ui/react";

function GeniePage() {
  return (
    <div style={{ height: 600 }}>
      <GenieChat alias="demo" />
    </div>
  );
}

alias prop には、サーバー側の spaces 設定にあるキーと一致する値を指定する必要があります。

useGenieChat フック

カスタムのチャット UI を構築する場合は、useGenieChat フックを直接使用します。

import { useGenieChat } from "@databricks/appkit-ui/react";

function CustomChat() {
  const { messages, status, sendMessage, reset } = useGenieChat({
    alias: "demo",
  });

  return (
    <>
      {messages.map((msg) => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <button onClick={() => sendMessage("Show top customers")}>Ask</button>
      <button onClick={reset}>New conversation</button>
    </>
  );
}

props APIの詳細については、GenieChat コンポーネントリファレンスを参照してください。