状态（Status）： Draft
作者（Authors）： @guowenna1
创建日期（Created）： YYYY-MM-DD
更新日期（Updated）： YYYY-MM-DD
**相关 Issue/PR：https://gitcode.com/Ascend/MindIE-SD/pull/308

1. 概述

本 RFC 设计 MindIE-SD Python wheel 包发布到 PyPI 的版本命名、平台标记、运行依赖约束和构建发布流程。目标是使 mindiesd wheel 在 PyPI 上能够明确表达其适配的 Python、平台、PyTorch 和 torch-npu 版本，降低用户安装错误版本后出现 ABI 不兼容或运行时失败的风险。

本方案采用与 torch-npu 类似的版本命名风格：mindiesd 的发行版本号默认与当前构建环境中的 torch 版本保持一致。例如在 torch 2.9.0 环境中构建时，生成 mindiesd-2.9.0-cp311-cp311-manylinux_2_38_aarch64.whl；未来在 torch 2.10.0 环境中构建时，生成 mindiesd-2.10.0-...whl。

1.2 动机

MindIE-SD wheel 包包含 CANN 自定义算子、PyTorch plugin 动态库以及 Python 包代码，属于和 Python ABI、操作系统平台、torch/torch-npu 运行时强相关的二进制分发包。此前构建出的 wheel 文件名为 mindiesd-3.0.0-cp311-cp311-linux_aarch64.whl，存在以下问题：

• linux_aarch64 不是 PyPI 可接受的 manylinux 平台 tag，上传 PyPI 时会返回 400 Bad Request。
• wheel 文件名只能体现 Python ABI 和平台，不能直观看出适配的 torch 版本。
• install_requires 中未精确约束 torch 和 torch-npu，用户可能在不兼容的 torch 环境中安装并运行。
• PyPI 上同一项目名下可能同时发布多条 torch 适配线，需要明确版本策略避免用户误装。

参考 torch-npu 的发布方式，torch_npu-2.10.0-cp313-cp313-manylinux_2_28_x86_64.whl 通过发行版本号 2.10.0 表达其对应的 PyTorch 版本线。MindIE-SD 也采用该风格，可以让用户在文件名中直接识别 torch 适配线。

1.3 目标

本 RFC 的目标如下：

• wheel 文件名符合 PyPI 规范，可以上传到 PyPI。
• wheel 文件名中的发行版本号直接体现 torch 适配版本，例如 mindiesd-2.9.0-...whl。
• wheel metadata 精确约束 torch、torch-npu 和 Python minor 版本。
• 保留环境变量覆盖能力，便于 CI 或特殊构建场景显式指定版本和平台 tag。
• 当前优先发布 torch 2.9 + Python 3.11 + Linux aarch64 的 wheel。
• 后续可扩展到 torch 2.10、其他 Python 版本或其他架构。

非目标如下：

• 本 RFC 不设计源码包 sdist 的发布策略。
• 本 RFC 不承诺一个 wheel 兼容多个 torch 主次版本。
• 本 RFC 不处理 CANN/驱动/固件版本的自动安装。
• 本 RFC 不改变 MindIE-SD Python API 或算子功能行为。

2. 用例分析

主要使用场景包括：

• 用户在 Python 3.11、Linux aarch64、torch 2.9.0、torch-npu 2.9.0.post1 环境中，通过 pip install mindiesd==2.9.0 安装 MindIE-SD。
• 维护者在指定 Docker 容器中执行 python3 setup.py bdist_wheel，生成可上传 PyPI 的 manylinux wheel。
• 维护者未来在 torch 2.10 环境中构建同名项目 mindiesd 的新版本 wheel，版本号自动变为 2.10.0。
• 用户或维护者通过 wheel 文件名和 metadata 判断该包是否匹配当前 Python、平台和 torch/torch-npu 环境。

关键约束如下：

• 当前 wheel 为二进制 wheel，不能声明为 pure python wheel。
• 当前构建环境为 Linux aarch64，glibc 版本为 2.38，因此平台 tag 为 manylinux_2_38_aarch64。
• 当前构建 Python 为 CPython 3.11，因此 Python/ABI tag 为 cp311-cp311。
• 当前构建 torch 为 2.9.0，torch-npu 为 2.9.0.post1，因此运行依赖需要精确写入：

Requires-Dist: torch==2.9.0
Requires-Dist: torch-npu==2.9.0.post1
Requires-Python: >=3.11,<3.12

3. 方案设计

3.1 总体方案

整体方案在 setup.py 中完成构建期动态决策：

