企业官网建设流程全解析

ZenML 集成阿里云 OSS 实战：基于 S3 Artifact Store 的 Artifact 存储配置与使用指南

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

本文围绕 ZenML 官方文档 Alibaba Cloud OSS 指南 展开，讲解如何借助阿里云 OSS 与 S3 API 的兼容性，直接复用 ZenML 的s3Artifact Store flavor 将流水线产物持久化到阿里云对象存储。读完本文，你将掌握 OSS bucket 与访问凭证的准备、两个必备的config_kwargs兼容参数、ZenML Secret 认证方式、区域 endpoint 的选择，以及注册后如何在 Stack 与流水线中无感使用，并能从源码层面理解这些参数最终是如何被透传到 s3fs / botocore 的。

为什么可以用 ZenML 的 S3 集成连接阿里云 OSS

阿里云对象存储服务（Object Storage Service，OSS）对外提供了一套与 S3 兼容的 API。这意味着，凡是按 S3 协议编写的客户端代码与配置，都可以在不改动协议层的前提下直接对接 OSS。ZenML 的 S3 Artifact Store 正是基于 s3fs / boto3 实现的，因此 Alibaba Cloud OSS 并不需要单独的 integration 或独立的 flavor——直接使用s3flavor，并针对 OSS 的 S3 实现差异做少量参数调整即可。

这一点在 ZenML 的 Artifact Store 总览 中的 flavor 列表里也有明确体现：Alibaba Cloud OSS 一栏的 Flavor 是s3、Integration 是s3、URI 协议为s3://，与 AWS S3、Backblaze B2、MinIO 一样共享 S3 兼容协议族。

适用场景：什么时候应该选用 OSS Artifact Store

按照官方文档的说明，以下情况适合将阿里云 OSS 作为 ZenML 的 Artifact Store：

• 你的基础设施已经部署在阿里云上，希望让流水线产物与计算资源保持在同一网络区域，维持数据局部性（data locality），降低跨云访问的延迟与带宽成本；
• 你需要把产物存放在阿里云覆盖的特定地理区域（中国、亚太、欧洲、中东等）以满足就近访问需求；
• 你需要获得 S3 兼容的对象存储能力，同时希望沿用阿里云的计费模式与服务等级协议；
• 合规要求规定数据必须驻留在阿里云区域的存储中。

需要提醒的是，OSS Artifact Store 通常面向的是生产化、需要共享与远程访问的场景。如果只是本地快速评估 ZenML，默认的localArtifact Store 就已足够（详见 Local Artifact Store）。

部署准备：安装 S3 集成与准备 OSS 资源

由于阿里云 OSS 走的是 S3 兼容协议，第一步是安装 ZenML 的 S3 集成：

zenml integration install s3 -y

该集成会安装 s3fs、boto3 等底层依赖。安装完成后，在命令行查看可用的 Artifact Store flavor，确认s3已就绪：

zenml artifact-store flavor list

同时，你需要提前在阿里云控制台完成两件事：

1. 创建 OSS bucket：记录 bucket 名称，注册时以s3://your-bucket-name形式作为根路径 URI。
2. 获取访问凭证：在阿里云控制台创建 AccessKey（AccessKey ID 与 AccessKey Secret），供后续写入 ZenML Secret。

从源码看，S3 Artifact Store 对路径有硬性约束：S3ArtifactStoreConfig中定义了SUPPORTED_SCHEMES: ClassVar[Set[str]] = {"s3://"}（见 s3_artifact_store_flavor.py），并且split_s3_path工具函数要求 URI 必须以s3://开头，否则抛出ValueError（见 utils.py）。集成测试也验证了非s3://路径（如本地路径或gs://）会被拒绝（见 test_s3_artifact_store.py）。

关键前提：OSS 必须配置的两个兼容参数

这是接入阿里云 OSS 时最容易踩坑、也最核心的一步。官方文档明确要求，使用阿里云 OSS 时必须在config_kwargs中设置如下内容：

{"signature_version": "s3", "s3": {"addressing_style": "virtual"}}

这两个参数的背景如下：

