29cb3fa2创建于 21 天前历史提交

状态 (Status): Draft 作者 (Authors): @wang-ruiju 创建日期 (Created): 2026-05-07 更新日期 (Updated): 2026-05-07 相关 Issue/PR: #（待关联）

1. 概述

1.1 简介

本提案旨在扩展 Ascend-Deployer 工具对 A5 代际（Atlas 950）的硬件形态支持。当前工具仅支持 Atlas 350 A5 标卡的单卡形态，无法满足 A5 Pod 集群和 A5 Server 整机的软件栈安装部署需求。本提案通过在 inventory_file 中新增 hardware_type 参数，实现 A5 Pod 和 A5 Server 两种硬件形态的完整软件栈安装、升级支持，使用户可通过统一工具完成昇腾软件栈的自动化部署，降低运维成本，提升部署效率。

1.2 动机

A5 代际（Atlas 950）是昇腾新一代训练产品，包含 A5 Pod 和 A5 Server 两种形态。现有 Ascend-Deployer 工具仅支持 Atlas 350 A5 标卡的单卡形态，存在以下关键差距：

A5 代际关键变化：

新增硬件形态：A5 Pod（集群形态）和 A5 Server（单机形态），区别于现有 Atlas 350 A5 标卡
软件配套变化：A5 代际涉及版本软件的配套，驱动固件、CANN、MindCluster 组件版本与 A2/A3 代际不同
组件差异：A5 代际不支持 NNAE、NNRT、MCU、Docker 镜像，新增 UBEngine 组件
OS 配套差异：A5 Pod/A5 Server 支持的 OS 版本与 Atlas 350 A5 可能不同

现有代码中 A5 支持现状：

项目	现状	差距
Hardware 类	仅有 `ATLAS_350_A5 = "Atlas 350 A5"`	缺少 A5 Pod、A5 Server 硬件型号
card_map	仅有 3 条 Atlas 350 A5 四元组	缺少 A5 Pod/A5 Server 四元组
product_model_dict	仅有 Atlas 350 A5 映射	缺少 A5 Pod/A5 Server 产品映射
OS_TO_CARD_TAG_MAP	仅 openEuler 22.03 LTS SP4 支持 A5	A5 Pod/A5 Server 可能需要更多 OS 支持
inventory_file	无硬件类型指定参数	无法区分 A5 Pod/A5 Server

痛点：

现有工具无法识别和部署 A5 Pod 集群形态和 A5 Server 整机形态
用户无法通过工具自动完成 A5 Pod/A5 Server 的软件安装、升级
缺少硬件类型指定参数，无法区分同一代际不同形态的硬件

用户价值： 通过适配，用户可使用统一工具完成 A5 Pod/A5 Server 的昇腾软件栈自动化安装、升级，降低运维成本，提升部署效率。

1.3 目标

目标：

实现 A5 Pod 集群形态的软件栈安装、升级支持
实现 A5 Server 整机形态的软件栈安装、升级支持
新增 hardware_type 参数，支持用户在 inventory_file 中显式指定硬件类型
支持 A5 Pod/A5 Server 配套 OS 版本的软件包安装
支持 A5 Pod/A5 Server 特有组件（UBEngine）的安装与升级
支持升级以下软件：驱动固件、MCU 固件、CANN、MindCluster 组件（性能测试、故障诊断、集群调度）
保持对现有 Atlas 350 A5 标卡及其他代际（A1/A2/A3/I1/I2）的向后兼容

非目标：

本提案不涉及 A5 Pod/A5 Server 的网络配置适配（HCCN/UB 网络配置，预留扩展点）
不涉及 A5 Pod 集群调度场景的专项优化
不涉及 A5 代际故障诊断工具的适配（由独立 RFC 覆盖）
不涉及 BMC/LCNE 日志格式的适配

2. 用例分析

本提案覆盖以下核心用例场景：

场景一：A5 Pod 集群软件栈首次安装部署

用户在 inventory_file 中配置 hardware_type=a910_95_pod，指定目标 OS 版本
工具自动下载 A5 Pod 配套的驱动固件、CANN、UBEngine、MindCluster 组件
批量部署到集群所有节点，自动识别硬件型号并完成安装
验证安装结果，输出部署报告

