企业官网建设流程全解析

ZenML 项目模板（Project Templates）完全指南：从三步快速上手到自建团队级 ML 模板

【免费下载链接】zenmlZenML 🙏: One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml

ZenML 项目模板（Project Templates）是官方为覆盖 ZenML 主要应用场景而设计的开箱即用工程骨架：一组组织良好的 steps 与 pipelines，外加一套简洁实用的 CLI。本文以官方文档为核心，结合 ZenML 仓库源码（CLI 实现、templates 依赖声明 与 e2e 参考实现）深入讲解：如何用zenml init --template在几分钟内生成项目、如何理解每个内置模板的适用场景，以及如何基于 Copier 打造属于自己团队的可复用模板。

什么是 ZenML 项目模板

想要快速理解 ZenML 框架并开始构建 ML 流水线，最直接的路径就是使用一个 ZenML 项目模板。模板本质上是一个"标准化的 ZenML 项目骨架"，打包了三样东西：

• 一组步骤（steps）与流水线（pipelines）：覆盖真实 MLOps 场景中的常见环节；
• 灵活的项目配置：通过 YAML 文件集中管理步骤参数与流水线参数；
• 一个简单但实用的 CLI：让生成、配置、运行流水线的操作可以完全在命令行中完成。

模板的价值在于把"从零搭建工程结构"的重复劳动沉淀成可复用的资产，让团队新成员或新项目能够在最短时间内获得一套符合 ZenML 最佳实践、可立刻运行的代码基础。

内置项目模板一览

ZenML 官方维护了四个项目模板。下表完整列出每个模板的短名称（Short name，用于 CLI 命令）、标签（Tags）与适用场景：

注：官方文档表格中列出的模板为前三者。从仓库源码看，内置模板注册表中还包含llm_finetuning模板（见下文"源码实现"一节），实际可用模板以当前安装版本的zenml init --template提示为准。

模板注册的源码证据

内置模板并非硬编码在文档里，而是由 CLI 在运行时通过一个注册表动态解析。在 src/zenml/cli/base.py#L80-L97 中定义了ZENML_PROJECT_TEMPLATES字典，每个模板指向一个 Git 仓库与固定 tag：

ZENML_PROJECT_TEMPLATES = dict( e2e_batch=ZenMLProjectTemplateLocation( github_url="zenml-io/template-e2e-batch", github_tag="2025.12.17", ), starter=ZenMLProjectTemplateLocation( github_url="zenml-io/template-starter", github_tag="2025.12.17", ), nlp=ZenMLProjectTemplateLocation( github_url="zenml-io/template-nlp", github_tag="2025.04.07", ), llm_finetuning=ZenMLProjectTemplateLocation( github_url="zenml-io/template-llm-finetuning", github_tag="2025.09.19", ), )

ZenMLProjectTemplateLocation（src/zenml/cli/base.py#L64-L77）是一个轻量模型，其copier_github_url属性会把zenml-io/xxx形式转换为 Copier 使用的gh:zenml-io/xxx协议地址。这意味着：

• 每个内置模板都对应一个固定版本的 Git tag，保证同一 ZenML 版本下生成的模板内容可复现；
• 当使用内置模板名（如e2e_batch）时，--template-tag会被忽略（源码注释明确说明 "template_tag is ignored in this case"，见 src/zenml/cli/base.py#L222-L223），版本由注册表锁定；
• 传入的不是内置名称时，CLI 会将其视为 URL 交给 Copier 直接拉取（见下文"创建自己的模板"）。

使用项目模板：三步生成一个 ZenML 项目

第一步：安装带 templates 扩展的 ZenML

模板功能依赖 Copier 等额外依赖，因此需要使用templatesextras 安装：

pip install 'zenml[templates]'

该 extras 在 pyproject.toml#L108 中声明：

templates = ["copier>=8.1.0", "jinja2-time>=0.2.0,<0.3.0", "ruff>=0.1.7", "pyyaml-include<2.0"]

