ZenML Local Orchestrator 完全指南：零基础设施本地运行与调试机器学习流水线-迪斯科星球

ZenML Local Orchestrator 完全指南：零基础设施本地运行与调试机器学习流水线

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

ZenML 的 Local Orchestrator（本地编排器）是随 ZenML 内置的编排器 flavor，负责在你自己的机器上以进程内方式直接执行流水线，无需任何云基础设施与额外配置。阅读本文后，你将掌握本地编排器的适用场景、通过zenml orchestrator register与zenml stack register注册激活的完整操作步骤、其底层执行流程与三种失败执行模式，并能结合源码理解它的能力边界与调试技巧。

什么是 Local Orchestrator

在 ZenML 中，**编排器（orchestrator）**是栈（Stack）中的一个核心组件，负责决定流水线（pipeline）中的各个步骤（step）在哪里、以何种方式执行。Local Orchestrator 是名为local的编排器 flavor，它随 ZenML 一起内置发布，直接在本机运行流水线。

从源码结构看，localflavor 由三部分构成，全部定义在本地编排器实现中：

LocalOrchestrator：继承自BaseOrchestrator的执行类，负责流水线提交与步骤执行；
LocalOrchestratorConfig：继承自BaseOrchestratorConfig的配置类；
LocalOrchestratorFlavor：flavor 定义，其name属性返回"local"，type为StackComponentType.ORCHESTRATOR。

其核心定位在源码类文档字符串中写得很清楚："Orchestrator responsible for running pipelines locally"，并且明确说明它不允许步骤并发执行，也不支持定时调度运行。这两个约束是理解本地编排器适用边界的关键。

在单元测试中，flavor 的基础属性得到了验证：flavor.type == StackComponentType.ORCHESTRATOR且flavor.name == "local"，确保local能被 ZenML 正确识别为编排器类型组件。

什么时候应该使用它

Local Orchestrator 是你初次接触 ZenML 时默认栈（default stack）的组成部分。由于它完全运行在你的机器上，因此：

无需任何额外搭建：不需要配置云账号、不需要安装 Kubernetes 集群、不需要申请 GPU 实例；
易于使用和调试：步骤与你的 Python 进程共享同一个环境，报错栈、日志输出和断点调试都像运行普通脚本一样直观。

官方文档给出的推荐使用场景有两个：

你刚开始使用 ZenML，希望在不搭建任何云基础设施的前提下先把流水线跑起来；
你在编写一个新的流水线，希望快速实验和调试，而不是把时间花在等待远程资源调度上。

相反，如果你的流水线需要并发执行步骤、按计划（schedule）定时运行，或者需要海量算力支撑的训练任务，那么本地编排器并不合适，应当考虑 local_docker 或其他远程编排器 flavor。

如何部署它

Local Orchestrator随 ZenML 一起发布，开箱即用，不需要任何额外部署步骤。安装 ZenML 之后它便立即可用，这也是它成为新手默认选择的原因。

如何注册并使用它

尽管它是默认栈的一部分，你也可以显式地注册它并在自己的栈中激活使用。完整操作如下：

# 注册一个 flavor 为 local 的编排器组件 zenml orchestrator register <ORCHESTRATOR_NAME> --flavor=local # 注册一个包含该编排器的栈，并立即激活它 zenml stack register <STACK_NAME> -o <ORCHESTRATOR_NAME> ... --set

其中：

<ORCHESTRATOR_NAME>是你要给这个编排器组件起的名字（例如local_orch）；
<STACK_NAME>是栈的名字；
-o <ORCHESTRATOR_NAME>指定栈使用的编排器；
...表示你还需要按需补充栈中的其他组件（如 artifact store、orchestrator 之外的可选组件）；
--set表示注册完成后立刻把该栈设为当前激活栈。

注册并激活后，你就可以用本地编排器运行任何 ZenML 流水线了——只需像执行普通 Python 脚本一样运行包含流水线构建与执行的代码：

python file_that_runs_a_zenml_pipeline.py

源码级原理：本地编排器如何执行流水线

要真正用好一个编排器，理解它的执行模型至关重要。下面我们沿着本地编排器实现中的submit_pipeline方法梳理一次流水线在本地的完整执行链路。

执行流程总览

生成运行 ID：submit_pipeline首先通过str(uuid4())为本次运行生成唯一的_orchestrator_run_id，流水线内所有步骤共享同一个 ID，供步骤执行上下文与元数据关联使用。
执行 init hook：调用run_init_hook，初始化流水线级运行上下文。
顺序执行每个步骤：进入setup_execution_context()，然后按顺序遍历snapshot.step_configurations中的每个步骤，逐个调用self.run_step(step=step)。这正是"不允许并发执行"的源码体现——步骤在一个进程内串行执行。
执行 cleanup hook：全部步骤结束后调用run_cleanup_hook收尾。
汇总结果：记录整个运行耗时并以人类可读格式（get_human_readable_time）打印Pipeline run has finished in ...。

