Back to Details

databricks-apps-python

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Databricks Applications — Python backends

Databricks 应用——Python 后端

First, confirm this skill is the right one. The default for new Databricks Apps is databricks-apps (AppKit — Node.js + TypeScript + React SDK). Load that skill first unless the user explicitly asks for a Python backend, is extending an existing Python app, or the team is Python-only. Everything below is the Python-backend alternative.
**首先，请确认本技能是合适的选择。**新建 Databricks App 的默认方案是 databricks-apps（AppKit — Node.js + TypeScript + React SDK）。除非用户明确要求 Python 后端、扩展现有 Python 应用，或团队仅使用 Python，否则请优先加载该技能。以下内容是 Python 后端的替代方案。

Critical Rules for Python apps (always follow)

Python 应用的核心规则（必须遵守）

  • MUST confirm framework choice or use Python Framework Selection below
  • MUST use SDK 
    Config()
    for authentication (never hardcode tokens)
  • MUST use 
    app.yaml
    valueFrom
    for resources (never hardcode resource IDs)
  • MUST use 
    dash-bootstrap-components
    for Dash app layout and styling
  • MUST use 
    @st.cache_resource
    for Streamlit database connections
  • MUST deploy Flask with Gunicorn, FastAPI with uvicorn (not dev servers)
  • 必须确认框架选择，或使用下方的Python框架选择
  • 必须使用 SDK 
    Config()
    进行认证（绝对不要硬编码令牌）
  • 必须在 
    app.yaml
    中使用 
    valueFrom
    配置资源（绝对不要硬编码资源 ID）
  • 必须使用 
    dash-bootstrap-components
    构建 Dash 应用的布局与样式
  • 必须为 Streamlit 数据库连接使用 
    @st.cache_resource
  • 必须使用 Gunicorn 部署 Flask，使用 uvicorn 部署 FastAPI（不要使用开发服务器）

Required Steps for Python apps

Python 应用的必备步骤

Copy this checklist and verify each item:
- [ ] 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
复制以下清单并逐一验证：
- [ ] 已选择框架
- [ ] 已确定认证策略：应用认证、用户认证，或两者兼用
- [ ] 已识别应用资源（SQL 仓库、Lakebase、服务端点等）
- [ ] 已确定后端数据策略（SQL 仓库、Lakebase 或 SDK）
- [ ] 已确定部署方式：CLI 或 DABs

Python Framework Selection

Python 框架选择

