---

[!NOTE]

项目状态更新 🚀

经过数年暂停后，我们很高兴地宣布 Kale 的开发已重新启动！🎉 当年，Kale 曾广受社区好评。如今，我们的目标是通过将所有组件更新至最新版本，并确保与最新 Kubeflow 发布版本完全兼容，重新建立一个稳固的基础。

更多详情请参阅 迈向 2.0 版本的议题

KALE（Kubeflow 自动化流水线引擎）是一个旨在简化数据科学人员部署 Kubeflow Pipelines 工作流体验的项目。 Kubeflow 是一个优秀的平台，用于在 Kubernetes 上编排复杂的流程；而 Kubeflow Pipelines 则提供了创建可重用组件的方法，这些组件可以作为工作流的一部分执行。Kubeflow 的自助服务特性使其对数据科学领域极具吸引力，因为它能够轻松访问高级分布式作业编排、组件复用、Jupyter Notebook、丰富的用户界面等功能。然而，对于可能不熟悉编排平台及相关 SDK 的数据科学家来说，开发和维护 Kubeflow 工作流仍然颇具挑战性。此外，数据科学通常涉及数据探索、迭代建模以及交互式环境（主要是 Jupyter Notebook）等环节。 Kale 通过提供一个简单的 UI，使用户可以直接从 JupyterLab 界面定义 Kubeflow Pipelines 工作流，而无需修改任何代码行，从而弥合了这一差距。

更多详细信息，请参阅 README 底部的 Kale v2.0 演示 视频。 有关 Kale 及其工作原理的更多信息，请阅读这篇 Medium 文章： 使用 Kale 将 Jupyter Notebook 部署自动化到 Kubeflow Pipelines

开始使用

要求

• Python 3.11+
• Kubeflow Pipelines v2.16.0+
  • 较旧的 KFP 服务器（kfp[kubernetes] < 2.16.0）无法识别 Kubernetes 执行器配置中的 securityContext 字段，这会导致流水线提交失败。
  • 按照官方 Kubeflow Pipelines 安装文档 中的建议安装 KFP（请确保设置 PIPELINE_VERSION=2.16.0 或更高版本）。
  • 如果您是从早期版本升级而来，请确保您的依赖项中包含 kfp[kubernetes]>=2.16.0 和 kfp>=2.0.0。
• 一个 Kubernetes 集群（minikube、kind 或任何 K8s 集群）

安装

[!IMPORTANT] Kale v2.0 尚未发布到 PyPI。 在此之前，请从源代码安装：

git clone https://github.com/kubeflow-kale/kale.git
cd kale
make dev      # 设置开发环境
make jupyter  # 启动 JupyterLab

详细的设置说明请参阅 CONTRIBUTING.md。 待 v2.0 发布后，您即可通过 PyPI 安装：

pip install "jupyterlab>=4.0.0" kubeflow-kale[jupyter]
jupyter lab

验证安装

1. 启动您的 Kubernetes 集群和 KFP：

   minikube start
   kubectl port-forward -n kubeflow svc/ml-pipeline-ui 8080:80
   

2. 测试命令行工具：

   kale --nb examples/base/candies_sharing.ipynb --kfp_host http://127.0.0.1:8080 --run_pipeline
   

   这将生成一个 .kale/ 目录下的流水线文件，并将其提交到 KFP。

3. 测试 JupyterLab 扩展：

   • 打开 JupyterLab（运行 make jupyter 或 jupyter lab）
   • 打开 examples/base/ 中的一个笔记本
   • 点击左侧面板中的 Kale 图标
   • 使用切换按钮启用 Kale 面板

Docker（本地测试）

您可以通过 Docker 在类似 Kubeflow 的 Notebook 环境中测试 Kale。该镜像基于官方的 Kubeflow Notebook 镜像（jupyter-scipy），并预先安装了 Kale。

make docker-build   # 构建 wheel 文件 + Docker 镜像
make docker-run     # 在 http://localhost:8889 启动 JupyterLab

要连接到 KFP 集群，请在不同的终端中分别运行以下命令：

# 终端 1：提供开发版 wheel 文件服务（以便编译后的流水线可以安装 Kale）
make kfp-serve

# 终端 2：转发 KFP API 端口
kubectl port-forward -n kubeflow svc/ml-pipeline 8080:8888

# 终端 3：启动容器
make docker-run

make docker-run 会自动配置：

• KFP API 通过 host.docker.internal 访问（适用于 macOS、Windows 和 Linux）
• KFP UI 链接 指向 localhost:8080（以便流水线链接能在浏览器中打开）
• Wheel 服务器 连通性，方便编译后的流水线安装

单元格类型

Kale 使用特殊的单元格类型（标签）来将您的笔记本组织成流水线组件。您可以使用 Kale 的 JupyterLab 扩展，或直接在笔记本元数据中添加标签，为单元格分配这些类型。

细胞类型参考

细胞类型	状态	描述
导入	✅ 正常工作	该细胞中的代码将在流水线的每一步之前插入。用于所有导入语句。所有导入必须放在标记为 imports 的细胞中。 在其他类型的细胞中导入库（pandas、tensorflow 等）会导致流水线执行错误。
函数	✅ 正常工作	该细胞中的代码将在 imports 之后，插入到流水线的每一步之前。仅用于函数和类的定义。请勿包含 顶级可执行语句
流水线参数	✅ 正常工作	定义将成为流水线参数的变量。如果存在多个流水线参数细胞，并且每个细胞都定义了一个参数，则仅采用最终值。
流水线指标	✅ 正常工作	打印标量指标并将其转换为流水线指标。
步骤	✅ 正常工作	具有自定义名称的常规流水线步骤。这是您数据处理和机器学习逻辑的默认细胞类型。每个步骤可以依赖于其他步骤。步骤也可以定义自己的镜像和 GPU 要求。
跳过细胞	✅ 正常工作	标记为跳过的细胞将被排除在流水线之外。适用于探索性代码或调试，这些内容不应成为生产流水线的一部分。

