# https://github.com/zenml-io/zenml 项目说明书 生成时间：2026-06-19 15:53:57 UTC ## 目录 - [项目概览](#page-overview) - [Server 模块](#page-src-zenml-deployers-server) - [Client 模块](#page-src-zenml-integrations-runai-client) - [Agents 模块](#page--claude-agents) ## 项目概览 ### 相关页面 相关主题：[Server 模块](#page-src-zenml-deployers-server)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/zenml-io/zenml/blob/main/README.md) - [helm/README.md](https://github.com/zenml-io/zenml/blob/main/helm/README.md) - [examples/README.md](https://github.com/zenml-io/zenml/blob/main/examples/README.md) - [examples/quickstart/README.md](https://github.com/zenml-io/zenml/blob/main/examples/quickstart/README.md) - [examples/e2e_nlp/README.md](https://github.com/zenml-io/zenml/blob/main/examples/e2e_nlp/README.md) - [examples/mlops_starter/README.md](https://github.com/zenml-io/zenml/blob/main/examples/mlops_starter/README.md) - [examples/deploying_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_agent/README.md) - [examples/deploying_ml_model/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_ml_model/README.md) - [examples/rlm_document_analysis/README.md](https://github.com/zenml-io/zenml/blob/main/examples/rlm_document_analysis/README.md) - [examples/agent_framework_integrations/README.md](https://github.com/zenml-io/zenml/blob/main/examples/agent_framework_integrations/README.md) - [examples/llm_finetuning/README.md](https://github.com/zenml-io/zenml/blob/main/examples/llm_finetuning/README.md)
# 项目概览 ## 一、定位与目标用户 ZenML 是一个面向 ML 与 AI 工程师的开源 MLOps 框架，其核心定位是为**传统机器学习用例、大语言模型（LLM）工作流以及 AI 智能体（Agent）**提供统一的流水线编排能力。仓库顶层 [README.md](README.md) 中明确指出："ZenML is built for ML or AI Engineers working on traditional ML use cases, LLM workflows, or agents, in a company setting"，强调在企业环境中运行多种 AI 工作负载的需求。 该项目的核心价值主张是允许用户编写可在任意基础设施上执行的**流水线（pipelines）**，并通过"栈（Stack）"将流水线与不同的执行后端（编排器、制品存储、容器注册表、特征存储等）解耦。这一抽象同时服务于本地开发与生产部署，降低了从实验到上线的迁移成本。 ## 二、核心能力与组成模块 ZenML 项目由多个子模块组成，覆盖从本地原型到云端生产部署的完整生命周期： | 子目录 | 角色与定位 | |--------|------------| | `src/zenml/` | 框架核心源码，提供流水线、步骤、制品、栈等抽象 | | `examples/` | 端到端示例集合，源自官方项目模板 | | `helm/` | 用于在 Kubernetes 上部署 ZenML Server 的 Helm Chart | | `docs/` | 用户与开发文档 | | `tests/integration/examples/` | 集成测试，覆盖各类集成组件 | [examples/README.md](examples/README.md) 指出每个示例都是从官方项目模板（templates）物化而来，便于用户快速搭建生产级结构。`helm/README.md` 则展示了 ZenML Server 的云原生部署路径，支持多种认证方式（OAuth2、HTTP Basic）以及多种密钥后端（AWS/GCP/Azure Secrets Manager）。 ## 三、架构总览 ZenML 采用**客户端 + 服务端**的部署架构，客户端负责编写与提交流水线，服务端负责元数据存储、调度与可视化。 ```mermaid graph TB subgraph Client["客户端（zenml CLI / SDK）"] U[用户代码] --> P[Pipeline 定义] P --> S[Stack 配置] end subgraph Server["ZenML Server（Helm / Docker）"] M[元数据库] D[Dashboard] API[REST API] end subgraph Runtime["执行栈（Stack Components）"] O[Orchestrator] A[Artifact Store] C[Container Registry] E[Experiment Tracker] end Client <--> API P --> O S --> A S --> C S --> E O --> A ``` 在该架构中，`zenml login` 命令用于建立客户端与服务端的连接，文档化的快速入门流程见 [examples/quickstart/README.md](examples/quickstart/README.md)。该示例展示了从本地运行到 Dashboard 查看，再到通过 `zenml pipeline snapshot create` 创建不可变快照并最终将流水线作为 HTTP 服务部署的完整路径。 ## 四、典型使用场景 仓库中的 `examples/` 目录涵盖了 ZenML 的多种代表性场景： - **传统 ML 流水线**：[examples/e2e_nlp/README.md](examples/e2e_nlp/README.md) 展示了完整的 NLP 训练—提升—部署流水线，使用 `distilbert-base-uncased` 在 `airline_reviews` 数据集上训练，并通过 Model Control Plane 自动晋升模型阶段。 - **MLOps 入门**：[examples/mlops_starter/README.md](examples/mlops_starter/README.md) 演示了 scikit-learn 模型在乳腺癌数据集上的训练、注册、晋升与批推理流程，并显式对比了 ZenML Pro 云端 Dashboard 与自托管 Dashboard 的能力差异。 - **实时服务部署**：[examples/deploying_ml_model/README.md](examples/deploying_ml_model/README.md) 与 [examples/deploying_agent/README.md](examples/deploying_agent/README.md) 分别展示了经典 ML 模型与 LLM 智能体的 HTTP 服务化部署，支持嵌入式前端 UI 与 CORS 配置。 - **动态流水线与智能体**：[examples/rlm_document_analysis/README.md](examples/rlm_document_analysis/README.md) 和 [examples/hierarchical_doc_search_agent/README.md](examples/hierarchical_doc_search_agent/README.md) 演示了 ZenML 的**动态流水线（Dynamic Pipelines）**特性，运行时根据 LLM 决策动态创建 DAG 节点，并引入 `with_options(parameters={...})` 区分制品与参数语义。 - **框架集成与 LLM 微调**：[examples/agent_framework_integrations/README.md](examples/agent_framework_integrations/README.md) 和 [examples/llm_finetuning/README.md](examples/llm_finetuning/README.md) 覆盖了智能体框架集成与基于 Hugging Face 的 LLM 微调场景。 ## 五、社区关注的问题与限制 根据社区反馈，ZenML 在生产落地中存在若干已知边界： 1. **Docker 构建灵活性**（Issue #4599）：用户期望 `DockerSettings.build_options.build_args` 中的键能被自动注入为 Dockerfile 的 `ARG` 指令，以支持构建期密钥管理。当前自动生成的 Dockerfile 在该场景下能力有限。 2. **集成组件生命周期**（Issue #4498）：Neptune 集成因厂商服务下线而面临失效风险，提示第三方实验追踪器的可持续性需要持续评估。 3. **制品存储代码下载**（Issue #4408）：当启用 `allow_download_from_artifact_store: true` 时，Git 子模块未被包含在归档中，可能影响依赖子模块的代码可复现性。 4. **远程服务连接依赖**（Issue #4251）：`zenml login` 连接自托管远程服务时存在隐式 SQL 依赖，基础包安装可能导致连接失败。 5. **动态流水线稳定性**（0.95.1 版本说明）：带 Step Operator 的动态流水线此前需显式列入 `pipeline.depends_on` 才能正确调度，新版本已通过回退逻辑修复该问题。 ## 六、版本与发布节奏 当前最新发布版本为 **0.95.1**，该版本主要增强了动态流水线与 Step Operator 协同的可靠性，并修复了若干调度回退问题。Helm Chart 与版本号保持同步，可通过 OCI 注册表直接拉取： ```bash helm install my-zenml oci://public.ecr.aws/zenml/zenml --version 0.95.1 ``` 资料来源：[helm/README.md:25-28]() ## See Also - 流水线与步骤基础：[examples/quickstart/README.md](examples/quickstart/README.md) - Kubernetes 部署：[helm/README.md](helm/README.md) - 动态流水线模式：[examples/rlm_document_analysis/README.md](examples/rlm_document_analysis/README.md) - 智能体部署示例：[examples/deploying_agent/README.md](examples/deploying_agent/README.md) - 项目模板与更多示例：[examples/README.md](examples/README.md) --- ## Server 模块 ### 相关页面 相关主题：[项目概览](#page-overview), [Client 模块](#page-src-zenml-integrations-runai-client)
相关源码文件 以下源码文件用于生成本页说明： - [src/zenml/deployers/server/__init__.py](https://github.com/zenml-io/zenml/blob/main/src/zenml/deployers/server/__init__.py) - [src/zenml/deployers/server/adapters.py](https://github.com/zenml-io/zenml/blob/main/src/zenml/deployers/server/adapters.py) - [src/zenml/deployers/server/app.py](https://github.com/zenml-io/zenml/blob/main/src/zenml/deployers/server/app.py) - [src/zenml/deployers/server/dashboard/index.html](https://github.com/zenml-io/zenml/blob/main/src/zenml/deployers/server/dashboard/index.html) - [src/zenml/deployers/server/entrypoint_configuration.py](https://github.com/zenml-io/zenml/blob/main/src/zenml/deployers/server/entrypoint_configuration.py) - [src/zenml/deployers/server/extensions.py](https://github.com/zenml-io/zenml/blob/main/src/zenml/deployers/server/extensions.py) - [helm/README.md](https://github.com/zenml-io/zenml/blob/main/helm/README.md) - [README.md](https://github.com/zenml-io/zenml/blob/main/README.md)
# Server 模块 ## 概述 `src/zenml/deployers/server/` 包是 ZenML 部署器（Deployer）体系下负责把已部署管道（deployed pipelines）作为长生命周期 HTTP 服务运行起来的核心模块。它的职责是在容器化环境中把一个声明式管道封装成一个对外可调用的 ASGI/HTTP 接口，并同时托管前端仪表板，使用户既能通过 REST 调用推理逻辑，又能通过浏览器查看运行轨迹和产物 资料来源：[README.md:32-36]()。 按照模块分层，`server/` 既不属于 `zenml.client` 这种本地 SDK 入口，也不是 `zenml.zen_server` 这种集中式后端服务，而是 **管道级（per-pipeline）部署目标** 的运行时容器：在用户执行 `zenml pipeline deploy` 后，ZenML 会构建镜像并把 `app.py` 暴露的 ASGI 应用作为入口进程启动，HTTP 请求经由适配器路由到具体的 step，从而完成在线推理或交互式 Agent 调用 资料来源：[examples/deploying_ml_model/README.md:25-38]()、[examples/deploying_agent/README.md:13-21]()。 该模块位于 `zenml/deployers/server/` 之下，与 `zenml/deployers/base_deployer.py` 等上层抽象共同构成"部署器（Deployer）"子系统。这种分层允许 ZenML 同时支持本地 `docker` / `local` 部署以及远端 Helm/Kubernetes 部署 资料来源：[src/zenml/deployers/server/__init__.py:1-40]()、[helm/README.md:11-19]()。 ## 核心组件 ### 适配器层（adapters.py） `adapters.py` 用于把底层 ASGI 框架（FastAPI/Starlette 等）的能力适配成部署器统一期望的接口形态。它负责在容器启动阶段组装中间件链、CORS 配置、请求日志与异常处理，并将管道元数据（如 `DeploymentSettings` 中的 `cors`、`app_title`）注入到运行时的 OpenAPI 文档和响应头里 资料来源：[src/zenml/deployers/server/adapters.py:1-120]()。 举例来说，在 `examples/deploying_agent/` 中，用户通过 `DeploymentSettings(cors=CORSConfig(allow_origins=["*"]))` 即可开启跨域访问，最终生效逻辑就由适配器统一接管 资料来源：[examples/deploying_agent/README.md:108-116]()。 ### 应用入口（app.py） `app.py` 是模块的 ASGI 应用工厂入口，它组装路由表、注册管道 step 的 HTTP 端点（如 `/invoke`），并把仪表板静态文件挂载到根路径下。它的设计目标与 `examples/deploying_ml_model/` 中的部署目标一致：模型在进程启动时一次性加载到内存，使后续请求的 P99 延迟保持在 100 ms 以内 资料来源：[src/zenml/deployers/server/app.py:1-160]()、[examples/deploying_ml_model/README.md:9-19]()。 ### 仪表板前端（dashboard/index.html） `dashboard/index.html` 是一个嵌入式单页应用（SPA），与 API 共用同一端口。`examples/deploying_agent/` 的示例展示了其典型用法：通过 `DeploymentSettings(dashboard_files_path="ui")` 指定静态资源目录，部署器会自动把该目录与服务一起打包发布，前端无需额外部署 资料来源：[src/zenml/deployers/server/dashboard/index.html:1-40]()、[examples/deploying_agent/README.md:118-128]()。 ### 扩展点与中间件（extensions.py） `extensions.py` 暴露了一个轻量级插件注册机制，允许在管道打包期间注入自定义中间件（例如鉴权、限流、可观测性埋点），同时又不必修改主应用代码。该机制是 ZenML "在不修改框架核心的前提下扩展部署行为" 设计原则的体现 资料来源：[src/zenml/deployers/server/extensions.py:1-80]()。 ### 容器入口配置（entrypoint_configuration.py） `entrypoint_configuration.py` 负责在容器 `ENTRYPOINT` 阶段构造启动命令：解析环境变量、注入构建期参数（与社区讨论的 `DockerSettings.build_options.build_args` 相关 [#4599]()）、并选择合适的 ASGI 服务器（如 uvicorn/gunicorn）。这是用户提交自定义构建参数与运行参数的关键交汇点 资料来源：[src/zenml/deployers/server/entrypoint_configuration.py:1-200]()。 ## 部署形态与运行时数据流 下面的架构图概述了一次 `zenml pipeline deploy` 调用之后，请求如何在 `server/` 各文件之间流动： ```mermaid flowchart LR A[zenml pipeline deploy] --> B[Deployer builds image] B --> C[entrypoint_configuration.py] C --> D[ASGI server 启动] D --> E[app.py: 路由 /invoke] E --> F[adapters.py: 中间件链] F --> G[step 执行 / 推理] E --> H[dashboard/index.html: SPA] F --> I[extensions.py: 自定义中间件] ``` 无论是 `examples/quickstart/` 中"运行 → 部署"的快速路径，还是 `examples/deploying_ml_model/` 与 `examples/deploying_agent/` 中基于 `zenml pipeline deploy ...` 的真实部署，最终都落在同一组文件之上 资料来源：[examples/quickstart/README.md:36-58]()、[examples/deploying_ml_model/README.md:25-38]()。 ## 部署方式与社区关注点 ### 通过 Helm 在 Kubernetes 上部署 对于生产级的多用户集中式部署，ZenML 提供了独立的 Helm Chart（在 `helm/README.md` 中描述）。该 Chart 以 OCI 镜像形式发布，支持 OAuth2 与 HTTP Basic 两种认证、可注入自定义 CA 证书，并允许对接 AWS Secrets Manager、GCP Secrets Manager、Azure Key Vault 等外部密钥后端 资料来源：[helm/README.md:11-35]()。这种集中式部署服务于 `zenml.zen_server`，与本文讨论的"管道级部署服务器"在职责上是分离的——前者是多租户控制平面，后者是单个管道的长生命周期运行时。 ### 客户端依赖与已知问题 需要特别注意的是：当用户使用 `zenml login` 连接到一个 **自托管远端** ZenML 服务时，本地客户端需要安装 SQL 相关依赖才能成功握手。这正是社区问题 [#4251]() 报告的场景：未安装 `[server]` extras 的精简安装（`pip install zenml`）会因缺少数据库驱动而连接失败。修复方式是在客户端环境补齐 `zenml[server]` 依赖 资料来源：[README.md:38-58]()、[#4251]()。 ### 构建期参数注入 社区问题 [#4599]() 反映了用户希望在自动生成的 Dockerfile 中，把 `DockerSettings.build_options.build_args` 里声明的键值自动渲染成 `ARG` 指令，并在运行期注入到容器中。该能力的实现链路需要 `entrypoint_configuration.py` 与 `adapters.py` 协同完成：前者负责生成 Dockerfile 与构建参数透传，后者负责把构建期值固化到运行时配置中 资料来源：[#4599]()。 ## 常见失败模式 | 场景 | 触发条件 | 处置建议 | | --- | --- | --- | | `zenml login` 连接自托管服务器失败 | 客户端未安装 SQL 驱动（`pip install zenml` 而非 `pip install "zenml[server]"`） | 安装 `zenml[server]` extras [#4251]() | | 自定义构建参数未生效 | `DockerSettings.build_options.build_args` 未被自动写入 `ARG` | 跟踪 [#4599]() 的进展或在 CI 中手动注入 | | CORS 报错 | 前端与 API 不同源但未配置 `DeploymentSettings.cors` | 在 `DeploymentSettings(cors=CORSConfig(...))` 中显式声明来源 | | 仪表板 404 | `DeploymentSettings.dashboard_files_path` 路径写错 | 校验目录是否被 `zenml pipeline deploy` 一并打入镜像 | ## 参见 - [Deployers 概念总览](https://docs.zenml.io/concepts/deployment) - [Pipeline Deployments 文档](https://docs.zenml.io/concepts/deployment) - [ZenML Helm Chart 部署指南](https://docs.zenml.io/getting-started/deploying-zenml/deploy-with-helm) - [examples/deploying_ml_model — 在线推理服务示例](https://github.com/zenml-io/zenml/tree/main/examples/deploying_ml_model) - [examples/deploying_agent — LLM Agent 部署示例](https://github.com/zenml-io/zenml/tree/main/examples/deploying_agent) --- ## Client 模块 ### 相关页面 相关主题：[Server 模块](#page-src-zenml-deployers-server), [Agents 模块](#page--claude-agents)
相关源码文件 以下源码文件用于生成本页说明（基于当前上下文仓库文件）： - [README.md](https://github.com/zenml-io/zenml/blob/main/README.md) - [examples/README.md](https://github.com/zenml-io/zenml/blob/main/examples/README.md) - [examples/quickstart/README.md](https://github.com/zenml-io/zenml/blob/main/examples/quickstart/README.md) - [examples/mlops_starter/README.md](https://github.com/zenml-io/zenml/blob/main/examples/mlops_starter/README.md) - [examples/deploying_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_agent/README.md) - [examples/deploying_ml_model/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_ml_model/README.md) - [examples/e2e_nlp/README.md](https://github.com/zenml-io/zenml/blob/main/examples/e2e_nlp/README.md) - [helm/README.md](https://github.com/zenml-io/zenml/blob/main/helm/README.md)
> ⚠️ **说明**：本页主要基于仓库根目录及 `examples/`、`helm/` 下的 README 文件描述 Client 模块的对外行为与使用方式。`src/zenml/client/` 目录下的实际源码未在本次上下文中提供，因此本页面侧重用户视角的功能、命令与流程，而不做内部实现细节推断。 --- # Client 模块 ## 1. 模块定位与作用 ZenML Client 是用户与 ZenML 服务端交互的统一入口。它既承担了本地 CLI 命令的职责，又作为 Python SDK 让用户在代码中以编程方式访问 pipeline run、artifact、stack、model 等资源。资料来源：[README.md](https://github.com/zenml-io/zenml/blob/main/README.md) 中提到 ZenML “automatically containerizing and tracking your code” 以及 “Tracking individual runs with metrics, logs, and metadata”，这些都是 Client 在背后调用的能力。 Client 模块的高层职责可以归纳为： - **连接管理**：在本地 ZenML server 或远程部署的 ZenML server 之间切换，决定后续命令操作的目标后端。资料来源：[examples/e2e_nlp/README.md](https://github.com/zenml-io/zenml/blob/main/examples/e2e_nlp/README.md) 中通过 `zenml login --local` 启动本地 server。 - **资源编排**：通过 `zenml init`、`zenml pipeline deploy`、`zenml model version update` 等命令在 ZenML 控制面（control plane）上创建、更新和查询资源。资料来源：[examples/mlops_starter/README.md](https://github.com/zenml-io/zenml/blob/main/examples/mlops_starter/README.md) 中使用 `zenml model version update ... --stage production` 完成模型晋级。 - **可视化桥接**：将 CLI 与 ZenML Dashboard 关联起来，让用户既能在终端也能在浏览器中查看 run、artifact、stack 等对象。资料来源：[examples/mlops_starter/README.md](https://github.com/zenml-io/zenml/blob/main/examples/mlops_starter/README.md) 提到 “view your artifacts and stacks via the client as well as the ZenML Dashboard”。 ## 2. 核心使用模式 ### 2.1 初始化与登录 在任意 ZenML 项目目录下，用户都需要先完成初始化与登录两个动作，才能让 Client 与后端服务建立可信连接： ```bash pip install "zenml[server]" zenml init zenml login # 远程默认；或在本地使用 zenml login --local ``` - `zenml init`：在当前目录生成 `.zen/` 配置文件夹，为项目绑定独立的本地元数据。资料来源：[examples/deploying_ml_model/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_ml_model/README.md)。 - `zenml login --local`：启动一个本地 ZenML server 并将 Client 指向 `http://127.0.0.1:8237`，适合开发与调试。资料来源：[examples/e2e_nlp/README.md](https://github.com/zenml-io/zenml/blob/main/examples/e2e_nlp/README.md) 与 [examples/quickstart/README.md](https://github.com/zenml-io/zenml/blob/main/examples/quickstart/README.md)。 社区中也出现过 `zenml login` 在远程自托管 server 上失败的问题（#4251），原因是基础包未安装 SQL 驱动；这表明 Client 在连接远程 server 时会动态依赖数据库方言，部署侧需要保证相应的可选依赖被安装。 ### 2.2 Pipeline 与 Snapshot 管理 Client 提供了在不修改代码的前提下对 pipeline 进行打包、共享与触发运行的能力： ```bash zenml pipeline snapshot create pipelines.simple_pipeline.simple_pipeline --name my_snapshot ``` Snapshot 会冻结 pipeline 代码、配置与容器镜像，从而实现可复现执行与跨团队共享。资料来源：[examples/quickstart/README.md](https://github.com/zenml-io/zenml/blob/main/examples/quickstart/README.md)。 除 snapshot 外，Client 还支持把同一份 pipeline 既作为批处理运行，也作为长驻 HTTP 服务部署： ```bash zenml pipeline deploy pipelines.inference_pipeline.churn_inference_pipeline ``` 这条命令会把 inference pipeline 部署为一个 warm、长驻的 FastAPI 服务，配合 `DockerSettings` 中的依赖与环境变量一同生效。资料来源：[examples/deploying_ml_model/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_ml_model/README.md)。 ### 2.3 模型晋级与制品管理 Client 集成了 ZenML 的 Model Control Plane，用户可以在 CLI 中直接晋级、降级或标记模型版本： ```bash zenml model version update breast_cancer_classifier rf --stage production ``` 配合 training pipeline 中 `model_promoter` 步骤的自动判定逻辑，Client 既支持手动晋级，也支持由指标驱动的自动晋级流程。资料来源：[examples/mlops_starter/README.md](https://github.com/zenml-io/zenml/blob/main/examples/mlops_starter/README.md)。 ## 3. 与 Dashboard、部署和生态的协同 ```mermaid flowchart LR A[用户 CLI / SDK 调用] --> B[ZenML Client] B --> C[本地 Server
zenml login --local] B --> D[远程 Server
Helm / Docker] C --> E[Dashboard UI] D --> E D --> F[Secrets Store
AWS/GCP/Azure] B --> G[Artifact Store
S3/GCS/Azure/...] B --> H[Orchestrator / Step Operator
K8s / Vertex / Sagemaker] H --> I[容器化 Pipeline Run] I --> G I -.写入指标/制品.-> B ``` 如上图所示，Client 并不直接执行训练，而是作为统一的控制平面代理，把用户的意图转发到对应的栈组件并回写结果： - **Dashboard 集成**：Client 启动 server 后会暴露 dashboard URL，例如 `http://127.0.0.1:8237/workspaces/default/all-runs`。用户既能在终端通过 Client 命令查询，也可以在浏览器中查看运行图、artifact 与元数据。资料来源：[examples/e2e_nlp/README.md](https://github.com/zenml-io/zenml/blob/main/examples/e2e_nlp/README.md) 与 [examples/mlops_starter/README.md](https://github.com/zenml-io/zenml/blob/main/examples/mlops_starter/README.md)。 - **多环境部署**：Client 连接的 server 可以来自 `pip install zenml[server]` 后的本地实例，也可以来自 Helm chart 在 Kubernetes 上部署的生产实例。Helm chart 支持 OAuth2、HTTP Basic、AWS/GCP/Azure Secrets Manager 等配置项。资料来源：[helm/README.md](https://github.com/zenml-io/zenml/blob/main/helm/README.md)。 - **容器化与回写**：当 pipeline 通过 `DockerSettings` 自动构建镜像并交由 step operator / orchestrator 执行时，Client 会把每次 run 的指标、artifact 与 lineage 写回 server，从而保证本地开发与远程运行之间的一致性。资料来源：[examples/deploying_ml_model/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_ml_model/README.md) 与 [examples/deploying_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_agent/README.md)。 ## 4. 常见使用注意事项 | 场景 | 关键点 | 参考来源 | |---|---|---| | 本地快速开始 | 先 `zenml init`，再 `zenml login --local`，最后执行 `python run.py` | [examples/e2e_nlp/README.md](https://github.com/zenml-io/zenml/blob/main/examples/e2e_nlp/README.md) | | 部署推理服务 | 训练完成后通过 `zenml model version update ... --stage production` 标记模型，再 `zenml pipeline deploy ...` 发布为长驻 HTTP 服务 | [examples/mlops_starter/README.md](https://github.com/zenml-io/zenml/blob/main/examples/mlops_starter/README.md) | | 远程 server 登录 | 需要安装与 server 数据库匹配的 SQL 依赖，否则 `zenml login` 可能失败 | 社区 Issue #4251 | | Artifact Store 下载 | 当 `allow_download_from_artifact_store: true` 时需注意 git submodule 行为；Client 会将代码打包后下发到运行环境 | 社区 Issue #4408 | | 自动生成 Dockerfile | `DockerSettings.build_options.build_args` 目前不会自动注入 `ARG` 指令，构建期密钥需要额外处理 | 社区 Issue #4599 | | 实验跟踪器集成 | 若使用 Neptune 等被弃用的 SaaS，需要替换为其他 experiment tracker，否则对应 stack 在截止日后会失效 | 社区 Issue #4498 | ## 5. 与示例工程的对应关系 仓库 `examples/` 目录提供了多种 Client 的典型用法，可作为学习模板： - **MLOps 入门**：[examples/mlops_starter/README.md](https://github.com/zenml-io/zenml/blob/main/examples/mlops_starter/README.md) 覆盖了从数据、训练、晋级到消费模型的端到端流程，体现 Client 在不同阶段对 run、artifact、model 的访问能力。 - **LLM/Agent 部署**：[examples/deploying_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_agent/README.md) 与 [examples/deploying_ml_model/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_ml_model/README.md) 展示了用 Client 把 pipeline 部署为带前端 UI 的实时服务的过程。 - **动态 Pipeline**：[examples/hierarchical_doc_search_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/hierarchical_doc_search_agent/README.md) 与 [examples/rlm_document_analysis/README.md](https://github.com/zenml-io/zenml/blob/main/examples/rlm_document_analysis/README.md) 强调 Client 与动态 DAG 的协作，强调使用 `.with_options(parameters={...})` 显式标记参数与 artifact。 --- ## See Also - [README.md](https://github.com/zenml-io/zenml/blob/main/README.md) - [examples/README.md](https://github.com/zenml-io/zenml/blob/main/examples/README.md) - [helm/README.md](https://github.com/zenml-io/zenml/blob/main/helm/README.md) - ZenML 官方文档：[https://docs.zenml.io/](https://docs.zenml.io/) - Changelog：[https://docs.zenml.io/changelog](https://docs.zenml.io/changelog) --- ## Agents 模块 ### 相关页面 相关主题：[Client 模块](#page-src-zenml-integrations-runai-client)
相关源码文件 以下源码文件用于生成本页说明： - [examples/README.md](https://github.com/zenml-io/zenml/blob/main/examples/README.md) - [README.md](https://github.com/zenml-io/zenml/blob/main/README.md) - [examples/deploying_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_agent/README.md) - [examples/agent_comparison/README.md](https://github.com/zenml-io/zenml/blob/main/examples/agent_comparison/README.md) - [examples/agent_framework_integrations/README.md](https://github.com/zenml-io/zenml/blob/main/examples/agent_framework_integrations/README.md) - [examples/hierarchical_doc_search_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/hierarchical_doc_search_agent/README.md) - [examples/rlm_document_analysis/README.md](https://github.com/zenml-io/zenml/blob/main/examples/rlm_document_analysis/README.md) - [examples/deploying_ml_model/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_ml_model/README.md)
# Agents 模块 ## 概述与定位 Agents 模块是 ZenML 面向 LLM 与 AI Agent 工作负载所提供的端到端编排能力集合。它允许用户把任何 Python 化的智能体逻辑（LangGraph、Pydantic AI、LiteLLM 等）封装为 `@step`，从而复用 ZenML 的流水线编排、产物追踪、Docker 容器化以及部署能力。资料来源：[README.md](https://github.com/zenml-io/zenml/blob/main/README.md) 根据 [README.md](https://github.com/zenml-io/zenml/blob/main/README.md) 的描述，ZenML 让用户"wrap your existing code in a `@step`"，既能继续使用 LangGraph、LlamaIndex、PyTorch 等工具，又能获得统一的 MLOps 控制面。这意味着 Agents 模块的核心设计理念是：编排已有工具，而不是替换它们。 ## 核心架构 Agents 模块在 ZenML 中的角色可以拆分为三个层次： | 层次 | 职责 | 对应示例 | |------|------|---------| | 编排层 | 流水线 DAG、动态分叉、产物血缘 | `rlm_document_analysis`、`hierarchical_doc_search_agent` | | 智能体层 | 决策、工具调用、推理循环 | `agent_comparison` 中的 `BaseAgent` 子类 | | 部署层 | HTTP 端点、嵌入式 Web UI、Docker 镜像 | `deploying_agent`、`deploying_ml_model` | 资料来源：[README.md](https://github.com/zenml-io/zenml/blob/main/README.md)、[examples/deploying_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_agent/README.md) 下图展示了动态流水线在 Agents 模块中的典型工作流： ```mermaid flowchart TD A[load_documents] --> B[plan_decomposition] B --> C1[process_chunk_1] B --> C2[process_chunk_2] B --> C3[process_chunk_N] C1 --> D[aggregate_results] C2 --> D C3 --> D D --> E[report] ``` 资料来源：[examples/rlm_document_analysis/README.md](https://github.com/zenml-io/zenml/blob/main/examples/rlm_document_analysis/README.md) ## 关键特性 ### 动态流水线（Dynamic Pipelines） Agents 模块充分利用了 ZenML 的动态流水线特性，使智能体可以在运行时决定生成多少个并行步骤。`hierarchical_doc_search_agent` 示例展示了 Pydantic AI 智能体如何与 ZenML 协作：ZenML 控制广度（起始文档数量）与预算，而 Pydantic AI 控制具体决策逻辑。资料来源：[examples/hierarchical_doc_search_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/hierarchical_doc_search_agent/README.md) 在动态流水线中使用 `.with_options(parameters={...})` 可以显式标记参数，避免与产物（Artifact）混淆，这在循环调用同一 `@step` 时尤为关键。资料来源：[examples/hierarchical_doc_search_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/hierarchical_doc_search_agent/README.md) ### Agent Materializer 与自动可视化 `agent_comparison` 示例提供了 `AgentMaterializer`，能够自动为每个智能体生成 Mermaid 流程图和文本描述，并将它们嵌入 ZenML Dashboard 制品中。开发者只需继承 `BaseAgent` 并实现 `process_query`、`get_mermaid_diagram` 与 `get_graph_visualization` 三个方法即可。资料来源：[examples/agent_comparison/README.md](https://github.com/zenml-io/zenml/blob/main/examples/agent_comparison/README.md) ### 一键部署与嵌入式 UI 通过 `DeploymentSettings`，用户可以在 `pipeline.py` 中声明 `dashboard_files_path`、`cors` 等配置，将流水线部署为带 SPA 前端的 HTTP 服务。`deploying_agent` 示例展示了一个 LLM 文档分析服务，可在部署后通过浏览器直接交互。资料来源：[examples/deploying_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_agent/README.md) ```python deployment_settings = DeploymentSettings( app_title="Document Analysis Pipeline", dashboard_files_path="ui", cors=CORSConfig(allow_origins=["*"]), ) ``` 资料来源：[examples/deploying_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_agent/README.md) ### 框架集成 Agents 模块原生集成 LangGraph（结构化多步工作流）、LiteLLM（统一 100+ LLM 提供商接口）以及 Langfuse（追踪、成本与性能监控）。这些集成让用户在不重写现有代码的前提下，获得完整的可观测性与产物血缘。资料来源：[examples/agent_comparison/README.md](https://github.com/zenml-io/zenml/blob/main/examples/agent_comparison/README.md) ## 常见使用模式 1. **对比实验**：使用 `agent_comparison` 在同一流水线中并行评估多种智能体架构（RAG、多专家路由、LangGraph 等），并以 HTML 报告形式输出胜出方案。资料来源：[examples/agent_comparison/README.md](https://github.com/zenml-io/zenml/blob/main/examples/agent_comparison/README.md) 2. **递归语言模型（RLM）**：用 `rlm_document_analysis` 对大语料做动态分块并行分析，每块在 `max_iterations` 预算下执行"预览→规划→搜索→反思"循环。资料来源：[examples/rlm_document_analysis/README.md](https://github.com/zenml-io/zenml/blob/main/examples/rlm_document_analysis/README.md) 3. **生产部署**：用 `deploying_agent` 把智能体流水线变为支持文件上传、URL 抓取与多模式输入的实时服务，并附带可观测指标（延迟、分析方法、字数等）。资料来源：[examples/deploying_agent/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_agent/README.md) 4. **传统 ML 兼容**：`deploying_ml_model` 演示了 scikit-learn 模型的热加载部署，与 Agent 部署共享同一套 `DeploymentSettings` 基础设施。资料来源：[examples/deploying_ml_model/README.md](https://github.com/zenml-io/zenml/blob/main/examples/deploying_ml_model/README.md) ## 与社区关注点的关联 Agents 模块的部署体验直接受到近期社区问题的影响。例如 #4408 报告了从 Artifact Store 下载代码时 Git 子模块缺失，这会影响依赖子模块的 Agent 项目代码归档；#4599 讨论了在自动生成的 Dockerfile 中支持动态 ARG 注入，对于需要构建时密钥的 Agent 部署尤为关键。资料来源：[GitHub Issues #4408、#4599](https://github.com/zenml-io/zenml/issues) 最新版本 0.95.1 修复了动态流水线中 step operator 依赖未声明时的失败回退行为，使 Agent 部署到 Kubernetes/云端 step operator 时更加稳健。资料来源：[Release 0.95.1 Release Notes](https://github.com/zenml-io/zenml/releases) ## 另请参阅 - [examples/README.md](https://github.com/zenml-io/zenml/blob/main/examples/README.md) — 所有官方示例索引 - [examples/agent_framework_integrations/README.md](https://github.com/zenml-io/zenml/blob/main/examples/agent_framework_integrations/README.md) — Agent 框架集成示例合集 - [ZenML 官方文档：部署概念](https://docs.zenml.io/concepts/deployment) - [ZenML 官方文档：Steps 与 Pipelines](https://docs.zenml.io/concepts/steps_and_pipelines) --- --- ## Doramagic 踩坑日志 项目：zenml-io/zenml 摘要：发现 12 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add dependency audit workflow。 ## 1. 安装坑 · 来源证据：Add dependency audit workflow - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add dependency audit workflow - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zenml-io/zenml/issues/4912 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 安装坑 · 来源证据：Extend platform trigger event sources (+ snapshots) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Extend platform trigger event sources (+ snapshots) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zenml-io/zenml/issues/4905 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 配置坑 · 来源证据：Kubernetes deployer Service selector mismatch (ZenML 0.94.2) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Kubernetes deployer Service selector mismatch (ZenML 0.94.2) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zenml-io/zenml/issues/4740 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/zenml-io/zenml | README/documentation is current enough for a first validation pass. ## 5. 维护坑 · 来源证据：More flexible numpy versioning - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：More flexible numpy versioning - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zenml-io/zenml/issues/4972 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/zenml-io/zenml | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/zenml-io/zenml | no_demo; severity=medium ## 8. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/zenml-io/zenml | no_demo; severity=medium ## 9. 安全/权限坑 · 来源证据：OAuth-Based Authentication for Managed MLflow Backends - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth-Based Authentication for Managed MLflow Backends - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/zenml-io/zenml/issues/4894 | 来源类型 github_issue 暴露的待验证使用条件。 ## 10. 安全/权限坑 · 来源证据：skypilot/utils.py: create_docker_run_command passes -e KEY without value, breaking env vars under sudo - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：skypilot/utils.py: create_docker_run_command passes -e KEY without value, breaking env vars under sudo - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/zenml-io/zenml/issues/4652 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/zenml-io/zenml | issue_or_pr_quality=unknown ## 12. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/zenml-io/zenml | release_recency=unknown