1. 构建时读取当前 Python 版本，生成 python_requires，例如 >=3.11,<3.12。
2. 构建时读取当前 torch.__version__，去掉 +local 后缀后作为 mindiesd 发行版本号。
3. 构建时读取当前 torch_npu.__version__，写入 install_requires。
4. bdist_wheel 阶段将 wheel 标记为非 pure wheel。
5. 根据系统 glibc 和 CPU 架构生成 manylinux 平台 tag，例如 manylinux_2_38_aarch64。
6. 使用 twine check 校验生成的 wheel metadata。
7. 上传 PyPI 前确认文件名、METADATA 和 WHEEL tag 均符合预期。

当前构建产物示例：

dist/mindiesd-2.9.0-cp311-cp311-manylinux_2_38_aarch64.whl

其含义如下：

字段	值	含义
distribution	mindiesd	PyPI 项目名
version	2.9.0	MindIE-SD 发行版本号，对齐 torch 2.9.0
python tag	cp311	CPython 3.11
abi tag	cp311	CPython 3.11 ABI
platform tag	manylinux_2_38_aarch64	Linux aarch64，glibc 2.38 基线

3.2 技术选型

考虑过以下方案：

方案	示例	优点	缺点	结论
固定 MindIE-SD 产品版本	mindiesd-3.0.0-...whl	能表达 MindIE-SD 自身产品版本	文件名无法表达 torch 适配线；用户容易误装	不采用
post 版本区分 torch	mindiesd-3.0.0.post29-...whl	同时保留产品版本和 torch 线索	与 torch-npu 风格不一致；用户识别成本更高	已放弃
发行版本号对齐 torch	mindiesd-2.9.0-...whl	与 torch-npu 风格一致；文件名直观体现 torch 线	MindIE-SD 产品版本需通过文档或其他 metadata 表达	采用
包名区分 torch	mindiesd-torch29	安装目标非常明确	PyPI 项目名分裂；用户希望项目名固定为 mindiesd	不采用

3.3 功能与性能设计

3.3.1 版本生成

默认版本生成规则：

• 若设置 MINDIE_SD_VERSION_OVERRIDE，优先使用该值。
• 若未设置，则读取 torch.__version__。
• 对版本字符串执行 split("+", 1)[0]，去除本地版本后缀。
• 将最终版本写入 MINDIE_SD_VERSION_OVERRIDE，保证 pyproject.toml 中动态版本读取 version.__version__ 时保持一致。

示例：

构建环境 torch 版本	MindIE-SD 发行版本	wheel 文件名前缀
2.9.0	2.9.0	mindiesd-2.9.0-...whl
2.10.0	2.10.0	mindiesd-2.10.0-...whl
2.10.0+cpu	2.10.0	mindiesd-2.10.0-...whl

3.3.2 依赖生成

构建时生成精确运行依赖：

torch==${torch_version}
torch-npu==${torch_npu_version}

当前 torch 2.9 构建环境中的结果为：

Requires-Dist: torch==2.9.0
Requires-Dist: torch-npu==2.9.0.post1

该设计确保 pip 解析依赖时不会将 MindIE-SD 安装到不匹配的 torch/torch-npu 环境中。

3.3.3 Python 版本约束

构建时根据当前 Python minor 生成约束：

>=${major}.${minor},<${major}.${minor + 1}

例如 Python 3.11 构建产物写入：

Requires-Python: >=3.11,<3.12

这样可以避免 Python 3.10 或 3.12 用户安装到仅针对 CPython 3.11 ABI 编译的 wheel。

3.3.4 平台 tag 生成

bdist_wheel 阶段将 wheel 标记为二进制 wheel，并自动生成 PyPI 可接受的平台 tag：

• Linux + glibc + aarch64: manylinux_${glibc_major}_${glibc_minor}_aarch64
• Linux + glibc + x86_64: manylinux_${glibc_major}_${glibc_minor}_x86_64
• 支持通过 MINDIE_SD_PLAT_NAME 显式覆盖。

当前构建环境生成：

manylinux_2_38_aarch64

3.3.5 发布流程

当前 torch 2.9 + Python 3.11 发布流程：

cd /home/g00576449/mindie26.1.0/task/pypi_task/MindIE-SD
rm -rf dist build/lib mindiesd.egg-info
python3 setup.py bdist_wheel
python3 -m twine check dist/*.whl
python3 -m twine upload dist/mindiesd-2.9.0-cp311-cp311-manylinux_2_38_aarch64.whl

上传前需要解包检查：

unzip -p dist/mindiesd-2.9.0-cp311-cp311-manylinux_2_38_aarch64.whl "*/METADATA" \
  | grep -E "^(Name|Version|Requires-Python|Requires-Dist):"
