databricks-apps-python

Databricks Applications — Python バックエンド

まず、このスキルが適切かどうかを確認してください。 新しい Databricks Apps では、デフォルトで databricks-apps（AppKit — Node.js + TypeScript + React SDK）を使用します。ユーザーが Python バックエンドを明示的に希望している場合、既存の Python アプリを拡張する場合、またはチームが Python のみを使用している場合を除き、まずそのスキルを読み込んでください。以下は Python バックエンドの代替手段です。

Python アプリの重要なルール（常に従ってください）

• 必須 フレームワークの選択を確認するか、以下のPython フレームワークの選択を使用してください
• 必須 認証には SDK の Config() を使用してください（トークンをハードコードしないでください）
• 必須 リソースには app.yaml の valueFrom を使用してください（リソース ID をハードコードしないでください）
• 必須 Dash アプリのレイアウトとスタイルには dash-bootstrap-components を使用してください
• 必須 Streamlit のデータベース接続には @st.cache_resource を使用してください
• 必須 Flask は Gunicorn、FastAPI は uvicorn でデプロイしてください（開発サーバーは使用しないでください）

Python アプリの必須手順

このチェックリストをコピーして、各項目を確認してください：

- [ ] Framework selected
- [ ] Auth strategy decided: app auth, user auth, or both
- [ ] App resources identified (SQL warehouse, Lakebase, serving endpoint, etc.)
- [ ] Backend data strategy decided (SQL warehouse, Lakebase, or SDK)
- [ ] Deployment method: CLI or DABs

---

Python フレームワークの選択

