使用 Databricks Connect 为 Visual Studio Code 的 Databricks 扩展调试代码

本文介绍如何通过在 Visual Studio Code 的 Databricks 扩展中使用 Databricks Connect 集成来调试代码。 请参阅什么是 Visual Studio Code 的 Databricks 扩展？。

此信息假定你已安装并设置 Visual Studio Code 的 Databricks 扩展。 请参阅安装 Visual Studio Code 的 Databricks 扩展。

Visual Studio Code 的 Databricks 扩展包括 Databricks Connect。 可以使用 Visual Studio Code 的 Databricks 扩展中的 Databricks Connect 运行和分步调试各个 Python (.py) 文件和 Python Jupyter 笔记本 (.ipynb)。 Visual Studio Code 的 Databricks 扩展包括适用于 Databricks Runtime 13.0 及更高版本的 Databricks Connect。 不支持更低版本的 Databricks Connect。

要求

在使用 Visual Studio Code 的 Databricks 扩展中的 Databricks Connect 之前，必须先满足 Databricks Connect 要求。 这些要求包括一个启用了 Unity Catalog 的工作区、一个运行 Databricks Runtime 13.0 或更高版本且群集访问模式为“单用户”或“共享”的群集，以及一个本地安装的、其主要版本和次要版本与群集上安装的 Python 匹配的 Python 版本。

步骤1：创建 Python 虚拟环境

为 Python 代码项目创建并激活一个 Python 虚拟环境。 Python 虚拟环境有助于确保代码项目使用兼容版本的 Python 和 Python 包（在本例中为 Databricks Connect 包）。 本文中的说明和示例使用 venv 或 Poetry 创建 Python 虚拟环境。 Databricks 尚未使用其他类型的 Python 虚拟环境（如 Conda）全面测试 Databricks Connect 包。

使用 venv 创建 Python 虚拟环境

1. 在 Visual Studio Code 终端（“视图”>“终端”）中设置为 Python 代码项目的根目录，指示 venv 将 Python 用于虚拟环境，然后运行以下命令，在 Python 代码项目根目录内名为 .venv 的隐藏目录中创建虚拟环境的支持文件：

   # Linux and macOS
   python3.10 -m venv ./.venv
   # Windows
   python3.10 -m venv .\.venv
   

   以上命令使用 Python 3.10，它与 Databricks Runtime 13.0 使用的 Python 主要和次要版本相匹配。 请务必使用与群集上安装的 Python 版本匹配的 Python 主要和次要版本。

2. 如果 Visual Studio Code 显示消息“我们发现已经创建了一个新环境。 是否要为工作区文件夹选择该环境”，请单击“是”。

3. 使用 venv 激活虚拟环境。 请根据你的操作系统和终端类型，参阅 venv 文档了解要使用的正确命令。 例如，在运行 zsh 的 macOS 上：

   source ./.venv/bin/activate
   

   如果虚拟环境的名称（例如 .venv）显示于紧靠在终端提示符前面的括号中，则表示该虚拟环境已激活。

   若要随时停用虚拟环境，请运行命令 deactivate。

   如果虚拟环境的名称不再显示于紧靠在终端提示符前面的括号中，则表示该虚拟环境已停用。

向前跳到步骤 2：更新 Python 代码以建立调试上下文。

使用 Poetry 创建 Python 虚拟环境

1. 如果尚未安装 Poetry，请先安装。

2. 从 Visual Studio Code 终端 (视图 > 终端) 设置为现有 Python 代码项目的根目录，通过运行以下命令指示 poetry 初始化 Poetry 的 Python 代码项目：

   poetry init
   

3. Poetry 显示多个需要完成的提示。 这些提示都不特定于 Visual Studio Code 的 Databricks 扩展或 Databricks Connect。 有关这些提示的信息，请参阅 init。

4. 完成提示后，Poetry 会将 pyproject.toml 文件添加到 Python 项目。 有关 pyproject.toml 文件的信息，请参阅 pyproject.toml 文件。

5. 如果 Visual Studio Code 终端仍设置为 Python 代码项目的根目录，请指示 poetry 读取 pyproject.toml 文件、解析依赖项并安装它们、创建 poetry.lock 文件来锁定依赖项，最后创建虚拟环境。 为此，请运行以下命令：

   poetry install
   

6. 指示 Visual Studio Code 使用此 Python 项目的虚拟环境中包含的 Python 解释器，如下所示：

   1. 通过从项目的根目录运行以下命令，查找此 Python 项目的虚拟环境中的 Python 解释器的完整路径：

      poetry env info
      

   2. 复制 Virtualenv > Executable 字段输出中显示的完整路径，例如包含 pypoetry/virtualenvs 的完整路径。

   3. 在命令面板 (视图 > 命令面板) 中输入命令 >Python: Select Interpreter。

   4. 输入刚复制的 Python 解释器的完整路径。

