配置无服务器环境

本页介绍如何为笔记本和作业任务配置无服务器环境。 对于标准无服务器笔记本,使用 环境 侧面板选择基础环境,安装笔记本范围的依赖,配置内存并应用使用策略。 对于作业任务,请在创建或编辑任务时配置环境。

若要展开“环境”侧窗格,请单击笔记本右侧的环境按钮。

无服务器环境窗格

选择基础环境

基础环境确定可用于无服务器笔记本的预安装的库和环境版本。 在环境侧窗格中的“基础环境”选择器中,您可在此选择环境。 若要查看每个环境版本的详细信息,请参阅 无服务器环境版本。 Databricks 建议使用最新版本,以获取最新的笔记本功能。

基本环境选择器包含以下选项:

  • 标准:具有 Databricks 提供库的默认无服务器基础环境。

  • ML:一个基础环境,预装了 Databricks Runtime for 机器学习 中的 Python 和系统软件包。 使用此环境可将使用经典 Databricks Runtime for 机器学习 的工作负载迁移到无服务器计算。 请参阅 ML 基础环境。

  • 更多:展开以显示其他选项:

    • 标准、ML 和 AI 环境的早期版本。

    • 自定义:使用 YAML 文件指定自定义环境。

  • 工作区环境:列出管理员为工作区配置的所有兼容基本环境。

若要选择基本环境,请执行以下操作:

  1. 在笔记本 UI 中,单击 “环境 ”侧窗格 环境。

  2. 在 “基本环境”下,从下拉菜单中选择一个环境。

  3. 单击“应用”。

将依赖项添加到笔记本

由于无服务器不支持计算策略或 init 脚本,因此必须使用 “环境” 端窗格安装自定义依赖项。 你可以单独安装依赖,或者使用可共享的基础环境一次性安装多个依赖。

Azure Databricks缓存笔记本的虚拟环境,因此每次重新打开笔记本或恢复处于非活动状态后,依赖项不会重新安装。 共享同一依赖项集的作业任务也受益于运行中的此缓存。

要单独安装某个依赖项:

  1. 在笔记本 UI 中,单击 “环境 ”侧窗格 环境。

  2. 在 依赖 部分,输入依赖路径,然后点击 +添加依赖。 可以在 requirements.txt 文件中指定有效的任何格式的依赖项。 Python wheel 文件或 Python 项目(例如,包含 pyproject.toml 或 setup.py 的目录)可以位于工作区文件或 Unity 编录卷中。

    • 如果使用工作区文件,则路径应为绝对路径,以 /Workspace/开头。

    • 如果在 Unity 目录卷中使用文件,路径应采用以下格式: /Volumes/<catalog>/<schema>/<volume>/<path>.whl

  3. 单击Apply安装依赖项并重启Python进程。

    重要

    不要在无服务器笔记本上安装 PySpark 或任何将 PySpark 作为依赖项安装的库。 这样做会停止会话并导致出现错误。 如果发生这种情况,请删除库并重置环境。

若要查看已安装的依赖项,请单击“环境”侧窗格中的“已安装”选项卡。 单击窗格底部的 pip 日志 ,打开笔记本环境的 pip 安装日志。

注释

无服务器计算并不保证特定的CPU架构。 笔记本或作业可以在任意aarch64x86_64或 上运行,且架构可以在运行间发生变化。 因为依赖可能安装在与其构建时不同的架构上,你的依赖必须支持计算可能使用的每一种架构。

如果依赖是一个带有原生(C)扩展的 Python 轮子,其预建二进制是架构特定的。 为一种架构构建的轮子无法安装到另一个架构上,导致错误。 为避免这种情况,尽量使用纯Python轮子(带py3-none-any标签),或者包含两个aarch64x86_64轮子变体,并用platform_machine环境标记限制每个轮子的架构。

注释

Azure Databricks 在笔记本或任务代码运行前就解析并安装依赖。 笔记本单元中的代码无法改变依赖的获取方式。 无服务器计算也不支持计算范围的环境变量,因此在运行时应用的代理设置不会影响依赖安装。 要从私有或认证的包仓库安装,请在依赖规范中指定 index-url 或 extra-index-url 。 你也可以请工作区管理员将仓库配置为默认的包仓库。 参见 配置默认包仓库。

配置默认包存储库

工作区管理员可以将专用或经过身份验证的包存储库配置为无服务器笔记本和作业的默认 pip 源。 这样,用户就可以从内部存储库安装包,而无需指定 index-url 或 extra-index-url。 参见 配置默认包仓库。

创建自定义环境规范

可以创建和重复使用自定义环境规范。

  1. 在无服务器笔记本中,选择一个基本环境并安装所需的任何依赖项。

  2. 单击“烤肉”菜单按钮 Kebab 菜单图标。 在环境窗格底部,然后单击“ 导出环境”。

  3. 将规范保存为工作区文件或 Unity 目录卷。 请确保您有权写入目标位置,否则导出将因出现 Forbidden 错误而失败。

