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

ZenML 集成阿里云 OSS 实战:基于 S3 Artifact Store 的 Artifact 存储配置与使用指南 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 ServiceOSS对外提供了一套与 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同时你需要提前在阿里云控制台完成两件事创建 OSS bucket记录 bucket 名称注册时以s3://your-bucket-name形式作为根路径 URI。获取访问凭证在阿里云控制台创建 AccessKeyAccessKey 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: s3OSS 的 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_kwargsself.config.config_kwargs直接作为ZenMLS3Filesystem继承自s3fs.S3FileSystem的构造参数见 s3_artifact_store.py。因此任何 s3fs / botocore 支持的配置项都可以通过这个 JSON 注入。认证方式ZenML SecretOSS 不支持 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_typeAWSSecretSchema)读取凭据见 s3_artifact_store.py。而AWSSecretSchema为兼容 S3 生态做了别名设计既支持 AWS 前缀字段名也支持通用字段名见 aws_secret_schema.py字段别名AWS 风格字段别名通用风格OSS/MinIO 等适用含义aws_access_key_idaccess_key_id访问密钥 IDaws_secret_access_keysecret_access_key访问密钥 Secretaws_session_tokensession_token临时会话 Token可选正因如此官方文档中创建 Secret 时使用--access_key_id与--secret_access_key这两个通用别名即可正确匹配 schemazenml secret create alibaba_secret \ --access_key_idYOUR_ALIBABA_ACCESS_KEY_ID \ --secret_access_keyYOUR_ALIBABA_SECRET_ACCESS_KEY若你的凭证是临时凭证例如通过 STS 获取还可以补充--session_tokenYOUR_SESSION_TOKEN。注册 Artifact Store完整参数说明准备好 Secret 之后即可注册阿里云 OSS Artifact Store。官方推荐的完整命令如下zenml artifact-store register alibaba_store -f s3 \ --paths3://your-bucket-name \ --authentication_secretalibaba_secret \ --client_kwargs{endpoint_url: https://oss-region.aliyuncs.com} \ --config_kwargs{signature_version: s3, s3: {addressing_style: virtual}}各参数的作用与取值说明参数作用说明-f s3指定 flavor复用 S3 Artifact Store flavor--path根路径 URI必须是s3://协议指向 OSS bucket如s3://your-bucket-name--authentication_secret指定认证 Secret指向上一步创建的alibaba_secret--client_kwargsS3 客户端参数必须提供endpoint_url指向 OSS 的区域 endpoint如https://oss-cn-hangzhou.aliyuncs.com--config_kwargsbotocore 配置参数必须包含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 → 类型化 SecretAWSSecretSchema→ 配置中的明文key/secret/token属性返回(key, secret, token, region)四元组。请求参数透传_build_filesystem_kwargs将client_kwargs、config_kwargs、s3_additional_kwargs原样传给 s3fs——这正是前面两个 OSS 兼容参数能够生效的机制所在。除了 OSS 必需的client_kwargs与config_kwargsS3 Artifact Store 还支持第三类高级参数s3_additional_kwargs。三者分工如下完整定义见 S3ArtifactStoreConfig参数透传目标典型用途client_kwargsbotocore client配置endpoint_url、region_name等客户端级参数config_kwargsbotocoreclient.Config配置signature_version、addressing_style等连接配置s3_additional_kwargsS3 API 调用配置ServerSideEncryption服务端加密、ACL访问控制等单次请求参数例如若要为 OSS 产物启用服务端加密可在注册命令中追加zenml artifact-store register alibaba_store -f s3 \ --paths3://your-bucket-name \ --authentication_secretalibaba_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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考