7. 如果 Visual Studio Code 终端仍设置为 Python 代码项目的根目录，请指示 poetry 激活虚拟环境并输入相应 shell。 为此，请运行以下命令：

   poetry shell
   

   当虚拟环境的名称显示在终端提示符之前的括号中时，即表示你的虚拟环境已激活并且已进入 shell。

   若要随时停用虚拟环境并退出 shell，请运行命令 exit。

   当虚拟环境的名称不再显示在紧接终端提示符前面的括号中时，就表示你已退出 shell。

   若要详细了解如何创建和管理 Poetry 环境，请参阅管理环境。

步骤 2：更新 Python 代码以建立调试上下文

若要在 Databricks Connect 和群集之间建立调试上下文，Python 代码必须通过调用 DatabricksSession.builder.getOrCreate() 来初始化 DatabricksSession 类。

请注意，在初始化 DatabricksSession 类时，无需指定工作区实例名称、访问令牌或群集 ID 和端口号等设置。 Databricks Connect 将从你先前在本文中通过 Visual Studio Code 的 Databricks 扩展提供的配置详细信息中获取此信息。

有关初始化 DatabricksSession 类的更多信息，请参阅 Databricks Connect 代码示例。

步骤 3：启用 Databricks Connect

打开扩展并为代码项目配置“工作区”部分后，执行以下操作：

1. 在 Visual Studio Code 状态栏中，单击红色的“Databricks Connect 已禁用”按钮。

2. 如果尚未在扩展中配置“群集”部分，则会显示以下消息：“请附加群集以使用 Databricks Connect”。单击“附加群集”并选择符合 Databricks Connect 要求的群集。

3. 如果配置了“群集”部分，但群集与 Databricks Connect 不兼容，请单击红色的“Databricks Connect 已禁用”按钮，单击“附加群集”，然后选择一个兼容的群集。

4. 如果尚未安装 Databricks Connect 包（及其依赖项），则会显示以下消息：“要进行交互式调试和自动完成，需要 Databricks Connect。 是否要在 <environment-name> 环境中安装它?”。单击“安装”。

5. 在 Visual Studio Code 状态栏中，会显示“Databricks Connect 已启用”按钮。

   如果仍然出现红色的“Databricks Connect 已禁用”按钮，请单击该按钮，然后按照屏幕上的说明按照，以显示“Databricks Connect 已启用”按钮。

6. 显示“Databricks Connect 已启用”按钮后，便可以使用 Databricks Connect。

poetry add databricks-connect==13.3.2

步骤 4：运行或调试 Python 代码

为代码项目启用 Databricks Connect 后，如下所述运行或调试 Python 文件或笔记本。

若要运行或调试 Python (.py) 文件，请执行以下操作：

1. 在代码项目中，打开要运行或调试的 Python 文件。

2. 在 Python 文件中设置任何调试断点。

3. 在文件编辑器的标题栏中，单击播放（“运行或调试”）图标旁边的下拉箭头。 然后在下拉列表中选择“调试 Python 文件”。 此选项支持逐步调试、断点、监视表达式、调用堆栈和类似功能。 此选项使用 Databricks Connect 在本地运行 Python 代码，在远程工作区中的群集上运行 PySpark 代码，并将远程响应发送回 Visual Studio Code 进行本地调试。

   注意

   其他不支持调试的选项包括：

   • 运行 Python 文件：使用 Databricks Connect 运行文件或笔记本，但不支持调试。 此选项将文件发送到远程工作区，在工作区中的远程群集上运行文件的 Python 和 PySpark 代码，并将远程响应发送到 Visual Studio Code 终端。
   • “在 Databricks 中上传和运行文件”将文件发送到远程工作区，在工作区中的远程群集上运行文件的 Python 和 PySpark 代码，并将远程响应发送到 Visual Studio Code 终端。 此选项不使用 Databricks Connect。
   • “在 Databricks 上将文件作为工作流运行”将文件发送到远程工作区，在与自动化 Azure Databricks 作业关联的群集上运行文件的 Python 和 PySpark 代码，并将结果发送到 Visual Studio Code 中的编辑器。 此选项不使用 Databricks Connect。

   

   “在交互式窗口中运行当前文件”选项（如果可用）尝试在特殊的 Visual Studio Code 交互式编辑器中本地运行文件。 Databricks 不建议使用此选项。

若要运行或调试 Python Jupyter 笔记本 (.ipynb)，请执行以下操作：

1. 在代码项目中，打开要运行或调试的 Python Jupyter 笔记本。 确保 Python 文件采用 Jupyter 笔记本格式并且扩展名为 .ipynb。

   提示

   可以通过在“命令面板”中运行“>创建: 新建 Jupyter 笔记本”命令来创建新的 Python Jupyter 笔记本。

2. 单击“运行所有单元格”以运行所有单元格但不调试、单击“执行单元格”以运行单个对应的单元格但不调试，或单击“逐行运行”以逐行运行单个单元格并进行有限的调试，变量值显示在“Jupyter”面板中（“视图”>“打开视图”>“Jupyter”）。

   要在单个单元格内进行全面调试，请设置断点，然后在该单元格的“运行”按钮旁边的菜单中单击“调试单元格”。

   单击其中的任一选项后，系统可能会提示你安装缺少的 Python Jupyter 笔记本包依赖项。 单击以进行安装。

   有关详细信息，请参阅 VS Code 中的 Jupyter 笔记本。