重要指南

[!WARNING] 不在 Imports 细胞中的导入将不会被检测以进行自动依赖项安装，这会导致运行时出现 ImportError，如果容器镜像中未预先安装该包。

最佳实践：

• 将所有导入放在笔记本的开头，并置于标记为 Imports 的细胞中
• 保持函数定义的纯粹性——无副作用（修改全局变量或可变参数）、打印或导入
• 使用 pipeline-parameters 来存储您可能希望在不同运行之间调整的值
• 使用 skip 细胞来进行不应包含在流水线中的探索性分析

示例

请查看 examples/ 中的示例笔记本，以了解细胞类型的实际应用。

常见问题解答

请前往 FAQ 阅读一些已知问题以及 Kale 数据编排模型所施加的一些限制。

资源

• Kale 介绍博客文章：从笔记本到 Kubeflow 流水线：端到端数据科学工作流 / 视频

• KubeCon NA 2019 教程：从笔记本到 Kubeflow 流水线：端到端数据科学工作流 / 视频

• KubeCon EU 2020 教程：从笔记本到 Kubeflow 流水线并结合超参数调优：数据科学之旅 / 视频

贡献

make dev      # 设置开发环境
make test     # 运行所有测试
make jupyter  # 启动 JupyterLab

请参阅 CONTRIBUTING.md，获取详细的开发说明，包括：

• 可用的 make 命令
• 使用 KFP 集群进行测试
• 构建发布工件
• 实时重载设置

Kale v2.0 演示

观看下方 Kubeflow Kale 演示——入门视频。

Kale 快速上手指南

Kale (Kubeflow Automated pipeLines Engine) 是一个旨在简化数据科学家部署 Kubeflow Pipelines 工作流体验的开源工具。它允许你直接在 JupyterLab 界面中定义工作流，无需编写额外的编排代码。

注意：Kale v2.0 目前尚未发布到 PyPI，以下指南基于源码安装方式（开发版）。

1. 环境准备

在开始之前，请确保你的环境满足以下要求：

• Python: 版本 3.11 或更高
• Kubernetes 集群: 本地测试推荐使用 minikube 或 kind，也可使用任意 K8s 集群
• Kubeflow Pipelines (KFP): 版本 v2.16.0 或更高
  • 重要：旧版本 KFP 服务器无法识别 executor config 中的 securityContext 字段，会导致提交失败。
  • 请确保安装 kfp[kubernetes]>=2.16.0 和 kfp>=2.0.0。
• 构建工具: 需要安装 make 和 git

2. 安装步骤

由于 v2.0 暂未发布，需从源代码克隆并设置开发环境。

第一步：克隆源码并设置环境

git clone https://github.com/kubeflow-kale/kale.git
cd kale
make dev      # 设置开发环境（安装依赖）

第二步：启动 JupyterLab

make jupyter  # 启动集成了 Kale 插件的 JupyterLab

如果后续 v2.0 正式发布，你将可以通过 pip 直接安装： pip install "jupyterlab>=4.0.0" kubeflow-kale[jupyter]

3. 基本使用

场景 A：通过命令行快速测试

如果你已有一个运行中的 KFP 集群，可以使用示例 Notebook 快速验证安装。

1. 启动集群并端口转发（以 minikube 为例）：

   minikube start
   kubectl port-forward -n kubeflow svc/ml-pipeline-ui 8080:80
   

2. 运行 CLI 命令： 该命令会将示例 Notebook 转换为 Pipeline 并提交到 KFP。

   kale --nb examples/base/candies_sharing.ipynb --kfp_host http://127.0.0.1:8080 --run_pipeline
   

   生成的 Pipeline 文件将保存在 .kale/ 目录下。

场景 B：在 JupyterLab 中可视化构建

这是 Kale 的核心用法，无需编写额外代码即可将 Notebook 转换为 Pipeline。

1. 打开 Notebook： 在启动的 JupyterLab 中，打开 examples/base/ 目录下的任意 Notebook（如 candies_sharing.ipynb）。

2. 启用 Kale 面板： 点击左侧边栏的 Kale 图标，并通过开关启用面板。

3. 标记单元格类型 (Cell Types)： Kale 通过给代码单元格打标签（Tags）来区分 Pipeline 的不同部分。选中单元格，在右侧属性面板或 Kale 面板中设置以下类型：

   单元格类型	用途说明	最佳实践
   Imports	存放所有 import 语句	必须将所有库导入放在此类单元格中，否则可能导致运行时错误。
   Functions	存放函数和类定义	仅包含定义，不要包含执行逻辑或打印语句。
   Pipeline Parameters	定义超参数或变量	用于在不同运行之间调整数值。
   Step	核心业务逻辑	默认类型。包含数据处理和模型训练代码。每个 Step 可独立配置依赖、镜像或 GPU。
   Skip Cell	跳过执行	用于探索性代码或调试，不会包含在最终 Pipeline 中。

4. 编译与运行： 在 Kale 面板中点击 Compile 生成 Pipeline 预览，确认无误后点击 Run 直接提交到 Kubeflow Pipelines。

本地 Docker 测试（可选）

如果你没有现成的 KFP 环境，可以使用 Docker 模拟完整流程：

# 构建包含 Kale 的 Docker 镜像
make docker-build

# 启动容器 (JupyterLab 运行在 http://localhost:8889)
make docker-run

注：若需连接外部 KFP 集群，需在额外终端运行 make kfp-serve 和 kubectl port-forward。