Kedro 完全指南:用软件工程最佳实践构建生产级数据与机器学习管道
Kedro 完全指南:用软件工程最佳实践构建生产级数据与机器学习管道
导读
Kedro 是一个面向生产环境数据工程与数据科学场景的开源 Python 框架,它把软件工程的最佳实践(模块化、可复现、可维护)系统性地引入数据管道开发。本篇指南以本仓库根目录的 README.md 为核心骨架,结合仓库内源码、配置与文档,完整讲解 Kedro 的定位、安装方式、五大核心特性、核心概念与项目结构、快速上手流程,以及其版本支持策略与社区生态。读完本文,你将掌握如何在真实项目中安装、创建、组织并运行一个 Kedro 项目,并能从源码层面理解其 CLI、Data Catalog、Pipeline 与 Runner 等关键组件的工作方式。
Kedro 是什么
Kedro 是一个用于生产级数据工程与数据科学管道(production-ready data engineering and data science pipelines)的工具箱。它的设计目标是帮助团队创建**可复现(reproducible)、可维护(maintainable)、模块化(modular)**的数据工程与数据科学管道,并将软件工程最佳实践作为底层原则。
Kedro 是一个由 LF AI & Data Foundation)。从仓库的 pyproject.toml 可以看到,它要求 Python 版本不低于 3.10,并依赖 click(命令行)、cookiecutter(项目模板生成)、dynaconf 与 omegaconf(配置加载)、fsspec(文件系统抽象)、pluggy(钩子机制)等关键库;其版本信息定义在 kedro/init.py 中(当前仓库版本为 1.5.0)。
值得留意的是,Kedro 的适用方式非常灵活(详见 docs/getting-started/architecture_overview.md):
- 端到端使用:框架、项目模板、starters 与库全部采用,获得 Kedro 的完整价值;
- 按需选用库组件:在既有代码库中仅引入
DataCatalog(I/O)、OmegaConfigLoader、Pipeline 与 Runner 等独立组件,无需套用项目模板; - 扩展 Kedro:开发自定义 starter、插件、hooks 等扩展。
如何安装 Kedro
Kedro 支持 macOS、Linux 与 Windows 三大平台(详见 docs/getting-started/install.md),安装前置条件为 Python 3.10+ 与 git。官方强烈建议为每一个新 Kedro 项目单独创建虚拟环境,以隔离依赖。
从 PyPI 安装
最直接的安装方式是从 Python Package Index(PyPI)安装:
uv pip install kedro
使用 uv add kedro 则可以把 Kedro 声明到项目的 pyproject.toml 中,并自动生成锁文件:
uv add kedro
如果不使用 uv,也可以用传统工具:
pip install kedro
poetry add kedro
使用 conda 安装
Kedro 同样可以通过 conda-forge 频道安装:
conda install -c conda-forge kedro
也可以创建独立的 conda 环境(官方安装文档示例使用 Python 3.13):
conda create --name kedro-environment python=3.13 kedro --yes
conda activate kedro-environment
从源码安装最新版本
如果需要抢先体验尚未正式发布的 Kedro 版本,可以直接从 main 分支安装:
uv pip install git+https://github.com/kedro-org/kedro@main
验证安装
安装完成后,通过 kedro info 验证。在 kedro/framework/cli/cli.py 中可以看到 info 命令的实现:它会打印 Kedro 的 ASCII 艺术 Logo 与版本号,并列出当前环境中通过入口点(entry points)注册的所有已安装插件及其版本。
kedro info
如果你在运行命令时遇到 "command not found" 或其它异常,请先确认当前虚拟环境是否已激活,以及是否使用了项目管理工具要求的前缀(如 uv run kedro)。
Kedro 的五大核心特性
README 用一张特性表概括了 Kedro 的核心能力,以下逐项结合仓库源码与文档展开讲解。
1. 项目模板(Project Template)
Kedro 提供一个标准、可修改、开箱即用的项目模板,其设计基于 Cookiecutter Data Science,生成逻辑由 kedro/framework/cli/starters.py 中的 new 命令驱动。
从 Kedro 0.19 起,运行 kedro new 时可以选择在项目中包含哪些工具(详见 docs/create/new_project_tools.md 与 starters 源码中的 TOOLS_ARG_HELP 帮助文本):
| 工具 | 作用 |
|---|---|
| Linting | 通过 Ruff 提供基础代码规范检查 |
| Testing | 通过 pytest 提供基础测试框架 |
| Custom Logging | 提供更丰富的日志配置选项 |
| Documentation | 使用 Sphinx 搭建项目文档 |
| Data Structure | 提供分层的数据存储目录结构 |
| PySpark | 提供使用 PySpark 所需的配置 |
对应的 CLI 用法为:
kedro new --tools=lint,test,log,docs,data,pyspark # 或任意子集
kedro new --tools=all
kedro new --tools=none
2. 数据目录(Data Catalog)
Data Catalog 是一系列轻量级数据连接器(data connectors),用于跨多种文件格式与文件系统保存和加载数据,覆盖本地与网络文件系统、云对象存储以及 HDFS;对于基于文件系统的数据,还支持数据与模型版本管理(versioning)。
其核心实现位于 kedro/io/data_catalog.py,正如其模块文档所述:DataCatalog 持有 AbstractDataset 实现的实例,从程序的任何位置提供 load 与 save 能力。它还通过 _LazyDataset 实现了懒加载——数据集对象只有在真正被请求时才实例化,从而优化启动性能(详见 docs/catalog-data/lazy_loading.md)。数据集配置的解析由 kedro/io/catalog_config_resolver.py 负责,基础的 I/O 抽象定义在 kedro/io/core.py,具体数据集实现(CSV、Excel、Parquet 等)由独立的 kedro-datasets 包提供。
一个典型的 catalog.yml 配置(位于项目的 conf/base/ 目录)形如:
companies:
type: pandas.CSVDataset
filepath: data/01_raw/companies.csv
3. 管道抽象(Pipeline Abstraction)
Kedro 提供管道抽象:自动解析纯 Python 函数之间的依赖关系,并支持使用 Kedro-Viz 对数据管道进行可视化。
管道与节点的核心实现位于 kedro/pipeline/pipeline.py 与 kedro/pipeline/node.py。Node 是管道的基本构件,其构造函数签名为(见 kedro/pipeline/node.py):
Node(
func, # 被包装的纯 Python 函数
inputs, # 输入:字符串 / 字符串列表 / 名称到参数的映射,或 None
outputs, # 输出:字符串 / 字符串列表 / 名称到结果的映射,或 None
name=None, # 节点名称
tags=None, # 标签,可用于分组与选择性运行
confirms=None, # 运行结束后确认存在的数据集
namespace=None # 命名空间,用于大规模管道的组织
)
管道则根据节点间的输入输出依赖自动确定执行顺序——它并不一定按照传入节点的先后顺序执行(见 docs/getting-started/kedro_concepts.md)。管道的实际执行由 kedro/runner/runner.py 中的 AbstractRunner 及其子类(SequentialRunner、ParallelRunner、ThreadRunner)完成,它们负责按依赖顺序调度节点、通过目录加载与保存数据,并支持异步 I/O(is_async 参数)与"仅运行缺失输出"(only_missing_outputs)等模式。项目的可运行管道通过 pipeline_registry.py 中的 register_pipelines() 函数注册(返回 dict[str, Pipeline])。
4. 编码标准(Coding Standards)
Kedro 项目内置一整套工程化规范:
- 测试驱动开发:使用
pytest(仓库中 tests/ 目录包含完整的单元与集成测试,覆盖率配置fail_under = 100见 pyproject.toml); - 文档化:使用 Sphinx / MkDocs 生成项目文档(仓库的 docs/ 目录即 MkDocs 站点);
- 代码规范:内置 Ruff 配置(
line-length = 88,启用 Pyflakes、pycodestyle、isort、pyupgrade、Pylint、flake8-bandit 等规则集); - 日志:使用 Python 标准
logging库,模板中附带默认日志配置 kedro/framework/project/default_logging.yml。
更详细的说明可参考 docs/develop/linting.md 与 docs/develop/automated_testing.md。
5. 灵活部署(Flexible Deployment)
Kedro 支持单机与分布式两种部署策略,并对 Argo、Prefect、Kubeflow、AWS Batch、Databricks 等平台提供额外支持。仓库中对应文档位于 docs/deploy/supported-platforms/(包含 airflow、aws_batch、aws_step_functions、azure、dagster、dask、databricks、kubeflow、prefect、vertexai 等专项指南),单机与分布式部署的一般性指导见 docs/deploy/single_machine.md 与 docs/deploy/distributed.md。
快速上手:从零创建一个 Kedro 项目
官方最推荐的入门路径是使用 starters 创建项目。以 Spaceflights(太空航班预测)starter 为例:
# 1. 使用 uvx 运行 kedro new(无需先安装 Kedro 到系统环境)
uvx kedro new --starter spaceflights-pandas --name spaceflights
# 2. 进入生成的项目目录
cd spaceflights
# 3. 同步项目依赖并运行默认管道
uv sync
uv run kedro run --pipelines __default__
关于 uvx 的说明:uvx 是 uv tool run 的别名,它会在一个临时、隔离的环境中运行 kedro new,不会污染你的系统环境。项目创建完成后,后续命令(如 uv sync、uv run kedro)都在项目自己的虚拟环境中执行。
如果你更习惯传统方式,也可以先全局安装 Kedro,再执行 kedro new:
pipx run kedro new # 使用 pipx
# 或
uvx kedro new # 使用 uv
# 或(conda 方式)
conda create --name kedro-environment python=3.13 kedro --yes
conda activate kedro-environment
kedro new
kedro new 支持多种交互/非交互模式(详见 kedro/framework/cli/starters.py 与 features/new.feature):
- 通过
--config指定 YAML 配置文件进行非交互式创建; - 通过
--starter指定 starter 模板; - 通过
--tools控制工具集(见上文)。
核心概念速览
在动手之前,先掌握四个核心概念(详见 docs/getting-started/kedro_concepts.md):
- Node(节点):对纯 Python 函数的包装,显式声明函数的输入与输出,是管道的最小构件;
- Pipeline(管道):组织一组节点的依赖关系与执行顺序,自动连接输入输出,同时保持代码模块化;
- Data Catalog(数据目录):项目全部数据源的注册表,将节点输入输出的名称映射为具体数据集;
- 项目模板结构:Kedro 项目遵循默认目录约定(
conf/、data/、docs/、notebooks/、src/、tests/等),便于团队协作。
一个最简节点与管道示例(取自概念文档):
from kedro.pipeline import Node
from kedro.pipeline import Pipeline
def return_greeting():
return "Hello"
def join_statements(greeting):
return f"{greeting} Kedro!"
return_greeting_node = Node(func=return_greeting, inputs=None, outputs="my_salutation")
join_statements_node = Node(func=join_statements, inputs="my_salutation", outputs="my_message")
greeting_pipeline = Pipeline([return_greeting_node, join_statements_node])
验证与常用命令
kedro info # 查看版本与已安装插件
kedro --version # 仅查看版本号
kedro run # 运行默认管道
kedro run --pipelines __default__
从 kedro/framework/cli/cli.py 的 KedroCLI 实现可以看出,Kedro CLI 分为两组命令:全局命令(new、starter,任何目录可用)与项目专属命令(run、package、jupyter、pipeline、catalog、registry、ipython、server 等,必须在项目目录内使用)。CLI 通过 bootstrap_project 探测项目根目录,且支持插件通过入口点覆盖内置命令;项目自身的 cli.py 还可以继续覆盖插件命令(优先级为:内置命令 < 插件命令 < 项目自定义 cli.py)。完整命令参考见 docs/getting-started/commands_reference.md。
Kedro 项目结构
Kedro 项目遵循默认模板,使用语义化命名组织数据、笔记本、配置与源码。以"全部工具都被选中"的默认结构为例:
project-dir # 模板的父目录
├── conf # 项目配置文件(含 base 与 local 两个子目录)
├── data # 本地项目数据(不纳入版本控制)
├── docs # 项目文档
├── notebooks # 项目相关的 Jupyter 笔记本(实验代码先放这里,成熟后移入 src)
├── src # 项目源码
├── tests # 单元与集成测试
├── .gitignore
├── pyproject.toml # 标识项目根目录,包含项目元数据
├── README.md
└── requirements.txt # 项目依赖(为兼容传统工作流保留)
其中值得重点关注的是:
conf/base/:存放需要跨安装环境共享的项目设置,典型文件包括catalog.yml(数据目录配置)、logging.yml(日志配置)、parameters.yml(机器学习实验参数,如训练/测试划分比例、迭代次数);conf/local/:存放不应共享的个人设置与敏感信息(如访问凭据credentials.yml),该目录被.gitignore忽略;src/<package_name>/:项目源码所在,其中pipeline_registry.py必须包含返回dict[str, Pipeline]的register_pipelines()函数,settings.py用于注册库组件与自定义 hooks;pyproject.toml:通过package_name、project_name、kedro_init_version等元数据标识项目根目录。
配置加载的具体机制(分层配置、模板化、凭据处理)详见 docs/configure/configuration_basics.md 与 docs/configure/parameters_and_credentials.md。
Kedro 的五层架构
Kedro 在宏观上由五个部分组成(对应 docs/getting-started/architecture_overview.md):
- Kedro Project:开发者日常打交道的对象,即上文所述的标准项目结构;
- Kedro Framework:项目与库组件之间的接口,包含 kedro/framework/session/(管理一次 Kedro run 的生命周期)、kedro/framework/context/(持有配置与核心功能)、kedro/framework/hooks/(扩展点规格)与 kedro/framework/cli/(内置 CLI 命令);
- Kedro Starter:用于生成包含样板代码的项目,官方维护一组 starters,也支持自定义;
- Kedro Library:独立的功能单元,包括 kedro/config/ 中的
OmegaConfigLoader(配置解析与加载)、kedro/pipeline/(管道建模)、kedro/runner/(不同执行策略)与 kedro/io/(DataCatalog与数据集实现); - Kedro Extension:自定义 starter、带额外 hook 实现的 Python 库、额外 CLI 命令(如 Kedro-Viz)、自定义库组件等。
这种分层设计保证了"Pipeline 与 IO 相互独立"、"Config 不依赖 Runner 等上层"等架构约束——仓库通过 pyproject.toml 中的 import-linter 契约(CLI > Context > Library, Runner > Extras > IO & Pipeline 分层契约、Pipeline and IO are independent 独立性契约、Config 与 Runner/IO/Pipeline 双向禁依赖契约)在 CI 中强制校验这些依赖边界。
使用 Kedro-Viz 可视化管道
Kedro 的管道可视化能力由独立的 Kedro-Viz 项目提供,用于自动解析节点依赖并生成交互式管道图。Kedro 官方文档为新手与中级用户提供了专门的可视化指南,包括分层展示、命名空间折叠、标签过滤、指标对比等功能。
对于尚处于设计阶段、尚未编写代码的场景,可以使用浏览器端的 Kedro Pipeline Builder(详见 docs/getting-started/pipeline_builder.md):这是一个拖拽式的可视化设计工具,无需安装 Kedro 即可在浏览器中搭建管道、预览生成的 Kedro 代码与配置,并导出 ZIP 项目脚手架继续本地开发。它还会校验图中是否存在循环依赖与非法命名等错误。
与 Jupyter 笔记本协作
Kedro 提供了完善的 Jupyter 笔记本集成方案(详见 docs/integrations-and-plugins/notebooks_and_ipython/),支持在笔记本中加载节点、重载 Kedro 上下文等操作,相关魔术命令实现于 kedro/ipython/。仓库内还包含一个完整的 notebook 示例项目 docs/integrations-and-plugins/notebooks_and_ipython/notebook-example/,展示如何把笔记本接入 Kedro 项目。
为什么 Kedro 存在
Kedro 诞生于作者团队在交付真实 ML 应用时积累的最佳实践(以及踩过的坑)——尤其是面对海量未经验证的原始数据时。README 明确了开发 Kedro 要解决的三个问题:
- 解决 Jupyter 笔记本、一次性脚本与胶水代码的主要缺陷——专注于创建可维护的数据工程与数据科学代码;
- 增强团队协作——不同成员对软件工程概念的掌握程度各不相同,统一框架降低了协作门槛;
- 提升效率——模块化与关注点分离等实践催生了可复用分析代码。
社区、贡献与引用
- 贡献:Kedro 欢迎各类贡献,仓库的 CONTRIBUTING.md 提供了详细指引;数据集实现类贡献(提交到
kedro-datasets)最常被接受,因为无需改动框架本身。 - 学习资源:官方文档提供 FAQ、课程、速查表 与 Spaceflights 教程,社区中还有不断增长的博客、视频与项目清单。
- 引用:如果 Kedro 用于学术研究(例如可复现研究),可以使用仓库中的 CITATION.cff 文件生成引用信息。
Python 版本支持政策
Kedro 对 Python 版本的支持遵循明确的双轨政策(README 与 docs/getting-started/install.md 均有说明):
- 核心 Kedro Framework:支持 CPython 核心团队当前积极维护的所有 Python 版本;当某个 Python 版本停止维护(EOL)时,Kedro 将随之放弃对它的支持,这不视为破坏性变更。从 pyproject.toml 的
classifiers可以看到,当前版本声明支持 Python 3.10 至 3.14;kedro/init.py 中还会对尚未完全兼容的新版本(如 Python 3.15)发出KedroPythonVersionWarning警告。 - Kedro Datasets(
kedro-datasets包):遵循 NEP 29 版本支持政策,通常会先于框架放弃旧版 Python 支持,因为该包依赖众多遵循 NEP 29 的第三方库。
此外,升级 Kedro 时遵循 Semantic Versioning 中的迁移指南,并同步更新项目 pyproject.toml 中的 kedro_init_version。
总结
- Kedro 是一个面向生产环境的开源 Python 数据管道框架,由 LF AI & Data Foundation 托管,支持 macOS、Linux、Windows;
- 安装前置条件为 Python 3.10+ 与 git,可通过
uv、pip、poetry、conda等任意主流工具安装; - 五大核心特性为:项目模板、Data Catalog、管道抽象、编码标准与灵活部署;
- 推荐入门路径是
uvx kedro new --starter spaceflights-pandas --name spaceflights,随后运行kedro run --pipelines __default__验证; - 项目结构遵循标准模板(
conf、data、docs、notebooks、src、tests),pipeline_registry.py注册可运行管道,settings.py配置项目设置; - 框架、库与扩展的分层架构由 import-linter 契约在 CI 中强制约束;
- 核心框架与
kedro-datasets采用不同的 Python 版本支持政策,升级时遵循语义化版本并参考 RELEASE.md 迁移指南。