场景二：A5 Server 整机软件栈首次安装部署

用户在 inventory_file 中配置 hardware_type=a910_95_srv，指定目标 OS 版本
工具自动下载 A5 Server 配套软件包
部署到目标设备，完成软件栈安装
验证安装结果

场景三：A5 Pod/A5 Server 软件升级

用户通过 CLI 指定升级组件（驱动固件、MCU 固件、CANN、MindCluster）
工具执行版本约束检查，确保升级路径合法
执行升级操作并验证结果

兼容性要求：

向后兼容现有 Atlas 350 A5 标卡及 A1/A2/A3/I1/I2 代际的部署流程
hardware_type 参数为可选参数，未指定时保持现有自动识别逻辑

使用限制：

A5 Pod/A5 Server 四元组信息需硬件团队确认后方可支持自动识别，在此之前需通过 hardware_type 手动指定
仅支持 A5 Pod/A5 Server 配套的 OS 版本

3. 方案设计

3.1 总体方案

本 RFC 采用硬件形态扩展方案，在现有 A5 代际支持基础上，新增 A5 Pod 和 A5 Server 两种硬件形态，通过在 inventory_file 中新增 hardware_type 参数指定硬件类型，实现 A5 Pod/A5 Server 的完整软件栈安装部署支持。

核心适配策略：

适配点	现有逻辑	A5 Pod/A5 Server 逻辑	适配方式
硬件型号	`ATLAS_350_A5 = "Atlas 350 A5"`	新增 `ATLAS_900_A5_POD`、`ATLAS_800I_A5`	Hardware 类扩展
四元组识别	3 条 Atlas 350 A5 四元组	新增 A5 Pod/A5 Server 四元组	card_map 扩展
产品映射	Atlas 350 A5 单条	新增 A5 Pod/A5 Server 产品映射	product_model_dict 扩展
硬件类型指定	无参数，自动识别	新增 `hardware_type` 参数指定 A5 Pod/A5 Server	inventory_file 参数扩展
OS 配套	openEuler 22.03 LTS SP4	按 A5 Pod/A5 Server 实际配套扩展	OS_TO_CARD_TAG_MAP 扩展
组件标签	A5_TAGS（已有）	复用 A5_TAGS，按形态微调	标签复用+扩展
场景映射	a910_95 场景	新增 A5 Pod/A5 Server 场景	scenes_dict 扩展

三流程架构：

下载流程：CLI 指定 OS → 下载配套软件包（驱动固件、CANN、UBEngine、MindCluster 组件）
安装流程：CLI 指定安装组件 → 自动识别硬件型号 → 批量部署到目标设备 → 验证安装结果
升级流程：CLI 指定升级组件 → 版本约束检查 → 执行升级（驱动固件、MCU 固件、CANN、MindCluster 组件）

架构总览

┌─────────────────────────────────────────────────────────────┐
│ CLI 层                                                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │hardware_type│  │ OS 选择     │  │ 组件选择    │         │
│  │ (A5 Pod/    │  │ (--os-list) │  │ (--install/ │         │
│  │  A5 Server) │  │             │  │  --upgrade) │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 设备识别层（common_info.py → get_npu_info()）                 │
│                                                              │
│  hardware_type 已指定？                                      │
│     ├── 是 → 用 hardware_type 覆盖 scene，补充 card/model/   │
│     │       product                                          │
│     └── 否 → 自动识别（PCI 四元组 → card_map → scenes_dict） │
│                                                              │
│  返回: {"card": ..., "model": ..., "scene": ...,             │
│          "product": ...}                                     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 兼容性配置层                                                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Hardware 类扩展                                      │   │
│  │ ATLAS_900_A5_POD = "Atlas 900 A5 Pod"               │   │
│  │ ATLAS_800I_A5 = "Atlas 800I A5"                     │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ HardwareOSTags 映射                                   │   │
│  │ A5_KEY → A5_TAGS (复用现有)                           │   │
│  │ OS_TO_CARD_TAG_MAP 新增 A5 Pod/A5 Server OS 映射     │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ CARD_OS_COMPONENTS_MAP                               │   │
│  │ ATLAS_900_A5_POD → A5_KEY 映射                       │   │
│  │ ATLAS_800I_A5 → A5_KEY 映射                          │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 设备识别层                                                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ card_map    │  │ product_    │  │ scenes_dict │         │
│  │ (四元组)    │  │ model_dict  │  │ (场景映射)  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 执行层                                                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ 下载软件    │  │ 安装部署    │  │ 升级软件    │         │
│  │ (download)  │  │ (install)   │  │ (upgrade)   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