失败处理与执行模式

submit_pipeline内部维护failed_steps、skipped_steps两个列表来跟踪执行状态。每当某个步骤抛出异常，它会被记入failed_steps并打印错误日志。此时具体行为取决于流水线配置的执行模式（execution mode），由执行模式枚举定义。本地编排器通过supported_execution_modes属性声明其支持的全部三种模式：

执行模式	枚举值	行为说明
`FAIL_FAST`	`fail_fast`	某个步骤失败后立即终止后续步骤，并抛出该步骤的异常
`STOP_ON_FAILURE`	`stop_on_failure`	一旦有步骤失败，跳过所有尚未执行的后续步骤（不继续执行）
`CONTINUE_ON_FAILURE`	`continue_on_failure`	某个步骤失败后仍继续执行其他步骤，最后统一报告失败

此外，代码还会针对上游步骤失败或跳过的下游步骤给出明确警告（"Skipping step ... due to failure in upstream step(s)"），保证依赖关系不被破坏。当所有步骤执行完毕且存在失败步骤时，最终会抛出RuntimeError("Pipeline run has failed due to failure in step(s): ...")。

同步执行与本地组件属性

LocalOrchestratorConfig覆盖了基类编排器基类配置中的两个关键属性：

is_local返回True：声明该组件运行在本地环境；
is_synchronous返回True：声明该编排器同步执行——python file_that_runs_a_zenml_pipeline.py会一直阻塞等待流水线完整结束，这在快速实验场景中非常友好。

与之对比，基类BaseOrchestratorConfig的默认is_synchronous为False（异步提交），is_schedulable为False（不可调度），而supports_client_side_caching默认为True，handles_step_retries默认为False。

Hook 的运行时机

基类中run_init_cleanup_at_step_level默认返回True（即 init/cleanup hook 需要在每个步骤级别执行，适用于步骤运行在相互隔离环境中的编排器），而本地编排器将其覆盖为False。源码注释解释了原因：由于本地编排器的步骤共享同一个进程环境和共享内存，init 与 cleanup hook 可以在运行（run）级别只执行一次，而不是在每个步骤中重复执行。这是本地编排器在语义上区别于容器化编排器的一个重要细节。

动态流水线与隔离步骤

除常规流水线外，本地编排器还实现了submit_dynamic_pipeline，通过DynamicPipelineRunner支持动态流水线（dynamic pipeline）的执行，同样以同步方式运行并在结束时打印耗时信息。

能力边界与注意事项

基于源码实现，使用本地编排器时有几个事实层面的边界需要了解：

不支持步骤级资源请求：submit_pipeline会检查requires_resources_in_orchestration_environment(step)，若步骤配置了资源需求，会打印警告 "Specifying step resources is not supported for the local orchestrator, ignoring resource configuration"，即资源配置会被忽略。如需 GPU、内存等资源约束，应使用支持资源调度的编排器或 step operator。
不支持并发：步骤严格串行执行。
不支持调度：is_schedulable为False，流水线只能手动触发。
运行环境依赖：由于步骤直接在你的 Python 进程中执行，所有步骤的依赖包、环境变量都在本机解释器环境中解析，因此保持本地环境的可复现性（例如使用虚拟环境或容器镜像管理依赖）对稳定运行尤为重要。

调试与验证建议

本地编排器最大的优势就是调试体验接近原生 Python 开发：

步骤抛出的异常会携带完整的 Python traceback 直接展示在终端，配合日志即可快速定位；
由于是同步执行，你可以在步骤函数内直接打断点进行单步调试；
参考本地编排器单元测试的写法，验证 flavor 的注册属性是否符合预期；
若你希望步骤在本地 Docker 容器中隔离执行以贴近生产环境，可以改用local_dockerflavor（见 local_docker 编排器），它同样运行在本地，但会为每个步骤构建并运行容器。

总结

Local Orchestrator 是 ZenML 中最轻量、最易上手的编排器：零部署成本、同步执行、进程内串行运行步骤，非常适合新手入门、流水线原型开发与快速调试。理解其"不支持并发、不支持调度、忽略步骤资源请求、hook 运行级执行"等源码级行为边界，能帮助你在正确的场景选择正确的编排器，避免在规模化需求上误用本地方案。需要进一步了解 flavor 的全部可配置属性时，可直接查阅本地编排器源码与编排器基类。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析