Databricks Genie Agentにボリュームをアタッチして非構造化ファイルを分析する

Posted at 2026-07-27

はじめに

Genie AgentにUnity Catalogボリュームをアタッチして、ボリューム内のPDF・Word文書・スライド・画像を分析できるようになりました。ベータ版の機能です。

これまでGenie Agentは構造化データ、つまりUnity Catalogのテーブルに対して質問する機能でした。ここにボリュームを足すと、テーブルとドキュメントを1つの会話の中で横断できるようになります。「返品が多いのはどのカテゴリか」と「その原因は問い合わせ記録に何と書かれているか」を、別々のツールに分かれずに聞ける、ということです。

実際に検証用のデータとドキュメントを用意して一通り触ってみたところ、ドキュメントに書かれていない挙動もいくつか見つかりました。そのあたりも含めて書いていきます。

検証環境をつくる

この機能の面白さは、構造化データと非構造化データが交わるところにあります。それを確かめるには、答えが片方にしか存在しない状況を作る必要があります。テーブルだけで答えられる質問では、ボリュームをアタッチした意味が見えません。

今回はECサイトの注文データを土台に、次の構成で用意しました。

種別	名前	中身
テーブル	`orders_enriched_silver`	注文490件。顧客名・商品カテゴリを含む
テーブル	`returns`	返品40件。注文IDと定型の理由コードのみ
ボリューム	`policies`	社内規程5件 (DOCX)
ボリューム	`support_tickets`	問い合わせ記録30件 (DOCX)
ボリューム	`qbr_decks`	四半期レビュー資料4件 (PPTX)

仕込みのポイントは2つです。

1つ目は、ドキュメントの本文に実在する注文IDと顧客IDを埋め込むことです。問い合わせ記録の冒頭に「注文ID: O000007 / 顧客ID: C0020」と書いておきます。これがないと、テーブルとドキュメントを突き合わせる質問がそもそも成立しません。

2つ目は、返品理由の詳細をテーブルから抜くことです。returns テーブルに入れたのは DAMAGED のような定型コードだけで、なぜ破損するのかはどこにも書いていません。その原因は問い合わせ記録の本文にしかない、という状態を作ります。

返品はBooksカテゴリに意図的に偏らせました。返品率はBooksが26.88%、2位のFood & Beverageが6.45%です。

ボリュームの作成

作成時にコメントを付けておくのがおすすめです。理由は後述します。

spark.sql("""
CREATE VOLUME IF NOT EXISTS takaakiyayoi_catalog.ecommerce.support_tickets
COMMENT 'カスタマーサポートの問い合わせ記録。1件1ファイルで注文IDと顧客IDを含む'
""")

ドキュメントの生成

日本語のPDFはフォント埋め込みでハマるので、対応形式にDOCXとPPTXが入っているのを利用して python-docx と python-pptx で直接生成しました。

%pip install python-docx python-pptx
dbutils.library.restartPython()

パッケージ名はハイフン、import名は docx と pptx です。ファイルはローカルの一時ディレクトリに作ってから /Volumes 配下にコピーします。ライブラリによってはFUSE経由の書き込みで失敗することがあるためです。

import shutil

doc.save("/tmp/ticket_0001.docx")
shutil.copyfile("/tmp/ticket_0001.docx",
                "/Volumes/takaakiyayoi_catalog/ecommerce/support_tickets/ticket_0001.docx")

これで30件のDOCXがボリュームに並びます。ちなみに python-docxが作るDOCXは、本文が数行でも1ファイル36 KB程度になります 。テンプレートのスタイル定義が丸ごと入るためです。10 MB制限を試したい場合、テキストだけでは到底届きません。

ボリュームをアタッチする

ドキュメントには「ソース タブを開き、追加をクリック」とあります。既存のエージェントにはこの手順で追加できます。

新規に作る場合は、作成時のデータ選択ダイアログからまとめて選べます。

テーブルとボリュームが同じリストで並んでいます。「ボリューム」のフィルタチップも用意されていて、両者が対等な「ソース」として扱われているのが分かります。今回は2テーブルと3ボリュームを一度に選択しました。

説明はUnity Catalogのコメントが引き継がれる

ボリュームの説明フィールドは、エージェントが関連ファイルを検索するときの入口になります。ドキュメントでも「明確な説明を追加します」と強調されている項目です。

ソースタブを開いてみると、CREATE VOLUME のときに書いたコメントがそのまま説明として表示されていました。

