Databricks 远程开发

重要

远程开发处于 Beta 阶段。

通过 Databricks 远程开发，可以使用 SSH 隧道访问工作区，并在 Databricks 计算资源上以交互方式运行工作负载。 设置简单，无需环境管理，并在 Databricks 工作区内保护所有代码和数据。

要求

若要使用远程开发，必须具备：

  • 在本地计算机上安装 Databricks CLI 0.269 或更高版本，并配置了身份验证。 请参阅 “安装”。
  • 运行 Databricks Runtime 17.0 或更高版本的专用（单用户）群集。 请参阅 专用计算概述。 此外：
    • 必须启用 Unity Catalog。
    • 如果计算策略存在，则它不得禁止执行作业。

设置 SSH 连接

首先，使用 databricks ssh 安装 命令设置 SSH 隧道。 将 <connection-name> 替换为连接的名称，例如 my-connection。

databricks ssh setup --name <connection-name>

CLI 会提示你选择群集。 您还可以直接使用 --cluster <cluster-id> 指定一个。

databricks ssh setup --name <connection-name> --cluster <cluster-id>

注释

对于 IntelliJ 用户，Databricks 建议将 --auto-start-cluster=false 添加到安装命令中，并在连接之前手动启动群集。 这是因为 JetBrains IDE 在启动时启动所有配置的群集，这可能会导致意外的计算费用。

连接到 Databricks

接下来，使用 IDE 或终端连接到 Databricks。

使用 Visual Studio Code 或 Cursor 进行连接

  1. 对于 Visual Studio Code，请安装 远程 SSH 扩展。 游标默认包含远程 SSH 扩展。

  2. 在 IDE 主菜单中，单击“ 查看>命令面板”。 选择 “远程 SSH：设置”。 或者，选择 “首选项：打开用户设置”（JSON） 以直接修改 settings.json 。

  3. 在 Remote.SSH: 默认扩展（或者在 remote.SSH.defaultExtensionssettings.json中），添加 ms-Python.Python 和 ms-toolsai.jupyter。

    如果要修改 settings.json：

    "remote.SSH.defaultExtensions": [
    "ms-Python.Python",
    "ms-toolsai.jupyter"
]

    注释

    （可选）增加 Remote.SSH: Connect Timeout 的值（或者在 remote.SSH.connectTimeout 中增加 settings.json），以进一步降低超时错误的可能性。 默认超时为 360。

  4. 在命令面板中，选择 “远程 SSH：连接到主机”。

  5. 从下拉列表中选择在第一步中设置的连接。 IDE 将继续在新窗口中进行连接。

使用 IntelliJ IDE 进行连接

  1. 按照 远程服务器教程 进行设置。
  2. 在新连接屏幕上，输入：
    • 用户名： root
    • 主机： <connection-name>

使用终端进行连接

ssh <connection-name>

打开项目

连接后，使用命令面板中的 “打开文件夹 ”并导航到 /Workspace/Users/<your-username>。

注释

群集重启后，/Workspace、/Volumes 和 /dbfs 中的文件会持久存留。 重启时，位于/home、/root以及其他本地路径中的文件是临时性的，会丢失。

运行代码（Visual Studio Code或Cursor）

若要使用远程开发运行代码，需要确保设置了 Databricks 虚拟环境。 此环境包括所有内置 DBR 库和 计算范围的库。

  1. 从 IDE 中的终端运行 echo $DATABRICKS_VIRTUAL_ENV 。

    示例输出： /local_disk0/.ephemeral_nfs/envs/pythonEnv-xxx/bin/python

  2. 打开命令面板并选择Python：选择解释器。 粘贴上述输出。

  3. 打开新的终端，虚拟环境应会自动激活。

  4. 若要运行 Jupyter 笔记本，请确保将虚拟环境选为内核。 单击笔记本右上角的 “选择内核 ”。

可以使用标准 Python 和 Jupyter 扩展运行和调试 Python 文件和 .ipynb 笔记本。

管理 Python 依赖项

Python依赖项可以在群集级别全局管理，也可以使用笔记本限定为单个项目。

在工作区 UI 内通过 计算 > 库安装依赖项。 这些内容在群集重启后持久存在，可用pythonEnv-xxx。 请参阅 群集库。

项目特定的笔记本设置

对于项目范围的依赖项，请在每个会话开始时运行包含 %pip install 命令的笔记本：

# Install from pyproject.toml
%pip install .

# Install from a requirements file
%pip install -r requirements.txt

# Install a wheel from Volumes or Workspace
%pip install /Volumes/catalog/schema/volume/your_library.whl

%pip 命令包括特定于 Databricks 的防护措施，并将依赖项传播到 Spark 执行程序节点。 这将启用具有自定义依赖项的用户定义函数（UDF）。

有关更多示例，请参阅 使用 %pip 命令管理库。

如果会话在 10 分钟内重新连接，则无需重新运行笔记本。 可以使用 SSH 配置中的 -shutdown-delay 来进行配置。

注释

同一群集上的多个 SSH 会话共享一个虚拟环境。

局限性

Databricks 远程开发具有以下限制：

  • 尚不支持具有多个用户和无服务器的共享群集。
  • 用于Visual Studio Code和远程开发的 Databricks 扩展尚不兼容，不应一起使用。
  • 在/Workspace、/Volumes和/dbfs之外编辑的文件将在群集重启时丢失。
  • 每个群集最多允许 10 个 SSH 连接。
  • 非活动会话可能会在 1 小时后结束。

Databricks 笔记本的不同之处