• signature_version: "s3"：OSS 的 S3 兼容实现需要以 S3 协议（v2/v4 之外的兼容签名）进行请求签名，而不是 botocore 默认的 AWS SigV4。显式指定为s3才能保证请求签名与 OSS 服务端对齐。
• s3.addressing_style: "virtual"：要求使用虚拟主机风格（virtual-hosted style）的 bucket 寻址，即请求 URL 形如https://<bucket>.<endpoint>/<key>，这是 OSS 兼容接口所要求的寻址方式。

从源码实现看，config_kwargs会被原样透传到 s3fs，进而交给 botocore 的botocore.client.Config。在S3ArtifactStore._build_filesystem_kwargs中，config_kwargs=self.config.config_kwargs直接作为ZenMLS3Filesystem（继承自s3fs.S3FileSystem）的构造参数（见 s3_artifact_store.py）。因此，任何 s3fs / botocore 支持的配置项都可以通过这个 JSON 注入。

认证方式：ZenML Secret（OSS 不支持 Service Connector）

需要特别留意的一点是：阿里云 OSS 不支持 ZenML Service Connectors。这与 AWS S3 的推荐用法（通过 AWS Service Connector 自动配置与鉴权）不同，因此必须使用 ZenML Secrets 来安全地存储和引用阿里云凭证。这是 OSS 接入在认证环节与原生 AWS S3 的主要差异。

ZenML 的 Secret 存储采用 schema 化校验。S3 Artifact Store 在get_credentials中通过get_typed_authentication_secret(expected_schema_type=AWSSecretSchema)读取凭据（见 s3_artifact_store.py）。而AWSSecretSchema为兼容 S3 生态做了别名设计：既支持 AWS 前缀字段名，也支持通用字段名（见 aws_secret_schema.py）：

正因如此，官方文档中创建 Secret 时使用--access_key_id与--secret_access_key这两个通用别名即可正确匹配 schema：

zenml secret create alibaba_secret \ --access_key_id='<YOUR_ALIBABA_ACCESS_KEY_ID>' \ --secret_access_key='<YOUR_ALIBABA_SECRET_ACCESS_KEY>'

若你的凭证是临时凭证（例如通过 STS 获取），还可以补充--session_token='<YOUR_SESSION_TOKEN>'。

注册 Artifact Store：完整参数说明

准备好 Secret 之后，即可注册阿里云 OSS Artifact Store。官方推荐的完整命令如下：

zenml artifact-store register alibaba_store -f s3 \ --path='s3://your-bucket-name' \ --authentication_secret=alibaba_secret \ --client_kwargs='{"endpoint_url": "https://oss-<region>.aliyuncs.com"}' \ --config_kwargs='{"signature_version": "s3", "s3": {"addressing_style": "virtual"}}'

各参数的作用与取值说明：

关于client_kwargs.endpoint_url，源码中有专门的校验逻辑：_validate_client_kwargs要求其必须是以https://或http://开头的合法 URL，否则抛出ValueError；同时，当 ZenML 运行在容器内部时，若 endpoint 使用了localhost，会自动替换为 Docker 或 K3D 的内部主机名（见 s3_artifact_store_flavor.py）。集成测试也覆盖了endpoint_url与自定义参数会被完整透传给 boto3 的行为（见 test_s3_artifact_store.py）。

区域与 endpoint 的选择

把命令中的<region>替换为你实际创建 bucket 的 OSS 区域即可。官方文档给出的示例区域包括：

• eu-central-1（欧洲）
• cn-hangzhou（中国杭州）
• ap-southeast-1（亚太新加坡）

完整的区域与 endpoint 列表可在阿里云 OSS 控制台的“访问域名”或对应帮助文档中查询。endpoint 通常形如https://oss-<region>.aliyuncs.com，务必与你 bucket 所在区域一致，否则会出现 bucket 定位失败的问题。

将 Artifact Store 加入 Stack

注册完成后，将 Artifact Store 加入你的 ZenML Stack 并设为激活栈：

zenml stack register custom_stack -a alibaba_store ... --set

其中...表示同一 Stack 中其余组件（如 Orchestrator、Container Registry 等），-a指定 Artifact Store，--set将该栈设为当前激活栈。之后你运行的所有流水线产物都会自动持久化到阿里云 OSS bucket 中。

使用方式：与其它 Artifact Store 完全一致