3.2 技术选型

方案一：硬件形态扩展方案（本提案采用）

在现有 A5 代际框架内，通过扩展 Hardware 类、card_map、product_model_dict 等配置，新增 A5 Pod 和 A5 Server 硬件形态。新增 hardware_type 参数作为可选覆盖手段。

优势：改动范围可控，复用现有 A5_TAGS 组件标签体系，向后兼容性好，实现成本低
劣势：需硬件团队提供四元组信息后方可支持自动识别

方案二：独立 A5 Pod/A5 Server 代际方案（放弃）

将 A5 Pod 和 A5 Server 作为独立代际处理，新建完整的标签体系、组件映射和场景配置。

优势：各形态完全独立，互不影响
劣势：大量重复配置，维护成本高，与 Atlas 350 A5 共用组件标签的逻辑被割裂，不符合实际产品关系

方案三：纯自动识别方案（放弃）

不新增 hardware_type 参数，完全依赖 PCI 四元组自动识别。

优势：用户无需额外配置
劣势：在四元组未确认或批量部署场景下无法工作，缺乏灵活性

选型结论： 采用方案一，兼顾自动识别与手动指定的灵活性，改动范围可控，向后兼容。

3.3 功能与性能设计

3.3.1 核心设计：新增 `hardware_type` 参数指定硬件类型

A5 Pod/A5 Server 适配的核心是新增 hardware_type 参数，解决同一代际不同形态硬件无法自动识别的问题。

在 inventory_file 的 [all:vars] 中新增：

现有方式：自动识别（通过 PCI 四元组）→ 匹配 card_map → 确定硬件型号
新增方式：hardware_type 参数显式指定 → 覆盖自动识别 → 确定硬件型号

场景说明：
- 单机部署：自动识别即可（PCI 四元组匹配）
- 批量部署：hardware_type 参数指定，避免逐台识别

3.3.2 A5 硬件形态映射设计

A5 代际硬件形态
    ├── Atlas 350 A5（标卡，已支持）
    │   └── card_map: ("0x19e5", "0xd806", "0x19e5", "0x4003/4004/4005")
    │   └── product_model_dict: {"product": "Atlas-350-A5", "model": "A5", "name": "A350-a5"}
    │   └── CARD_OS_COMPONENTS_MAP: ATLAS_350_A5 → A5_KEY
    │
    ├── Atlas 900 A5 Pod（集群形态，新增）
    │   └── card_map: 新增四元组（待确认）
    │   └── product_model_dict: {"product": "Atlas-900-A5-Pod", "model": "A5", "name": "A900-a5"}
    │   └── CARD_OS_COMPONENTS_MAP: ATLAS_900_A5_POD → A5_KEY
    │
    └── Atlas 800I A5（Server 形态，新增）
        └── card_map: 新增四元组（待确认）
        └── product_model_dict: {"product": "Atlas-800I-A5", "model": "A5", "name": "A800i-a5"}
        └── CARD_OS_COMPONENTS_MAP: ATLAS_800I_A5 → A5_KEY

说明：
- A5 Pod/A5 Server/Atlas 350 A5 共用 A5_TAGS 组件标签
- A5_TAGS = (BASIC_TAGS | MINDCLUSTER_TAGS | {UBENGINE}) - {DOCKER_IMAGES, NNAE, NNRT, MCU}
- 三种形态的 OS 配套可能不同，通过 OS_TO_CARD_TAG_MAP 区分
- 当 A5 Pod/A5 Server 四元组未确认时，用户可通过 hardware_type=a910_95_pod / a910_95_srv 手动指定

3.3.3 关键链路