• copier：模板渲染引擎，负责把模板仓库渲染成真实项目；
• jinja2-time：在模板中提供时间相关的 Jinja2 扩展（如生成时间戳）；
• ruff：模板项目初始化后用于代码风格检查；
• pyyaml-include：让 YAML 配置文件支持!include引用其他 YAML 片段。

如果没有安装该 extras 就使用--template，CLI 会给出明确报错："You need to install the ZenML project template requirements to use templates. Please runpip install 'zenml[templates]'and try again."（见 src/zenml/cli/base.py#L164-L173）。

第二步：用zenml init生成项目

zenml init是初始化 ZenML 仓库的命令，其--template参数支持传入内置模板短名称或模板仓库 URL：

zenml init --template <short_name_of_template> # 示例：zenml init --template e2e_batch

执行上述命令后，CLI 会进入交互模式，向你逐项询问模板参数（如项目名、目标环境、模型搜索空间等）。如果你希望直接采用模板默认值、跳过交互式提问，可以追加--template-with-defaults：

zenml init --template <short_name_of_template> --template-with-defaults # 示例：zenml init --template e2e_batch --template-with-defaults

第三步：理解zenml init的参数与执行流程

从 src/zenml/cli/base.py#L100-L136 可以看到init命令的完整参数定义：

当传入模板时，CLI 的执行链路大致如下（对应 src/zenml/cli/base.py#L164-L252）：

1. 依赖检查：尝试from copier import Worker，失败则提示安装zenml[templates]；
2. 模板解析：若名称命中ZENML_PROJECT_TEMPLATES，则声明 "Using the xxx template..."，取注册表中锁定的github_tag作为vcs_ref；否则列出已知模板并提示 "No known templates specified. Usingxxxas URL."，将--template原样作为src_path，把--template-tag作为vcs_ref；
3. 交互式提问：若未指定--template-with-defaults，CLI 会打印 "Project template parameters" 章节标题并展示 Copier 定义的参数提示；
4. Copier 渲染：通过Worker(src_path=..., vcs_ref=..., dst_path=path, defaults=template_with_defaults, overwrite=template_with_defaults, unsafe=True)执行worker.run_copy()，将模板仓库渲染到目标目录；
5. 仓库初始化：随后调用Client.initialize(root=path)完成 ZenML 仓库初始化，并提示本地 active stack 的名称。

注意：项目模板 ≠ Run Templates

一个常见的概念混淆点：项目模板（Project Templates）与运行模板（Run Templates）是两回事。

• 项目模板（本文主题）：通过zenml init --template生成一个新的项目目录，属于"脚手架"性质；
• Run Templates：用于从 Dashboard 或 Python SDK 触发某条已存在流水线的一次运行，属于"运行配置"性质。

官方文档对此有专门提醒：不要将两者混为一谈。

模板背后的参考实现：以 e2e_batch 为例

官方 Production Guide 文档基于E2E Batch项目模板的代码编写，绝大多数示例都以它为蓝本。官方强烈建议在深入阅读 Production Guide 之前，先按如下命令安装e2e_batch模板，以便在本地环境中跟着文档实操：

mkdir e2e_batch cd e2e_batch zenml init --template e2e_batch --template-with-defaults

该模板对应的参考实现可以在本仓库的 examples/e2e 中查看，其结构恰好印证了文档对模板的描述：

examples/e2e/ ├── configs/ # 流水线配置文件 │ ├── deployer_config.yaml │ ├── inference_config.yaml │ └── train_config.yaml ├── pipelines/ # 训练、部署、批量推理三条流水线 │ ├── training.py │ ├── deployment.py │ └── batch_inference.py └── steps/ # ETL / HP 调优 / 训练 / 部署 / 数据质量 / 告警 等步骤 ├── etl/ ├── hp_tuning/ ├── training/ ├── deployment/ ├── data_quality/ └── alerts/