若要在笔记本中使用自定义环境规范,请从“基本环境”下拉菜单中选择“自定义”,然后使用文件夹文件夹图标选择 YAML 文件。

创建可在工作区中共享的常用工具

此示例将实用工具存储在工作区文件中,并将其安装为无服务器笔记本依赖项:

  1. 使用以下结构创建文件夹。 确保其他用户具有对此路径的读取访问权限:

    helper_utils/
    ├── helpers/
    │   └── __init__.py   # your common functions live here
    ├── pyproject.toml
    
  2. 按如下方式填充 pyproject.toml:

    [project]
    name = "common_utils"
    version = "0.1.0"
    
  3. 向文件添加函数 init.py 。 例如:

    def greet(name: str) -> str:
       return f"Hello, {name}!"
    
  4. 在笔记本 UI 中,单击“环境侧窗格环境”图标。

  5. 在“ 依赖项 ”部分中,单击“ 添加依赖项 ”,然后输入 util 文件的路径。 例如: /Workspace/helper_utils。

  6. 单击“应用”。

现在可以在笔记本中使用函数:

from helpers import greet
print(greet('world'))

此输出方式为:

Hello, world!

在源文件导出中包含环境

对于 Python 笔记本,可以在环境配置中切换 在源文件导出中包含 选项。 启用后,基础环境和依赖项以 PEP 723 格式存储在源文件导出中。 当笔记本存储在 Git 文件夹中 或下载为 源文件时,这有助于保留环境配置。

例如,使用 Standard v5 的笔记本会将其环境配置以内联元数据的形式导出,并放在文件顶部:

# Databricks notebook source
# /// script
# [tool.databricks.environment]
# environment_version = "5"
# ///
print("Hello World!")

重置环境依赖项

如果笔记本连接到无服务器计算,Databricks 会自动缓存笔记本虚拟环境的内容。 这意味着打开现有笔记本时,通常无需重新安装在 Environment 侧窗格中指定的Python依赖项,即使由于不活动而断开连接也是如此。

Python 虚拟环境缓存也适用于作业。 当作业运行时,与同一运行中已完成的任务共享相同依赖项集的任何任务都更快完成,因为缓存已包含所需的依赖项。

注释

如果更改无服务器作业中使用的自定义 Python 包的实现,则还必须更新其版本号,以便作业可以采用最新的实现。

若要清除环境缓存并执行附加到无服务器计算的笔记本的“ 环境 ”侧窗格中指定的依赖项的全新安装,请单击 “应用 ”旁边的箭头,然后单击“ 重置为默认值”。

如果安装了会中断或更改核心笔记本或 Apache Spark 环境的包,您应先删除这些有问题的包,然后重置环境。 启动新会话不会清除整个环境缓存。

为作业任务配置环境

每个作业任务在一个独立环境中运行,其中包括一个基本环境和你指定的任何其他库。 基本环境设置Python和 Scala 运行时版本以及预安装的库。 任务从环境版本继承已安装库的默认集。 要查看其中包含的内容,请参阅你正在使用的环境版本中的已安装的 Python 库或已安装的 Java 和 Scala 库部分。

可以使用 工作区文件、Unity 目录 卷或公共包存储库中的库来补充预安装的库。 运行时仅安装任务所需的依赖项。

重要

选择托管基础环境功能目前为 Beta 版。 通过“配置环境”对话框中的“基本环境”下拉列表,可以从 Databricks 提供的环境(例如标准环境和 ML)或工作区配置的环境中进行选择。 如果没有此功能,对话框将改为显示 环境版本 下拉列表。 工作区管理员可以从 “预览 ”页启用此功能。

“配置环境”对话框,显示已展开的“基础环境”下拉列表,其中包含“Databricks 环境”和“工作区环境”部分

按任务类型配置环境

如何在作业中配置环境取决于任务类型:

笔记本任务

笔记本任务默认为 Notebook 环境,该环境使用笔记本自己的配置基础环境和依赖项。 可以使用作业级环境替代此设置。

笔记本任务的“环境和库”下拉菜单,显示“笔记本环境”和“作业环境”选项

