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-bootstrap-components 设置 Dash 应用的布局和样式
• 必须使用 @st.cache_resource 缓存 Streamlit 数据库连接
• 必须使用 Gunicorn 部署 Flask，使用 uvicorn 部署 FastAPI（而非开发服务器）

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	快速原型开发、数据科学应用、界面由一系列 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、服务主体、用户身份验证、代表用户、访问令牌、范围）

应用资源：将应用连接到 Databricks 资源时，请使用 references/2-app-resources.md——其中介绍 SQL 仓库、Lakebase、模型服务、机密、卷，以及 valueFrom 模式。（关键词：资源、valueFrom、SQL 仓库、模型服务、机密、卷、连接）

框架：请参阅 references/3-frameworks.md，了解各框架特有的 Databricks 模式——FastAPI（默认）、Flask、Dash、Streamlit、Gradio、Reflex——以及身份验证集成和部署命令。（关键词：FastAPI、Flask、Dash、Streamlit、Gradio、Reflex、框架选择）

部署：部署应用时，请使用 references/4-deployment.md——其中介绍 Databricks CLI、声明式自动化 Bundle（DAB）、app.yaml 配置，以及部署后的验证。（关键词：部署、CLI、DAB、资产 Bundle、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 部署应用