尧图网站建设 
为 ZenML 实现自定义集成Custom Integration完整指南从自定义 Flavor 到核心代码库贡献【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenmlZenML 将不断膨胀的 MLOps 工具生态抽象为统一的栈Stack与组件Component体系而集成Integration机制则是这套体系对外开放的插槽它允许你把任意 MLOps 工具打包成一组可复用的栈组件 Flavor并随 ZenML 主仓库分发给所有人。本文以 implement-a-custom-integration.md 为骨架结合src/zenml/integrations/下的真实源码完整讲解从规划集成、注册自定义 Flavor到编写Integration子类、提交 Pull Request 的每一步读完后你将具备为 ZenML 贡献一个生产级工具集成的全部实战能力。一、前置知识理解 ZenML 的集成体系在动手之前先明确三个概念之间的关系这是本指南的前提Stack Component Type组件类型一个宽泛的功能类别如orchestrator、artifact_store、experiment_tracker。ZenML 的完整类别列表可在 component-guide 中查看包括 alerter、annotator、artifact store、container registry、data validator、deployer、experiment tracker、feature store、image builder、log store、model deployer、model registry、orchestrator、service connector、step operator 等。Flavor口味/实现变体某一组件类型下的具体实现例如artifact_store类型下有local、s3等 Flavor。Integration集成将一组相关 Flavor以及 materializer、service connector、steps 等配套模块打包的集合是 ZenML 主代码库中的一等公民。一个集成可以横跨多个组件类别。例如云厂商集成AWS/GCP/Azure同时包含 container registry、artifact store 等 Flavor再如仓库中的 MLflow 集成 一次声明了实验追踪器experiment tracker、模型部署器model deployer与模型注册表model registry三个类别的 Flavor。因此规划阶段的第一步就是先确定你的集成属于哪些类别。从源码层面看所有集成最终都汇聚在一个全局注册表中。IntegrationMeta元类在Integration子类创建时自动将其注册进integration_registry见 integration.py而注册表会遍历zenml.integrations包下所有含__init__.py的子目录并逐个导入见 registry.py。这意味着只要你的集成目录结构正确、类定义完整ZenML 就能在启动时自动发现它无需额外注册中心。二、Step 1规划你的集成这是成本最低、但最容易出错的步骤。请回答两个问题你的集成属于哪些类别回到上文提到的组件类别清单勾选与你的工具能力匹配的类别。例如要接入一个实验追踪工具就对应experiment_tracker要接入云端对象存储就对应artifact_store两者都要就同时规划两个类别。每个类别下要实现哪些 Flavor一个类别下通常只需一个 Flavor但也可以像 MLflow 那样为一个类别提供不同语义的多个 FlavorMLFlowModelDeployerFlavor、MLFlowExperimentTrackerFlavor、MLFlowModelRegistryFlavor。建议同时研读 如何编写自定义栈组件它会详细讲解StackComponent、StackComponentConfig、Flavor三个核心抽象——它们是后续所有实现的基础。三、Step 2先以自定义 Flavor形态开发并验证不要急着打包成集成。先用 ZenML 的自定义 Flavor 机制把每个组件开发、测试到可用状态再进入打包阶段可以大幅降低集成开发的调试成本。3.1 注册自定义 Flavor假设你正在开发一个自定义 orchestratorFlavor 类MyOrchestratorFlavor定义在flavors/my_flavor.py中注册命令为zenml orchestrator flavor register flavors.my_flavor.MyOrchestratorFlavor该命令的底层实现见 stack_components.py它通过client.create_flavor(sourcesource, component_typecomponent_type)解析点分路径并创建 Flavor 模型命令名由组件类型自动生成artifact_store→zenml artifact-store flavor register ...orchestrator →zenml orchestrator flavor register ...。注册成功后可用如下命令确认新 Flavor 已出现在列表中zenml orchestrator flavor listlist命令会调用client.get_flavors_by_type()拉取该类型下的全部 Flavor内置与自定义的都会列出。3.2 关于解析路径的重要警告⚠️ZenML 解析 Flavor 类的起点是zenml init初始化的仓库根目录而不是当前所在目录。因此务必遵循最佳实践在仓库根目录执行zenml init。如果 ZenML 在任何父目录中都找不到已初始化的仓库它会退而使用当前工作目录作为解析起点——这种机制可以工作但通常不应依赖它。这一点在 CLI 源码中有直接体现当client.root为空时命令会打印警告你的当前工作目录将被用作 source 参数的解析根目录请在你的源码根目录运行zenml init以消除此警告见 stack_components.py若加载失败错误信息也会明确提示请确保你已在仓库根目录运行过zenml init。四、Step 3将组件打包成 Integration当所有组件以自定义 Flavor 形态验证通过后就可以开始打包并最终并入 ZenML 主包。以下是完整的 checklist。4.1 Clone 主仓库并搭建开发环境参考仓库根目录的 CONTRIBUTING.md 完成本地开发环境配置。注意集成开发是面向 ZenML 主代码库的贡献因此需要在 ZenML 源码而非你自己的独立仓库中进行。4.2 创建集成目录所有集成都位于src/zenml/integrations/下的独立子目录中。一个典型的集成目录结构如下src/zenml/integrations/ - ZenML 集成目录 example-integration - 集成根目录 | ├── artifact-stores - 按组件类型分目录存放 | ├── __init__.py | └── example-artifact-store - artifact store 的实现类 ├── flavors | ├── __init__.py | └── example-artifact-store-flavor - Config 类与 Flavor 类 | └── __init__.py - Integration 类以仓库中真实的 mlflow 集成目录 为参照可以看到它按experiment_trackers/、model_deployers/、model_registries/、flavors/、services/、steps/组织与上述规范完全一致。实际项目中还常出现materializers/自定义物化器与utils/工具函数等子目录。4.3 在 constants 中定义集成名称在 src/zenml/integrations/constants.py 中新增一行常量EXAMPLE_INTEGRATION name-of-integration该常量名即zenml integration install name-of-integration命令中的集成名。从现有文件可以看出仓库中每个集成都对应一个字符串常量例如MLFLOW mlflow、AWS aws、WANDB wandb等共约 80 个。命名遵循全大写 下划线的 Python 常量惯例值则使用小写连字符风格。4.4 创建 Integration 类init.py在src/zenml/integrations/YOUR_INTEGRATION/__init__.py中创建Integration的子类设置NAME与REQUIREMENTS属性并覆写flavors类方法from typing import List, Type from zenml.integrations.constants import EXAMPLE_INTEGRATION from zenml.integrations.integration import Integration from zenml.stack import Flavor # 该 Flavor 名称将用于注册栈组件 # zenml type-of-stack-component register ... -f example-orchestrator-flavor EXAMPLE_ORCHESTRATOR_FLAVOR example-orchestrator-flavor # 创建 Integration 类的子类 class ExampleIntegration(Integration): Definition of Example Integration for ZenML. NAME EXAMPLE_INTEGRATION REQUIREMENTS [INSERT PYTHON REQUIREMENTS HERE] classmethod def flavors(cls) - List[Type[Flavor]]: Declare the stack component flavors for the EXAMPLE integration. from zenml.integrations.example_flavor import ExampleFlavor return [ExampleFlavor] ExampleIntegration.check_installation() # 检查依赖是否已安装对照基类源码integration.pyIntegration还提供了以下可扩展点成员类型/默认值说明NAME类属性默认base_integration集成唯一名称必须与 constants 中的常量一致IntegrationMeta用它做注册键REQUIREMENTSList[str]默认[]集成的 Python 依赖列表PEP 508 格式由get_requirements()返回APT_PACKAGESList[str]默认[]需要以系统包形式安装的依赖如某些原生库REQUIREMENTS_IGNORED_ON_UNINSTALLList[str]默认[]卸载集成时不应移除的依赖前缀防止误删公共依赖参见 MLflow 集成中的用法check_installation()类方法逐个解析并校验依赖是否已安装含传递依赖供注册表与 CLI 使用get_requirements()类方法返回依赖列表可按目标 OS / Python 版本动态调整MLflow 集成即在此追加 numpy、pandas 依赖activate()类方法激活钩子用于注册 materializer、service connector 等运行时模块flavors()类方法默认返回[]声明本集成提供的全部 Flavor 类4.5 在正确的位置导入集成必须被导入到 src/zenml/integrations/init.py 中以保证IntegrationMeta的自动注册机制生效。实际上registry.py 会在首次访问时扫描zenml.integrations包下所有子目录并逐个importlib.import_module因此__init__.py中的显式导入与注册表的自动发现共同构成了完整的加载链路。五、源码级原理注册表、依赖校验与激活机制理解以下三个运行机制能帮你写出符合 ZenML 内部约定的集成。5.1 自动注册IntegrationMeta元类任何Integration子类类名非Integration本身在定义时都会被IntegrationMeta.__new__捕获并以cls.NAME为键注册进全局单例integration_registryintegration.py。注册表对外暴露list_integration_names、is_installed()、get_installed_integrations()、select_integration_requirements()等能力registry.py。5.2 依赖校验check_installation()check_installation()遍历get_requirements()返回的每个依赖用packaging.requirements.Requirement解析后调用requirement_installed()校验版本还会递归校验每个依赖自身的传递依赖integration.py。因此你的REQUIREMENTS中每个条目都应是合法的 PEP 508 规范字符串例如mlflow2.1.1,4见 MLflow 集成。5.3 激活钩子activate()activate_integrations()会对所有通过依赖校验的集成逐个调用activate()用于急切地注册 materializer、service connector 等运行时模块单个集成激活失败如第三方库导入错误不会阻断其他集成registry.py。MLflow 集成即在activate()中导入services模块来完成部署服务的注册。如果你的集成需要注册 materializer 或 service connector覆写此方法即可。六、实战参考解剖 MLflow 集成MLflow 集成是官方文档点名的范例也是仓库中最完整的实现之一src/zenml/integrations/mlflow/init.py。它的设计值得照抄多 Flavor 声明flavors()返回三个 Flavor——MLFlowModelDeployerFlavor、MLFlowExperimentTrackerFlavor、MLFlowModelRegistryFlavor分别对应三个组件类别Flavor 常量统一为mlflow。动态依赖get_requirements()在基础依赖之外追加 numpy、pandas 的依赖实现跨集成复用。卸载保护通过REQUIREMENTS_IGNORED_ON_UNINSTALL声明python-rapidjson、pydantic、numpy、pandas为卸载时忽略的公共依赖。激活钩子activate()导入services子模块完成部署服务注册。再看单个 Flavor 的构成以 mlflow_experiment_tracker_flavor.py 为例它清晰展示了 Flavor 类的三件套name属性返回 Flavor 名称mlflowconfig_class返回 Pydantic 配置类MLFlowExperimentTrackerConfig含tracking_uri、tracking_username/password、tracking_token、Databricks 相关字段等并使用SecretField标记敏感字段、用model_validator做凭据配对校验implementation_class返回真正实现组件逻辑的类MLFlowExperimentTracker。这与 Flavor 基类 定义的抽象接口name、type、implementation_class、config_class一一对应你的集成 Flavor 也应遵循同样的模式。七、Step 4提交 Pull Request 并庆祝完成以上所有步骤后即可向 ZenML 仓库发起 Pull Request等待核心维护者 review。提交前请自检集成的每个 Flavor 都已作为自定义 Flavor 验证可用目录结构符合src/zenml/integrations/name/规范并按组件类型分子目录constants 中已添加集成名常量Integration子类设置了NAME与REQUIREMENTSflavors()返回完整列表集成已在src/zenml/integrations/__init__.py中导入zenml integration install name与zenml integration list行为符合预期。完成这些你就把一个新的 MLOps 工具真正融入了 ZenML 的集成生态让所有 ZenML 用户都能通过一行zenml integration install使用它。附完整文件速查本文档 implement-a-custom-integration.md自定义栈组件指南custom-stack-component.md集成常量定义constants.pyIntegration 基类与元类integration.py集成注册表实现registry.pyMLflow 集成范例mlflow/init.pyFlavor 基类抽象flavor.pyflavor register/flavor listCLI 实现stack_components.py【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 为 ZenML 实现自定义集成（Custom Integration）完整指南：从自定义 Flavor 到核心代码库贡献
为 ZenML 实现自定义集成Custom Integration完整指南从自定义 Flavor 到核心代码库贡献【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenmlZenML 将不断膨胀的 MLOps 工具生态抽象为统一的栈Stack与组件Component体系而集成Integration机制则是这套体系对外开放的插槽它允许你把任意 MLOps 工具打包成一组可复用的栈组件 Flavor并随 ZenML 主仓库分发给所有人。本文以 implement-a-custom-integration.md 为骨架结合src/zenml/integrations/下的真实源码完整讲解从规划集成、注册自定义 Flavor到编写Integration子类、提交 Pull Request 的每一步读完后你将具备为 ZenML 贡献一个生产级工具集成的全部实战能力。一、前置知识理解 ZenML 的集成体系在动手之前先明确三个概念之间的关系这是本指南的前提Stack Component Type组件类型一个宽泛的功能类别如orchestrator、artifact_store、experiment_tracker。ZenML 的完整类别列表可在 component-guide 中查看包括 alerter、annotator、artifact store、container registry、data validator、deployer、experiment tracker、feature store、image builder、log store、model deployer、model registry、orchestrator、service connector、step operator 等。Flavor口味/实现变体某一组件类型下的具体实现例如artifact_store类型下有local、s3等 Flavor。Integration集成将一组相关 Flavor以及 materializer、service connector、steps 等配套模块打包的集合是 ZenML 主代码库中的一等公民。一个集成可以横跨多个组件类别。例如云厂商集成AWS/GCP/Azure同时包含 container registry、artifact store 等 Flavor再如仓库中的 MLflow 集成 一次声明了实验追踪器experiment tracker、模型部署器model deployer与模型注册表model registry三个类别的 Flavor。因此规划阶段的第一步就是先确定你的集成属于哪些类别。从源码层面看所有集成最终都汇聚在一个全局注册表中。IntegrationMeta元类在Integration子类创建时自动将其注册进integration_registry见 integration.py而注册表会遍历zenml.integrations包下所有含__init__.py的子目录并逐个导入见 registry.py。这意味着只要你的集成目录结构正确、类定义完整ZenML 就能在启动时自动发现它无需额外注册中心。二、Step 1规划你的集成这是成本最低、但最容易出错的步骤。请回答两个问题你的集成属于哪些类别回到上文提到的组件类别清单勾选与你的工具能力匹配的类别。例如要接入一个实验追踪工具就对应experiment_tracker要接入云端对象存储就对应artifact_store两者都要就同时规划两个类别。每个类别下要实现哪些 Flavor一个类别下通常只需一个 Flavor但也可以像 MLflow 那样为一个类别提供不同语义的多个 FlavorMLFlowModelDeployerFlavor、MLFlowExperimentTrackerFlavor、MLFlowModelRegistryFlavor。建议同时研读 如何编写自定义栈组件它会详细讲解StackComponent、StackComponentConfig、Flavor三个核心抽象——它们是后续所有实现的基础。三、Step 2先以自定义 Flavor形态开发并验证不要急着打包成集成。先用 ZenML 的自定义 Flavor 机制把每个组件开发、测试到可用状态再进入打包阶段可以大幅降低集成开发的调试成本。3.1 注册自定义 Flavor假设你正在开发一个自定义 orchestratorFlavor 类MyOrchestratorFlavor定义在flavors/my_flavor.py中注册命令为zenml orchestrator flavor register flavors.my_flavor.MyOrchestratorFlavor该命令的底层实现见 stack_components.py它通过client.create_flavor(sourcesource, component_typecomponent_type)解析点分路径并创建 Flavor 模型命令名由组件类型自动生成artifact_store→zenml artifact-store flavor register ...orchestrator →zenml orchestrator flavor register ...。注册成功后可用如下命令确认新 Flavor 已出现在列表中zenml orchestrator flavor listlist命令会调用client.get_flavors_by_type()拉取该类型下的全部 Flavor内置与自定义的都会列出。3.2 关于解析路径的重要警告⚠️ZenML 解析 Flavor 类的起点是zenml init初始化的仓库根目录而不是当前所在目录。因此务必遵循最佳实践在仓库根目录执行zenml init。如果 ZenML 在任何父目录中都找不到已初始化的仓库它会退而使用当前工作目录作为解析起点——这种机制可以工作但通常不应依赖它。这一点在 CLI 源码中有直接体现当client.root为空时命令会打印警告你的当前工作目录将被用作 source 参数的解析根目录请在你的源码根目录运行zenml init以消除此警告见 stack_components.py若加载失败错误信息也会明确提示请确保你已在仓库根目录运行过zenml init。四、Step 3将组件打包成 Integration当所有组件以自定义 Flavor 形态验证通过后就可以开始打包并最终并入 ZenML 主包。以下是完整的 checklist。4.1 Clone 主仓库并搭建开发环境参考仓库根目录的 CONTRIBUTING.md 完成本地开发环境配置。注意集成开发是面向 ZenML 主代码库的贡献因此需要在 ZenML 源码而非你自己的独立仓库中进行。4.2 创建集成目录所有集成都位于src/zenml/integrations/下的独立子目录中。一个典型的集成目录结构如下src/zenml/integrations/ - ZenML 集成目录 example-integration - 集成根目录 | ├── artifact-stores - 按组件类型分目录存放 | ├── __init__.py | └── example-artifact-store - artifact store 的实现类 ├── flavors | ├── __init__.py | └── example-artifact-store-flavor - Config 类与 Flavor 类 | └── __init__.py - Integration 类以仓库中真实的 mlflow 集成目录 为参照可以看到它按experiment_trackers/、model_deployers/、model_registries/、flavors/、services/、steps/组织与上述规范完全一致。实际项目中还常出现materializers/自定义物化器与utils/工具函数等子目录。4.3 在 constants 中定义集成名称在 src/zenml/integrations/constants.py 中新增一行常量EXAMPLE_INTEGRATION name-of-integration该常量名即zenml integration install name-of-integration命令中的集成名。从现有文件可以看出仓库中每个集成都对应一个字符串常量例如MLFLOW mlflow、AWS aws、WANDB wandb等共约 80 个。命名遵循全大写 下划线的 Python 常量惯例值则使用小写连字符风格。4.4 创建 Integration 类init.py在src/zenml/integrations/YOUR_INTEGRATION/__init__.py中创建Integration的子类设置NAME与REQUIREMENTS属性并覆写flavors类方法from typing import List, Type from zenml.integrations.constants import EXAMPLE_INTEGRATION from zenml.integrations.integration import Integration from zenml.stack import Flavor # 该 Flavor 名称将用于注册栈组件 # zenml type-of-stack-component register ... -f example-orchestrator-flavor EXAMPLE_ORCHESTRATOR_FLAVOR example-orchestrator-flavor # 创建 Integration 类的子类 class ExampleIntegration(Integration): Definition of Example Integration for ZenML. NAME EXAMPLE_INTEGRATION REQUIREMENTS [INSERT PYTHON REQUIREMENTS HERE] classmethod def flavors(cls) - List[Type[Flavor]]: Declare the stack component flavors for the EXAMPLE integration. from zenml.integrations.example_flavor import ExampleFlavor return [ExampleFlavor] ExampleIntegration.check_installation() # 检查依赖是否已安装对照基类源码integration.pyIntegration还提供了以下可扩展点成员类型/默认值说明NAME类属性默认base_integration集成唯一名称必须与 constants 中的常量一致IntegrationMeta用它做注册键REQUIREMENTSList[str]默认[]集成的 Python 依赖列表PEP 508 格式由get_requirements()返回APT_PACKAGESList[str]默认[]需要以系统包形式安装的依赖如某些原生库REQUIREMENTS_IGNORED_ON_UNINSTALLList[str]默认[]卸载集成时不应移除的依赖前缀防止误删公共依赖参见 MLflow 集成中的用法check_installation()类方法逐个解析并校验依赖是否已安装含传递依赖供注册表与 CLI 使用get_requirements()类方法返回依赖列表可按目标 OS / Python 版本动态调整MLflow 集成即在此追加 numpy、pandas 依赖activate()类方法激活钩子用于注册 materializer、service connector 等运行时模块flavors()类方法默认返回[]声明本集成提供的全部 Flavor 类4.5 在正确的位置导入集成必须被导入到 src/zenml/integrations/init.py 中以保证IntegrationMeta的自动注册机制生效。实际上registry.py 会在首次访问时扫描zenml.integrations包下所有子目录并逐个importlib.import_module因此__init__.py中的显式导入与注册表的自动发现共同构成了完整的加载链路。五、源码级原理注册表、依赖校验与激活机制理解以下三个运行机制能帮你写出符合 ZenML 内部约定的集成。5.1 自动注册IntegrationMeta元类任何Integration子类类名非Integration本身在定义时都会被IntegrationMeta.__new__捕获并以cls.NAME为键注册进全局单例integration_registryintegration.py。注册表对外暴露list_integration_names、is_installed()、get_installed_integrations()、select_integration_requirements()等能力registry.py。5.2 依赖校验check_installation()check_installation()遍历get_requirements()返回的每个依赖用packaging.requirements.Requirement解析后调用requirement_installed()校验版本还会递归校验每个依赖自身的传递依赖integration.py。因此你的REQUIREMENTS中每个条目都应是合法的 PEP 508 规范字符串例如mlflow2.1.1,4见 MLflow 集成。5.3 激活钩子activate()activate_integrations()会对所有通过依赖校验的集成逐个调用activate()用于急切地注册 materializer、service connector 等运行时模块单个集成激活失败如第三方库导入错误不会阻断其他集成registry.py。MLflow 集成即在activate()中导入services模块来完成部署服务的注册。如果你的集成需要注册 materializer 或 service connector覆写此方法即可。六、实战参考解剖 MLflow 集成MLflow 集成是官方文档点名的范例也是仓库中最完整的实现之一src/zenml/integrations/mlflow/init.py。它的设计值得照抄多 Flavor 声明flavors()返回三个 Flavor——MLFlowModelDeployerFlavor、MLFlowExperimentTrackerFlavor、MLFlowModelRegistryFlavor分别对应三个组件类别Flavor 常量统一为mlflow。动态依赖get_requirements()在基础依赖之外追加 numpy、pandas 的依赖实现跨集成复用。卸载保护通过REQUIREMENTS_IGNORED_ON_UNINSTALL声明python-rapidjson、pydantic、numpy、pandas为卸载时忽略的公共依赖。激活钩子activate()导入services子模块完成部署服务注册。再看单个 Flavor 的构成以 mlflow_experiment_tracker_flavor.py 为例它清晰展示了 Flavor 类的三件套name属性返回 Flavor 名称mlflowconfig_class返回 Pydantic 配置类MLFlowExperimentTrackerConfig含tracking_uri、tracking_username/password、tracking_token、Databricks 相关字段等并使用SecretField标记敏感字段、用model_validator做凭据配对校验implementation_class返回真正实现组件逻辑的类MLFlowExperimentTracker。这与 Flavor 基类 定义的抽象接口name、type、implementation_class、config_class一一对应你的集成 Flavor 也应遵循同样的模式。七、Step 4提交 Pull Request 并庆祝完成以上所有步骤后即可向 ZenML 仓库发起 Pull Request等待核心维护者 review。提交前请自检集成的每个 Flavor 都已作为自定义 Flavor 验证可用目录结构符合src/zenml/integrations/name/规范并按组件类型分子目录constants 中已添加集成名常量Integration子类设置了NAME与REQUIREMENTSflavors()返回完整列表集成已在src/zenml/integrations/__init__.py中导入zenml integration install name与zenml integration list行为符合预期。完成这些你就把一个新的 MLOps 工具真正融入了 ZenML 的集成生态让所有 ZenML 用户都能通过一行zenml integration install使用它。附完整文件速查本文档 implement-a-custom-integration.md自定义栈组件指南custom-stack-component.md集成常量定义constants.pyIntegration 基类与元类integration.py集成注册表实现registry.pyMLflow 集成范例mlflow/init.pyFlavor 基类抽象flavor.pyflavor register/flavor listCLI 实现stack_components.py【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考