若要配置作业级环境,请执行以下操作:

  1. 在任务配置中,单击“ 环境和库 ”下拉菜单。

  2. 在 “作业环境”中,单击 “默认”旁边的铅笔图标,或单击“ + 添加新作业环境”。

  3. 在配置环境对话框中,在环境源下,选择标准或项目。 Project选项仅在你的工作区管理员从预览页面启用Project-Scoped Shared Compute预览时才可用。 请参阅 Manage Azure Databricks 预览版。 如果对话框没有显示 环境源,请按照 标准 步骤操作。

  4. 对于 “标准”,请从 “基本环境” 下拉菜单中进行选择:

    • Databricks 环境:Azure Databricks提供的选项,如 Standard 和 ML。

    • 工作区环境:工作区管理员配置的自定义环境。 请参阅 “管理工作区基础环境”。

    • 更多:以前的版本和 自定义 (指定 YAML 文件)。

  5. 对于 标准模式,在 依赖项下添加任何额外的库。 使用 requirements.txt 文件中有效的任何格式。 你也可以使用工作区文件或 Unity Catalog 卷的绝对路径。

  6. 对于 Project,在 Project 环境中,输入到 pyproject.toml 的工作区路径,或选择该文件。 在pyproject.toml中配置环境版本和依赖关系。 你也不能设置 基础环境 或 依赖关系。 参见使用pyproject.toml配置项目环境。

  7. 单击“确认”。

注释

如果工作区没有为作业预览启用工作区基础环境,“ 配置环境 ”对话框会显示 环境版本 下拉列表,而不是 基本环境。

若要配置环境,请选择版本,然后单击“ + 添加库”。 可以指定工作区文件路径(以 /Workspace/ 开头)、Unity Catalog 卷路径(以 /Volumes/ 开头)或 requirements 文件引用(例如 -r /Workspace/path/to/requirements.txt)。

Python脚本和Python轮任务

Python脚本和Python轮任务需要配置环境。

显示“添加依赖项”链接的 Python wheel 任务的环境和库部分

  1. 在任务配置中,在 “环境和库”下,单击“ + 添加依赖项”。

  2. 在配置环境对话框中,在环境源下,选择标准或项目。 Project选项仅在你的工作区管理员从预览页面启用Project-Scoped Shared Compute预览时才可用。 请参阅 Manage Azure Databricks 预览版。 如果对话框没有显示 环境源,请按照 标准 步骤操作。

  3. 对于 “标准”,请从 “基本环境” 下拉菜单中进行选择:

    • Databricks 环境:Azure Databricks提供的选项,如 Standard 和 ML。

    • 工作区环境:工作区管理员配置的自定义环境。 请参阅 “管理工作区基础环境”。

    • 更多:以前的版本和 自定义 (指定 YAML 文件)。

  4. 对于 标准模式,在 依赖项下添加任何额外的库。

  5. 对于 Project,在 Project 环境中,输入 pyproject.toml 的绝对工作区路径(例如,/Workspace/path/to/pyproject.toml),或选择该文件。 Python wheel 任务不支持相对的项目-环境路径。 在pyproject.toml中配置环境版本和依赖关系。 你也不能设置 基础环境 或 依赖关系。 参见使用pyproject.toml配置项目环境。

  6. 单击“确认”。

注释

如果工作区没有为作业预览启用工作区基础环境,“ 配置环境 ”对话框会显示 环境版本 下拉列表,而不是 基本环境。

若要配置环境,请选择版本,然后单击“ + 添加库”。 可以指定工作区文件路径(以 /Workspace/ 开头)、Unity Catalog 卷路径(以 /Volumes/ 开头)或 requirements 文件引用(例如 -r /Workspace/path/to/requirements.txt)。

Dbt 任务

DBT 任务使用作业级环境进行库配置。

显示“作业环境”选项的 dbt 任务“环境和库”下拉列表

若要配置作业级环境,请执行以下操作:

  1. 在任务配置中,单击“ 环境和库 ”下拉菜单。

  2. 在 “作业环境”中,单击现有环境旁边的铅笔图标,或单击“ + 添加新作业环境”。

  3. 在 “配置环境 ”对话框中,从 “基本环境 ”下拉菜单中进行选择:

    • Databricks 环境:Azure Databricks提供的选项,如 Standard 和 ML。

    • 工作区环境:工作区管理员配置的自定义环境。 请参阅 “管理工作区基础环境”。

    • 更多:以前的版本和 自定义 (指定 YAML 文件)。

  4. 在 “依赖项”下,添加任何其他库。 您可以使用 requirements.txt 文件中任何有效的格式指定库,也可以使用工作区文件或 Unity Catalog 卷中某个文件的绝对路径。

  5. 单击“确认”。

注释

如果工作区没有为作业预览启用工作区基础环境,“ 配置环境 ”对话框会显示 环境版本 下拉列表,而不是 基本环境。

若要配置环境,请选择版本,然后单击“ + 添加库”。 可以指定工作区文件路径(以 /Workspace/ 开头)、Unity Catalog 卷路径(以 /Volumes/ 开头)或 requirements 文件引用(例如 -r /Workspace/path/to/requirements.txt)。

JAR 任务

JAR 任务不支持工作区基础环境。 若要为 JAR 任务配置环境,请执行以下操作:

用于 JAR 任务的“环境和库”部分,其中显示“添加 JAR 依赖项”链接

  1. 在任务配置中,在 “环境和库”下,单击“ + 添加 JAR 依赖项”。

  2. 在 “配置环境” 对话框中:

    • (可选)在 “基本环境 ”字段中输入 YAML 文件的路径。

    • 从 “环境版本 ”下拉菜单中选择环境版本。

    • 在 JAR 依赖项下,将路径添加到 JAR 文件。

  3. 单击“确认”。

若要创建自定义基于 YAML 的基本环境,请参阅 “创建自定义环境规范”。

环境和计算兼容性

选择的基本环境必须与任务的计算类型兼容。 例如,为 GPU 计算生成的环境与 CPU 计算不兼容。 在作业 UI 中,不兼容的环境在基本环境下拉菜单中不可用。

配置笔记本任务时,计算类型(CPU 或 GPU)和基本环境都可以来自作业设置或笔记本设置。

  • 如果在作业级别设置硬件加速器(GPU),则还必须在作业级别选择基本环境。 不能将笔记本的环境与作业级加速器一起使用。

  • 如果你有引用笔记本的作业任务,并且更新引用的笔记本的计算类型(例如从 CPU 到 GPU),则现有任务可能与其配置的环境不兼容。 更改笔记本的计算配置后,查看作业的环境设置。

  • 对于 API 用户:如果在作业级别设置了基础环境,但笔记本定义了计算类型,Azure Databricks在运行时验证兼容性,而不是在创建作业时验证兼容性。 如果配置不兼容,则运行失败并出现错误。

使用 配置项目环境

重要

此功能在 Beta 版中。 要使用它,工作区管理员必须从预览页面开启Project-Scoped Shared Compute。 请参阅 Manage Azure Databricks 预览版。

项目环境通过 pyproject.toml 文件配置无服务器作业任务。 使用该文件声明笔记本、Python 脚本和 Python wheel 任务的依赖。 要为任务选择项目环境,请参见“配置作业任务环境”。

对于使用 Shared Serverless 的笔记本,请参阅使用 管理环境。

Requirements

  • 使用 无服务器环境版本 5及以上。

  • 将pyproject.toml存储在工作区文件中,例如/Workspace/path/to/pyproject.toml。

  • 要在project_environment中使用,请使用 Databricks CLI 1.21.0 及以上版本。

  • 当你使用 Jobs API 或捆绑包时, project_environment 必须是环境中 spec唯一的环境源字段。 省略诸如 environment_version、base_environment 和 dependencies 等字段。 改为在 pyproject.toml 中设置环境版本和依赖项。

准备项目环境

要定义 pyproject.toml 文件,请在 [project] 下声明依赖项。 在 [tool.databricks.environment] 下设置无服务器环境版本。 例如:

[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    # Keep your other dependencies here.
    "cowsay==6.1",
]

[tool.databricks.environment]
# Serverless environment version.
environment_version = "6"

对于仅安装项目依赖的作业,缺失或过期 uv.lock 会导致运行时退回到 uv pip install -r pyproject.toml。 这种回退方案从 pyproject.toml 解析依赖项,但不强制执行锁定版本,并且不安装项目包本身。

要将项目本身安装为一个包,请向 pyproject.toml 添加构建后端。 例如,要使用 Hatchling,可以添加以下内容:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Hatchling 从与项目名称匹配的源目录构建包。 例如,对于 my-project,Hatchling 使用 src/my_project/__init__.py。 Project 安装需要在 pyproject.toml 旁边放置一个最新的 uv.lock 文件。 在项目目录中生成该 uv lock 文件。

要检查 pyproject.toml 是否与 uv.lock 匹配,可以在项目目录中的 notebook 里运行以下命令:

%uv lock --check

在捆绑中配置项目环境

将 project_environment 设置为 pyproject.toml 的路径。 在部署过程中,Databricks CLI将该路径转换为工作区路径。

以下示例 bundle 安装了自己的包,my-project。 它采用了以下布局:

.
├── databricks.yml
├── pyproject.toml
├── uv.lock
├── resources/
│   └── my_project.job.yml
└── src/
    ├── main.py
    └── my_project/
        └── __init__.py

根 pyproject.toml 节点声明了依赖关系,Hatchling构建后端和环境版本:

[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    "cowsay==6.1",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.databricks.environment]
environment_version = "6"

将以下配置保存为 resources/my_project.job.yml。 project_environment和python_file路径相对于此文件:

resources:
  jobs:
    my_project_job:
      name: my-project-job
      environments:
        - environment_key: project
          spec:
            project_environment: ../pyproject.toml
      tasks:
        - task_key: main
          environment_key: project
          spark_python_task:
            python_file: ../src/main.py