Genie側で改めて書き直す必要はありません。地味ですが、これは運用上ありがたい挙動です。説明がGenieの設定ではなくカタログ側の資産になるので、エージェントを作り直しても、別のエージェントに同じボリュームを付けても、説明が付いてきます。テーブルにコメントを付けるのと同じ作業として、ボリューム作成時に済ませておけます。

指示を書く

テーブルが2つあるので、結合条件は明示しておきます。returns に外部キー制約を付けていないため、書かないと結合を外す可能性があります。

このエージェントはECサイトの注文と返品に関する質問に回答します。

- orders_enriched_silver は注文1件1行。顧客名・商品カテゴリを含む
- returns は返品1件1行。orders_enriched_silver.order_id = returns.order_id で結合する
- 返品率は「返品件数 / 注文件数」で計算する。カテゴリ別に見る場合は product_category で集計する
- returns.reason_code は集計用の定型コード。返品の詳細な経緯は support_tickets ボリュームの
  問い合わせ記録に記載されている
- 社内規程に関する質問 (返送料の負担、承認権限、SLA、エスカレーション基準) は
  policies ボリュームを参照する
- 回答は日本語で行う

4行目と5行目が、テーブルとボリュームのどちらを見るべきかの振り分けです。

なお、ファイルに関する質問に答えさせるにはエージェントモードが必要です。通常モードのままだとテーブル側だけで回答が完結します。

質問してみる

構造化と非構造化を1回で横断する

まずは2ホップの質問です。

返品率が最も高い商品カテゴリはどれですか。そのカテゴリの返送料は誰の負担になりますか

前半はテーブル、後半は規程にしか答えがありません。

Books 26.88%、返送料は当社負担。両方正解です。93件の注文に対して25件の返品、という内訳まで出ています。

回答の中で、棒グラフはSQLの結果、返送料の記述は規程からの引用と、それぞれ別の引用番号が付いています。どの記述がどこから来たかが追える形になっているのは、社内で使うことを考えると重要な点です。

思考トレースには「関連するファイルを探しています」の下に3本のボリューム名が並びます。どこを見に行ったかが可視化されます。

ちなみに同じ質問を2回投げたところ、1回目はQBR資料まで引いて施策の背景を説明し、2回目は規程だけで簡潔に答えました。引くファイルは毎回同じとは限りません。

SQLの結果を検索キーにしてドキュメントを引く

次はもう少し込み入った質問です。

注文 O000007 の顧客は問い合わせで何を訴えていましたか。この顧客の累計購入額はいくらですか

ここは思考トレースが面白いところです。まず注文の詳細と返品情報をSQLで引き、そこで顧客がC0020だと判明します。次にそのC0020を検索キーにして問い合わせ記録を探し、あわせて累計購入額を計算しています。

質問文にC0020という文字列は一度も出てきません。SQLの結果として初めて分かった値でドキュメント側を検索している、という動きです。テーブルとボリュームが同じ会話の中にある意味が、いちばん出ている場面だと思います。

通貨をまたいで合算しない

同じ回答で、累計購入額はこう返ってきました。

JPY: 3,116.99円 (4件)
EUR: 3,007.35ユーロ (6件)
USD: 595.51ドル (1件)

orders_enriched_silver に currency 列があるので、通貨をまたいで単純合算せずに分けました。指示には通貨のことを何も書いていません。

正しい判断です。ただ「累計購入額はいくら」という問いに対して数字が3つ返るので、質問者の期待には応えきれていません。換算レートを持っていない以上これが誠実な答えではありますが、実務では指示に換算ルールを書くか、通貨を統一した列を用意するかを決めておく必要があります。ボリューム側の整備だけでなく、テーブル側のメタデータも同じだけ効いてきます。

テーブルに存在しない答えを引き出す

本命の質問です。

返品が多いカテゴリについて、問い合わせ記録から共通する原因を挙げてください

この答えはテーブルには一切ありません。あるのは DAMAGED というコードだけです。

エージェントは3段階で組み立てました。SQLで理由コードを集計してDAMAGEDが25件中13件と特定し、問い合わせ記録から顧客の生の文言を引き、QBR資料から社内の対応履歴を拾っています。

顧客の文言はこう引用されました。

箱を開けたら商品の角が潰れていました
外箱にも凹みがあり、緩衝材はほとんど入っていない状態
同じ商品を以前も購入したが、今回も箱が潰れている