unzip -p dist/mindiesd-2.9.0-cp311-cp311-manylinux_2_38_aarch64.whl "*/WHEEL" \
  | grep "^Tag:"

期望结果：

Name: mindiesd
Version: 2.9.0
Requires-Python: >=3.11,<3.12
Requires-Dist: torch==2.9.0
Requires-Dist: torch-npu==2.9.0.post1
Tag: cp311-cp311-manylinux_2_38_aarch64

3.4 安全隐私与DFX设计

兼容性

• wheel 文件名和 metadata 同时约束 Python ABI、平台、torch 和 torch-npu。
• 对于不同 torch 版本，需要分别构建和发布独立 wheel。
• 同一 PyPI 项目名 mindiesd 下通过版本号区分 torch 适配线。

可维护性

• 版本、依赖、Python 约束、平台 tag 均在 setup.py 内集中生成。
• 构建脚本无需为每个 torch 版本手动维护不同文件名。
• 环境变量提供覆盖能力，便于 CI、回滚和特殊发布。

可测试性

• 可通过 setup.py --version 快速验证版本生成。
• 可通过 setup.py egg_info 验证 metadata。
• 可通过 twine check 验证 PyPI metadata 基本合法性。
• 可通过解包 wheel 验证 METADATA 和 WHEEL。

可靠性

• 依赖精确钉死，降低运行时 ABI 不兼容风险。
• manylinux tag 替代 linux_aarch64，避免 PyPI 上传失败。
• 构建日志输出版本、依赖和平台 tag，便于定位发布问题。

安全隐私

• 本方案不引入用户数据处理，不涉及隐私数据存储或传输。
• PyPI 上传凭证仍通过 twine 标准认证流程输入或配置，不写入源码仓。

3.5 编程与调用设计

本需求不新增 MindIE-SD 运行时 API，仅影响构建和发布行为。

3.5.1 编程模型基本设计

开发环境：

• Python: 当前构建目标对应 Python 版本，例如 Python 3.11。
• torch: 当前构建目标对应 torch 版本，例如 torch 2.9.0。
• torch-npu: 与 torch 匹配，例如 torch-npu 2.9.0.post1。
• CANN/Ascend 编译环境：需满足 MindIE-SD 自定义算子和 plugin 编译要求。
• 构建命令：python3 setup.py bdist_wheel。

开发约束：

• 每个 wheel 仅面向一个 Python ABI 和一个平台 tag。
• 每个 wheel 仅面向一个 torch/torch-npu 版本组合。
• 发布前必须在目标容器中完成编译和 metadata 校验。

可验收设计：

• python3 setup.py --version 输出与当前 torch 版本一致。
• python3 -m twine check dist/*.whl 返回 PASSED。
• wheel 文件名包含正确的版本、Python tag、ABI tag 和 manylinux tag。
• wheel metadata 包含正确的 Requires-Python 和 Requires-Dist。

3.5.2 接口定义与设计

本方案不新增用户 API，但新增或保留以下构建期环境变量：

环境变量	默认值	作用
MINDIE_SD_VERSION_OVERRIDE	未设置	覆盖 MindIE-SD 发行版本号
MINDIE_SD_TORCH_VERSION	当前 torch.__version__	覆盖写入版本和依赖的 torch 版本
MINDIE_SD_TORCH_NPU_VERSION	当前 torch_npu.__version__	覆盖写入依赖的 torch-npu 版本
MINDIE_SD_PYTHON_REQUIRES	当前 Python minor 范围	覆盖 Requires-Python
MINDIE_SD_PLAT_NAME	自动检测	覆盖 wheel platform tag

使用示例：

MINDIE_SD_VERSION_OVERRIDE=2.9.0 \
MINDIE_SD_TORCH_VERSION=2.9.0 \
MINDIE_SD_TORCH_NPU_VERSION=2.9.0.post1 \
python3 setup.py bdist_wheel

3.5.3 编程手册设计

需要在开发者构建文档中补充以下内容：

• PyPI wheel 命名规则说明。
• torch 版本与 mindiesd 发行版本号的对应关系。
• 构建前环境检查命令。
• twine check 和 METADATA 解包检查命令。
• PyPI 上传命令和失败排查说明。
• 已发布错误版本的 yank 策略说明。

4. 测试设计

测试分为构建期测试、metadata 测试和发布前校验。

构建期测试：

python3 setup.py --version

预期输出：

2.9.0

metadata 测试：

rm -rf mindiesd.egg-info
python3 setup.py egg_info
grep -E "^(Name|Version|Requires-Python|Requires-Dist):" mindiesd.egg-info/PKG-INFO
cat mindiesd.egg-info/requires.txt

预期包含：

Name: mindiesd
Version: 2.9.0
Requires-Python: >=3.11,<3.12
torch==2.9.0
torch-npu==2.9.0.post1

wheel 测试：

python3 setup.py bdist_wheel
python3 -m twine check dist/*.whl

预期生成：

dist/mindiesd-2.9.0-cp311-cp311-manylinux_2_38_aarch64.whl

解包测试：

unzip -p dist/mindiesd-2.9.0-cp311-cp311-manylinux_2_38_aarch64.whl "*/METADATA" \
  | grep -E "^(Name|Version|Requires-Python|Requires-Dist):"
