ZenML 多环境配置实践指南Client、Server、Execution 与 Image Builder 环境的依赖管理【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenmlZenML 的流水线往往跨越多个运行环境本机开发、CI 执行器、ZenML Server、远程编排器以及镜像构建环境。本文以 docs/book/user-guide/best-practices/configure-python-environments.md 为骨架结合仓库源码CLI 实现、集成注册表、容器化配置系统讲解每个环境的职责边界、依赖管理方法、zenml integration系列命令的底层原理以及依赖冲突的排查与规避策略帮助你在真实项目中把各环境的 Python 依赖治理得井井有条。环境全景一张图看懂 ZenML 的多环境布局ZenML 部署通常涉及多个环境依赖与配置需要在它们之间保持一致。核心环境可以分为四类Client 环境Runner 环境流水线在此“编译”即调用pipeline装饰的流水线函数通常在run.py脚本中。ZenML Server 环境负责管理流水线与元数据的 FastAPI 应用自带 ZenML Dashboard。Execution 环境远程编排器如 Kubernetes、Vertex AI中实际运行 step 的 Docker 容器。Image Builder 环境负责构建并推送这些 Docker 镜像的专用环境。从源码结构看这四类环境对应了 ZenML 源码中的不同职责模块src/zenml/zen_server/是 Server 的 FastAPI 实现src/zenml/orchestrators/与src/zenml/image_builders/分别承载执行与构建逻辑。理解这些环境的边界是做好依赖管理的前提。Client 环境Runner 环境流水线编译发生的地方Client 环境是调用流水线函数典型场景是run.py脚本的地方也是流水线被“编译”的地方。它可以是本地开发环境生产环境中的 CI runnerZenML Pro runner由 ZenML Server 编排启动流水线的runner镜像。在所有 Client 环境中都建议使用自己偏好的包管理器如pip、poetry、uv管理依赖并确保安装了 ZenML 包及其所需的 integrations。启动流水线的三个关键步骤Client 环境启动一条流水线时典型经历以下步骤通过pipeline函数编译出中间流水线表示intermediate pipeline representation若在远程运行创建或触发 pipeline 与 step 的构建环境即后续的镜像构建在 orchestrator 中触发一次运行。编译期与执行期Client 环境独有的约束一个必须牢记的约束是pipeline函数只会在 Client 环境中被调用一次。因此流水线函数内执行的任何计算逻辑都必须服务于所谓“编译期”compile time而不是稍后才会发生的“执行期”execution time。换句话说不要在流水线函数体内写真正依赖数据、需要在 step 里运行的逻辑——那部分逻辑应当放在 step 函数中由 Execution 环境去执行。ZenML Server 环境FastAPI 应用与 DashboardZenML Server 是一个 FastAPI 应用负责管理流水线与元数据并包含 ZenML Dashboard。它的依赖管理方式与 Client 环境不同绝大多数集成能力是 Server内置的不需要额外安装只有在使用自定义集成时才需要在 部署 ZenML 时安装相应依赖。从仓库看Server 的完整实现位于 src/zenml/zen_server/ 目录涵盖 API 路由、认证、元数据存储等逻辑。若需要扩展 Server 能力应在部署阶段通过官方部署流程Docker 镜像、Helm Chart 或云平台部署注入额外依赖而不是在运行时动态安装。Execution 环境远程运行时的 Docker 镜像本地运行时“执行环境”的概念并不真正存在——Client、Server、Execution 三者合一。但一旦流水线在远程运行ZenML 就需要把代码与环境“搬运”到远程 orchestrator。为此ZenML 会构建称为execution environments的 Docker 镜像。镜像的构建方式ZenML 负责 Docker 镜像的配置、构建与推送流程如下从包含 ZenML 与 Python 的 base image 开始自动检测栈中使用的集成并安装对应依赖可选地将你的源码文件拷贝进容器设置用户自定义的环境变量。完整的容器化配置请参考 containerize your pipeline 指南其中涵盖了指定额外 pip 依赖、使用自定义父镜像、自定义构建过程等内容。用 DockerSettings 控制依赖注入在远程编排器场景下如果你手动调整了集成依赖版本就必须把这些版本同步到 Execution 环境。最直接的方式是通过DockerSettings对象源码定义于 src/zenml/config/docker_settings.py指定from zenml import pipeline from zenml.config import DockerSettings docker_settings DockerSettings( requirements[my-pinned-package1.2.3], required_integrations[gcp], install_stack_requirementsTrue, ) pipeline(settings{docker: docker_settings}) def my_pipeline(...): ...DockerSettings支持的常用配置项包括配置项作用默认值parent_image自定义父镜像必须包含 Python、pip、ZenML官方 ZenML 镜像required_integrations显式安装指定集成的依赖空列表requirements追加 pip 依赖列表或 requirements 文件路径空install_stack_requirements是否自动安装当前栈所需依赖Truereplicate_local_python_environment用pip freeze复刻本地环境的全部包Falseskip_build跳过构建、直接使用parent_image运行Falseenvironment/runtime_environment构建期 / 运行期环境变量空依赖安装顺序ZenML 会按以下顺序安装依赖每一步都是可选的本地 Python 环境中已安装的包若启用replicate_local_python_environment当前栈所需的包除非设置install_stack_requirementsFalse通过required_integrations指定的集成包通过requirements指定的包。这个顺序意味着后安装的依赖有可能覆盖先安装的版本理解它有助于预判版本冲突。Image Builder 环境在专用环境构建镜像默认情况下Execution 环境是在 Client 环境中用本地 Docker 客户端构建的但这要求本机安装 Docker 并具备相应权限。ZenML 提供了 image builders 这一特殊的 stack component允许在独立的 Image Builder 环境中构建并推送 Docker 镜像。注意即使你的栈中没有配置 image builderZenML 仍会使用 local image builder 来保持所有构建的一致性——此时 Image Builder 环境与 Client 环境是同一个。容器引擎的选择本地构建依赖本机的容器引擎当前支持Docker与Podman。这是 ZenML client 的全局设置默认行为ZenML 自动选择——优先尝试 Docker若不可用则回退到 Podman固定引擎通过环境变量ZENML_CONTAINER_ENGINE设置为docker或podman例如export ZENML_CONTAINER_ENGINEpodman依赖处理冲突从何而来ZenML 力求与栈和集成“解耦”stack- and integration-agnostic允许你用适合自己问题的工具运行流水线。但这种灵活性也带来了依赖冲突的可能当你在环境中同时使用其他库时集成所需的依赖版本可能与它们互斥。ZenML 提供zenml integration install ...命令来安装某个集成所需的依赖。这是一个便捷途径但如果在同一个环境中混用其他库也可能引入冲突。用zenml integration list快速验证安装额外依赖后一个快速验证 ZenML 自身要求是否仍被满足的方法是zenml integration list检查你需要的集成是否仍带有绿色勾选标记表示其全部依赖要求均已满足。从源码看该命令实现在 src/zenml/cli/integration.py它通过integration_registry遍历所有注册的集成并调用check_installation()判断每个集成的依赖是否齐备。zenml integration命令族从安装到导出zenml integration是管理集成依赖的核心 CLI 命令组实现在 src/zenml/cli/integration.py。其底层机制是zenml integration install ...本质上是在背后执行pip install ...安装的是集成对象中列出的依赖。例如zenml integration install gcp会执行类似于pip install kfp2.6.0 gcsfs... google-cloud-secret-manager ...的命令——这些依赖定义在 src/zenml/integrations/gcp/init.py 的REQUIREMENTS列表中。常用子命令一览子命令作用zenml integration list列出所有可用集成及其安装状态zenml integration install NAME安装指定集成的依赖默认用 pip--uv可用 uvzenml integration uninstall NAME卸载指定集成的依赖zenml integration upgrade NAME升级指定集成的依赖zenml integration requirements NAME列出某个集成的全部依赖要求zenml integration export-requirements NAME将依赖导出到文件或打印到控制台install 子命令的进阶选项从 src/zenml/cli/integration.py 可以看到install支持以下选项-i/--ignore-integration显式跳过某些集成-y/--yes跳过确认步骤并强制重装已存在的包--uv实验性使用uv作为包安装器不指定集成名时会安装所有注册集成的依赖可用--ignore-integration排除。此外源码还包含两个与 Python 版本相关的防护逻辑见 src/zenml/cli/integration.py在 Python 3.12 环境下tensorflow与deepchecks集成会被自动跳过并给出警告因为它们尚未兼容 Python 3.12。手动绕过集成安装跳过 ZenML 的集成安装流程、手动安装依赖是可能但不受推荐的做法风险自负。具体步骤如下首先导出集成依赖# 将依赖导出到文件 zenml integration export-requirements --output-file integration-requirements.txt INTEGRATION_NAME # 将依赖打印到控制台 zenml integration export-requirements INTEGRATION_NAME然后按需修改这些依赖并手动pip install。export-requirements命令src/zenml/cli/integration.py还支持这些选项选项作用-i/--ignore-integration显式忽略某些集成可多次指定-o/--output-file导出到指定文件不指定则打印到 stdout-ov/--overwrite输出文件已存在时覆盖仅配合--output-file--installed-only仅导出当前环境中已安装集成的依赖--poetry将导出的依赖直接poetry add到当前 Poetry 项目注意--installed-only不能与显式指定集成名同时使用--poetry与--output-file互斥。若使用远程编排器手动调整版本后必须通过DockerSettings见上文把这些依赖注入到 Execution 镜像中才能保证实际运行环境与预期一致。依赖冲突排查建议用pip-compile保证可复现性推荐使用pip-compile来自 pip-tools 包把依赖编译成静态的requirements.txt供所有环境共用。如果使用uv可以用uv pip compile作为替代方案。这样做的价值在于把间接依赖的版本也锁定下来避免不同环境解析出不同版本。ZenML 官方仓库提供了一个名为 zenml-gitflow 的实战示例专门演示如何用pip-compile解决跨环境依赖管理问题值得参考。用pip check发现依赖冲突运行pip check会验证当前环境中所有依赖是否互相兼容若不兼容会列出冲突清单。冲突不一定阻止你的具体用例运行但了解冲突的存在是必要的——它往往是诡异运行时错误的来源。已知的依赖解析问题部分 ZenML 集成对依赖及包版本有严格要求。ZenML 自研集成会尽量放宽依赖范围但并非总能做到完美平滑。一个已知问题是clickZenML 目前要求click~8.0.3用于其 CLI这源于 ZenML 的另一个依赖。如果你在自己的项目中使用高于 8.0.3 的click版本可能引发未预期的行为。本地运行当所有环境合而为一当流水线在本地运行时Client、Server 与 Execution 环境是同一个——无需构建镜像、无需传输代码。此时依赖管理回归到最简单的形态只要本地环境中安装了 ZenML、相关集成以及业务依赖流水线就能直接执行。多环境治理的复杂性主要在远程场景中体现。小结与最佳实践ZenML 的多环境架构可以用一句话概括Client 负责编译Server 负责编排Execution 负责执行Image Builder 负责构建。基于本文内容可以沉淀出如下最佳实践区分编译期与执行期逻辑pipeline函数只在 Client 环境执行一次计算逻辑务必放在 step 中统一锁定依赖用pip-compile/uv pip compile生成静态requirements.txt保证各环境版本一致定期自检安装新依赖后运行zenml integration list检查绿色勾选、pip check检查冲突远程环境同步手动调整集成依赖后务必通过DockerSettings把版本注入 Execution 镜像按需使用 image builder需要独立构建环境如云端构建、无本机 Docker时在栈中配置对应 image builder留意版本陷阱如click的~8.0.3约束以及 Python 3.12 下tensorflow、deepchecks集成暂不可用。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZenML 多环境配置实践指南：Client、Server、Execution 与 Image Builder 环境的依赖管理
ZenML 多环境配置实践指南Client、Server、Execution 与 Image Builder 环境的依赖管理【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenmlZenML 的流水线往往跨越多个运行环境本机开发、CI 执行器、ZenML Server、远程编排器以及镜像构建环境。本文以 docs/book/user-guide/best-practices/configure-python-environments.md 为骨架结合仓库源码CLI 实现、集成注册表、容器化配置系统讲解每个环境的职责边界、依赖管理方法、zenml integration系列命令的底层原理以及依赖冲突的排查与规避策略帮助你在真实项目中把各环境的 Python 依赖治理得井井有条。环境全景一张图看懂 ZenML 的多环境布局ZenML 部署通常涉及多个环境依赖与配置需要在它们之间保持一致。核心环境可以分为四类Client 环境Runner 环境流水线在此“编译”即调用pipeline装饰的流水线函数通常在run.py脚本中。ZenML Server 环境负责管理流水线与元数据的 FastAPI 应用自带 ZenML Dashboard。Execution 环境远程编排器如 Kubernetes、Vertex AI中实际运行 step 的 Docker 容器。Image Builder 环境负责构建并推送这些 Docker 镜像的专用环境。从源码结构看这四类环境对应了 ZenML 源码中的不同职责模块src/zenml/zen_server/是 Server 的 FastAPI 实现src/zenml/orchestrators/与src/zenml/image_builders/分别承载执行与构建逻辑。理解这些环境的边界是做好依赖管理的前提。Client 环境Runner 环境流水线编译发生的地方Client 环境是调用流水线函数典型场景是run.py脚本的地方也是流水线被“编译”的地方。它可以是本地开发环境生产环境中的 CI runnerZenML Pro runner由 ZenML Server 编排启动流水线的runner镜像。在所有 Client 环境中都建议使用自己偏好的包管理器如pip、poetry、uv管理依赖并确保安装了 ZenML 包及其所需的 integrations。启动流水线的三个关键步骤Client 环境启动一条流水线时典型经历以下步骤通过pipeline函数编译出中间流水线表示intermediate pipeline representation若在远程运行创建或触发 pipeline 与 step 的构建环境即后续的镜像构建在 orchestrator 中触发一次运行。编译期与执行期Client 环境独有的约束一个必须牢记的约束是pipeline函数只会在 Client 环境中被调用一次。因此流水线函数内执行的任何计算逻辑都必须服务于所谓“编译期”compile time而不是稍后才会发生的“执行期”execution time。换句话说不要在流水线函数体内写真正依赖数据、需要在 step 里运行的逻辑——那部分逻辑应当放在 step 函数中由 Execution 环境去执行。ZenML Server 环境FastAPI 应用与 DashboardZenML Server 是一个 FastAPI 应用负责管理流水线与元数据并包含 ZenML Dashboard。它的依赖管理方式与 Client 环境不同绝大多数集成能力是 Server内置的不需要额外安装只有在使用自定义集成时才需要在 部署 ZenML 时安装相应依赖。从仓库看Server 的完整实现位于 src/zenml/zen_server/ 目录涵盖 API 路由、认证、元数据存储等逻辑。若需要扩展 Server 能力应在部署阶段通过官方部署流程Docker 镜像、Helm Chart 或云平台部署注入额外依赖而不是在运行时动态安装。Execution 环境远程运行时的 Docker 镜像本地运行时“执行环境”的概念并不真正存在——Client、Server、Execution 三者合一。但一旦流水线在远程运行ZenML 就需要把代码与环境“搬运”到远程 orchestrator。为此ZenML 会构建称为execution environments的 Docker 镜像。镜像的构建方式ZenML 负责 Docker 镜像的配置、构建与推送流程如下从包含 ZenML 与 Python 的 base image 开始自动检测栈中使用的集成并安装对应依赖可选地将你的源码文件拷贝进容器设置用户自定义的环境变量。完整的容器化配置请参考 containerize your pipeline 指南其中涵盖了指定额外 pip 依赖、使用自定义父镜像、自定义构建过程等内容。用 DockerSettings 控制依赖注入在远程编排器场景下如果你手动调整了集成依赖版本就必须把这些版本同步到 Execution 环境。最直接的方式是通过DockerSettings对象源码定义于 src/zenml/config/docker_settings.py指定from zenml import pipeline from zenml.config import DockerSettings docker_settings DockerSettings( requirements[my-pinned-package1.2.3], required_integrations[gcp], install_stack_requirementsTrue, ) pipeline(settings{docker: docker_settings}) def my_pipeline(...): ...DockerSettings支持的常用配置项包括配置项作用默认值parent_image自定义父镜像必须包含 Python、pip、ZenML官方 ZenML 镜像required_integrations显式安装指定集成的依赖空列表requirements追加 pip 依赖列表或 requirements 文件路径空install_stack_requirements是否自动安装当前栈所需依赖Truereplicate_local_python_environment用pip freeze复刻本地环境的全部包Falseskip_build跳过构建、直接使用parent_image运行Falseenvironment/runtime_environment构建期 / 运行期环境变量空依赖安装顺序ZenML 会按以下顺序安装依赖每一步都是可选的本地 Python 环境中已安装的包若启用replicate_local_python_environment当前栈所需的包除非设置install_stack_requirementsFalse通过required_integrations指定的集成包通过requirements指定的包。这个顺序意味着后安装的依赖有可能覆盖先安装的版本理解它有助于预判版本冲突。Image Builder 环境在专用环境构建镜像默认情况下Execution 环境是在 Client 环境中用本地 Docker 客户端构建的但这要求本机安装 Docker 并具备相应权限。ZenML 提供了 image builders 这一特殊的 stack component允许在独立的 Image Builder 环境中构建并推送 Docker 镜像。注意即使你的栈中没有配置 image builderZenML 仍会使用 local image builder 来保持所有构建的一致性——此时 Image Builder 环境与 Client 环境是同一个。容器引擎的选择本地构建依赖本机的容器引擎当前支持Docker与Podman。这是 ZenML client 的全局设置默认行为ZenML 自动选择——优先尝试 Docker若不可用则回退到 Podman固定引擎通过环境变量ZENML_CONTAINER_ENGINE设置为docker或podman例如export ZENML_CONTAINER_ENGINEpodman依赖处理冲突从何而来ZenML 力求与栈和集成“解耦”stack- and integration-agnostic允许你用适合自己问题的工具运行流水线。但这种灵活性也带来了依赖冲突的可能当你在环境中同时使用其他库时集成所需的依赖版本可能与它们互斥。ZenML 提供zenml integration install ...命令来安装某个集成所需的依赖。这是一个便捷途径但如果在同一个环境中混用其他库也可能引入冲突。用zenml integration list快速验证安装额外依赖后一个快速验证 ZenML 自身要求是否仍被满足的方法是zenml integration list检查你需要的集成是否仍带有绿色勾选标记表示其全部依赖要求均已满足。从源码看该命令实现在 src/zenml/cli/integration.py它通过integration_registry遍历所有注册的集成并调用check_installation()判断每个集成的依赖是否齐备。zenml integration命令族从安装到导出zenml integration是管理集成依赖的核心 CLI 命令组实现在 src/zenml/cli/integration.py。其底层机制是zenml integration install ...本质上是在背后执行pip install ...安装的是集成对象中列出的依赖。例如zenml integration install gcp会执行类似于pip install kfp2.6.0 gcsfs... google-cloud-secret-manager ...的命令——这些依赖定义在 src/zenml/integrations/gcp/init.py 的REQUIREMENTS列表中。常用子命令一览子命令作用zenml integration list列出所有可用集成及其安装状态zenml integration install NAME安装指定集成的依赖默认用 pip--uv可用 uvzenml integration uninstall NAME卸载指定集成的依赖zenml integration upgrade NAME升级指定集成的依赖zenml integration requirements NAME列出某个集成的全部依赖要求zenml integration export-requirements NAME将依赖导出到文件或打印到控制台install 子命令的进阶选项从 src/zenml/cli/integration.py 可以看到install支持以下选项-i/--ignore-integration显式跳过某些集成-y/--yes跳过确认步骤并强制重装已存在的包--uv实验性使用uv作为包安装器不指定集成名时会安装所有注册集成的依赖可用--ignore-integration排除。此外源码还包含两个与 Python 版本相关的防护逻辑见 src/zenml/cli/integration.py在 Python 3.12 环境下tensorflow与deepchecks集成会被自动跳过并给出警告因为它们尚未兼容 Python 3.12。手动绕过集成安装跳过 ZenML 的集成安装流程、手动安装依赖是可能但不受推荐的做法风险自负。具体步骤如下首先导出集成依赖# 将依赖导出到文件 zenml integration export-requirements --output-file integration-requirements.txt INTEGRATION_NAME # 将依赖打印到控制台 zenml integration export-requirements INTEGRATION_NAME然后按需修改这些依赖并手动pip install。export-requirements命令src/zenml/cli/integration.py还支持这些选项选项作用-i/--ignore-integration显式忽略某些集成可多次指定-o/--output-file导出到指定文件不指定则打印到 stdout-ov/--overwrite输出文件已存在时覆盖仅配合--output-file--installed-only仅导出当前环境中已安装集成的依赖--poetry将导出的依赖直接poetry add到当前 Poetry 项目注意--installed-only不能与显式指定集成名同时使用--poetry与--output-file互斥。若使用远程编排器手动调整版本后必须通过DockerSettings见上文把这些依赖注入到 Execution 镜像中才能保证实际运行环境与预期一致。依赖冲突排查建议用pip-compile保证可复现性推荐使用pip-compile来自 pip-tools 包把依赖编译成静态的requirements.txt供所有环境共用。如果使用uv可以用uv pip compile作为替代方案。这样做的价值在于把间接依赖的版本也锁定下来避免不同环境解析出不同版本。ZenML 官方仓库提供了一个名为 zenml-gitflow 的实战示例专门演示如何用pip-compile解决跨环境依赖管理问题值得参考。用pip check发现依赖冲突运行pip check会验证当前环境中所有依赖是否互相兼容若不兼容会列出冲突清单。冲突不一定阻止你的具体用例运行但了解冲突的存在是必要的——它往往是诡异运行时错误的来源。已知的依赖解析问题部分 ZenML 集成对依赖及包版本有严格要求。ZenML 自研集成会尽量放宽依赖范围但并非总能做到完美平滑。一个已知问题是clickZenML 目前要求click~8.0.3用于其 CLI这源于 ZenML 的另一个依赖。如果你在自己的项目中使用高于 8.0.3 的click版本可能引发未预期的行为。本地运行当所有环境合而为一当流水线在本地运行时Client、Server 与 Execution 环境是同一个——无需构建镜像、无需传输代码。此时依赖管理回归到最简单的形态只要本地环境中安装了 ZenML、相关集成以及业务依赖流水线就能直接执行。多环境治理的复杂性主要在远程场景中体现。小结与最佳实践ZenML 的多环境架构可以用一句话概括Client 负责编译Server 负责编排Execution 负责执行Image Builder 负责构建。基于本文内容可以沉淀出如下最佳实践区分编译期与执行期逻辑pipeline函数只在 Client 环境执行一次计算逻辑务必放在 step 中统一锁定依赖用pip-compile/uv pip compile生成静态requirements.txt保证各环境版本一致定期自检安装新依赖后运行zenml integration list检查绿色勾选、pip check检查冲突远程环境同步手动调整集成依赖后务必通过DockerSettings把版本注入 Execution 镜像按需使用 image builder需要独立构建环境如云端构建、无本机 Docker时在栈中配置对应 image builder留意版本陷阱如click的~8.0.3约束以及 Python 3.12 下tensorflow、deepchecks集成暂不可用。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考