ZenML 管道 YAML 配置完全指南用配置文件解耦代碼、參數(shù)與運行環(huán)境【免費下載鏈接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.項目地址: https://gitcode.com/GitHub_Trending/ze/zenmlZenML 允許通過 YAML 配置文件在不改動任何 Python 代碼的前提下覆蓋管道Pipeline與步驟Step的運行行為包括參數(shù)、緩存策略、Docker 鏡像、計算資源、調(diào)度計劃與模型關(guān)聯(lián)等。本文以官方文檔docs/book/how-to/steps-pipelines/yaml_configuration.md為核心骨架結(jié)合倉庫源碼如src/zenml/pipelines/pipeline_definition.py、src/zenml/config/下的配置模型深入講解配置解析層級、每個配置項的底層字段語義與真實命令行用法讀完后你可以直接為任意 ZenML 管道編寫可復(fù)用的 YAML 配置。為什么需要 YAML 配置ZenML 管道本身由 Python 代碼定義但“如何運行”往往與“運行什么”是兩回事。YAML 配置能力讓你可以配置與代碼分離換環(huán)境、換參數(shù)、換資源規(guī)格時只改 YAML不動代碼實驗不同參數(shù)組合同一管道搭配多份配置反復(fù)試跑保證可復(fù)現(xiàn)性將配置隨管道、步驟與運行記錄一并固化任何人可以用同一份 YAML 復(fù)現(xiàn)同樣的運行。在 ZenML 中一份 YAML 配置會被解析為PipelineRunConfiguration對象定義于 pipeline_run_configuration.py其中包含run_name、enable_cache、enable_artifact_metadata、enable_artifact_visualization、enable_step_logs、enable_pipeline_logs、schedule、build、steps、settings、environment、secrets、tags、model、parameters、retry等全部運行級配置字段。基本用法一行代碼掛載配置在運行管道時傳入config_path即可應(yīng)用配置文件my_pipeline.with_options(config_pathconfig.yaml)()在源碼層面with_options見 pipeline_definition.py會拷貝管道實例并應(yīng)用配置真正執(zhí)行時_compile方法pipeline_definition.py會調(diào)用_parse_config_file讀取 YAML 文件再將其與代碼中顯式傳入的選項合并。這意味著“改配置不改代碼”是字面意義上的同一管道對象可以掛不同的config_path跑出完全不同的運行。一份最小的示例配置# Enable/disable features enable_cache: False enable_step_logs: True # Pipeline parameters parameters: dataset_name: my_dataset learning_rate: 0.01 # Step-specific configuration steps: train_model: parameters: learning_rate: 0.001 # Override the pipeline parameter for this step enable_cache: True # Override the pipeline cache setting這份配置做了三件事全局關(guān)閉緩存、開啟步驟日志、給管道注入兩個參數(shù)同時單獨給train_model步驟覆蓋學(xué)習(xí)率并重新開啟緩存。配置解析層級優(yōu)先級ZenML 解析配置時遵循嚴(yán)格優(yōu)先級從高到低為運行時 Python 代碼——最高優(yōu)先級。即with_options(...)中以關(guān)鍵字參數(shù)顯式傳入的值如run_name、schedule、settings等。源碼中_compile會先解析配置文件再用代碼參數(shù)構(gòu)造的PipelineRunConfiguration通過pydantic_utils.update_model覆蓋前者注釋明確寫著“Update with the values in code so they take precedence”pipeline_definition.py步驟級 YAML 配置——覆蓋管道級設(shè)置steps: train_model: parameters: learning_rate: 0.001 # Overrides pipeline-level setting管道級 YAML 配置——作為各步驟的默認值parameters: learning_rate: 0.01 # Lower precedence than step-level代碼中的默認值——最低優(yōu)先級即定義管道/步驟函數(shù)時給出的默認參數(shù)。這一層級設(shè)計讓你可以在管道級定義“基準(zhǔn)配置”再針對個別步驟做細粒度覆蓋無需復(fù)制整段配置。管道與步驟參數(shù)parametersparameters與你在 Python 中傳給管道、步驟函數(shù)的參數(shù)一一對應(yīng)# Pipeline parameters parameters: dataset_name: my_dataset learning_rate: 0.01 batch_size: 32 epochs: 10 # Step parameters steps: preprocessing: parameters: normalize: True fill_missing: mean train_model: parameters: learning_rate: 0.001 # Override the pipeline parameter optimizer: adam從源碼看管道級parameters對應(yīng)PipelineRunConfiguration.parameters類型為Dict[str, Any]步驟級parameters對應(yīng)StepConfigurationUpdate.parameters見 step_configurations.py它們在編譯階段被注入到管道入口函數(shù)與步驟函數(shù)的實參中因此必須與函數(shù)簽名中定義的參數(shù)名、類型保持一致否則編譯會失敗。布爾開關(guān)Enable Flags這些布爾標(biāo)志控制管道執(zhí)行層面的若干行為對應(yīng)PipelineRunConfiguration與StepConfigurationUpdate中的同名可選布爾字段# Pipeline-level flags enable_artifact_metadata: True # Whether to collect and store metadata for artifacts enable_artifact_visualization: True # Whether to generate visualizations for artifacts enable_cache: True # Whether to use caching for steps enable_step_logs: True # Whether to capture and store step logs # Step-specific flags steps: preprocessing: enable_cache: False # Disable caching for this step only train_model: enable_artifact_visualization: False # Disable visualizations for this step各字段語義依據(jù)源碼字段注釋enable_cache是否啟用步驟緩存命中緩存時跳過步驟重算enable_artifact_metadata是否采集并存儲產(chǎn)出 Artifact 的元數(shù)據(jù)enable_artifact_visualization是否為產(chǎn)出 Artifact 生成可視化enable_step_logs是否捕獲并存儲步驟日志此外PipelineRunConfiguration還支持enable_pipeline_logs管道級日志與enable_heartbeat步驟心跳用于長時間運行任務(wù)?；畹茸侄尉砂葱鑼懭?YAML。設(shè)置運行名稱run_namerun_name為一次管道運行指定自定義名稱run_name: training_run_cifar10_resnet50_lr0.001重要限制管道運行名稱在同一個項目內(nèi)必須唯一重復(fù)名稱會直接報錯。三種避免沖突的做法使用動態(tài)占位符保證唯一性# Example 1: Use placeholders for date and time to ensure uniqueness run_name: training_run_{date}_{time} # Example 2: Combine placeholders with specific details for better context run_name: training_run_cifar10_resnet50_lr0.001_{date}_{time}刪除配置中的run_name讓 ZenML 自動生成唯一名稱每次重跑前更換run_name?？捎谜嘉环▄date}、{time}以及你在管道配置中定義的任意參數(shù)。在源碼層面PipelineConfigurationUpdate.finalize_substitutions見 pipeline_configurations.py會在運行時注入{date}格式%Y_%m_%d與{time}格式%H_%M_%S_%f精確到微秒因此只要包含{time}基本不可能重名。資源與組件配置Docker 設(shè)置settings.docker控制管道以容器方式執(zhí)行時的鏡像構(gòu)建行為對應(yīng)DockerSettings類docker_settings.pysettings: docker: # Packages to install via apt-get apt_packages: [curl, git, libgomp1] # Whether to copy files from current directory to the Docker image copy_files: True # Environment variables to set in the container environment: ZENML_LOGGING_VERBOSITY: DEBUG PYTHONUNBUFFERED: 1 # Parent image to use for building parent_image: zenml-io/zenml-cuda:latest # Additional Python packages to install requirements: [torch1.10.0, transformers4.0.0, pandas]結(jié)合源碼補充幾個關(guān)鍵字段的細節(jié)parent_image鏡像構(gòu)建的父鏡像默認使用與當(dāng)前 Python/ZenML 版本匹配的官方鏡像若自定義鏡像必須確保其中已安裝 ZenML若同時指定了dockerfileparent_image會被忽略requirements接受一個 pip 包列表或指向 requirements 文件的路徑構(gòu)建時通過 pip 安裝environment/runtime_environment前者在安裝依賴前注入環(huán)境變量后者在依賴安裝后注入copy_files是否把當(dāng)前目錄下的文件復(fù)制進鏡像更多可選字段還包括dockerfile、build_context_root、skip_build、prevent_build_reuse、replicate_local_python_environment、install_stack_requirements、required_integrations、target_repository等。依賴安裝遵循固定順序本機pip freeze導(dǎo)出的包 → 棧組件所需的包可用install_stack_requirements: False關(guān)閉→required_integrations的依賴 →pyproject_path指向的pyproject.toml依賴 →requirements字段。若以上均未指定ZenML 會自動探測源碼根目錄下的requirements.txt或pyproject.toml可用disable_automatic_requirements_detection: True關(guān)閉。資源設(shè)置settings.resources控制步驟或管道獲得的計算資源對應(yīng)ResourceSettings類resource_settings.py# Pipeline-level resource settings settings: resources: cpu_count: 2 gpu_count: 1 memory: 4Gb # Step-specific resource settings steps: train_model: settings: resources: cpu_count: 4 gpu_count: 2 memory: 16Gb字段說明cpu_count申請的 CPU 核數(shù)gpu_count申請的 GPU 數(shù)量memory內(nèi)存大小需匹配MEMORY_REGEX^[0-9](B|KB|MB|GB|TB|PB|...)等字節(jié)單位大小寫敏感如4Gb、16Gbpreemptible是否允許使用可搶占資源僅在使用 ZenML 資源池時生效面向部署場景還可配置min_replicas/max_replicas副本與彈性伸縮范圍、autoscaling_metriccpu、memory、concurrency、rps、autoscaling_target與max_concurrency等。棧組件設(shè)置可以為單個步驟指定使用哪個已注冊的棧組件并為其傳入組件專屬配置steps: train_model: # Use specific named components experiment_tracker: mlflow_tracker step_operator: vertex_gpu # Component-specific settings settings: # MLflow specific configuration experiment_tracker.mlflow: experiment_name: image_classification nested: Trueexperiment_tracker與step_operator對應(yīng)StepConfigurationUpdate中同名可選字段接受組件名稱字符串可把某一步的計算卸載到遠程 step operator如 Vertex AI、SageMaker或?qū)嶒炗涗泴懭胫付?trackersettings下按組件類型.組件flavor的鍵組織如experiment_tracker.mlflow這些鍵最終由settings字典Dict[str, SerializeAsAny[BaseSettings]]承載具體字段隨 flavor 而定。配置文件的工作流技巧自動生成配置模板ZenML 提供了生成模板配置文件的命令zenml pipeline build-configuration my_pipeline config.yaml該命令輸出包含管道參數(shù)、步驟參數(shù)及各項配置選項含默認值的完整 YAML可作為手寫配置的起點。此外當(dāng)前 CLI 的zenml pipeline run、zenml pipeline build、zenml pipeline deploy子命令均支持--config/-c參數(shù)直接掛載 YAML見 cli/pipeline.py例如zenml pipeline run my_module.my_pipeline --config configs/prod.yaml zenml pipeline build my_module.my_pipeline --config config.yaml -o build.yaml其中zenml pipeline run還支持--stack指定棧、--build復(fù)用既有構(gòu)建、--prevent-build-reuse禁止構(gòu)建復(fù)用zenml pipeline build支持--output將構(gòu)建信息寫為 YAML 文件。在配置中引用環(huán)境變量YAML 配置內(nèi)可直接引用宿主機環(huán)境變量settings: docker: environment: # References an environment variable from the host system API_KEY: ${MY_API_KEY} DATABASE_URL: ${DB_CONNECTION_STRING}源碼中_compile在合并完代碼覆蓋項后會對整個run_config調(diào)用substitute_env_variable_placeholders見 env_utils.py將所有${VAR}占位符替換為os.environ中的實際值。注意若引用的環(huán)境變量未設(shè)置默認會拋出KeyError而不是靜默替換為空這能避免把錯誤的空值帶入云端運行。用多份配置管理多環(huán)境常見做法是為每個環(huán)境維護一份配置├── configs/ │ ├── dev.yaml # Development configuration │ ├── staging.yaml # Staging configuration │ └── prod.yaml # Production configuration示例開發(fā)配置# dev.yaml enable_cache: False enable_step_logs: True parameters: dataset_size: small settings: docker: parent_image: zenml-io/zenml:latest示例生產(chǎn)配置# prod.yaml enable_cache: True enable_step_logs: False parameters: dataset_size: full settings: docker: parent_image: zenml-io/zenml-cuda:latest resources: cpu_count: 8 memory: 16Gb運行時按需選擇# For development my_pipeline.with_options(config_pathconfigs/dev.yaml)() # For production my_pipeline.with_options(config_pathconfigs/prod.yaml)()開發(fā)環(huán)境關(guān)閉緩存、使用輕量鏡像加快迭代生產(chǎn)環(huán)境開啟緩存、使用 CUDA 鏡像并申請大內(nèi)存參數(shù)dataset_size也隨環(huán)境切換。高級配置模型配置通過model將管道關(guān)聯(lián)到一個 ZenML Model用于統(tǒng)一管理模型工件、版本與元數(shù)據(jù)model: name: classification_model description: Image classifier trained on the CIFAR-10 dataset tags: [computer-vision, classification, pytorch] # Specific model version version: 1.2.3PipelineRunConfiguration.model對應(yīng)Model對象解析時經(jīng)Model.model_validate校驗見_parse_config_file支持name、description、tags、version等字段步驟級也可通過steps.name.model單獨關(guān)聯(lián)模型。調(diào)度設(shè)置當(dāng)編排器orchestrator支持調(diào)度時可通過schedule定時觸發(fā)管道schedule: # Whether to run the pipeline for past dates if schedule is missed catchup: false # Cron expression for scheduling (daily at midnight) cron_expression: 0 0 * * * # Time to start scheduling from start_time: 2023-06-01T00:00:00Zschedule由Schedule模型承載schedule.py可用字段還包括cron_expressioncron 表達式設(shè)置后優(yōu)先于“起始時間 間隔”方式start_time/end_time調(diào)度起止時間未帶時區(qū)的 datetime 會被視為本地時區(qū)源碼中_ensure_timezone校驗器會發(fā)出警告并按本地時區(qū)處理interval_second周期調(diào)度的間隔秒數(shù)catchup錯過調(diào)度時是否補跑若你的管道內(nèi)部自行處理回填建議設(shè)False避免重復(fù)回填run_once_start_time僅運行一次的時間點。從源碼看配置如何被編譯理解底層流程有助于排查配置不生效的問題。_compilepipeline_definition.py的完整鏈路為_parse_config_file(config_path, matcherlist(PipelineRunConfiguration.model_fields.keys()))用yaml.SafeLoader讀取 YAML并只保留PipelineRunConfiguration已聲明字段的鍵見 pipeline_definition.py用解析結(jié)果構(gòu)造PipelineRunConfiguration將代碼中傳入的run_configuration_argsrun_name、schedule、settings等構(gòu)造為另一個PipelineRunConfiguration通過update_model合并——代碼值覆蓋文件值對合并結(jié)果執(zhí)行${VAR}環(huán)境變量占位符替換交給Compiler().compile(...)生成管道快照隨后快照同樣執(zhí)行環(huán)境變量替換最終提交執(zhí)行。因此代碼 文件、步驟 管道、管道 默認值的優(yōu)先級順序是由“配置文件先解析、代碼后覆蓋”的合并邏輯在源碼層面保證的而配置文件中的鍵名必須與PipelineRunConfiguration/StepConfigurationUpdate字段名嚴(yán)格一致未知鍵會被直接過濾掉不報錯也不生效這也是值得注意的排查點。小結(jié)YAML 配置是 ZenML 中把“管道定義”與“運行方式”解耦的核心機制with_options(config_path...)一處掛載即可覆蓋參數(shù)、緩存與日志開關(guān)、運行名稱、Docker 鏡像、計算資源、棧組件選擇、模型關(guān)聯(lián)與調(diào)度計劃并通過“代碼 步驟 管道 默認值”的層級讓配置既可全局復(fù)用、又可局部覆蓋。配合zenml pipeline run/build/deploy --config命令與${VAR}環(huán)境變量替換你可以在不改動一行業(yè)務(wù)代碼的前提下讓同一套管道在開發(fā)、預(yù)發(fā)、生產(chǎn)環(huán)境之間無縫切換同時保證每次運行的可復(fù)現(xiàn)性。延伸閱讀Steps Pipelines - 管道與步驟核心概念A(yù)dvanced Features - 緩存、日志等高級管道特性【免費下載鏈接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.項目地址: https://gitcode.com/GitHub_Trending/ze/zenml創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考