管理 Databricks 应用的依赖项

Databricks 应用可以包括Python依赖项、Node.js 依赖项或两者。 在部署应用时，在特定于语言的文件中声明Azure Databricks安装的依赖项：

• 使用 requirements.txt 文件管理通过 pip 安装的 Python 包。 请参阅定义 Python 依赖项与 pip。
• 使用 pyproject.toml 文件管理通过 uv 安装的 Python 包。 请参阅定义 Python 依赖项与 uv。
• 对使用 npm 或 pnpm 安装的 Node.js 包，请使用 package.json 文件。 请参阅 定义 Node.js 依赖项。

定义 Python 依赖项，使用 pip

使用pip的应用包含一组预安装的Python库。 若要定义其他 Python 库，请使用 requirements.txt 文件。 如果列出的任何包与预安装的包匹配，则文件中的版本将替代默认值。

从标准应用转换而来的水平扩展应用（Beta）可以选择不使用预装库，改为在纯净的基础操作系统映像上运行。 请参阅选择退出 Databricks 应用预安装的 Python 库。

例如：

# Override default version of dash
dash==2.10.0

# Add additional libraries not pre-installed
requests==2.31.0
numpy==1.24.3

# Specify a compatible version range
scikit-learn>=1.2.0,<1.3.0

预安装的 Python 库

基于 pip 的应用包含以下预安装的 Python 库。 除非你需要不同的版本，否则不必将它们添加到 requirements.txt 中。

定义 Python 依赖项，使用 uv

如果应用用于 uv 依赖项管理，请在 pyproject.toml 文件中定义 Python 依赖项，而不是 requirements.txt。 基于 uv 的应用不包含预装库，因此你必须在 pyproject.toml 中声明所有依赖项。 你还可以通过 requires-python 字段指定任意 Python 版本，这一点与基于 pip 的应用不同，后者使用的是 Python 3.11。

这同样适用于选择不使用预安装库的水平扩展应用。 请参阅选择退出 Databricks 应用预安装的 Python 库。

在部署期间，Databricks Apps 根据存在的文件选择安装策略：

• 如果 requirements.txt 存在，则应用将用于 pip 安装依赖项，而不考虑是否 pyproject.toml 也存在。 requirements.txt 始终具有优先权。
• 如果requirements.txt不存在，且pyproject.toml和uv.lock都存在，则应用uv来从锁定文件安装依赖项。

安装程序 uv 创建和管理其自己的虚拟环境，因此无需创建 .venv 目录。

以下示例演示 Databricks 应用的最小值 pyproject.toml ：

[project]
name = "my-app"
requires-python = ">=3.11"
dependencies = [
    "dash==2.10.0",
    "requests==2.31.0",
]

若要使用 uv，必须将 uv.lock 文件与你的 pyproject.toml 文件一起包含。 通过在本地运行 uv lock 并将其包含在应用目录中来生成它。

定义 Node.js 依赖项

若要定义 Node.js 库，请在应用的根目录中包括一个 package.json 文件。 Azure Databricks 同时支持 npm 和 pnpm，并会根据你提供的锁定文件选择包管理器：

• 如果 pnpm-lock.yaml 存在，则应用使用 pnpm。 请参阅 “使用 pnpm”。
• 否则，应用使用 npm。
• 如果 pnpm-lock.yaml 和 package-lock.json 同时存在，则 pnpm 优先。

例如， 一个使用 Vite 的 React 应用文件可能如下所示：

{
  "name": "react-fastapi-app",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "npm run build:frontend",
    "build:frontend": "vite build frontend"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "typescript": "^5.0.0",
    "vite": "^5.0.0",
    "@vitejs/plugin-react": "^4.2.0",
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0"
  }
}

使用 pnpm

若要使用 pnpm 进行构建，请将一个 pnpm-lock.yaml 文件与您的 package.json 放在一起。 通过在本地运行 pnpm install 并将其包含在应用目录中来生成它。 Azure Databricks 通过 Corepack 提供 pnpm。

请注意以下应用要求 pnpm ：

• 依赖项通过 pnpm install --frozen-lockfile 安装，因此 pnpm-lock.yaml 必须与 package.json 保持同步。 如果包发生漂移，构建将失败，而非更新锁定文件。 更改依赖项后，使用 pnpm install 重新生成锁定文件。
• 您必须在 app.yaml 中指定启动命令。 与 npm 应用不同，pnpm 应用不会回退到默认的 start 脚本。 请参阅使用 app.yaml 配置 Databricks 应用执行。

对于 pnpm 工作区项目（其中 pnpm-workspace.yaml 存在文件），某些 app.yaml 命令以递归方式运行 pnpm 。 例如，构建或启动步骤可能会运行 pnpm -r run build。 这些命令必须调用 corepack pnpm 而不是 pnpm，以便正确解析嵌套命令。

避免版本冲突

遵循以下准则以避免版本冲突：

• 对于基于pip的应用程序，覆盖预安装的包可能会导致兼容性问题，特别是当您指定的版本与预安装的版本有显著差异时。
• 始终测试应用以验证包版本更改是否不引入错误。
• 将特定版本固定在 requirements.txt 中有助于在部署过程中保持应用程序行为的一致性。
• 使用 uv时，请包括一个 uv.lock 文件，用于跨部署进行完全可重现的安装。

依赖项安装和管理

Azure Databricks 会将 requirements.txt、pyproject.toml 和 package.json 中定义的库直接安装到在您的专用计算资源上运行的容器中。 你负责管理和修补这些依赖项。

可以在依赖项文件中指定来自多个源的库：

• 从公共存储库（如 PyPI 和 npm）下载的库
• 使用 Azure Databricks 机密中存储的凭据进行身份验证的专用存储库
• 存储在 /Volumes/ 目录中的库（例如 /Volumes/<catalog>/<schema>/<volume>/<path>）

从专用存储库安装

若要从专用存储库安装包，请配置用于身份验证的环境变量。 例如，设置 PIP_INDEX_URL 为指向您的专用存储库:

env:
  - name: PIP_INDEX_URL
    valueFrom: my-pypi-secret

工作区网络配置必须允许访问专用存储库。 请参阅 为 Databricks 应用配置网络。

从 Unity Catalog 卷安装 wheel 文件

要从存储在 Unity Catalog 卷中的 wheel 文件安装 Python 包：

1. 将 Unity 目录卷作为资源添加到应用。 请参阅 Unity 目录卷。
2. 在 requirements.txt 中直接引用 wheel 文件的完整路径。

/Volumes/<catalog>/<schema>/<volume>/my_package-1.0.0-py3-none-any.whl

若要增强访问外部包存储库时的安全性，请使用无服务器出口控制来限制对公共存储库的访问并配置专用网络。 请参阅 为 Databricks 应用配置网络。