unzip -p dist/mindiesd-2.9.0-cp311-cp311-manylinux_2_38_aarch64.whl "*/WHEEL" \
  | grep "^Tag:"

验收标准：

• twine check 通过。
• 文件名为 mindiesd-2.9.0-cp311-cp311-manylinux_2_38_aarch64.whl。
• Version 为 2.9.0。
• Requires-Dist 精确约束 torch==2.9.0 和 torch-npu==2.9.0.post1。
• Tag 为 cp311-cp311-manylinux_2_38_aarch64。

5. 缺点和风险

5.1 产品版本表达能力下降

发行版本号用于表达 torch 适配线后，MindIE-SD 自身产品版本无法直接通过 wheel 文件名表达。

应对措施：

• 在 release notes、README 或包内 metadata 中说明 MindIE-SD 产品版本。
• 如未来必须同时表达产品版本和 torch 版本，可重新讨论 post/local/build tag 方案。

5.2 多版本矩阵维护成本

若未来支持 torch 2.9、2.10、多个 Python minor 和多个平台，需要维护构建矩阵。

应对措施：

• 每个 torch/Python/平台组合使用独立容器构建。
• 在 CI 中固化构建矩阵和验收脚本。
• 发布前统一执行 metadata 解包检查。

5.3 依赖精确钉死导致安装灵活性降低

torch==2.9.0 和 torch-npu==2.9.0.post1 可以降低 ABI 风险，但用户无法在 patch 版本不同的环境中直接复用该 wheel。

应对措施：

• 对于二进制扩展包，优先保证可靠性。
• 如确认 patch 版本 ABI 兼容，可后续将依赖约束调整为受控范围，例如 torch>=2.9,<2.10，但需单独验证。

6. 现有技术

6.1 torch-npu

torch-npu 采用发行版本号与 PyTorch 版本线对齐的方式，例如：

torch_npu-2.10.0-cp313-cp313-manylinux_2_28_x86_64.whl

其中 2.10.0 是 torch_npu 自身发行版本号，同时表达其适配 torch 2.10 版本线。MindIE-SD 本方案借鉴该命名策略。

6.2 Python wheel 规范

wheel 文件名遵循如下格式：

{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl

因此 wheel 文件名本身没有专门的 torch version tag。若需要在文件名中体现 torch 版本，推荐通过发行版本号或包名策略表达。本方案选择发行版本号对齐 torch。

6.3 manylinux 平台 tag

PyPI 不接受泛化的 linux_aarch64 tag 作为公开分发 wheel 的平台 tag。本方案生成 manylinux_2_38_aarch64，满足 PyPI 对 Linux 二进制 wheel 的平台 tag 要求。

7. 未解决问题

以下问题需在 RFC 评审或后续版本中继续确认：

• 是否需要为 Python 3.10、3.12、3.13 分别构建 wheel。
• 是否需要支持 x86_64 平台。
• torch/torch-npu patch 版本是否可以放宽为范围依赖。
• MindIE-SD 自身产品版本应通过何种方式在 PyPI 页面或包内展示。
• CANN 版本是否需要写入额外 metadata 或发布说明。
• 已上传的 3.0.0 是否立即 yank，以及 yank reason 文案。

附录

• 参考资料链接：
  • PEP 427 - The Wheel Binary Package Format: https://peps.python.org/pep-0427/
  • PEP 440 - Version Identification and Dependency Specification: https://peps.python.org/pep-0440/
  • Python Packaging - Platform compatibility tags: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/
• 术语表：
  • wheel：Python 二进制分发包格式。
  • CPython ABI：CPython 解释器二进制接口，例如 cp311。
  • manylinux：Linux wheel 平台兼容性标签。
  • yank：在 PyPI 上标记 release 不推荐安装，但不删除文件，已指定版本的用户仍可安装。
• 文档更新计划：
  • RFC 评审通过后，同步更新 MindIE-SD 构建指南和 PyPI 发布操作手册。

欢迎加入社区，感谢您对社区的贡献 🎉!