フレームワーク	最適な用途	app.yaml コマンド
FastAPI（デフォルト）	デフォルトであらゆる Python バックエンド — 非同期 API、自動生成される OpenAPI ドキュメント、JSON を提供するアプリ	["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
Flask	カスタム REST API、軽量アプリ、Webhook	["gunicorn", "app:app", "-w", "4", "-b", "0.0.0.0:8000"]
Dash	本番環境向けダッシュボード、BI ツール、複雑なインタラクティブ機能	["python", "app.py"]
Streamlit	迅速なプロトタイピング、データサイエンスアプリ、UI が一連の Python ウィジェットで構成される内部ツール	["streamlit", "run", "app.py"]
Gradio	ML デモ、モデルインターフェース、チャット UI	["python", "app.py"]
Reflex	JavaScript を使わないフルスタック Python アプリ	["reflex", "run", "--env", "prod"]

デフォルト：FastAPI。 ユーザーが Streamlit 形式のウィジェットによるプロトタイピング（Streamlit）、大規模なダッシュボードグリッド（Dash）、または Gradio 形式の ML デモを明示的に希望していない限り、FastAPI を選択してください。FastAPI は、JS/HTML フロントエンドや JSON を利用する呼び出し元と自然に連携します。これは databricks-apps が Node 側で採用している方式と同じです。

---

クイックリファレンス

概念	詳細
ランタイム	Python 3.11、Ubuntu 22.04、2 vCPU、6 GB RAM
プリインストール済み	Dash 2.18.1、Streamlit 1.38.0、Gradio 4.44.0、Flask 3.0.3、FastAPI 0.115.0
認証（アプリ）	Config() を介したサービスプリンシパル — DATABRICKS_CLIENT_ID/DATABRICKS_CLIENT_SECRET が自動注入されます
認証（ユーザー）	x-forwarded-access-token ヘッダー — references/1-authorization.mdを参照してください
リソース	app.yaml の valueFrom — references/2-app-resources.mdを参照してください
SDK / Foundation Models / Vector Search / Model Serving	databricks-python-sdk スキルを使用してください。同じ WorkspaceClient と OpenAI 互換の基盤モデルのパターンを Databricks App 内でも利用できます。UC モデルサービス（system.ai.*）については、references/2-app-resources.mdのモデルサービスに関する注記と、databricks-unity-gateway スキルを参照してください
ドキュメント	https://docs.databricks.com/dev-tools/databricks-apps/

---

詳細ガイド

認証：references/1-authorization.mdは、アプリまたはユーザーの認証を設定する場合に使用します。サービスプリンシパル認証、ユーザーに代わるトークン、OAuth スコープ、フレームワークごとのコード例について説明しています。（キーワード：OAuth、サービスプリンシパル、ユーザー認証、ユーザーに代わる認証、アクセストークン、スコープ）

アプリのリソース：references/2-app-resources.mdは、アプリを Databricks のリソースに接続する場合に使用します。SQL ウェアハウス、Lakebase、モデルサービング、シークレット、ボリューム、valueFromパターンについて説明しています。（キーワード：リソース、valueFrom、SQL ウェアハウス、モデルサービング、シークレット、ボリューム、接続）

フレームワーク：フレームワークごとの Databricks 固有のパターンについては、references/3-frameworks.mdを参照してください。FastAPI（デフォルト）、Flask、Dash、Streamlit、Gradio、Reflexを対象に、認証の統合方法とデプロイコマンドを説明しています。（キーワード：FastAPI、Flask、Dash、Streamlit、Gradio、Reflex、フレームワークの選択）

デプロイ：アプリをデプロイする場合は、references/4-deployment.mdを使用します。Databricks CLI、Declarative Automation Bundles（DABs）、app.yaml の設定、デプロイ後の検証について説明しています。（キーワード：デプロイ、CLI、DABs、アセットバンドル、app.yaml、ログ）

Lakebase：アプリのデータレイヤーとして Lakebase（PostgreSQL）を使用する場合は、references/5-lakebase.mdを使用します。自動挿入される環境変数、psycopg2/asyncpg のパターン、Lakebase と SQL ウェアハウスの選択基準について説明しています。（キーワード：Lakebase、PostgreSQL、psycopg2、asyncpg、トランザクション、PGHOST）

CLI コマンド：CLI でアプリのライフサイクルを管理するには、references/6-cli-approach.mdを使用します。アプリの作成、デプロイ、監視、削除について説明しています。（キーワード：CLI、アプリの作成、アプリのデプロイ、アプリのログ）

Foundation Models / SDK / Vector Search / Model Serving：OpenAI 互換の基盤モデルクライアント、WorkspaceClientの呼び出し、Vector Search、モデルサービングの呼び出しには、**databricks-python-sdkスキルを使用してください。同じパターンを Databricks App 内でも使用できます。このスキルのexamples/フォルダーにある例（fm-minimal-chat.py、fm-parallel-calls.py、fm-structured-outputs.py、llm_config.py）では、App 側の接続方法のみを示しています。UC モデルサービス（system.ai.*、/ai-gateway/mlflow/v1で呼び出し）については、references/2-app-resources.mdのモデルサービスに関する注記と、databricks-unity-gateway**スキルを参照してください。

---

ワークフロー

1. タスクの種類を判断します。

   新しいアプリをゼロから作成しますか？ → まず**databricks-apps**を読み込みます（AppKit / Node）。ユーザーが Python バックエンドを明示的に求めている場合に限り、このスキルを使用してください。 Python バックエンドを使用することが確定していますか？ → Python フレームワークの選択を参照してください。デフォルトは FastAPI です。 認証を設定しますか？ → references/1-authorization.mdを読んでください。 データ／リソースに接続しますか？ → references/2-app-resources.mdを読んでください。 Lakebase（PostgreSQL）を使用しますか？ → references/5-lakebase.mdを読んでください。 Databricks にデプロイしますか？ → references/4-deployment.mdを読んでください。 アプリのライフサイクルに CLI を使用しますか？ → references/6-cli-approach.mdを読んでください。 基盤モデル／LLM API、Vector Search、またはモデルサービングのエンドポイントを呼び出しますか？ → **databricks-python-sdk**スキルを読み込んでください。このスキルのexamples/フォルダーでは、それらの SDK パターンを利用した App 側の接続方法のみを示しています。

2. 該当するガイドの手順に従ってください。

---

コアアーキテクチャ

すべての Python Databricks アプリは、次のパターンに従います。

app-directory/
├── app.py                 # Main application (or framework-specific name)
├── models.py              # Pydantic data models
├── backend.py             # Data access layer
├── requirements.txt       # Additional Python dependencies
├── app.yaml               # Databricks Apps configuration
└── README.md

バックエンド切り替えパターン

import os
from databricks.sdk.core import Config

USE_MOCK = os.getenv("USE_MOCK_BACKEND", "true").lower() == "true"

if USE_MOCK:
    from backend_mock import MockBackend as Backend
else:
    from backend_real import RealBackend as Backend

backend = Backend()

SQL ウェアハウス接続（すべてのフレームワークで共通）

from databricks.sdk.core import Config
from databricks import sql

cfg = Config()  # Auto-detects credentials from environment
conn = sql.connect(
    server_hostname=cfg.host,
    http_path=f"/sql/1.0/warehouses/{os.getenv('DATABRICKS_WAREHOUSE_ID')}",
    credentials_provider=lambda: cfg.authenticate,
)

Pydantic モデル

from pydantic import BaseModel, Field
from datetime import datetime
from enum import Enum

class Status(str, Enum):
    ACTIVE = "active"
    PENDING = "pending"

class EntityOut(BaseModel):
    id: str
    name: str
    status: Status
    created_at: datetime

class EntityIn(BaseModel):
    name: str = Field(..., min_length=1)
    status: Status = Status.PENDING

---

よくある問題

問題	解決策
接続数の上限に達した	@st.cache_resource（Streamlit）またはコネクションプーリングを使用します
認証トークンが見つからない	x-forwarded-access-token ヘッダーを確認します。このヘッダーはデプロイ時にのみ利用でき、ローカルでは利用できません
アプリが起動しない	app.yaml のコマンドがフレームワークと一致しているか確認します。databricks apps logs <name> も確認してください
リソースにアクセスできない	UI からリソースを追加し、SP に権限があることを確認して、app.yaml で valueFrom を使用します
デプロイ時にインポートエラーが発生する	不足しているパッケージを requirements.txt に追加します（プリインストール済みのパッケージは記載不要です）
Lakebase アプリが起動時にクラッシュする	psycopg2／asyncpg はプリインストールされていません。requirements.txt に必ず追加してください
ポートが競合する	アプリは DATABRICKS_APP_PORT 環境変数にバインドする必要があります（デフォルトは 8000）。8080 は使用しないでください。Streamlit は自動設定されます。それ以外の場合は、コード内で環境変数を読み取るか、app.yaml のコマンドで 8000 を使用します
Streamlit：set_page_config エラー	st.set_page_config() は Streamlit の最初のコマンドでなければなりません
Dash：スタイルが適用されないレイアウト	dash-bootstrap-components を追加し、dbc.themes.BOOTSTRAP を使用します
クエリが遅い	トランザクション処理や低レイテンシが必要な場合は Lakebase を、分析クエリには SQL ウェアハウスを使用します

---

プラットフォームの制約

制約	詳細
ランタイム	Python 3.11、Ubuntu 22.04 LTS
コンピューティング	2 vCPU、メモリ 6 GB（デフォルト）
プリインストール済みフレームワーク	Dash、Streamlit、Gradio、Flask、FastAPI、Shiny
カスタムパッケージ	アプリのルートにある requirements.txt に追加します
ネットワーク	アプリは Databricks API にアクセスできます。外部アクセスの可否はワークスペースの設定によって異なります
ユーザー認証	GA で、デフォルトで有効です。管理者による有効化は不要です。スコープを追加するには user_api_scopes を宣言します

---

公式ドキュメント

• Databricks Apps の概要 — 主なドキュメントハブ
• 認可 — アプリ認証とユーザー認証
• リソース — SQL ウェアハウス、Lakebase、サービング、シークレット
• app.yaml リファレンス — コマンドと環境設定
• システム環境 — プリインストール済みパッケージ、ランタイムの詳細

関連スキル

• databricks-apps — 新しい Databricks Apps のデフォルト（AppKit / Node / TypeScript + React）です。Python バックエンドが明示的に必要な場合を除き、最初に読み込んでください
• databricks-python-sdk — WorkspaceClient、OpenAI 互換の基盤モデルクライアント、Vector Search、モデルサービングの呼び出しに対応しています。同じパターンを Databricks App 内でも使用できます
• databricks-lakebase — 永続的な PostgreSQL 状態（ブランチ機能を備えたオートスケーリング対応のマネージド PG）
• databricks-model-serving — App が呼び出す ML モデルのエンドポイントライフサイクル
• databricks-dabs — DABs を使用したアプリのデプロイ