FrameworkBest Forapp.yaml Command
FastAPI (default)Any Python backend by default — async APIs, auto-generated OpenAPI docs, JSON-serving apps
["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
FlaskCustom REST APIs, lightweight apps, webhooks
["gunicorn", "app:app", "-w", "4", "-b", "0.0.0.0:8000"]
DashProduction dashboards, BI tools, complex interactivity
["python", "app.py"]
StreamlitRapid prototyping, data science apps, internal tools where the UI is a series of Python widgets
["streamlit", "run", "app.py"]
GradioML demos, model interfaces, chat UIs
["python", "app.py"]
ReflexFull-stack Python apps without JavaScript
["reflex", "run", "--env", "prod"]
Default: FastAPI. Reach for FastAPI unless the user explicitly asks for Streamlit-style widget prototyping (Streamlit), a heavy dashboard grid (Dash), or a Gradio-style ML demo. FastAPI pairs naturally with a JS/HTML frontend or a JSON-consuming caller — the same posture 
databricks-apps
uses on the Node side.
框架适用场景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快速原型开发、数据科学应用、以 Python 组件为核心的内部工具
["streamlit", "run", "app.py"]
GradioML 演示、模型交互界面、聊天 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 端的架构一致。

Quick Reference

快速参考

ConceptDetails
RuntimePython 3.11, Ubuntu 22.04, 2 vCPU, 6 GB RAM
Pre-installedDash 2.18.1, Streamlit 1.38.0, Gradio 4.44.0, Flask 3.0.3, FastAPI 0.115.0
Auth (app)Service principal via 
Config()
— auto-injected 
DATABRICKS_CLIENT_ID
/
DATABRICKS_CLIENT_SECRET
Auth (user)
x-forwarded-access-token
header — see references/1-authorization.md
Resources
valueFrom
in app.yaml — see references/2-app-resources.md
SDK / Foundation Models / Vector Search / Model ServingUse the 
databricks-python-sdk
skill — same 
WorkspaceClient
and OpenAI-compatible foundation-model patterns work inside a Databricks App
Docshttps://docs.databricks.com/dev-tools/databricks-apps/
概念详情
运行时Python 3.11，Ubuntu 22.04，2 vCPU，6 GB 内存
预安装组件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 / 基础模型 / 向量搜索 / 模型服务使用 
databricks-python-sdk
技能——Databricks App 内可使用相同的 
WorkspaceClient
和兼容 OpenAI 的基础模型模式
文档https://docs.databricks.com/dev-tools/databricks-apps/

Detailed Guides

详细指南

Authorization: Use references/1-authorization.md when configuring app or user authorization — covers service principal auth, on-behalf-of user tokens, OAuth scopes, and per-framework code examples. (Keywords: OAuth, service principal, user auth, on-behalf-of, access token, scopes)
App resources: Use references/2-app-resources.md when connecting your app to Databricks resources — covers SQL warehouses, Lakebase, model serving, secrets, volumes, and the 
valueFrom
pattern. (Keywords: resources, valueFrom, SQL warehouse, model serving, secrets, volumes, connections)
Frameworks: See references/3-frameworks.md for Databricks-specific patterns per framework — FastAPI (default), Flask, Dash, Streamlit, Gradio, Reflex — with auth integration and deployment commands. (Keywords: FastAPI, Flask, Dash, Streamlit, Gradio, Reflex, framework selection)
Deployment: Use references/4-deployment.md when deploying your app — covers Databricks CLI, Asset Bundles (DABs), app.yaml configuration, and post-deployment verification. (Keywords: deploy, CLI, DABs, asset bundles, app.yaml, logs)
Lakebase: Use references/5-lakebase.md when using Lakebase (PostgreSQL) as your app's data layer — covers auto-injected env vars, psycopg2/asyncpg patterns, and when to choose Lakebase vs SQL warehouse. (Keywords: Lakebase, PostgreSQL, psycopg2, asyncpg, transactional, PGHOST)
CLI commands: Use references/6-cli-approach.md for managing app lifecycle via CLI — covers creating, deploying, monitoring, and deleting apps. (Keywords: CLI, create app, deploy app, app logs)
Foundation Models / SDK / Vector Search / Model Serving: Use the databricks-python-sdk skill for the OpenAI-compatible foundation-model client, 
WorkspaceClient
calls, Vector Search, and model-serving invocation — the same patterns apply inside a Databricks App. The examples in this skill's 
examples/
folder (
fm-minimal-chat.py
, 
fm-parallel-calls.py
, 
fm-structured-outputs.py
, 
llm_config.py
) show the App-side wiring only.
认证：配置应用或用户认证时，请参考 references/1-authorization.md——涵盖服务主体认证、代表用户令牌、OAuth 权限范围，以及各框架的代码示例。（关键词：OAuth、服务主体、用户认证、代表用户、访问令牌、权限范围）
应用资源：将应用连接到 Databricks 资源时，请参考 references/2-app-resources.md——涵盖 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、资产包（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、创建应用、部署应用、应用日志）
基础模型 / SDK / 向量搜索 / 模型服务：兼容 OpenAI 的基础模型客户端、
WorkspaceClient
调用、向量搜索、模型服务调用，请使用 databricks-python-sdk 技能。本技能的 
examples/
文件夹（
fm-minimal-chat.py
、
fm-parallel-calls.py
、
fm-structured-outputs.py
、
llm_config.py
）仅展示 App 端的对接代码。

Workflow

工作流程

  1. Determine the task type:
    New app from scratch? → Load databricks-apps first (AppKit / Node). Only stay in this skill if the user explicitly asks for a Python backend. Python-backend confirmed? → Python Framework Selection — default to FastAPI. Setting up authorization? → Read references/1-authorization.md Connecting to data/resources? → Read references/2-app-resources.md Using Lakebase (PostgreSQL)? → Read references/5-lakebase.md Deploying to Databricks? → Read references/4-deployment.md Using CLI for app lifecycle? → Read references/6-cli-approach.md Calling foundation model / LLM APIs, Vector Search, or model-serving endpoints? → Load the databricks-python-sdk skill. This skill's 
    examples/
    folder shows only the App-side wiring on top of those SDK patterns.
  2. Follow the instructions in the relevant guide.
  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、向量搜索或模型服务端点？ → 加载 databricks-python-sdk 技能。本技能的 
    examples/
    文件夹仅展示基于这些 SDK 模式的 App 端对接代码。
  2. 遵循对应指南中的说明操作。

Core Architecture

核心架构

All Python Databricks apps follow this pattern:
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
所有 Databricks Python 应用遵循以下结构：
app-directory/
├── app.py                 # 主应用文件（或框架专属命名）
├── models.py              # Pydantic 数据模型
├── backend.py             # 数据访问层
├── requirements.txt       # 额外 Python 依赖
├── app.yaml               # Databricks Apps 配置文件
└── README.md

Backend Toggle Pattern

后端切换模式

python
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()
python
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 Warehouse Connection (shared across all frameworks)

SQL 仓库连接（所有框架通用）

python
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,
)
python
from databricks.sdk.core import Config
from databricks import sql