阿里云 OSS Artifact Store 的使用体验与其它任何 flavor 的 Artifact Store 没有差别——S3 兼容 API 的转换由 ZenML 在底层自动完成。具体到日常开发：

• 流水线 step 返回的对象会被自动序列化并写入当前激活栈的 Artifact Store（序列化逻辑由对应类型的 Materializer 决定）；
• 你可以通过zenml.client.Client与zenml.io.fileio提供的统一文件系统风格 API 直接读写 OSS 中的对象，例如：

import os from zenml.client import Client from zenml.io import fileio root_path = Client().active_stack.artifact_store.path artifact_contents = "example artifact" artifact_path = os.path.join(root_path, "artifacts", "examples") artifact_uri = os.path.join(artifact_path, "test.txt") fileio.makedirs(artifact_path) with fileio.open(artifact_uri, "w") as f: f.write(artifact_contents)

关于 Artifact Store 更完整的使用方式（包括自定义 Materializer 时如何调用底层 IO API），可参考 Artifact Store 总览文档 的 “How to use it” 一节，以及 S3 Artifact Store 详细文档。

源码层面：OSS 请求链路与高级配置选项

理解底层实现有助于排查问题。S3 Artifact Store 的核心实现位于 s3_artifact_store.py，关键机制如下：

• 文件系统层：ZenMLS3Filesystem继承自s3fs.S3FileSystem，但将cachable置为False，禁用 s3fs 基于构造参数的实例缓存，避免 ZenML Server 这类长驻进程因缓存不释放而内存持续增长；同时重写了close_session以复用现有事件循环，修复 s3fs 原实现的内存泄漏问题。
• 凭证解析顺序：get_credentials依次尝试 Service Connector → 类型化 Secret（AWSSecretSchema）→ 配置中的明文key/secret/token属性，返回(key, secret, token, region)四元组。
• 请求参数透传：_build_filesystem_kwargs将client_kwargs、config_kwargs、s3_additional_kwargs原样传给 s3fs——这正是前面两个 OSS 兼容参数能够生效的机制所在。

除了 OSS 必需的client_kwargs与config_kwargs，S3 Artifact Store 还支持第三类高级参数s3_additional_kwargs。三者分工如下（完整定义见 S3ArtifactStoreConfig）：

例如，若要为 OSS 产物启用服务端加密，可在注册命令中追加：

zenml artifact-store register alibaba_store -f s3 \ --path='s3://your-bucket-name' \ --authentication_secret=alibaba_secret \ --client_kwargs='{"endpoint_url": "https://oss-cn-hangzhou.aliyuncs.com"}' \ --config_kwargs='{"signature_version": "s3", "s3": {"addressing_style": "virtual"}}' \ --s3_additional_kwargs='{"ServerSideEncryption": "AES256"}'

另外值得一提的是 bucket 版本化：S3ArtifactStore会惰性检测 bucket 是否开启版本控制（is_versioned属性），并在日志写入路径上清理旧版本文件。若 bucket 开启了版本控制但缺少s3:GetBucketVersioning/s3:ListBucketVersions/s3:DeleteObjectVersion权限，ZenML 会给出警告并自动降级处理，不会让流水线失败（见 s3_artifact_store.py 与 L542-L565）。

小结与排错提示

接入阿里云 OSS 的完整流程可归纳为四步：安装s3集成 → 创建 OSS bucket 与 AccessKey → 用 ZenML Secret 保存凭证 → 按本文参数注册s3flavor 的 Artifact Store 并加入 Stack。遇到问题时可按下述清单自查：

• 注册时报 “Invalid S3 URI”：确认--path以s3://开头；
• 鉴权失败（403 / SignatureDoesNotMatch）：确认config_kwargs中已设置{"signature_version": "s3", "s3": {"addressing_style": "virtual"}}，并确认 Secret 使用了access_key_id/secret_access_key别名；
• bucket 定位失败（404 / NoSuchBucket）：确认client_kwargs.endpoint_url中的区域与 bucket 所在区域一致；
• endpoint_url校验报错：确认其以https://或http://开头。

更完整的 S3 Artifact Store 配置选项与认证方法，可继续阅读 S3 Artifact Store 文档；Artifact Store 的整体概念与自定义实现方式，见 Artifact Store 总览 与 自定义 Artifact Store。

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