そして倉庫チームからの梱包資材に関する指摘、2024年Q3の梱包仕様変更とQ4時点での効果検証中、というところまで辿り着いています。

コードから始めて、顧客の文言で裏を取り、社内の対応履歴まで繋ぐ。 テーブルだけでもドキュメントだけでも到達できない結論です。この機能の価値がいちばん分かりやすく出た回答でした。

広い問いには確認の一手を挟む

最後に、ドキュメントが「うまくいきません」の例として挙げている種類の質問を投げてみました。

このボリューム内のすべての問い合わせ記録を要約してください

返ってきたのは4カテゴリに分類した要約でした。商品破損10件、返品希望8件、配送遅延6件、一般問い合わせ4件。よく整理されていますが、最初のカテゴリの件数が違います。正解は12件です。

ここで、読んだ範囲を確認してみます。

その要約は何件のファイルを実際に読んで作成しましたか。読んだファイル名を挙げてください

エージェントは前回の回答が不正確だったことを認め、30件のファイル名をすべて列挙した上で、商品破損は12件だったと訂正しました。

念のため、ファイル名からは分からない情報で裏を取ります。注文IDはファイル名に入っていますが、顧客IDは本文にしか書いていません。

30件それぞれについて、記録されている注文IDと顧客IDの対応表を作成してください

結果は全件正解でした。さらに「顧客C0003は3件の問い合わせを行っています」といった重複の指摘まで付いてきて、これも4組すべて正しい。ファイル名からは絶対に導けない情報なので、30件の本文を読んでいることになります。

思考トレースを見ると「続けて残りのチケットを検索します」というステップが入っていました。検索を複数回に分けて全件を回収しています。ドキュメントには質問ごとに最大5ファイルとありますが、これは1回の検索あたりの上限で、多段推論と組み合わさると質問全体ではそれを超えられるようです。

実務的な教訓としては、広い問いには確認の一手を挟むと精度が上がる、ということになります。1回目の要約は数件のサンプルから組み立てられていて、件数がずれていました。読んだ範囲を尋ねると全件を読み直して訂正してきます。ドキュメントが「質問の対象を少数のファイルに限定してください」と書いているのは、この不安定さを踏まえた推奨として読むのが良さそうです。

質問を絞れるなら絞る。絞れない広い問いを投げるなら、返ってきた数字を鵜呑みにせず一度確認を入れる。この2つで実用上はかなり安定します。

事前に押さえておく要件

エンタイトルメントが最初の関門

一般要件はUnity Catalogの有効化、AI Gateway (ベータ版) の有効化、エージェントモードのリージョン提供、対象ボリュームへの READ VOLUME です。

そのうえで注意したいのが、エージェントのすべてのユーザーにワークスペースアクセスとDatabricks SQLアクセスの両方のエンタイトルメントが必要という点です。Genieの他の機能はワークスペースアクセスなしでも使えますが、この機能は両方を要求します。コンシューマーのみのユーザー、Databricks SQLのみのユーザー、アカウントのみのユーザーは対象外です。

ビジネスユーザーにコンシューマーアクセスだけを付与して展開している組織は、そのままでは使えません。パイロットの対象者を決める前にエンタイトルメントの管理を確認しておくことをおすすめします。

また、ワークスペース管理者が プレビュー ページで「Genieエージェントによるボリューム内のファイル分析」をオンにする必要があります。Databricksのプレビューを管理するを参照してください。

権限は常に質問するユーザーのものが使われます。作成者の権限で読まれるわけではないので、展開時には利用者側の READ VOLUME を忘れずに。

ボリュームとファイルの制限

項目	制限
エージェントにアタッチできるボリューム数	最大10
1ボリュームあたりのファイル数	合計500まで (TXT・MDはカウント対象外)
対応ファイルタイプ	PDF、JPG、JPEG、PNG、TIFF、TIF、DOC、DOCX、PPT、PPTX
1ファイルのサイズ	10 MBまで

エラーの出方が非対称なので注意が必要です。500ファイルを超えるボリュームへの質問は エラーになります が、非対応のファイルタイプと10 MBを超えるファイルは 無視されて処理が続きます 。後者は回答が返ってくるだけに気づきにくいので、重要な資料が落ちていないかは最初に確認しておきたいところです。

ボリューム全体が処理対象になる

アタッチできるのはボリューム単位で、フォルダやファイルの一部を選ぶことはできません。既存のボリュームが何でも置く場所になっている場合、そのままアタッチすると無関係なファイルまで検索対象に入ります。