流水线骨架：训练流水线

examples/e2e/pipelines/training.py#L42-L53 定义了训练流水线的入口与全部参数，完整体现了"ETL → 超参调优 → 训练 → 评估 → 提升"的文档描述流程：

@pipelines(on_failure=notify_on_failure) def e2e_use_case_training( model_search_space: Dict[str, Any], # 超参搜索空间 target_env: str, # 模型提升的目标环境 test_size: float = 0.2, # 测试集比例 drop_na: Optional[bool] = None, # 是否剔除 NA 值 normalize: Optional[bool] = None, # 是否用 MinMaxScaler 归一化 drop_columns: Optional[List[str]] = None, # 需要丢弃的列 min_train_accuracy: float = 0.0, # 训练集准确率质量门槛 min_test_accuracy: float = 0.0, # 测试集准确率质量门槛 fail_on_accuracy_quality_gates: bool = False, # 未达标时是否中止 ):

其内部编排（examples/e2e/pipelines/training.py#L76-L120）分为三个明确阶段：

• ETL 阶段：data_loader→train_data_splitter→train_data_preprocessor，加载、切分、预处理数据；
• 超参调优阶段：遍历model_search_space中的每个模型配置，动态生成hp_tuning_search_<config_name>命名的调优步骤并并行运行，最后用hp_tuning_select_best_model挑选最优模型；
• 训练与评估阶段：model_trainer训练最优模型，model_evaluator依据min_train_accuracy/min_test_accuracy等参数完成评估，若开启fail_on_accuracy_quality_gates且准确率不达标则提前中止流水线。

配置驱动：YAML 中的参数体系

模板的"灵活配置"体现在 examples/e2e/configs/train_config.yaml 这样的 YAML 文件中，它展示了 ZenML 配置分层的完整形态：

# environment configuration settings: docker: required_integrations: - aws - evidently - kubeflow - kubernetes - mlflow - sklearn - slack # configuration of steps steps: model_trainer: parameters: name: e2e_use_case promote_with_metric_compare: parameters: mlflow_model_name: e2e_use_case notify_on_success: parameters: notify_on_success: False # configuration of the Model Control Plane model: name: e2e_use_case license: apache description: e2e_use_case E2E Batch Use Case audience: All ZenML users tags: - e2e - batch - sklearn - from template # pipeline level extra configurations extra: notify_on_failure: True # pipeline level parameters parameters: target_env: staging model_search_space: random_forest: model_package: sklearn.ensemble model_class: RandomForestClassifier search_grid: criterion: [gini, entropy] max_depth: [2, 4, 6]

可以看到四个层级的分工：

• settings：环境级配置，如 Docker 镜像构建时需要的集成列表（required_integrations）；
• steps：单个步骤的参数（如model_trainer的模型名、notify_on_success是否发送成功通知）；
• model：Model Control Plane（模型控制平面）元数据，用于模型注册与追踪；
• parameters：流水线级参数，直接对应流水线函数的形参（如target_env、model_search_space）。

在 examples/e2e/run.py#L178-L186 中可以看到配置文件的注入方式：通过e2e_use_case_training.with_options(config_path="configs/train_config.yaml")(**run_args_train)把 YAML 配置与命令行参数合并后运行流水线。

创建自己的 ZenML 模板

自建模板是跨项目、跨团队标准化 ML 工作流的最佳方式。ZenML 使用Copier管理项目模板——Copier 是一个简单、通用且强大的"从模板生成项目"的库。下面是根据官方文档整理的完整步骤：

1. 为模板创建独立仓库

创建存放模板代码与配置文件的 Git 仓库。这是模板的分发载体，Copier 与zenml init都会从该仓库拉取内容。

2. 将 ML 工作流写成 ZenML steps 与 pipelines

可以直接从现有模板（如 starter 模板）复制代码再按需修改，把团队沉淀的 ETL、训练、评估、部署逻辑封装成 ZenML 步骤与流水线。参考本仓库 examples/e2e/steps 的组织方式：每个功能域一个子目录（etl/、hp_tuning/、training/等），步骤按职责拆分。

3. 创建copier.yml配置文件

copier.yml是 Copier 定义模板参数及默认值的核心文件。它声明了生成项目时用户会被问到哪些问题（对应zenml init --template未加--template-with-defaults时的交互式提问），每个参数包含提示文本、类型与默认值。格式大致如下：

project_name: type: str help: Name of the project default: my_ml_project target_env: type: str help: Environment to promote the model to default: staging

zenml init在执行模板渲染时会把这些参数通过Worker(data=dict(email=..., template=...), defaults=template_with_defaults, user_defaults=dict(email=...))传给 Copier（见 src/zenml/cli/base.py#L241-L249），用户邮箱会自动注入到模板数据中。

4. 测试你的模板

使用 Copier 命令行工具，从模板仓库生成一个新项目并验证一切正常：

copier copy https://github.com/your-username/your-template.git your-project

将https://github.com/your-username/your-template.git替换为你的模板仓库地址，your-project替换为要生成的项目目录名。

5. 用zenml init消费你的模板

模板就绪后，直接通过 URL 使用它：

zenml init --template https://github.com/your-username/your-template.git

CLI 会把该 URL 直接传给 Copier 拉取（对应 src/zenml/cli/base.py#L224-L235 的 URL 分支）。也支持gh:前缀形式，如zenml init --template gh:your-username/your-template。

如需锁定模板的某个版本，使用--template-tag指定 Git tag：

zenml init --template https://github.com/your-username/your-template.git --template-tag v1.0.0

将v1.0.0替换为你模板仓库中的任意 Git tag。注意：该参数只对 URL 形式的模板生效，内置模板使用注册表锁定的 tag。

6. 维护与演进

模板创建完成后即可用于快速搭建新 ML 项目。请记得持续维护模板，使其与最新的最佳实践及 ML 工作流变更保持同步——模板是团队工程资产的载体，只有保持更新才能持续发挥作用。

模板功能的测试保障

模板功能有专门的集成测试守护。tests/integration/functional/cli/test_base.py#L40-L69 中，test_init_creates_from_templates会对ZENML_PROJECT_TEMPLATES中注册的每一个模板执行参数化测试：在临时目录中以--template <name> --template-with-defaults --test调用init，断言退出码为 0、.zen仓库目录存在，并检查生成项目包含.copier-answers.yml、.dockerignore等必备文件。这意味着模板在版本发布时经过了自动化验证，可以放心作为项目脚手架使用。

常见问题与最佳实践

• 交互式提问太多？使用--template-with-defaults直接采用默认参数，官方在跟随 Production Guide 时就是这么推荐的；生成后仍可手工修改 YAML 配置与代码。
• 模板名报错？检查是否漏装zenml[templates]extras（Copier 未安装时会明确报错）；确认短名称拼写正确，可用源码中的ZENML_PROJECT_TEMPLATES键（e2e_batch、starter、nlp、llm_finetuning）对照。
• 想要固定模板版本？对自建模板用--template-tag指定 Git tag；内置模板的版本由 ZenML 版本锁定，无需也无法手动指定。
• 想贡献自己的模板？官方欢迎用户分享基于 ZenML 的真实项目作为模板，以帮助社区理解 MLOps 的真实使用场景。
• 跟着文档实操：安装e2e_batch模板后再阅读 Production Guide，绝大多数示例都可以在本地直接运行对照。

从"三步生成项目"到"自建团队模板"，ZenML 项目模板把工程脚手架、配置管理和 Copier 模板引擎串联成一条完整的标准化路径。无论你是刚接触 ZenML 的新手，还是需要为团队沉淀最佳实践的资深工程师，都能从这套模板机制中受益。

【免费下载链接】zenmlZenML 🙏: One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml