ZenML 环境变量完全指南：从日志控制到服务器可观测性的 18 个关键开关-平芜编程栈

ZenML 环境变量完全指南：从日志控制到服务器可观测性的 18 个关键开关

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

ZenML 提供了一组预定义的环境变量，用于在不修改代码的情况下精确控制其运行时行为——从日志级别、控制台输出格式、文件复制策略，到服务器 OpenTelemetry 可观测性导出、CI/CD 客户端连接方式等。本文以 ZenML 官方环境变量参考文档为主体，结合仓库源码（src/zenml/constants.py、src/zenml/logger.py、src/zenml/zen_server/otel.py）逐项讲解每个变量的默认值、可选项与底层实现原理，帮助你在本地开发、远程编排、CI/CD 与生产部署等场景下精准配置 ZenML。

日志行为控制

1. 日志详细程度：ZENML_LOGGING_VERBOSITY

ZenML 的日志输出级别通过ZENML_LOGGING_VERBOSITY控制，可选值为INFO、WARN、ERROR、CRITICAL、DEBUG：

export ZENML_LOGGING_VERBOSITY=INFO

从源码看，该变量的默认值为INFO，并且会在模块加载时被读取并统一转为大写，见 src/zenml/constants.py：

ZENML_LOGGING_VERBOSITY = os.getenv( ENV_ZENML_LOGGING_VERBOSITY, default="INFO" ).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)s`

export ZENML_CONSOLE_LOGGING_FORMAT=console export ZENML_CONSOLE_LOGGING_FORMAT=json 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, validate=True)校验是否为合法的 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_STORAGE=true

代价是 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设为false：

export ZENML_ENABLE_RICH_TRACEBACK=true # 默认值 export ZENML_ENABLE_RICH_TRACEBACK=false # 关闭 rich 回溯

源码 src/zenml/constants.py 中，ENABLE_RICH_TRACEBACK = handle_bool_env_var(ENV_ZENML_ENABLE_RICH_TRACEBACK, True)，即默认开启。

控制台日志默认使用彩色输出。若需禁用彩色日志（例如在无颜色的 CI 日志系统或终端记录器中），设置：

export ZENML_LOGGING_COLORS_DISABLED=true

src/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_SIZE=16777216 # 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, default=DEFAULT_FILEIO_COPY_CHUNK_SIZE )

实际复制实现在 src/zenml/io/fileio.py。在慢速网络或超大 artifact 场景下增大块大小可减少 IO 系统调用次数；而在内存受限的容器中应保持默认值或适当减小。

6. ZenML 仓库路径：ZENML_REPOSITORY_PATH

ZenML 默认会沿当前目录向上递归查找.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_PATH

ZenML 的全局配置（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_IN

ZenML 默认收集匿名的使用分析数据以改进产品。如需完全退出分析，设置：

export ZENML_ANALYTICS_OPT_IN=false

关于具体收集哪些数据以及更细粒度的退出方式，可参考全局设置文档。该变量在 src/zenml/constants.py 中定义，并在 src/zenml/zen_server/deploy/daemon/daemon_zen_server.py 等服务端部署路径中被读取。

9. 调试模式：ZENML_DEBUG

设为true会切换到开发者模式：所有 ZenML 分析事件被重定向到开发用的分析服务器，而非官方分析服务器。

export ZENML_DEBUG=true

该变量不应在生产环境使用。源码中 src/zenml/constants.py 以handle_bool_env_var(ENV_ZENML_DEBUG, default=False)解析为IS_DEBUG_ENV，随后在 src/zenml/analytics/client.py 等位置把"debug": IS_DEBUG_ENV附加到分析事件中。

Pipeline 与 Stack 控制

10. 指定激活 Stack：ZENML_ACTIVE_STACK_ID

将ZENML_ACTIVE_STACK_ID设为某个 stack 的 UUID，即可让该 stack 成为当前激活 stack：

export ZENML_ACTIVE_STACK_ID=<UUID-OF-YOUR-STACK>

src/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 实际执行（文档示例中的默认展示值为false）：

export ZENML_PREVENT_PIPELINE_EXECUTION=false

该开关适合在只希望注册/编译 pipeline、或做静态检查的 CI 场景中使用，避免误触发真实运行。

12. 跳过 Stack 验证：ZENML_SKIP_STACK_VALIDATION

ZenML 在运行 pipeline 前会验证当前 stack 的各组件配置是否完整、可用。若希望跳过该验证（例如在只做轻量测试或临时运行的环境中），设置：

ZENML_SKIP_STACK_VALIDATION=true

源码 src/zenml/stack/stack.py 在验证入口处以handle_bool_env_var(ENV_ZENML_SKIP_STACK_VALIDATION, default=False)判断是否直接跳过，默认False（即默认执行验证）。注意跳过验证后配置错误会在运行时才暴露，生产环境不建议开启。

13. 忽略未跟踪的代码仓库文件：ZENML_CODE_REPOSITORY_IGNORE_UNTRACKED_FILES

使用代码仓库（code repository）功能时，ZenML 默认要求本地 checkout 没有任何未提交（uncommitted）或未跟踪（untracked）文件，才能用该仓库追踪 commit 并下载对应文件。设置该变量为True可跳过这一限制：

export ZENML_CODE_REPOSITORY_IGNORE_UNTRACKED_FILES=True

开启后，你需要自行保证提交到仓库的文件包含运行 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_OUTPUT=json

可选值：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_WIDTH=120

在 CI/CD 环境或需要跨终端保持表格格式一致时非常有用。src/zenml/cli/utils.py 中的实现会先读取该变量，未设置时回退到shutil的终端宽度探测。

服务器可观测性：OpenTelemetry 导出

自托管 ZenML 服务器可通过 OpenTelemetry（OTLP/HTTP）导出 traces、metrics 与 logs 到兼容后端。整体开关为ZENML_SERVER_OTEL_EXPORTER_OTLP_ENDPOINT，标准变量OTEL_EXPORTER_OTLP_ENDPOINT作为回退同样受支持：

export ZENML_SERVER_OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 # OR # export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

该端点应是 OTLP/HTTP 的基础端点，ZenML 会自动为各信号追加/v1/traces、/v1/metrics、/v1/logs路径。标准的分信号端点变量优先级更高：

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://otel-collector:4318/v1/metrics export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://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_ENABLED=false export ZENML_SERVER_OTEL_METRICS_ENABLED=false export ZENML_SERVER_OTEL_LOGS_ENABLED=false

服务名（出现在 OpenTelemetry resource attributes 中）可通过ZENML_SERVER_OTEL_SERVICE_NAME自定义，标准OTEL_SERVICE_NAME作为回退；未设置时，自托管部署默认zenml-server（见 src/zenml/constants.py），云端部署则使用 ZenML Pro 工作空间名称：

export ZENML_SERVER_OTEL_SERVICE_NAME=zenml-server # OR # export OTEL_SERVICE_NAME=zenml-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 login：

export ZENML_STORE_URL=https://... export ZENML_STORE_API_KEY=<API_KEY> export ZENML_ACTIVE_PROJECT_ID=<PROJECT_ID>

ZENML_STORE_URL：ZenML 服务器地址；
ZENML_STORE_API_KEY：API Key（以ZENKEY_开头，见 src/zenml/constants.py）；
ZENML_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 与 Stack（ZENML_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）确认变量注入位置——尤其是客户端环境变量会向远程编排器传播这一行为，稍加利用即可实现"一处配置、处处生效"。