硬件类型指定：新增 hardware_type 参数，支持 A5 Pod/A5 Server 选项，覆盖自动识别结果
硬件型号注册：在 Hardware 类中新增 ATLAS_900_A5_POD 和 ATLAS_800I_A5
四元组适配：在 card_map 中新增 A5 Pod/A5 Server 的 PCI 四元组映射
产品映射：在 product_model_dict 和 scenes_dict 中新增 A5 Pod/A5 Server 映射
OS 配套：在 OS_TO_CARD_TAG_MAP 中新增 A5 Pod/A5 Server 支持的 OS 版本映射
组件映射：在 CARD_OS_COMPONENTS_MAP 中新增 A5 Pod/A5 Server 到 A5_KEY 的映射
版本约束：在 NOT_FULL_LIFECYCLE_SUPPORT 中按需添加 A5 Pod/A5 Server 的驱动固件版本约束
标签适配：在 label_node.py 中新增 A5 Pod/A5 Server 的 accelerator-type 标签

3.3.4 数据模型变更

Hardware 类新增常量：

ATLAS_900_A5_POD = "Atlas 900 A5 Pod"
ATLAS_800I_A5 = "Atlas 800I A5"

card_map 新增条目（四元组待确认）：

# A5 Pod 四元组（待硬件团队确认）
("0xXXXX", "0xXXXX", "0xXXXX", "0xXXXX"): Hardware.ATLAS_900_A5_POD,
# A5 Server 四元组（待硬件团队确认）
("0xXXXX", "0xXXXX", "0xXXXX", "0xXXXX"): Hardware.ATLAS_800I_A5,

product_model_dict 新增映射：

Hardware.ATLAS_900_A5_POD: {"product": "Atlas-900-A5-Pod", "model": "A5", "name": "A900-a5"},
Hardware.ATLAS_800I_A5: {"product": "Atlas-800I-A5", "model": "A5", "name": "A800i-a5"},

CARD_OS_COMPONENTS_MAP 新增映射：

Hardware.ATLAS_900_A5_POD: A5_KEY,
Hardware.ATLAS_800I_A5: A5_KEY,

3.4 安全隐私与 DFX 设计

兼容性：

向后兼容：hardware_type 为可选参数，未指定时保持现有自动识别逻辑不变
现有 Atlas 350 A5 标卡及 A1/A2/A3/I1/I2 代际的部署流程不受影响
A5 Pod/A5 Server/Atlas 350 A5 共用 A5_TAGS 组件标签，确保组件层面的一致性

可维护性：

新增硬件形态遵循现有 Hardware 类 + card_map + product_model_dict 的扩展模式，与现有代码风格一致
配置集中管理，新增形态仅需在对应字典中添加条目

可测试性：

hardware_type 参数可模拟不同硬件形态，便于自动化测试
自动识别与手动指定两条路径可独立测试验证

可靠性：

hardware_type 显式指定优先级高于自动识别，避免识别错误
版本约束检查确保升级路径合法，防止不兼容版本安装

3.5 编程与调用设计

3.5.1 编程模型基本设计

开发环境设计：

开发语言：Python
运行环境：Linux（openEuler / CentOS / Ubuntu 等昇腾支持的操作系统）
依赖：Ascend-Deployer 现有框架，无新增第三方依赖

开发约束：

需遵循现有 Hardware 类、card_map、product_model_dict 的扩展模式
hardware_type 参数值需与 scenes_dict 中的场景类型对应

可验收设计：

在 A5 Pod 测试环境中验证 hardware_type=a910_95_pod 的完整安装流程
在 A5 Server 测试环境中验证 hardware_type=a910_95_srv 的完整安装流程
验证未指定 hardware_type 时现有流程不受影响（回归测试）
验证 UBEngine 组件的安装与升级

3.5.2 接口定义与设计

3.5.2.1 inventory_file 新增参数

参数名称：hardware_type
配置位置：inventory_file 的 [all:vars] 段
类型：string
描述：显式指定目标设备的硬件类型，覆盖自动识别结果
取值范围：a910_95_pod（A5 Pod）、a910_95_srv（A5 Server），或留空（自动识别）
默认值：空（自动识别）
约束说明：该参数为可选参数；当指定时，优先级高于 PCI 四元组自动识别
变更说明：新增参数，不影响现有配置

