ZenML 环境变量完全指南从日志控制到服务器可观测性的 18 个关键开关【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenmlZenML 提供了一组预定义的环境变量用于在不修改代码的情况下精确控制其运行时行为——从日志级别、控制台输出格式、文件复制策略到服务器 OpenTelemetry 可观测性导出、CI/CD 客户端连接方式等。本文以 ZenML 官方环境变量参考文档为主体结合仓库源码src/zenml/constants.py、src/zenml/logger.py、src/zenml/zen_server/otel.py逐项讲解每个变量的默认值、可选项与底层实现原理帮助你在本地开发、远程编排、CI/CD 与生产部署等场景下精准配置 ZenML。日志行为控制1. 日志详细程度ZENML_LOGGING_VERBOSITYZenML 的日志输出级别通过ZENML_LOGGING_VERBOSITY控制可选值为INFO、WARN、ERROR、CRITICAL、DEBUGexport ZENML_LOGGING_VERBOSITYINFO从源码看该变量的默认值为INFO并且会在模块加载时被读取并统一转为大写见 src/zenml/constants.pyZENML_LOGGING_VERBOSITY os.getenv( ENV_ZENML_LOGGING_VERBOSITY, defaultINFO ).upper()在 src/zenml/logger.py 中日志系统据此设置客户端日志处理器级别。值得注意的是ZENML_LOGGING_VERBOSITY只影响终端输出与日志记录日志本身的存储行为由单独的开关控制见下文禁用 Step 日志存储。排查问题时设置为DEBUG可获得最详细的内部调用链信息而生产环境通常保持INFO或WARN以减少噪音。2. 控制台日志格式ZENML_CONSOLE_LOGGING_FORMAT控制台终端日志的输出格式由ZENML_CONSOLE_LOGGING_FORMAT控制默认值为console可选值如下取值行为console默认客户端INFO日志使用紧凑布局DEBUG日志与服务端日志使用完整结构化文本布局json以 JSON 格式输出控制台/stdout 日志任意合法的 Python%-style 日志格式字符串自定义输出如%(asctime)s - %(message)sexport ZENML_CONSOLE_LOGGING_FORMATconsole export ZENML_CONSOLE_LOGGING_FORMATjson export ZENML_CONSOLE_LOGGING_FORMAT%(asctime)s - %(message)s该变量仅控制终端日志的格式化存储到 artifact store 的日志仍保留原始消息与结构化元数据不受影响。旧变量ZENML_LOGGING_FORMAT仍作为已弃用的别名受支持。源码中src/zenml/logger.py 的_get_console_logging_format()体现了完整的取值解析逻辑ZENML_CONSOLE_LOGGING_FORMAT优先于旧的ZENML_LOGGING_FORMAT取值为json或console时直接使用其他字符串会尝试通过logging.Formatter(log_format, validateTrue)校验是否为合法的 Python%-style 格式串非法时回退到console格式化器并输出告警未设置任何变量时返回None客户端与服务端统一使用结构化布局。3. 禁用 Step 日志存储ZENML_DISABLE_STEP_LOGS_STORAGE默认情况下ZenML 会把 step 产生的日志写入 artifact store并在仪表盘dashboard上展示。但当代码中大量使用进度条等高频输出时日志写入可能成为性能瓶颈。此时可将ZENML_DISABLE_STEP_LOGS_STORAGE设为true关闭日志存储export ZENML_DISABLE_STEP_LOGS_STORAGEtrue代价是 step 日志不再落盘也就无法在仪表盘上查看。该开关在 src/zenml/utils/logging_utils.py 中通过handle_bool_env_var(ENV_ZENML_DISABLE_STEP_LOGS_STORAGE, False)读取默认False。从 src/zenml/constants.py 可以看出它与ZENML_DISABLE_PIPELINE_LOGS_STORAGE是相互独立的控制项可按需分别禁用 step 级或 pipeline 级的日志存储。4. Rich 回溯与彩色日志开关ZenML 默认启用基于rich库的异常回溯显示便于阅读的彩色堆栈。如需关闭将ZENML_ENABLE_RICH_TRACEBACK设为falseexport ZENML_ENABLE_RICH_TRACEBACKtrue # 默认值 export ZENML_ENABLE_RICH_TRACEBACKfalse # 关闭 rich 回溯源码 src/zenml/constants.py 中ENABLE_RICH_TRACEBACK handle_bool_env_var(ENV_ZENML_ENABLE_RICH_TRACEBACK, True)即默认开启。控制台日志默认使用彩色输出。若需禁用彩色日志例如在无颜色的 CI 日志系统或终端记录器中设置export ZENML_LOGGING_COLORS_DISABLEDtruesrc/zenml/logger.py 会读取该变量决定是否启用颜色。有一个实用的传播行为在客户端环境即运行 pipeline 的本地机器设置该变量会自动传递到远程编排器orchestrator的日志输出。如果你希望本地禁用颜色、远程保留颜色则不要在本地设置该变量而是通过容器设置把它注入编排器环境from zenml.config import DockerSettings docker_settings DockerSettings( environment{ZENML_LOGGING_COLORS_DISABLED: false} ) # 方式一写在 pipeline 装饰器上 pipeline(settings{docker: docker_settings}) def my_pipeline() - None: my_step() # 方式二通过 with_options 配置 my_pipeline my_pipeline.with_options(settings{docker: docker_settings})文件与存储行为5. 文件复制块大小ZENML_FILEIO_COPY_CHUNK_SIZE当 ZenML 在不同文件系统之间复制文件时例如向远端 artifact store 上传/下载 artifact、模型或代码归档采用分块流式传输以保证内存占用有界。默认块大小为8 MiB可通过该变量调整export ZENML_FILEIO_COPY_CHUNK_SIZE16777216 # 16 MiB非正数值会被忽略并回退到默认值。源码中src/zenml/constants.py 定义了默认值与读取逻辑DEFAULT_FILEIO_COPY_CHUNK_SIZE 8 * 1024 * 1024 # 8 MiB ZENML_FILEIO_COPY_CHUNK_SIZE handle_int_env_var( ENV_ZENML_FILEIO_COPY_CHUNK_SIZE, defaultDEFAULT_FILEIO_COPY_CHUNK_SIZE )实际复制实现在 src/zenml/io/fileio.py。在慢速网络或超大 artifact 场景下增大块大小可减少 IO 系统调用次数而在内存受限的容器中应保持默认值或适当减小。6. ZenML 仓库路径ZENML_REPOSITORY_PATHZenML 默认会沿当前目录向上递归查找.zen仓库目录目录名由ZENML_REPOSITORY_DIRECTORY_NAME控制默认.zen见 src/zenml/constants.py。如需把仓库固定安装/定位到指定位置设置export ZENML_REPOSITORY_PATH/path/to/somewhere在 src/zenml/client.py 中ZENML_REPOSITORY_PATH被用于在查找本地仓库时优先返回该路径若路径下不存在.zen目录则明确报错并提示初始化方式。该变量适合在脚本化环境或无法依赖工作目录约定的场景下强制指定仓库位置。7. 全局配置路径ZENML_CONFIG_PATHZenML 的全局配置global config文件用于管理并持久化一系列设置的状态其路径可通过ZENML_CONFIG_PATH指定export ZENML_CONFIG_PATH/path/to/somewhere从源码看src/zenml/utils/io_utils.py 读取该变量定位全局配置目录src/zenml/services/container/container_service.py 在启动容器服务时也会把该变量注入容器环境保证容器内外使用同一份全局配置。默认情况下配置存放在用户主目录下的 ZenML 专属目录中。分析与调试8. 使用分析开关ZENML_ANALYTICS_OPT_INZenML 默认收集匿名的使用分析数据以改进产品。如需完全退出分析设置export ZENML_ANALYTICS_OPT_INfalse关于具体收集哪些数据以及更细粒度的退出方式可参考 全局设置文档。该变量在 src/zenml/constants.py 中定义并在 src/zenml/zen_server/deploy/daemon/daemon_zen_server.py 等服务端部署路径中被读取。9. 调试模式ZENML_DEBUG设为true会切换到开发者模式所有 ZenML 分析事件被重定向到开发用的分析服务器而非官方分析服务器。export ZENML_DEBUGtrue该变量不应在生产环境使用。源码中 src/zenml/constants.py 以handle_bool_env_var(ENV_ZENML_DEBUG, defaultFalse)解析为IS_DEBUG_ENV随后在 src/zenml/analytics/client.py 等位置把debug: IS_DEBUG_ENV附加到分析事件中。Pipeline 与 Stack 控制10. 指定激活 StackZENML_ACTIVE_STACK_ID将ZENML_ACTIVE_STACK_ID设为某个 stack 的 UUID即可让该 stack 成为当前激活 stackexport ZENML_ACTIVE_STACK_IDUUID-OF-YOUR-STACKsrc/zenml/client.py 在客户端初始化时优先读取该变量覆盖本地激活状态。此外远程编排器或 step operator 执行环境也会被注入该变量确保远端执行与本地使用同一个 stack见 src/zenml/orchestrators/utils.py 与 src/zenml/zen_server/pipeline_execution/utils.py。11. 阻止 Pipeline 执行ZENML_PREVENT_PIPELINE_EXECUTION设为true时阻止 pipeline 实际执行文档示例中的默认展示值为falseexport ZENML_PREVENT_PIPELINE_EXECUTIONfalse该开关适合在只希望注册/编译 pipeline、或做静态检查的 CI 场景中使用避免误触发真实运行。12. 跳过 Stack 验证ZENML_SKIP_STACK_VALIDATIONZenML 在运行 pipeline 前会验证当前 stack 的各组件配置是否完整、可用。若希望跳过该验证例如在只做轻量测试或临时运行的环境中设置ZENML_SKIP_STACK_VALIDATIONtrue源码 src/zenml/stack/stack.py 在验证入口处以handle_bool_env_var(ENV_ZENML_SKIP_STACK_VALIDATION, defaultFalse)判断是否直接跳过默认False即默认执行验证。注意跳过验证后配置错误会在运行时才暴露生产环境不建议开启。13. 忽略未跟踪的代码仓库文件ZENML_CODE_REPOSITORY_IGNORE_UNTRACKED_FILES使用代码仓库code repository功能时ZenML 默认要求本地 checkout 没有任何未提交uncommitted或未跟踪untracked文件才能用该仓库追踪 commit 并下载对应文件。设置该变量为True可跳过这一限制export ZENML_CODE_REPOSITORY_IGNORE_UNTRACKED_FILESTrue开启后你需要自行保证提交到仓库的文件包含运行 pipeline 所需的全部内容。读取逻辑位于 src/zenml/code_repositories/git/local_git_repository_context.py默认False。CLI 输出格式化14. 默认输出格式ZENML_DEFAULT_OUTPUT设置所有 CLI 列表类命令如zenml stack list、zenml pipeline list的默认输出格式export ZENML_DEFAULT_OUTPUTjson可选值table默认、json、yaml、csv、tsv。src/zenml/cli/utils.py 中以os.environ.get(ENV_ZENML_DEFAULT_OUTPUT, table)读取同时zenml stack describe等描述类命令也支持该变量见 src/zenml/cli/stack.py。在自动化脚本中用json输出配合jq解析是集成 ZenML CLI 的推荐姿势。15. 终端宽度覆盖ZENML_CLI_COLUMN_WIDTH覆盖表格渲染时的自动终端宽度检测export ZENML_CLI_COLUMN_WIDTH120在 CI/CD 环境或需要跨终端保持表格格式一致时非常有用。src/zenml/cli/utils.py 中的实现会先读取该变量未设置时回退到shutil的终端宽度探测。服务器可观测性OpenTelemetry 导出自托管 ZenML 服务器可通过 OpenTelemetryOTLP/HTTP导出 traces、metrics 与 logs 到兼容后端。整体开关为ZENML_SERVER_OTEL_EXPORTER_OTLP_ENDPOINT标准变量OTEL_EXPORTER_OTLP_ENDPOINT作为回退同样受支持export ZENML_SERVER_OTEL_EXPORTER_OTLP_ENDPOINThttp://otel-collector:4318 # OR # export OTEL_EXPORTER_OTLP_ENDPOINThttp://otel-collector:4318该端点应是 OTLP/HTTP 的基础端点ZenML 会自动为各信号追加/v1/traces、/v1/metrics、/v1/logs路径。标准的分信号端点变量优先级更高export OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://otel-collector:4318/v1/traces export OTEL_EXPORTER_OTLP_METRICS_ENDPOINThttp://otel-collector:4318/v1/metrics export OTEL_EXPORTER_OTLP_LOGS_ENDPOINThttp://otel-collector:4318/v1/logs也可以使用对应的 ZenML 专属命名ZENML_SERVER_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT、ZENML_SERVER_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT、ZENML_SERVER_OTEL_EXPORTER_OTLP_LOGS_ENDPOINT。若未设置任何基础端点或分信号端点服务器的 OpenTelemetry 插桩将完全禁用——零 OTel 开销。每种信号在端点配置后默认启用可通过以下变量单独禁用export ZENML_SERVER_OTEL_TRACES_ENABLEDfalse export ZENML_SERVER_OTEL_METRICS_ENABLEDfalse export ZENML_SERVER_OTEL_LOGS_ENABLEDfalse服务名出现在 OpenTelemetry resource attributes 中可通过ZENML_SERVER_OTEL_SERVICE_NAME自定义标准OTEL_SERVICE_NAME作为回退未设置时自托管部署默认zenml-server见 src/zenml/constants.py云端部署则使用 ZenML Pro 工作空间名称export ZENML_SERVER_OTEL_SERVICE_NAMEzenml-server # OR # export OTEL_SERVICE_NAMEzenml-server实现层面src/zenml/zen_server/otel.py 的configure_otel()从ServerConfiguration它读取ZENML_SERVER_OTEL_*及兼容的标准 OTel 环境变量见 src/zenml/config/server_config.py读取配置若无任一信号的有效端点则立即返回。值得注意的实现细节ZenML 采用编程式插桩而非 OTel 自动插桩因为自动插桩与 uvicorn 的--reload模式及多 worker--workers N模式不兼容。OTLP 头、超时、压缩、trace sampler 与 resource attributes 等标准 OTel 环境变量由 OpenTelemetry Python SDK 与 OTLP/HTTP exporter 处理OTLP/gRPC 协议环境变量不受支持因为 ZenML 直接配置 OTLP/HTTP exporter。无头客户端配置面向 CI/CD 与容器在 CI/CD 工作负载如 GitHub Actions、GitLab CI或容器化环境Docker、Kubernetes中使用 ZenML 客户端时可通过以下三个环境变量自动连接指定服务器的指定项目替代交互式zenml loginexport ZENML_STORE_URLhttps://... export ZENML_STORE_API_KEYAPI_KEY export ZENML_ACTIVE_PROJECT_IDPROJECT_IDZENML_STORE_URLZenML 服务器地址ZENML_STORE_API_KEYAPI Key以ZENKEY_开头见 src/zenml/constants.pyZENML_ACTIVE_PROJECT_ID要激活的项目 UUID。src/zenml/client.py 会读取ZENML_ACTIVE_PROJECT_ID自动切换到对应项目服务端在执行 pipeline 时也会向运行环境注入ZENML_STORE_URL等变量见 src/zenml/zen_server/pipeline_execution/utils.py。这是把 ZenML 接入自动化流水线的标准方式能让每次 CI 运行都使用确定性的服务器、凭据与项目避免交互式登录带来的不确定性。服务器配置速查除本文列出的客户端与服务器可观测性变量外ZenML 服务器还有一整套以ZENML_SERVER_为前缀的配置项如ZENML_SERVER_DEPLOYMENT_TYPE、ZENML_SERVER_AUTH_SCHEME等定义于 src/zenml/constants.py。完整的服务端配置选项清单请参见 Docker 部署 ZenML 服务器文档 中 ZenML server configuration options 一节。小结ZenML 的环境变量体系可按使用场景划分为五类日志与输出ZENML_LOGGING_VERBOSITY、ZENML_CONSOLE_LOGGING_FORMAT、ZENML_DISABLE_STEP_LOGS_STORAGE、ZENML_ENABLE_RICH_TRACEBACK、ZENML_LOGGING_COLORS_DISABLED、路径与存储ZENML_REPOSITORY_PATH、ZENML_CONFIG_PATH、ZENML_FILEIO_COPY_CHUNK_SIZE、分析与调试ZENML_ANALYTICS_OPT_IN、ZENML_DEBUG、Pipeline 与 StackZENML_ACTIVE_STACK_ID、ZENML_PREVENT_PIPELINE_EXECUTION、ZENML_SKIP_STACK_VALIDATION、ZENML_CODE_REPOSITORY_IGNORE_UNTRACKED_FILES、服务器与客户端连接ZENML_SERVER_OTEL_*、ZENML_STORE_URL/ZENML_STORE_API_KEY/ZENML_ACTIVE_PROJECT_ID以及CLI 格式化ZENML_DEFAULT_OUTPUT、ZENML_CLI_COLUMN_WIDTH。所有变量均已在源码 src/zenml/constants.py 中集中定义多数布尔型开关通过handle_bool_env_var解析并带有明确的默认值。在配置前建议结合你的具体部署方式本地、Docker、Kubernetes 或 CI确认变量注入位置——尤其是客户端环境变量会向远程编排器传播这一行为稍加利用即可实现一处配置、处处生效。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZenML 环境变量完全指南：从日志控制到服务器可观测性的 18 个关键开关
ZenML 环境变量完全指南从日志控制到服务器可观测性的 18 个关键开关【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenmlZenML 提供了一组预定义的环境变量用于在不修改代码的情况下精确控制其运行时行为——从日志级别、控制台输出格式、文件复制策略到服务器 OpenTelemetry 可观测性导出、CI/CD 客户端连接方式等。本文以 ZenML 官方环境变量参考文档为主体结合仓库源码src/zenml/constants.py、src/zenml/logger.py、src/zenml/zen_server/otel.py逐项讲解每个变量的默认值、可选项与底层实现原理帮助你在本地开发、远程编排、CI/CD 与生产部署等场景下精准配置 ZenML。日志行为控制1. 日志详细程度ZENML_LOGGING_VERBOSITYZenML 的日志输出级别通过ZENML_LOGGING_VERBOSITY控制可选值为INFO、WARN、ERROR、CRITICAL、DEBUGexport ZENML_LOGGING_VERBOSITYINFO从源码看该变量的默认值为INFO并且会在模块加载时被读取并统一转为大写见 src/zenml/constants.pyZENML_LOGGING_VERBOSITY os.getenv( ENV_ZENML_LOGGING_VERBOSITY, defaultINFO ).upper()在 src/zenml/logger.py 中日志系统据此设置客户端日志处理器级别。值得注意的是ZENML_LOGGING_VERBOSITY只影响终端输出与日志记录日志本身的存储行为由单独的开关控制见下文禁用 Step 日志存储。排查问题时设置为DEBUG可获得最详细的内部调用链信息而生产环境通常保持INFO或WARN以减少噪音。2. 控制台日志格式ZENML_CONSOLE_LOGGING_FORMAT控制台终端日志的输出格式由ZENML_CONSOLE_LOGGING_FORMAT控制默认值为console可选值如下取值行为console默认客户端INFO日志使用紧凑布局DEBUG日志与服务端日志使用完整结构化文本布局json以 JSON 格式输出控制台/stdout 日志任意合法的 Python%-style 日志格式字符串自定义输出如%(asctime)s - %(message)sexport ZENML_CONSOLE_LOGGING_FORMATconsole export ZENML_CONSOLE_LOGGING_FORMATjson export ZENML_CONSOLE_LOGGING_FORMAT%(asctime)s - %(message)s该变量仅控制终端日志的格式化存储到 artifact store 的日志仍保留原始消息与结构化元数据不受影响。旧变量ZENML_LOGGING_FORMAT仍作为已弃用的别名受支持。源码中src/zenml/logger.py 的_get_console_logging_format()体现了完整的取值解析逻辑ZENML_CONSOLE_LOGGING_FORMAT优先于旧的ZENML_LOGGING_FORMAT取值为json或console时直接使用其他字符串会尝试通过logging.Formatter(log_format, validateTrue)校验是否为合法的 Python%-style 格式串非法时回退到console格式化器并输出告警未设置任何变量时返回None客户端与服务端统一使用结构化布局。3. 禁用 Step 日志存储ZENML_DISABLE_STEP_LOGS_STORAGE默认情况下ZenML 会把 step 产生的日志写入 artifact store并在仪表盘dashboard上展示。但当代码中大量使用进度条等高频输出时日志写入可能成为性能瓶颈。此时可将ZENML_DISABLE_STEP_LOGS_STORAGE设为true关闭日志存储export ZENML_DISABLE_STEP_LOGS_STORAGEtrue代价是 step 日志不再落盘也就无法在仪表盘上查看。该开关在 src/zenml/utils/logging_utils.py 中通过handle_bool_env_var(ENV_ZENML_DISABLE_STEP_LOGS_STORAGE, False)读取默认False。从 src/zenml/constants.py 可以看出它与ZENML_DISABLE_PIPELINE_LOGS_STORAGE是相互独立的控制项可按需分别禁用 step 级或 pipeline 级的日志存储。4. Rich 回溯与彩色日志开关ZenML 默认启用基于rich库的异常回溯显示便于阅读的彩色堆栈。如需关闭将ZENML_ENABLE_RICH_TRACEBACK设为falseexport ZENML_ENABLE_RICH_TRACEBACKtrue # 默认值 export ZENML_ENABLE_RICH_TRACEBACKfalse # 关闭 rich 回溯源码 src/zenml/constants.py 中ENABLE_RICH_TRACEBACK handle_bool_env_var(ENV_ZENML_ENABLE_RICH_TRACEBACK, True)即默认开启。控制台日志默认使用彩色输出。若需禁用彩色日志例如在无颜色的 CI 日志系统或终端记录器中设置export ZENML_LOGGING_COLORS_DISABLEDtruesrc/zenml/logger.py 会读取该变量决定是否启用颜色。有一个实用的传播行为在客户端环境即运行 pipeline 的本地机器设置该变量会自动传递到远程编排器orchestrator的日志输出。如果你希望本地禁用颜色、远程保留颜色则不要在本地设置该变量而是通过容器设置把它注入编排器环境from zenml.config import DockerSettings docker_settings DockerSettings( environment{ZENML_LOGGING_COLORS_DISABLED: false} ) # 方式一写在 pipeline 装饰器上 pipeline(settings{docker: docker_settings}) def my_pipeline() - None: my_step() # 方式二通过 with_options 配置 my_pipeline my_pipeline.with_options(settings{docker: docker_settings})文件与存储行为5. 文件复制块大小ZENML_FILEIO_COPY_CHUNK_SIZE当 ZenML 在不同文件系统之间复制文件时例如向远端 artifact store 上传/下载 artifact、模型或代码归档采用分块流式传输以保证内存占用有界。默认块大小为8 MiB可通过该变量调整export ZENML_FILEIO_COPY_CHUNK_SIZE16777216 # 16 MiB非正数值会被忽略并回退到默认值。源码中src/zenml/constants.py 定义了默认值与读取逻辑DEFAULT_FILEIO_COPY_CHUNK_SIZE 8 * 1024 * 1024 # 8 MiB ZENML_FILEIO_COPY_CHUNK_SIZE handle_int_env_var( ENV_ZENML_FILEIO_COPY_CHUNK_SIZE, defaultDEFAULT_FILEIO_COPY_CHUNK_SIZE )实际复制实现在 src/zenml/io/fileio.py。在慢速网络或超大 artifact 场景下增大块大小可减少 IO 系统调用次数而在内存受限的容器中应保持默认值或适当减小。6. ZenML 仓库路径ZENML_REPOSITORY_PATHZenML 默认会沿当前目录向上递归查找.zen仓库目录目录名由ZENML_REPOSITORY_DIRECTORY_NAME控制默认.zen见 src/zenml/constants.py。如需把仓库固定安装/定位到指定位置设置export ZENML_REPOSITORY_PATH/path/to/somewhere在 src/zenml/client.py 中ZENML_REPOSITORY_PATH被用于在查找本地仓库时优先返回该路径若路径下不存在.zen目录则明确报错并提示初始化方式。该变量适合在脚本化环境或无法依赖工作目录约定的场景下强制指定仓库位置。7. 全局配置路径ZENML_CONFIG_PATHZenML 的全局配置global config文件用于管理并持久化一系列设置的状态其路径可通过ZENML_CONFIG_PATH指定export ZENML_CONFIG_PATH/path/to/somewhere从源码看src/zenml/utils/io_utils.py 读取该变量定位全局配置目录src/zenml/services/container/container_service.py 在启动容器服务时也会把该变量注入容器环境保证容器内外使用同一份全局配置。默认情况下配置存放在用户主目录下的 ZenML 专属目录中。分析与调试8. 使用分析开关ZENML_ANALYTICS_OPT_INZenML 默认收集匿名的使用分析数据以改进产品。如需完全退出分析设置export ZENML_ANALYTICS_OPT_INfalse关于具体收集哪些数据以及更细粒度的退出方式可参考 全局设置文档。该变量在 src/zenml/constants.py 中定义并在 src/zenml/zen_server/deploy/daemon/daemon_zen_server.py 等服务端部署路径中被读取。9. 调试模式ZENML_DEBUG设为true会切换到开发者模式所有 ZenML 分析事件被重定向到开发用的分析服务器而非官方分析服务器。export ZENML_DEBUGtrue该变量不应在生产环境使用。源码中 src/zenml/constants.py 以handle_bool_env_var(ENV_ZENML_DEBUG, defaultFalse)解析为IS_DEBUG_ENV随后在 src/zenml/analytics/client.py 等位置把debug: IS_DEBUG_ENV附加到分析事件中。Pipeline 与 Stack 控制10. 指定激活 StackZENML_ACTIVE_STACK_ID将ZENML_ACTIVE_STACK_ID设为某个 stack 的 UUID即可让该 stack 成为当前激活 stackexport ZENML_ACTIVE_STACK_IDUUID-OF-YOUR-STACKsrc/zenml/client.py 在客户端初始化时优先读取该变量覆盖本地激活状态。此外远程编排器或 step operator 执行环境也会被注入该变量确保远端执行与本地使用同一个 stack见 src/zenml/orchestrators/utils.py 与 src/zenml/zen_server/pipeline_execution/utils.py。11. 阻止 Pipeline 执行ZENML_PREVENT_PIPELINE_EXECUTION设为true时阻止 pipeline 实际执行文档示例中的默认展示值为falseexport ZENML_PREVENT_PIPELINE_EXECUTIONfalse该开关适合在只希望注册/编译 pipeline、或做静态检查的 CI 场景中使用避免误触发真实运行。12. 跳过 Stack 验证ZENML_SKIP_STACK_VALIDATIONZenML 在运行 pipeline 前会验证当前 stack 的各组件配置是否完整、可用。若希望跳过该验证例如在只做轻量测试或临时运行的环境中设置ZENML_SKIP_STACK_VALIDATIONtrue源码 src/zenml/stack/stack.py 在验证入口处以handle_bool_env_var(ENV_ZENML_SKIP_STACK_VALIDATION, defaultFalse)判断是否直接跳过默认False即默认执行验证。注意跳过验证后配置错误会在运行时才暴露生产环境不建议开启。13. 忽略未跟踪的代码仓库文件ZENML_CODE_REPOSITORY_IGNORE_UNTRACKED_FILES使用代码仓库code repository功能时ZenML 默认要求本地 checkout 没有任何未提交uncommitted或未跟踪untracked文件才能用该仓库追踪 commit 并下载对应文件。设置该变量为True可跳过这一限制export ZENML_CODE_REPOSITORY_IGNORE_UNTRACKED_FILESTrue开启后你需要自行保证提交到仓库的文件包含运行 pipeline 所需的全部内容。读取逻辑位于 src/zenml/code_repositories/git/local_git_repository_context.py默认False。CLI 输出格式化14. 默认输出格式ZENML_DEFAULT_OUTPUT设置所有 CLI 列表类命令如zenml stack list、zenml pipeline list的默认输出格式export ZENML_DEFAULT_OUTPUTjson可选值table默认、json、yaml、csv、tsv。src/zenml/cli/utils.py 中以os.environ.get(ENV_ZENML_DEFAULT_OUTPUT, table)读取同时zenml stack describe等描述类命令也支持该变量见 src/zenml/cli/stack.py。在自动化脚本中用json输出配合jq解析是集成 ZenML CLI 的推荐姿势。15. 终端宽度覆盖ZENML_CLI_COLUMN_WIDTH覆盖表格渲染时的自动终端宽度检测export ZENML_CLI_COLUMN_WIDTH120在 CI/CD 环境或需要跨终端保持表格格式一致时非常有用。src/zenml/cli/utils.py 中的实现会先读取该变量未设置时回退到shutil的终端宽度探测。服务器可观测性OpenTelemetry 导出自托管 ZenML 服务器可通过 OpenTelemetryOTLP/HTTP导出 traces、metrics 与 logs 到兼容后端。整体开关为ZENML_SERVER_OTEL_EXPORTER_OTLP_ENDPOINT标准变量OTEL_EXPORTER_OTLP_ENDPOINT作为回退同样受支持export ZENML_SERVER_OTEL_EXPORTER_OTLP_ENDPOINThttp://otel-collector:4318 # OR # export OTEL_EXPORTER_OTLP_ENDPOINThttp://otel-collector:4318该端点应是 OTLP/HTTP 的基础端点ZenML 会自动为各信号追加/v1/traces、/v1/metrics、/v1/logs路径。标准的分信号端点变量优先级更高export OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://otel-collector:4318/v1/traces export OTEL_EXPORTER_OTLP_METRICS_ENDPOINThttp://otel-collector:4318/v1/metrics export OTEL_EXPORTER_OTLP_LOGS_ENDPOINThttp://otel-collector:4318/v1/logs也可以使用对应的 ZenML 专属命名ZENML_SERVER_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT、ZENML_SERVER_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT、ZENML_SERVER_OTEL_EXPORTER_OTLP_LOGS_ENDPOINT。若未设置任何基础端点或分信号端点服务器的 OpenTelemetry 插桩将完全禁用——零 OTel 开销。每种信号在端点配置后默认启用可通过以下变量单独禁用export ZENML_SERVER_OTEL_TRACES_ENABLEDfalse export ZENML_SERVER_OTEL_METRICS_ENABLEDfalse export ZENML_SERVER_OTEL_LOGS_ENABLEDfalse服务名出现在 OpenTelemetry resource attributes 中可通过ZENML_SERVER_OTEL_SERVICE_NAME自定义标准OTEL_SERVICE_NAME作为回退未设置时自托管部署默认zenml-server见 src/zenml/constants.py云端部署则使用 ZenML Pro 工作空间名称export ZENML_SERVER_OTEL_SERVICE_NAMEzenml-server # OR # export OTEL_SERVICE_NAMEzenml-server实现层面src/zenml/zen_server/otel.py 的configure_otel()从ServerConfiguration它读取ZENML_SERVER_OTEL_*及兼容的标准 OTel 环境变量见 src/zenml/config/server_config.py读取配置若无任一信号的有效端点则立即返回。值得注意的实现细节ZenML 采用编程式插桩而非 OTel 自动插桩因为自动插桩与 uvicorn 的--reload模式及多 worker--workers N模式不兼容。OTLP 头、超时、压缩、trace sampler 与 resource attributes 等标准 OTel 环境变量由 OpenTelemetry Python SDK 与 OTLP/HTTP exporter 处理OTLP/gRPC 协议环境变量不受支持因为 ZenML 直接配置 OTLP/HTTP exporter。无头客户端配置面向 CI/CD 与容器在 CI/CD 工作负载如 GitHub Actions、GitLab CI或容器化环境Docker、Kubernetes中使用 ZenML 客户端时可通过以下三个环境变量自动连接指定服务器的指定项目替代交互式zenml loginexport ZENML_STORE_URLhttps://... export ZENML_STORE_API_KEYAPI_KEY export ZENML_ACTIVE_PROJECT_IDPROJECT_IDZENML_STORE_URLZenML 服务器地址ZENML_STORE_API_KEYAPI Key以ZENKEY_开头见 src/zenml/constants.pyZENML_ACTIVE_PROJECT_ID要激活的项目 UUID。src/zenml/client.py 会读取ZENML_ACTIVE_PROJECT_ID自动切换到对应项目服务端在执行 pipeline 时也会向运行环境注入ZENML_STORE_URL等变量见 src/zenml/zen_server/pipeline_execution/utils.py。这是把 ZenML 接入自动化流水线的标准方式能让每次 CI 运行都使用确定性的服务器、凭据与项目避免交互式登录带来的不确定性。服务器配置速查除本文列出的客户端与服务器可观测性变量外ZenML 服务器还有一整套以ZENML_SERVER_为前缀的配置项如ZENML_SERVER_DEPLOYMENT_TYPE、ZENML_SERVER_AUTH_SCHEME等定义于 src/zenml/constants.py。完整的服务端配置选项清单请参见 Docker 部署 ZenML 服务器文档 中 ZenML server configuration options 一节。小结ZenML 的环境变量体系可按使用场景划分为五类日志与输出ZENML_LOGGING_VERBOSITY、ZENML_CONSOLE_LOGGING_FORMAT、ZENML_DISABLE_STEP_LOGS_STORAGE、ZENML_ENABLE_RICH_TRACEBACK、ZENML_LOGGING_COLORS_DISABLED、路径与存储ZENML_REPOSITORY_PATH、ZENML_CONFIG_PATH、ZENML_FILEIO_COPY_CHUNK_SIZE、分析与调试ZENML_ANALYTICS_OPT_IN、ZENML_DEBUG、Pipeline 与 StackZENML_ACTIVE_STACK_ID、ZENML_PREVENT_PIPELINE_EXECUTION、ZENML_SKIP_STACK_VALIDATION、ZENML_CODE_REPOSITORY_IGNORE_UNTRACKED_FILES、服务器与客户端连接ZENML_SERVER_OTEL_*、ZENML_STORE_URL/ZENML_STORE_API_KEY/ZENML_ACTIVE_PROJECT_ID以及CLI 格式化ZENML_DEFAULT_OUTPUT、ZENML_CLI_COLUMN_WIDTH。所有变量均已在源码 src/zenml/constants.py 中集中定义多数布尔型开关通过handle_bool_env_var解析并带有明确的默认值。在配置前建议结合你的具体部署方式本地、Docker、Kubernetes 或 CI确认变量注入位置——尤其是客户端环境变量会向远程编排器传播这一行为稍加利用即可实现一处配置、处处生效。【免费下载链接】zenmlZenML : One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考