cfg = Config()  # 自动从环境中检测凭据
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 Models

Pydantic 模型

python
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
python
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

Common Issues

常见问题

IssueSolution
Connection exhaustedUse 
@st.cache_resource
(Streamlit) or connection pooling
Auth token not foundCheck 
x-forwarded-access-token
header — only available when deployed, not locally
App won't startCheck 
app.yaml
command matches framework; check 
databricks apps logs <name>
Resource not accessibleAdd resource via UI, verify SP has permissions, use 
valueFrom
in app.yaml
Import error on deployAdd missing packages to 
requirements.txt
(pre-installed packages don't need listing)
Lakebase app crashes on start
psycopg2
/
asyncpg
are NOT pre-installed — MUST add to 
requirements.txt
Port conflictApps must bind to 
DATABRICKS_APP_PORT
env var (defaults to 8000). Never use 8080. Streamlit is auto-configured; for others, read the env var in code or use 8000 in app.yaml command
Streamlit: set_page_config error
st.set_page_config()
must be the first Streamlit command
Dash: unstyled layoutAdd 
dash-bootstrap-components
; use 
dbc.themes.BOOTSTRAP
Slow queriesUse Lakebase for transactional/low-latency; SQL warehouse for analytical queries
问题解决方案
连接耗尽使用 
@st.cache_resource
（Streamlit）或连接池
未找到认证令牌检查 
x-forwarded-access-token
请求头——仅部署后可用，本地环境不可用
应用无法启动检查 
app.yaml
命令与框架匹配；查看 
databricks apps logs <name>
资源无法访问通过 UI 添加资源，验证服务主体权限，在 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 仓库

Platform Constraints

平台限制

ConstraintDetails
RuntimePython 3.11, Ubuntu 22.04 LTS
Compute2 vCPUs, 6 GB memory (default)
Pre-installed frameworksDash, Streamlit, Gradio, Flask, FastAPI, Shiny
Custom packagesAdd to 
requirements.txt
in app root
NetworkApps can reach Databricks APIs; external access depends on workspace config
User authPublic Preview — workspace admin must enable before adding scopes
限制详情
运行时Python 3.11，Ubuntu 22.04 LTS
计算资源2 vCPU，6 GB 内存（默认）
预安装框架Dash、Streamlit、Gradio、Flask、FastAPI、Shiny
自定义包添加到应用根目录的 
requirements.txt
网络应用可访问 Databricks API；外部访问取决于工作区配置
用户认证公开预览阶段——工作区管理员必须先启用才能添加权限范围

Official Documentation

官方文档

Related Skills

相关技能

  • databricks-apps — the default for new Databricks Apps (AppKit / Node / TypeScript + React); load it first unless a Python backend is explicitly required
  • databricks-python-sdk — 
    WorkspaceClient
    , OpenAI-compatible foundation-model client, Vector Search, model-serving invocation; the same patterns work inside a Databricks App
  • databricks-lakebase — persistent PostgreSQL state (autoscaling managed PG with branching)
  • databricks-model-serving — endpoint lifecycle for ML models an App calls
  • databricks-dabs — deploying apps via DABs
  • databricks-apps —— 新建 Databricks App 的默认方案（AppKit / Node / TypeScript + React）；除非明确要求 Python 后端，否则优先加载该技能
  • databricks-python-sdk —— 
    WorkspaceClient
    、兼容 OpenAI 的基础模型客户端、向量搜索、模型服务调用；Databricks App 内可使用相同模式
  • databricks-lakebase —— 持久化 PostgreSQL 状态（支持分支的自动扩缩容托管 PG）
  • databricks-model-serving —— App 调用的 ML 模型端点生命周期管理
  • databricks-dabs —— 通过 DABs 部署应用