Genie Agentを使用してボリューム内のファイルを分析する
Genie Agent は、PDF、Word ドキュメント、スライドデッキ、画像など、Unity Catalog ボリュームに保存されている構造化されていないファイルを分析できます。エージェント作成者はエージェントにボリュームをアタッチし、ビジネスユーザーは1回の会話の中で、エージェントの構造化データと一緒にそのコンテンツに関する質問をします。
プレビュー
この機能は パブリック プレビュー段階です。ワークスペース管理者は、 プレビュー ページから Genieエージェントでボリューム内のファイルを分析 へのアクセスを制御できます。Databricksのプレビューを管理するを参照してください。
Genie エージェントは、以前は Genie Space として知られていました。
Genie Agentにファイルについて質問できること
エージェントにボリュームをアタッチすることで、ビジネスユーザーはサポートチケット、営業電話 Logs、ポリシーファイルなどのドキュメントからのデータと、エージェントの構造化テーブルからのデータを組み合わせることができます。ユーザーは次のような質問に回答できます。
- 解決に最も時間がかかっているサポート問題はどれですか?また、顧客はエスカレーション要求で何を言っていますか?
- なぜ終盤の営業機会が停滞しているのでしょうか?また、営業電話のLogsにはどのような異議が最も頻繁に現れるのでしょうか?
- どのリージョンが低パフォーマンスであり、どのような内部エスカレーションポリシーが適用されますか?
Genie Agentでファイル分析を使用するタイミング
特定のドメイン用の専門的なエージェントが必要な場合は、ボリュームをGenie Agentにアタッチします。ニーズがより広範な場合は、別のアプローチを選択してください。
- Genie Oneを、構造化データに関するすべての質問の統合エントリポイントとして使用します。Genie Oneは、ファイルに関する質問に回答するためにGenie Agentを呼び出せます。
- モデルの選択、チャンク化戦略、複数のサブエージェントのオーケストレーションなど、エージェントの動作をきめ細かく制御する必要がある場合にのみ、Agent Bricks CLIを使用してコード内でカスタムエージェントを構築します。
- ファイルuploadを使用して、ボリュームに保存されているファイルを分析する代わりに、ローカルのCSVまたはExcelファイルを1つの会話に統合します。
Genie Agentによるファイルの分析方法
ユーザーがボリュームからのコンテキストを必要とする質問をすると、Genie Agentは質問に最も関連するファイルコンテンツを取得し、エージェントのコンテキストに追加します。その後、エージェントはそのコンテンツと構造化データを照らし合わせ、引用付きの回答を生成します。これらの引用は、ソースファイルの特定のページを指すことができます。
ファイル分析はエージェントモードでのみ実行されます。これは、多段階の推論を使用して関連ファイルを検索および分析します。エージェントモードを参照してください。
Genie Agentは、常に質問をするユーザーの権限を使用します。ユーザーが添付されたボリュームの一部に対して少なくともREAD VOLUMEの権限を持っていない場合、エージェントはユーザーがアクセスできるボリュームのみを使用して回答します。データオブジェクトの管理を参照してください。ユーザーは、同じ会話の中で、特定のボリューム、複数のボリューム、および構造化データにまたがって質問をすることができます。
要件
エージェントとそのユーザーには、次の要件が適用されます。
- ワークスペースでUnity Catalogが有効になっていること。
- 使用しているリージョンでエージェントモードが利用可能であること。Databricks指定サービスを参照してください。
- 明確な指示とテーブルメタデータを持つ、十分に準備されたGenie Agent。効果的なGenie Agentをキュレーションするを参照してください。
- 関連ファイルを含む1つ以上のUnity Catalogボリューム。
- ファイルについて質問する各ユーザーの接続済みボリュームに対する少なくとも
READ VOLUMEの権限。 - お使いのリージョンで利用可能な Lakebase、
ai_parse_document、および 基盤モデル APIs。コンテンツ検索のサポート対象リージョンを参照してください。
Genie Agentにボリュームをアタッチする
開始する前に、要件を確認してください。
Genie Agentにボリュームをアタッチするには:
- ファイルを追加したいGenie Agentを開きます。
- ソース タブを開き、 追加 をクリックします。
- 1つ以上のボリュームを選択してください。Genie Agentはボリューム全体を処理します。ボリューム内のフォルダーまたはファイルの一部をアタッチすることはできません。
- 説明 フィールドに明確な説明を追加します。ファイルに関する質問に対するエージェントの最適化を参照してください。
特定のワークスペースにバインドされているカタログなど、defaultではこのワークスペースからカタログにアクセスできない場合でも、ボリュームをソースとしてアタッチできます。
ボリュームをアタッチすると、Databricksによってコンテンツ検索が自動的に有効になります。
コンテンツ検索のしくみ
コンテンツ検索機能は、Genie Agentがより多くのファイル群に対する推論を行い、多くのファイルから特定のパッセージを抽出し、より低いレイテンシで質問に回答できるように、ファイルを解析してインデックス化します。ファイルとボリュームの制限については、 制限事項を参照してください。
コンテンツ検索はボリュームと自動的に同期された状態に保たれます。ファイルを追加、変更、または削除すると、Databricksが変更を反映してインデックスを更新するため、Genie Agentは手動のステップなしで現在のコンテンツに基づいて推論を行います。
ファイルに関する質問向けにエージェントを最適化する
ボリュームをアタッチしたら、Genie Agentがそのコンテンツを使用できるように、以下の推奨事項に従ってください。
- 明確な説明を追加します : ボリュームにどのようなコンテンツが含まれているか、どのように編成されているか、そしてエージェントがそれをどのように使用すべきかを説明します。エージェントはこの説明を使用して、関連ファイルを検索します。
- 重複するコンテンツを避けてください :重複する情報を含む複数のボリュームをアタッチすると、エージェントが関連ドキュメントを取得することがより困難になります。ボリューム内の個々のファイルにも同じことが適用されます。
- 無関係なファイルを避ける :エージェントのドメインに関連するファイルのみを含めます。無関係なファイルはエージェントを混乱させる可能性があります。
- 明確なファイル名を使用する :エージェントがファイルを区別できるように、わかりやすいファイル名を使用してください。
ファイルについて質問します
Genie Agent内のファイルについて質問するには:
- ボリュームがアタッチされている Genie Agent を開きます。
- チャットボックスでエージェント モードをオンにします。ファイルに関する質問に回答するには、エージェント モードを使用する必要があります。
- 質問を入力し、プロンプトを送信します。エージェントモードは、関連するボリュームからコンテキストを取得し、分析が完了した後に回答を生成します。
コンテンツ検索のサポート対象リージョン
コンテンツ検索は、このセクションに記載されている地域で利用できます。
一部の地域では、アカウント管理者がGeo間処理を有効にした場合にのみコンテンツ検索がランします。これにより、DatabricksはワークスペースのGeoの外でファイルを処理できるようになります。Geo間処理の有効化を参照してください。
Geo間処理を必要としない地域
以下のリージョンについて、コンテンツ検索はワークスペースのリージョンで実行されます:
us-central1(アイオワ)us-east4(バージニア)
クロスGeo処理が必要なリージョン
次の地域では、コンテンツ検索の実行前にアカウント管理者がGeo間処理を有効にする必要があります。
europe-west3(フランクフルト)
制限事項
次の制限が適用されます:
-
Genie Agent に最大10個のボリュームをアタッチできます。
-
GoogleドライブやSharePointなどの外部ソースのコンテンツを使用するには、代わりにMCPコネクタを接続してください。Genie AgentをMCPツールおよびソースに接続するを参照してください。
-
エージェントのすべてのユーザーには、 ワークスペースアクセス と Databricks SQLアクセス の両方の資格が必要です。アクセス権限を参照してください。
-
パブリックプレビュー期間中は、アカウント専用ユーザーはこの機能を使用できません。Genie Oneへのアカウント専用ユーザーのアクセスを参照してください。
-
Unity Catalog管理ボリュームのみがコンテンツ検索をサポートしています。外部ボリュームとMy Filesボリュームはサポートされていません。My Filesへのファイルの保存を参照してください。
-
各ワークスペースで、Genie Agentにアタッチできるボリュームは最大250件です。
-
各インデックス付きボリュームには、最大10,000ファイルを含めることができます。より大きなボリュームを使用するには、ファイルイベントを有効にします。「10,000ファイルを超えるボリュームの使用」を参照してください。
-
コンテンツ検索では、100 MBを超えるファイルおよび500ページを超えるファイルはスキップされます。
-
コンテンツ検索は、PDF、JPG、JPEG、PNG、TIFF、TIF、DOC、DOCX、PPT、PPTX、MD、または TXT ファイルをサポートしています。他のすべてのファイル形式はスキップされます。
10,000件を超えるファイルを持つボリュームを使用する
ファイルイベントがない場合、コンテンツ検索は最大10,000ファイルまでのUnity Catalogマネージドボリュームをサポートします。10,000ファイルを超えるマネージドボリュームを使用するには、ボリュームが含まれる外部ロケーションでファイルイベントを有効にします。ファイルイベントにより、コンテンツ検索はストレージを繰り返しスキャンする代わりに、クラウドストレージの通知を通じて新規ファイル、変更済みファイル、削除済みファイルを検出できます。ファイルイベントとは何か、どのように機能するかについては、 ファイルイベントFAQを参照してください。
セットアップには次のステップがあります。
- ボリュームを含む外部ロケーションを見つけます。
- その外部ロケーションのファイル イベントを有効にして、接続をテストします。
- テストが失敗した場合は、ファイルイベントに必要なクラウド権限を構成します。「外部ロケーションのファイル イベントのセットアップ」を参照してください。
次の場合は、このセットアップをスキップできます:
- ボリュームはdefaultのストレージを使用しています。確認するには、 カタログエクスプローラー でボリュームを開き、 詳細 tabに移動します。 ストレージロケーション が defaultストレージ である場合、このセットアップをスキップできます。
- ボリュームが含まれている外部ロケーションでは、ファイルイベントが既に有効になっており、動作しています。外部ロケーションを見つけてそのステータスを確認するには、ステップ1:ボリュームが含まれている外部ロケーションを見つけるを参照してください。
ステップ1: ボリュームを含む外部ロケーションを見つける
必要なアクセス許可 :
USE CATALOGボリュームを含むカタログ上の。USE SCHEMAボリュームを含むスキーマで。READ METADATAボリューム上で。READ VOLUME、MANAGE、またはボリュームの所有権によって、そのメタデータを表示することもできます。READ METADATA検査する必要がある各外部ロケーション上の。MANAGE、外部ロケーションの所有権、またはメタストア管理者のアクセス権も適格です。
- Catalog Explorer
- Python SDK
-
サイドバーで [
カタログ ]をクリックします。
-
Genie Agentが使用するボリュームを開きます。 Details (詳細)tabで、 Storage location (ストレージの場所)を見つけ、クラウドパスをコピーします。これを使用して、一致する外部ロケーションを検索します。例えば:
gs://bucket-1/6c55cf12…/volumes/de8e8205… -
接続 > 外部ロケーション をクリックします。
-
ボリュームのストレージパスの先頭にある URL の外部ロケーションを見つけます。
例えば、
gs://bucket-1/6c55cf12…の外部ロケーションはgs://bucket-1/6c55cf12…/volumes/de8e8205…に格納されているマネージドボリュームをカバーします。 -
一致する外部ロケーションの 概要 tabを開き、 ファイルイベントを有効にする にチェックを入れます。 有効 と表示されている場合は、 接続をテスト をクリックして、ファイルイベントが機能していることを確認します。テストがパスした場合は、ステップ2および3は不要です。失敗した場合は、 ステップ3にスキップします。
ノートブックで次のコードをランします。<catalog>.<schema>.<volume>をボリュームのフル名に置き換えます。これらのスニペットには、Databricks SDK for Pythonの新しいバージョンが必要です。ImportErrorまたはAttributeErrorが発生した場合は、%pip install --upgrade databricks-sdkをランしてからdbutils.library.restartPython()をランします。
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
# Storage location of the volume
print(w.volumes.read("<catalog>.<schema>.<volume>").storage_location)
# External locations that you can access
for location in w.external_locations.list():
print(location.name, location.url)
URLがボリュームのストレージ場所の先頭である外部ロケーションを見つけます。
一致する外部ロケーションが __databricks_managed_storage_locationの場合、ボリュームはdefaultストレージを使用するため、このセットアップは不要です。
一致する外部ロケーションが見つかった場合は、ファイルイベントが有効になっているかを確認してください。
print(w.external_locations.get("<external-location-name>").effective_enable_file_events)
Trueが表示された場合は、 Catalog Explorer の外部ロケーションで 接続のテスト をクリックして、ファイル イベントが動作していることを確認します。テストに合格した場合は、ステップ2とステップ3は不要です。失敗した場合は、ステップ3に進みます。FalseまたはNoneが表示された場合は、ステップ2を続行します。
一致する外部ロケーションがない場合、そのロケーションにアクセスできない可能性があります。リストには、アクセスできる外部ロケーションのみが表示されます。メタストア管理者または外部ロケーションの所有者に確認してください。ボリュームが外部ロケーションなしでメタストア ルート ストレージを使用している場合、ボリュームが存在するまでファイル イベントを有効にすることはできません。メタストアレベルのストレージを削除すると新しいストレージが作成されますが、それ以降は、すべての新しいカタログに独自のストレージロケーションが必要になります。メタストア レベルのストレージを削除するを参照してください。
Catalog Explorer の外部ロケーションの 概要 tabで、 資格情報 行にあるストレージ資格情報名に注目してください。ステップ2の権限とステップ3のクラウド構成には、この名前が必要です。
ステップ2:ファイルイベントを有効にし、接続をテストする
ステップ1で確認した外部ロケーションとストレージ資格情報を使用してください。
必要な権限: メタストア管理者はこのステップを完了できます。そうでない場合は、以下の両方が必要です。
MANAGE外部ロケーションに対する、または外部ロケーションの所有権。MANAGEストレージ資格情報、資格情報の所有権、または資格情報と外部ロケーションを含むメタストアの両方に対するCREATE EXTERNAL LOCATION。
- Catalog Explorer
- Python SDK
- カタログエクスプローラー で外部ロケーションに移動します。
接続のテスト の横にある ケバブ メニューをクリックし、 編集 を選択します。
- Advanced Options を展開します。 Enable file events をオンにし、 File event type を Automatic に設定します。
- 更新 をクリックします。検証が失敗し、強制的にアップデートするように求められた場合、キャンセルして「ステップ3」に進んでください。強制アップデートを行うと、ファイルイベントは有効のままになりますが、機能しなくなります。
- 数秒待ってから、[ 接続をテスト ]をクリックして、ファイルイベントが動作していることを確認します。テストが失敗し、このステップの前にファイルイベントがオフになっていた場合は、このロケーションでのファイルの到着Triggerが動作し続けるように、[ ファイルイベントを有効にする ]を再びオフにします。次に、ステップ3に進みます。
ノートブックで次のコードをランします。<external-location-name> をステップ1の外部ロケーションに置き換えます。
GCS の外部ロケーションの場合:
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import GcpPubsub, FileEventQueue
w = WorkspaceClient()
w.external_locations.update(
name="<external-location-name>",
enable_file_events=True,
file_event_queue=FileEventQueue(managed_pubsub=GcpPubsub()),
)
次に、 カタログエクスプローラー で 接続のテスト をクリックして、ファイルイベントが機能していることを確認します。updateで検証エラーが発生した場合は、ステップ3に進みます。テストが失敗し、このステップの前にファイルイベントがオフになっていた場合は、この場所へのファイルの到着Triggerが引き続き機能するように再度オフにし、ステップ3に進みます。
w.external_locations.update(name="<external-location-name>", enable_file_events=False)
ステップ3: クラウド権限の構成
ステップ1またはステップ2で 接続のテスト に失敗した場合、またはステップ2で 更新 をクリックしたときにファイルイベントの検証に失敗した場合は、このステップを完了します。
完全なクラウド構成の手順については、「外部ロケーションのファイル イベントのセットアップ」を参照してください。以下のメモと例は、外部ロケーションに必要な権限とクラウド リソースを特定するのに役立ちます。
必要な権限 :ストレージ資格情報が使用するクラウドIDへのアクセスを許可し、ガイドが必要とするストレージ設定を変更するための権限。このアクセス権がない場合は、クラウド管理者に問い合わせてください。
そのクラウド ID を見つけるには、 カタログ エクスプローラー で外部ロケーションの 概要 tabを開き、 資格情報 行の名前をクリックしてストレージ資格情報の詳細を表示します。
クラウド管理者が変更を行う場合は、外部ロケーションのURLとストレージ資格情報の詳細を管理者に提供して、正しいクラウド リソースとIDを識別できるようにしてください。
たとえば、URL gs://bucket-1/6c55cf12… を持つ GCS 上の外部ロケーションの場合、バケット名は bucket-1 です。
ストレージ資格情報のサービスアカウントに、以下の権限を持つカスタムロールを付与します:
pubsub.subscriptions.consume
pubsub.subscriptions.create
pubsub.subscriptions.delete
pubsub.subscriptions.get
pubsub.subscriptions.list
pubsub.subscriptions.update
pubsub.topics.attachSubscription
pubsub.topics.detachSubscription
pubsub.topics.create
pubsub.topics.delete
pubsub.topics.get
pubsub.topics.list
pubsub.topics.update
storage.buckets.update
次に、Cloud Storage サービスエージェントに Pub/Sub パブリッシャー ロールを付与します。サービスエージェントを見つけるには、クラウド Storage サービスエージェントを取得するをご覧ください。
自動セットアップのガイドのクラウド構成が完了したら、 ステップ2に戻り、ファイルイベントを有効にして接続をテストします。
よくある質問
以下の質問は、ボリューム内のファイルを分析するための一般的なトピックについて扱っています。
この機能はどのように請求されますか?
Databricks は以下の料金を請求します。
- ファイルの準備 :Databricks がコンテンツ検索を有効にするか、ボリュームを同期すると、ファイルが
ai_parse_documentAI 関数で解析されます。これには AI Functions の価格に基づいて料金が請求されます。 - 質問に対する回答 : ファイルに対するエージェントの推論は、標準的なGenieの使用量の一部として課金されます。See Genie 価格.
APIを介してボリューム内のファイルを分析できますか?
はい。AgentモードAPIを介してボリューム内のファイルを分析できます。AgentモードAPIリファレンスを参照してください。
10,000ファイルを超えるボリュームをどのように使用できますか?
10,000 ファイルを超える Unity Catalog 管理ボリュームを使用するには、そのボリュームを含む外部ロケーションでファイルイベントを有効にします。10,000ファイルを超えるボリュームの使用を参照してください。
その他のリソース
関連情報については、以下のリソースを参照してください。