使用IDE、dbx和Databricks Repos开发Kedro项目

警告

dbx 已在2023年弃用，现在推荐的工作流程是使用 Databricks Asset Bundles

本指南演示了一个工作流程，用于在Databricks上开发Kedro项目：先在本地环境进行开发，然后使用dbx和Databricks Repos同步代码，以便在Databricks上进行测试。

通过在本地环境中工作，您可以利用IDE中Databricks笔记本不具备的功能：

• 代码自动补全和建议功能，提升开发速度和准确性。

• 可以集成像Ruff这样的代码检查工具来发现代码中的潜在问题。

• 像Mypy这样的静态类型检查器可以检查代码中的类型，帮助在开发过程中早期发现潜在的类型相关问题。

要设置这些功能，请查找适用于您集成开发环境（IDE）的具体说明（例如，VS Code）。

如果您更喜欢在笔记本而非集成开发环境中开发项目，请参考我们的指南如何在Databricks工作区中开发Kedro项目。

注意

Databricks现在推荐您使用Databricks资产包替代dbx。这份Kedro部署文档尚未更新，但您可以参考什么是Databricks资产包？以及从dbx迁移到资产包获取更多信息。

本页内容涵盖

本教程的主要步骤如下：

• 创建虚拟环境并安装配置dbx。

• 使用databricks-iris起始模板创建一个新的Kedro项目。

• 在Databricks上创建一个仓库并使用dbx同步您的项目。

• 将项目数据上传到在Databricks上运行Kedro时可访问的位置（如DBFS）。

• 创建一个Databricks笔记本来运行你的项目。

• 在本地环境中修改项目，并在Databricks上以迭代循环方式测试变更。

先决条件

• 一个活跃的Databricks部署。

• 配置了Databricks运行时最新版本（建议>=11.3）的Databricks集群。

• Conda installed 已安装在您的本地机器上，用于创建具有特定Python版本（要求≥3.9）的虚拟环境。如果您已安装Python≥3.9，可以使用其他软件创建虚拟环境。

设置你的项目

记录您的Databricks用户名和主机

请记下您的Databricks用户名和主机地址，因为在后续指南中会需要用到这些信息。

在Databricks工作区界面的右上角查找您的用户名，并在浏览器地址栏中获取主机地址（截取到第一个斜杠之前的部分，例如https://adb-123456789123456.1.azuredatabricks.net/）：

注意

