Databricks のエージェント評価用のチュートリアル dbdemos llm-rag-chatbot を触っていて、
Unity Catalog の External Python Function（UC Python Function）を作ろうとしたらハマったので、その学びをまとめる。
結論、リージョン非対応そのものが原因だった。
経緯
1. エラーの発端：初期化ができない
UC に Python 関数を登録しようとして、まずは以下を実行した。
from unitycatalog.ai.core.databricks import DatabricksFunctionClient
client = DatabricksFunctionClient()
このコードは、DatabricksのUnity CatalogでAI関数を扱うためのクライアントを初期化している。
DatabricksFunctionClient は、Unity Catalog上で関数を作成・管理・実行するための専用インターフェイスで、DatabricksのAI Functions機能を利用する際の基本となるコンポーネント。
ただし、上記を実行するとこのエラー。
PERMISSION_DENIED: Cannot access Spark Connect.
最初は「権限がないのかな？」と思ってたけど、違う様子。
以下のドキュメントより、サーバレスコンピュートが必須であること を確認した。
自分はVM ベースの Classic Computeを使用していた。
Unity カタログ関数を実行するには:
運用環境で AI エージェント ツールとして Unity カタログ機能を実行するには、ワークスペースでサーバーレス コンピューティングを有効にする必要があります。 サーバーレス コンピューティング要件を参照してください。
2. Japan Westではサーバレスコンピュートが提供されていなかった
社内の検証環境がJapan Westだったため、特に考えず色々やっていたが、
Japan Westではサーバレスコンピュートがまだ使用できないようだった。
今回の検証を行う場合、別のリージョンにデプロイしたワークスペースが必要ということがわかった。
3. LOCALモードで実行すればいい？
ただ、上のドキュメントには以下の文章もある。
Python 関数のローカル モードの実行では、サーバーレス汎用コンピューティングを実行する必要はありません。ただし、ローカル モードは開発とテストのみを目的としています。
じゃあローカルモードで実行すればこのコンピュートでできるのでは？と思い、実行してみた。
client = DatabricksFunctionClient(execution_mode=ExecutionModeDatabricks.LOCAL)
すると、できた。
You are running in 'local' execution mode, which is intended only for development and debugging. For production, please switch to 'serverless' execution mode. Before deploying, create a client using 'serverless' mode to validate your code's behavior and ensure full compatibility.
「一旦やってるけど、本番環境ではサーバーレスに切り替えてちょー」とのこと。
4. LOCALにしても内部でサーバレスに接続しようとする
クライアントを LOCAL モードで初期化できたので、
ついに Python 関数を Unity Catalog にデプロイできると思い、次を実行した。
python_tool_uc_info = client.create_python_function(
func=calculate_math_expression,
catalog='main',
schema=dbName,
replace=True
)
create_python_function() は、Python 関数を External Python Function として
Unity Catalog に登録するメソッド。
ところが、ここでまた最初と同じエラーが発生する。
PERMISSION_DENIED: Cannot access Spark Connect.
スタックトレースをよく確認すると、
create_python_function() の内部で呼ばれる
DatabricksFunctionClient.set_spark_session() → initialize_spark_session() の中で
SparkSession.builder.serverless(True)
が選択されていることが分かった。
つまり、たとえこちらが execution_mode=LOCAL を指定していても、
関数を UC にデプロイする処理だけは “Serverless Spark 用のセッション” を前提に動くコードパスになっている。
このため、ワークスペース側に Serverless Runtime / Spark Connect が存在しない場合は、
内部的に Serverless への接続を試みた時点で必ず落ちる。
結論として、
- External Python Function（UC Python Function）は
Serverless Spark 上での実行が前提の仕組み - そのため、 VM ベースのクラスタ（Personal Compute / Shared Compute）だけの環境ではデプロイできない
という仕様であることがわかった。
まとめ
今回、Databricks の RAG エージェントを作成しようとする中で、
Unity Catalog の External Python Function（UC Python Function）をデプロイできない問題にぶつかった。
最初は「権限の問題？」「Classic Compute の制約？」と考えていたが、
サーバレスコンピュートとリージョンに強く依存する機能だったことが分かった。
今回の検証で得たポイントは次の通り。
- Unity Catalog External Python Function は Serverless Spark 前提で設計されている
- Databricks の機能は リージョン × SKU × Runtime に強く制約される
- なかでも Serverless 系機能はリージョン依存が特に大きい
- Japan West では Serverless 自体が未対応のため、ワークスペースの配置が重要
- 単純な権限設定の問題ではなく、“そもそも Workspace に機能が存在しない” というケースがある
そのため、Databricks の AI エージェントや UC Functions を使う際は、まず最初に
- 対応リージョンか？
- SKU は Premium 以上か？
- Serverless Runtime が UI に表示されているか？
などを確認することが、トラブル回避に重要だと実感した。
Discussion