今回、規程・問い合わせ記録・レビュー資料を3本に分けたのはこのためです。役割ごとに分けておくと説明も書きやすく、エージェントが引くべきボリュームを選びやすくなります。機能を試す前にボリューム設計の話になる、という順序は意識しておくと良さそうです。

精度を出すための設計

ドキュメントの推奨事項は4つです。実際に触ってみて、それぞれ納得感がありました。

明確な説明を追加する: 検索の入口になります。Unity Catalogのコメントで済むので、ボリューム作成時に書いてしまうのが楽です
重複するコンテンツを避ける: 同じ情報を含む複数のボリュームは取得を難しくします
無関係なファイルを避ける: エージェントのドメインに関係するファイルだけを入れます
わかりやすいファイル名を使う: 今回は ticket_0001_damaged_packaging_O000170.docx のように、連番・テーマ・注文IDを入れました

ファイル名については、注文IDを入れておいたことが効いていた場面がありました。個別の注文について聞いたときに、目的のファイルを一発で引き当てています。

他の選択肢との使い分け

手元のCSVやExcelを1つの会話に持ち込みたいだけなら、ボリュームではなくファイルのアップロードを使います。ボリュームは「エージェントに恒久的に持たせるドキュメント群」、アップロードは「今回の会話限りの持ち込み」という住み分けです。

モデルの選択やチャンク戦略まで細かく制御したい場合は、カスタムのスーパーバイザーエージェントという選択肢になります。逆に言うと、そこを気にしないで済むのがこの機能の手軽さです。今回の検証でも、チャンクや埋め込みについては何も設定していません。

Genie Oneは全社の統合エントリポイントで、ファイルに関する質問に答えるためにGenie Agentを呼び出せます。特定ドメインの専門エージェントを作るのがボリュームのアタッチ、その入口がGenie One、という関係です。

AgentモードのAPI経由でもボリューム内のファイルを分析できます。

制限事項と課金

ベータ期間中の制限です。

AWS GovCloudでは利用できない
コンシューマーのみ、Databricks SQLのみ、アカウントのみのユーザーは利用できない
GoogleドライブやSharePointなどの外部ファイルは分析できない
Web検索ツールは利用できない

外部ファイルを分析できない点は導入時に議論になるはずです。分析したいドキュメントをUnity Catalogボリュームに集約する経路を先に用意しておく必要があります。

課金は2段階です。質問すると、まず関連ファイルの取得と処理が走り、これが基盤モデルサービングのコスト (トークン単位の従量課金) としてServerlessリアルタイム推論のSKUで請求されます。取得したコンテンツに基づく推論の部分は、標準のGenie使用量として請求されます。

構造化データだけを扱っていたときと比べると、1質問あたりのコストがファイルの量と大きさに影響されます。全社展開の前に、パイロットで実際の消費量を見ておくのが安全です。

まとめ

ボリュームをアタッチして一通り触ってみて分かったことをまとめます。

構造化データとドキュメントを1つの会話で横断でき、回答にはソースごとの引用が付く
SQLの結果として得た値を検索キーにしてドキュメントを引く という多段の使い方ができる
ボリュームの説明はUnity Catalogのコメントが引き継がれる。作成時に書いておけばよい
テーブルとボリュームは同じデータ選択ダイアログに並ぶ。対等な「ソース」として扱われている
通貨が混在していれば安易に合算しない。テーブル側のメタデータも回答の質に効く
引くファイルは毎回同じとは限らない。同じ質問でも回答の構成は揺れる
広い問いには確認の一手を挟むと精度が上がる。読んだ範囲を尋ねると全件を読み直して訂正してくる
すべてのユーザーにワークスペースアクセスとDatabricks SQLアクセスの両方が必要
フォルダ単位のアタッチはできない。ボリュームの切り方が設計の起点になる

一番の収穫は、返品理由コードから顧客の生の声、そして社内の対応履歴まで一息に繋がった回答でした。テーブルに DAMAGED としか書かれていない事象について、なぜそれが起きているのかをドキュメント側から引いてくる。BIツールとドキュメント検索を行き来していた作業が1つの質問に収まる、というのはやってみると想像以上でした。

準備の手間はほとんどがボリューム設計とドキュメントの整理で、機能そのものの設定は数クリックです。チャンク戦略も埋め込みモデルも選ばずに済むぶん、力を入れるべきところがデータの置き方に寄っている。非構造化データを扱う仕組みとしては、むしろ健全な形だと思います。