您的Databricks主机地址必须包含协议前缀(https://)。

在新虚拟环境中安装Kedro和dbx

在本地开发环境中，使用Conda为本教程创建一个虚拟环境：

conda create --name iris-databricks python=3.10

创建完成后，请激活它：

conda activate iris-databricks

激活您的Conda环境后，安装Kedro和dbx：

pip install kedro dbx --upgrade

验证Databricks CLI

现在，您必须使用您的Databricks实例对Databricks CLI进行身份验证。

参考Databricks文档获取完整的CLI认证指南。关键步骤如下：

1. 在您的Databricks实例上为用户创建个人访问令牌。

2. 运行 databricks configure --token。

3. 在提示时输入您的令牌和Databricks主机地址。

4. 在命令行运行 databricks fs ls dbfs:/ 来验证您的认证。

注意

dbx是Databricks CLI的扩展，这是一个无需使用UI即可与Databricks交互的命令行程序。您将使用dbx将项目代码与Databricks同步。虽然Git可以将代码同步到Databricks Repos，但dbx更适合开发使用，因为它避免了为每个更改创建新提交，即使这些更改不起作用。

创建一个新的Kedro项目

在本地环境中使用以下命令创建一个基于databricks-iris初始模板的Kedro项目：

kedro new --starter=databricks-iris

将您的新项目命名为iris-databricks以保持与本指南其余部分一致。此命令使用databricks-iris起始模板创建一个新的Kedro项目。

注意

如果您没有使用databricks-iris启动器创建Kedro项目，且您使用的Kedro版本早于0.19.0，那么您应该禁用基于文件的日志记录以防止Kedro尝试写入只读文件系统。

在Databricks上创建仓库

在Databricks上创建新仓库，请导航至Databricks工作区UI侧边栏中的New选项卡，然后点击出现的下拉菜单中的Repo。

在本指南中，您不会将项目与远程Git提供商同步，因此请取消勾选Create repo by cloning a Git repository并输入iris-databricks作为新仓库的名称：

使用dbx将代码与您的Databricks Repo同步

下一步是使用dbx将您的项目同步到您的代码仓库。

打开一个新的终端实例，激活你的conda环境，导航到项目目录并启动dbx sync：

conda activate iris-databricks
cd <project_root>
dbx sync repo --dest-repo iris-databricks --source .

该命令会将您的本地目录(--source .)与Databricks上的代码仓库(--dest-repo iris-databricks)进行同步。首次启动时，dbx sync会在终端输出类似以下内容：

...
[dbx][2023-04-13 21:59:48.148] Putting /Repos/<databricks_username>/iris-databricks/src/tests/__init__.py
[dbx][2023-04-13 21:59:48.168] Putting /Repos/<databricks_username>/iris-databricks/src/tests/test_pipeline.py
[dbx][2023-04-13 21:59:48.189] Putting /Repos/<databricks_username>/iris-databricks/src/tests/test_run.py
[dbx][2023-04-13 21:59:48.928] Done. Watching for changes...

在开发过程中保持第二个终端（运行dbx sync）处于活动状态；关闭它将停止同步新更改。

dbx sync 在运行时会自动将本地项目目录中的任何后续更改同步到您的Databricks Repo中。

注意

与dbx的同步是单向的，这意味着您使用Databricks Repos代码编辑器所做的更改不会反映在您的本地环境中。在同步时，请仅在本地环境中对项目进行更改，而不要在Databricks Repos提供的编辑器中进行更改。

在你的Databricks Repo中创建conf/local目录

Kedro要求您的项目必须存在conf/local目录才能成功运行，即使该目录为空。dbx sync不会将本地conf/local目录的内容复制到Databricks Repo中，因此您必须手动创建它。

打开Databricks工作区用户界面，使用左侧面板导航至Repos -> -> iris-databricks -> conf，右键点击并选择Create -> Folder，如下图所示：

将新文件夹命名为local。在本指南中，我们没有需要存储的本地凭证，因此我们将保持新创建的文件夹为空。现在，您的conf/local和local目录应如下所示：

将项目数据上传至DBFS

在Databricks上运行时，Kedro无法访问项目目录中存储的数据。因此，您需要将项目数据上传到可访问的位置。在本指南中，我们将把数据存储在Databricks文件系统(DBFS)上。

databricks-iris 启动器包含一个 catalog，该目录配置用于访问存储在 DBFS 中的数据（<project_root>/conf/）。在 Databricks 上创建作业时，您需要通过 --conf-source 选项将项目指向使用 DBFS 上存储的配置。

有几种方法可以将数据上传到DBFS。在本指南中，由于提供的便利性，建议使用Databricks CLI。在本地环境的命令行中，使用以下Databricks CLI命令将本地存储的数据上传到DBFS：

databricks fs cp --recursive <project_root>/data/ dbfs:/FileStore/iris-databricks/data

--recursive 标志确保上传整个文件夹及其内容。您可以使用以下命令列出 DBFS 中目标文件夹的内容：

databricks fs ls dbfs:/FileStore/iris-databricks/data

你应该会在终端看到项目data/目录下的内容打印出来：

01_raw
02_intermediate
03_primary
04_feature
05_model_input
06_models
07_model_output
08_reporting

创建新的Databricks笔记本

现在您的项目已在Databricks上可用，您可以使用笔记本在集群上运行它。

要从您的Databricks Repo运行Python代码，请在您的工作区创建一个新的Python笔记本。将其命名为iris-databricks以便追踪，并将其附加到您的集群：

运行你的项目

打开你新创建的笔记本，并在其中新建四个单元格。你将在这些单元格中填入运行项目所需的代码。复制以下代码片段时，请记得将替换为你在Databricks上的用户名，以确保project_root能正确指向你项目的位置。

1. 在导入并运行你的Python代码之前，你需要在笔记本连接的集群上安装项目的依赖项。你的项目为此提供了一个requirements.txt文件。将以下代码添加到第一个新单元格中以安装依赖项：

%pip install -r "/Workspace/Repos/<databricks_username>/iris-databricks/requirements.txt"

2. 要在笔记本中运行你的项目，必须加载Kedro IPython扩展。将以下代码添加到第二个新单元格以加载IPython扩展：

%load_ext kedro.ipython

3. 加载该扩展后，您可以使用%reload_kedro行魔法来加载您的Kedro项目。将以下代码添加到第三个新单元格中以加载您的Kedro项目：

%reload_kedro /Workspace/Repos/<databricks_username>/iris-databricks

4. 使用%reload_kedro行魔法加载你的Kedro项目时，会在笔记本中定义四个全局变量：context、session、catalog和pipelines。你将使用session变量来运行你的项目。将以下代码添加到第四个新单元格中以运行你的Kedro项目：

session.run()

完成这些步骤后，你的笔记本应该与下图匹配：

使用界面右上角的Run All按钮运行完整的笔记本：

首次运行时，系统会提示您同意分析数据收集，在出现的字段中输入y或N并按Enter键：

在单元格运行时，您应该能看到日志输出。执行完成后，您将看到类似以下的输出：

...
2023-06-06 17:21:53,221 - iris_databricks.nodes - INFO - Model has an accuracy of 0.960 on test data.
2023-06-06 17:21:53,222 - kedro.runner.sequential_runner - INFO - Completed 3 out of 3 tasks
2023-06-06 17:21:53,224 - kedro.runner.sequential_runner - INFO - Pipeline execution completed successfully.

修改您的项目并测试变更

既然你的项目已成功运行一次，现在可以利用本地开发环境的便利性和强大功能进行修改。在本节中，你将调整项目以使用不同的训练数据与测试数据比例，并在Databricks上检查这一变更带来的影响。

修改训练/测试集分割比例

databricks-iris 初始项目在训练分类器时默认使用80-20的训练数据与测试数据比例。本节中，您将通过本地环境编辑项目将此比例更改为70-30，然后使用dbx将其与Databricks Repo同步，最后在Databricks上运行修改后的项目以观察不同结果。

在本地环境中打开文件/conf/base/parameters.yml。将train_fraction: 0.8这一行修改为train_fraction: 0.7并保存更改。查看运行dbx sync的终端，您应该会看到它自动将您的更改同步到Databricks Repo中：

...
[dbx][2023-04-14 18:29:39.235] Putting /Repos/<databricks_username>/iris-databricks/conf/base/parameters.yml
[dbx][2023-04-14 18:29:40.820] Done

重新运行你的项目

返回到您的Databricks笔记本。重新运行笔记本中的第三和第四个单元格（包含代码%reload_kedro ...和session.run()）。项目现在将再次运行，产生类似以下的输出：

...
2023-06-06 17:23:19,561 - iris_databricks.nodes - INFO - Model has an accuracy of 0.972 on test data.
2023-06-06 17:23:19,562 - kedro.runner.sequential_runner - INFO - Completed 3 out of 3 tasks
2023-06-06 17:23:19,564 - kedro.runner.sequential_runner - INFO - Pipeline execution completed successfully.

可以看到，由于使用了不同的分类器来生成结果，模型的准确率发生了变化。

注意

如果集群终止，您必须重新运行整个笔记本，因为使用%pip install ...安装的库是临时的。如果没有终止，则仅当项目需求变更时才需要重复此步骤。

概述

本指南展示了在Databricks上的开发工作流程，利用本地开发环境、dbx和Databricks Repos实现代码同步。这种方法提高了开发效率，并能使用强大的开发功能（如自动补全、代码检查及静态类型检查），这些功能在仅使用Databricks笔记本时无法获得。