使用远程开发时笔记本存在一些差异：

  • Python 文件不定义任何 Databricks 全局文件（如 spark 或 dbutils）。 必须显式地导入from databricks.sdk.runtime import spark它们。
  • 对于 ipynb 笔记本，可以使用这些功能：
    • Databricks 全局：display、displayHTML、dbutils、table、sql、udf、getArgument、sc、sqlContext、spark
    • %sql 用于执行 SQL 单元格的魔术命令

若要使用 Python 源代码“notebooks”，请按以下步骤进行：

  • 搜索jupyter.interactiveWindow.cellMarker.codeRegex，并将其设置为：

    ^# COMMAND ----------|^# Databricks notebook source|^(#\\s*%%|#\\s*\\<codecell\\>|#\\s*In\\[\\d*?\\]|#\\s*In\\[ \\])

  • 搜索jupyter.interactiveWindow.cellMarker.default，并将其设置为：

    # COMMAND ----------

Troubleshooting

本部分包含有关解决常见问题的信息。

SSH 连接失败或超时

  • 验证群集是否在工作区 UI 中运行。
  • 检查外发端口 22 是否已打开，并确保它在您的笔记本电脑、网络和 VPN 上是被允许的。
  • 延长 SSH 超时期限。 请参阅 使用 Visual Studio Code 或 Cursor 进行连接。
  • 对于密钥不匹配错误，请删除 ~/.databricks/ssh-tunnel-keys 并重新运行 databricks ssh setup。
  • 对于“远程主机标识已更改”错误，请检查 ~/.ssh/known_hosts 文件并删除与群集相关的条目。
  • 在 1 小时后，SSH 会话可能会断开，并且无法与单个群集建立超过 10 个 SSH 连接。 请参阅限制。

CLI 身份验证错误

  • 使用databricks auth login确认 Databricks CLI 配置文件是否有效。
  • 确认你对群集具有 CAN MANAGE 权限。

我的代码不起作用

群集重启后文件消失或环境重置

  • 在 /Workspace、/Volumes 和 /dbfs 装载中的文件在群集重启后将保持存在。 文件位于/home、/root和其他本地路径中，这些文件是临时的，会在重启时丢失。
  • 对持久性依赖项使用群集库管理。 根据需要使用 init 脚本自动重新安装。 请参阅什么是 init 脚本？。

SSH 设置在 Windows （WSL） 上失败

直接在 Windows 上运行 databricks ssh setup，而不是在 WSL 中运行。 Windows VS Code 实例找不到在 WSL 端创建的 SSH 配置。

FAQ

远程开发与 Databricks Connect 有何不同？

Databricks Connect 允许使用 Spark API 编写代码，并在 Databricks 计算中远程运行代码，而不是在本地 Spark 会话中运行这些代码。 Databricks Visual Studio Code 扩展通过 Databricks Connect 提供在 Databricks 上对用户代码的内置调试功能。

通过远程开发，可以从 IDE 访问工作区，并将整个开发环境移到群集上 ， Python、内核和所有执行在 Databricks 上运行，并且完全有权访问群集资源。

我的代码和数据如何受到保护？

所有代码都在您的 Databricks 云 VPC 中运行。 没有任何数据或代码离开安全环境。 SSH 流量已完全加密。

支持哪些 IDE？

正式支持 Visual Studio Code 和 Cursor。 任何具有 SSH 功能的 IDE 都兼容，但仅测试 VS Code 和 Cursor。

IDE 中是否提供了所有 Databricks 笔记本功能？

某些功能，例如 display()、dbutils 和 %sql，在使用时受到限制或需要手动设置。 请参阅 Databricks Notebook 的差异之处。

使用 SSH 隧道进行连接时，群集是否会自动启动？

是的，但如果启动群集的时间比连接超时时间长，则连接尝试将失败。 若要防止这种情况，请从命令面板（或 remote.SSH.connectTimeout in settings.json）中增加Remote.SSH: Connect Timeout的值，以进一步降低发生超时错误的可能性。

如何知道我的群集是否正在运行？

导航到 Databricks 工作区 UI 中的 “计算 ”，并检查群集的状态。 群集必须显示正在运行，SSH 连接才能正常工作。

如何断开 SSH/IDE 会话的连接？

可以通过关闭 IDE 窗口、使用 IDE 中的 “断开连接 ”选项、关闭 SSH 终端或在终端中运行 exit 命令来断开会话连接。

如何在我不使用时关停群集避免产生费用？

若要立即停止，请从工作区 UI 终止群集。 导航到 Databricks 工作区 UI 中的 “计算 ”，找到群集，然后单击“ 终止 ”或“ 停止”。

从工作区 UI 将简短的自动终止策略设置在群集上。 断开连接后，SSH 服务器会等待 shutdown-delay 的时间段（默认值：10 分钟），随后应用集群的空闲超时设置。

应如何处理持久性依赖项？

群集重启后，会话期间安装的依赖项会丢失。 对要求和设置脚本使用永久性存储（/Workspace/Users/<your-username>）。 使用群集库或 init 脚本进行自动化。

支持哪些身份验证方法？

身份验证使用 Databricks CLI 和 ~/.databrickscfg 配置文件文件。 SSH 密钥由 Databrick 远程开发处理。

是否可以从群集连接到外部数据库或服务？

是的，只要群集网络允许出站连接，并且你拥有必要的库。

是否可以使用其他 IDE 扩展？

大多数扩展在远程 SSH 会话中安装时都起作用，具体取决于 IDE 和群集。 默认情况下，Visual Studio Code 不会在远程主机上安装本地扩展。 可以通过打开扩展面板并在远程主机上启用本地扩展来手动安装它们。 还可以将 Visual Studio Code 配置为始终远程安装某些扩展。 请参阅 “连接到 Databricks”。

是的，但工作区管理员必须允许列出 VS Code 和 Cursor 扩展市场的 URL。 用户本地计算机还必须能够访问 Internet。

  • Last updated on