3.5.2.2 get_npu_info() 函数变更

接口描述：获取 NPU 设备信息，新增 hardware_type 参数支持
变更说明：在 common_info.py 的 get_npu_info() 中新增 hardware_type 参数处理逻辑
处理逻辑：
1. 若 hardware_type 已指定，使用 hardware_type 覆盖 scene，补充 card/model/product 信息
2. 若 hardware_type 未指定，保持现有 PCI 四元组自动识别逻辑
约束说明：hardware_type 指定的值必须在 scenes_dict 中存在对应映射

3.5.3 编程手册设计

本提案涉及的新增参数和硬件形态需在以下文档中更新：

Ascend-Deployer 用户手册：新增 hardware_type 参数说明及 A5 Pod/A5 Server 部署指南
inventory_file 配置参考：补充 hardware_type 参数定义和示例

4. 缺点和风险

潜在风险：

风险项	影响	应对措施
A5 Pod/A5 Server 四元组信息待确认	无法支持自动识别，需用户手动指定 `hardware_type`	需硬件团队提供 PCI 设备 ID，确认后补充 card_map
A5 Pod/A5 Server 配套 OS 版本待确认	OS 兼容性检查可能不完整	需产品团队确认支持的 OS 列表，确认后补充 OS_TO_CARD_TAG_MAP
A5 Pod/A5 Server 软件包版本约束待确认	升级路径约束可能不准确	需与版本团队确认驱动固件起始版本，确认后补充 NOT_FULL_LIFECYCLE_SUPPORT
`hardware_type` 参数与自动识别的优先级	用户误配置可能导致识别错误	`hardware_type` 显式指定优先级高于自动识别，需在文档中明确说明

负面影响：

对现有功能无冲击，hardware_type 为可选参数，不影响现有部署流程
无 API 或版本兼容性问题，无 Breaking Change

实现成本：

代码改动量较小，主要集中在配置层（Hardware 类、card_map、product_model_dict、OS_TO_CARD_TAG_MAP、CARD_OS_COMPONENTS_MAP、scenes_dict）
核心逻辑变更集中在 common_info.py 的 get_npu_info() 函数
维护成本低，新增形态遵循现有扩展模式

5. 现有技术

本提案参考了 Ascend-Deployer 现有代际（A2/A3/I1/I2）的硬件形态扩展模式。现有框架已通过 Hardware 类 + card_map + product_model_dict + scenes_dict 的四层映射机制支持多代际多形态硬件，本提案在此基础上扩展 A5 Pod 和 A5 Server，遵循相同的设计模式，无引入新的技术范式。

与现有 Atlas 350 A5 标卡支持的关系：三者共用 A5_TAGS 组件标签体系和 A5_KEY，仅在硬件型号识别和 OS 配套上存在差异，设计上保持一致性。

6. 未解决问题

以下问题需在 RFC 通过前由相关团队确认：

待确认项	确认方	影响
A5 Pod PCI 四元组	硬件团队	card_map 适配
A5 Server PCI 四元组	硬件团队	card_map 适配
A5 Pod/A5 Server 支持 OS 列表	产品团队	OS_TO_CARD_TAG_MAP 适配
A5 Pod/A5 Server 驱动固件起始版本	版本团队	NOT_FULL_LIFECYCLE_SUPPORT 适配
A5 Pod/A5 Server 产品名称（dmidecode 输出）	硬件团队	product_model_dict 适配
A5 Pod/A5 Server 场景类型	产品团队	scenes_dict 适配

附录

术语表：
- A5 代际：Atlas 950 系列，昇腾新一代训练产品
- 四元组：PCI 设备识别四元组 (vendor_id, device_id, subsystem_vendor_id, subsystem_device_id)
- UBEngine：A5 代际新增的计算引擎组件
- MindCluster：昇腾集群调度与管理组件集合
文档更新计划：
- Ascend-Deployer 用户手册：新增 hardware_type 参数说明及 A5 Pod/A5 Server 部署指南
- inventory_file 配置参考：补充 hardware_type 参数定义和示例