Star135
208
代码
代码
Issues16
Pull Requests33
Actions
项目讨论
Wiki
分析
Star135
208
已合并
[DOC] 资料优化：安装部署资料优化，新增功能特性章节 #2322
penghuiyang创建于 3月19日
[DOC] 资料优化：安装部署资料优化，新增功能特性章节 #2322
已合并
penghuiyang创建于 3月19日
从huiyangpeng/RecSDK0317_dev合入到Ascend/RecSDKdevelop
共 10 个文件变更+748-322
M.gitignore+3-2
@@ -1,5 +1,6 @@
1.idea/1.idea/
2-cmake-build-debug/2+cmake-build-*/
3.vscode/3.vscode/
4.DS_Store4.DS_Store
5-build/5+build/
6+__pycache__/
MREADME.md+64-75
@@ -1,68 +1,25 @@
1# Rec SDK1# Rec SDK
2 2 
3<div align="center">3<div align="center">
4- 4+ 
5[![Zread](https://img.shields.io/badge/Zread-Ask_AI-_.svg?style=flat&color=0052D9&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/Ascend/RecSDK)&nbsp;&nbsp;&nbsp;&nbsp;5[![Zread](https://img.shields.io/badge/Zread-Ask_AI-_.svg?style=flat&color=0052D9&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/Ascend/RecSDK)&nbsp;&nbsp;&nbsp;&nbsp;
6[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_AI-_.svg?style=flat&color=0052D9&labelColor=000000&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/Ascend/RecSDK)6[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_AI-_.svg?style=flat&color=0052D9&labelColor=000000&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/Ascend/RecSDK)
7- 7+ 
8</div>8</div>
9 9 
10## 最新消息10## 最新消息
11 11 
12* [20260224] 资料结构整改，更新Roadmap（2026Q1）12* [20260224] 资料结构整改，更新Roadmap（2026Q1）
13 13 
14-### Roadmap（2026Q1）14+### Roadmap
15- 
16-#### HierarchicalKV
17- 
18-1. 支持保存加载。
19-2. 支持基础属性查询设置功能。
20-3. 支持KV查询功能。
21-4. 支持KV插值功能。
22-5. 支持建表功能。
23-6. 功能适配封装。
24- 
25-#### TensorFlow(v1)
26- 
27-1. 例行镜像、配套表更新。
28- 
29-#### TensorFlow(v2)
30- 
31-1. 例行镜像、配套表更新。
32- 
33-#### TorchRec(v1)
34- 
35-1. 支持在算力切分设备上推理。
36-2. 查表反向算子重构。
37-3. HSTU：
38- 1. 算子重构。
39- 2. 反向性能优化。
40- 3. 支持int32。
41-4. 保存和加载功能增强：
42- 1. 支持n卡保存，m卡加载。
43- 2. 支持增量保存、加载。
44-5. norm_mul融合算子。
45-6. ln_linear_silu融合算子。
46-7. concat_2d_jagged算子。
47- 
48-#### TorchRec(v2)
49- 
50-1. Row-wise稀疏表：
51- 1. 支持建表。
52- 2. 支持查表。
53- 3. 支持特征淘汰。
54- 4. 支持更新。
55- 5. 反向更新融合优化器。
56- 6. 支持全量保存和加载
57- 7. 支持梯度规约。
58-2. 适配TorchRec EmbeddingShardingPlanner。
59-3. 适配TorchRec EmbeddingCollectionSharder。
60 15 
16+[Roadmap（2026Q1）](https://gitcode.com/Ascend/RecSDK/issues/1075)
61 17 
62## 简介18## 简介
63 19 
64-Rec SDK作为面向互联网市场搜索推荐广告的应用使能SDK产品，对于搜索推荐广告模型训练的应用场景需求，提供基于昇腾平台的搜索推荐广告框架，支撑大规模搜推广场景，助力完成搜推广模型的高效训练。Rec20+Rec SDK作为面向互联网市场搜索推荐广告的应用使能SDK产品，对于搜索推荐广告模型训练的应用场景需求，提供基于昇腾平台的搜索推荐广告框架，支撑大规模搜推广场景，助力完成搜推广模型的高效训练。
65-SDK的功能涉及：21+ 
22+Rec SDK的功能涉及：
66 23 
671. 模型训练基础功能。支持单机单卡训练、多机多卡分布式训练。241. 模型训练基础功能。支持单机单卡训练、多机多卡分布式训练。
682. 推荐场景特有功能。基于Rec SDK的稀疏表方案，Rec SDK提供必备功能，如特征保存和加载、特征准入、特征淘汰等。252. 推荐场景特有功能。基于Rec SDK的稀疏表方案，Rec SDK提供必备功能，如特征保存和加载、特征准入、特征淘汰等。
@@ -70,31 +27,44 @@ SDK的功能涉及：
70 27 
71## 目录结构28## 目录结构
72 29 
73-```30+```text
74-mxrec/ # 项目根目录31+RecSDK/ # 项目根目录
75-|-- build/ # 构建脚本、生成的wheel包等32+ |-- build/ # 构建脚本、生成的wheel包等
76-|33+ |
77-|-- cust_op/34+ |-- cust_op/
78-| |-- ascendc_op # Ascend C编写，编译后在AI Core执行的算子和其编译脚本35+ | |-- ascendc_op # Ascend C编写，编译后在AI Core执行的算子和其编译脚本
79-| |-- framework # 算子适配层36+ | |-- framework # 算子适配层
80-| |-- hkv # hkv子模块代码，项目代码来自https://gitcode.com/Ascend/HierarchicalKV-ascend.git37+ | |-- hkv # hkv子模块代码，项目代码来自https://gitcode.com/Ascend/HierarchicalKV-ascend.git
81-| |-- test # 算子测试用例38+ | |-- test # 算子测试用例
82-| |-- tf_cpu_op # CPU算子39+ | |-- tf_cpu_op # CPU算子
83-|40+ |
84-|-- docs/ # 项目镜像构建脚本、公网和邮箱地址及通信矩阵文档41+ |-- docs/ # 项目资料文档、镜像构建脚本、公网和邮箱地址及通信矩阵文档
85-|42+ |
86-|-- training43+ |-- training
87- |-- common # 公共组件44+ |-- common # 公共组件
88- |-- tf_rec_v1 # 基于TensorFlow，适配NPU设备的非全下沉稀疏推荐框架45+ |-- tf_rec_v1 # 基于TensorFlow，适配NPU设备的非全下沉稀疏推荐框架
89- |-- tf_rec_v2 # 基于TensorFlow，适配NPU设备的全下沉稀疏推荐框架（POC状态）46+ |-- tf_rec_v2 # 基于TensorFlow，适配NPU设备的全下沉稀疏推荐框架（POC状态）
90- |-- torch_rec_v1 # 基于PyTorch、torchrec开源软件，适配NPU设备的非全下沉稀疏推荐框架47+ |-- torch_rec_v1 # 基于PyTorch、TorchRec开源软件，适配NPU设备的非全下沉稀疏推荐框架
91- |-- hybrid_torchrec # 适配NPU纯显存模式（Device Memory）的推荐训练框架48+ |-- torch_rec_v2 # 基于PyTorch、TorchRec开源软件，适配NPU设备的全下沉稀疏推荐框架（POC状态）
92- |-- torchrec_embcache # 适配NPU多级缓存模式（Device Memory + Host DDR）的推荐训练框架
93- |-- torchrec_npu # 基于torchrec开源组件的NPU适配pacth
94- |-- torch_rec_v2 # 基于PyTorch、torchrec开源软件，适配NPU设备的全下沉稀疏推荐框架（POC状态）
95```49```
96 50 
51+### 各组件说明
52+ 
53+| 组件名称 | 基础框架 | 适配状态 | 框架类型 | 功能描述 |
54+|---------|---------|---------|---------|---------|
55+| tf_rec_v1 | TensorFlow | 非全下沉 | 稀疏推荐框架 | 基于TensorFlow，适配NPU设备的非全下沉稀疏推荐框架 |
56+| tf_rec_v2 | TensorFlow | 全下沉 | 稀疏推荐框架 | 基于TensorFlow，适配NPU设备的全下沉稀疏推荐框架（POC状态） |
57+| torch_rec_v1 | PyTorch + TorchRec | 非全下沉 | 稀疏推荐框架 | 基于PyTorch、TorchRec开源软件，适配NPU设备的非全下沉稀疏推荐框架 |
58+| torch_rec_v2 | PyTorch + TorchRec | 全下沉 | 稀疏推荐框架 | 基于PyTorch、TorchRec开源软件，适配NPU设备的全下沉稀疏推荐框架（POC状态） |
59+ 
60+### 关键术语说明
61+ 
62+- **非全下沉**：指部分计算任务在NPU上执行，部分在CPU上执行的混合模式
63+- **全下沉**：指所有计算任务都下沉到NPU上执行，以获得更好的性能
64+- **POC状态**：Proof of Concept（概念验证）状态，表示该组件仍处于试验验证阶段，功能可能不完整或不稳定
65+ 
97## 版本说明66## 版本说明
67+ 
98通常，RecSDK一年会有4个正式release版本。68通常，RecSDK一年会有4个正式release版本。
99 69 
100具体版本更新内容，参见：70具体版本更新内容，参见：
@@ -104,6 +74,7 @@ mxrec/ # 项目根目录
104## 环境部署74## 环境部署
105 75 
106支持的产品型号如下：76支持的产品型号如下：
77+ 
107* Atlas 200T A2 Box1678* Atlas 200T A2 Box16
108* Atlas 800T A2 训练服务器79* Atlas 800T A2 训练服务器
109* Atlas 900 A3 SuperPoD 超节点80* Atlas 900 A3 SuperPoD 超节点
@@ -124,7 +95,6 @@ mxrec/ # 项目根目录
124* [torch_rec_v1](./docs/zh/torch/torch_rec_v1/recsdk_torch_installation_guide.md#源码编译安装)95* [torch_rec_v1](./docs/zh/torch/torch_rec_v1/recsdk_torch_installation_guide.md#源码编译安装)
125* [torch_rec_v2](./docs/zh/torch/torch_rec_v2/recsdk_torch_installation_guide.md#源码编译安装)96* [torch_rec_v2](./docs/zh/torch/torch_rec_v2/recsdk_torch_installation_guide.md#源码编译安装)
126 97 
127- 
128## 快速入门98## 快速入门
129 99 
130参见具体组件：100参见具体组件：
@@ -152,6 +122,25 @@ mxrec/ # 项目根目录
152* [torch_rec_v1](./docs/zh/torch/torch_rec_v1/api)122* [torch_rec_v1](./docs/zh/torch/torch_rec_v1/api)
153* [torch_rec_v2](./docs/zh/torch/torch_rec_v2/api)123* [torch_rec_v2](./docs/zh/torch/torch_rec_v2/api)
154 124 
125+## 模式适配样例
126+ 
127+| 模型名称 | 适配框架 | 组件名称 | 说明 |
128+|---------|---------|---------|------|
129+| DIN | PyTorch | torch_rec_v1 | [代码链接](https://gitcode.com/Ascend/RecSDK/tree/develop_torch_benchmark/torch2.6.0_examples_benchmark/develop/din) |
130+| DLRM(DCNv2) | PyTorch | torch_rec_v1 | [代码链接](https://gitcode.com/Ascend/RecSDK/tree/develop_torch_benchmark/torch2.6.0_examples_benchmark/develop/dlrm) |
131+| GR | PyTorch | torch_rec_v1 | Facebook GR模型，[代码链接](https://gitcode.com/Ascend/RecSDK/tree/develop_torch_benchmark/torch2.6.0_examples_benchmark/develop/gr/gr_meta) |
132+| GR | PyTorch | torch_rec_v1 | NVIDIA recsys-GR模型，[代码链接](https://gitcode.com/Ascend/RecSDK/tree/develop_torch_benchmark/torch2.6.0_examples_benchmark/develop/gr_nv) |
133+| mmoe、eta | PyTorch | torch_rec_v1 | [代码链接](https://gitcode.com/Ascend/RecSDK/blob/develop_torch_benchmark/torch2.6.0_examples_benchmark/develop/model_zoo/README.md) |
134+| GR | PyTorch | torch_rec_v2 | NVIDIA recsys-GR模型，[代码链接](https://gitcode.com/Ascend/RecSDK/tree/develop_examples_and_tools/torch_rec_v2_examples/gr) |
135+ 
simmerchan
simmerchansimmerchan3月19日

问题类型: 编码规范

问题描述: README.md 中"模式适配样例"表格的 GR 模型两行说明列格式不统一，一行使用 <br> 换行另一行没有。

文件路径: README.md

代码行号: 131

修改建议: 统一表格中多行内容的格式，建议都使用 <br> 换行或添加额外列区分不同实现。

likedislike
P
penghuiyang
3月28日 评论：
136+## 分支维护策略
137+ 
138+| 分支名 | 描述 | 维护状态 |
139+|---------|---------|---------|
140+| develop | 主开发分支 | 长期维护 |
141+| develop_examples_and_tools | demo，模型样例，模型相关工具 | 活跃维护 |
142+| develop_torch_benchmark | benchmark模型适配 | 活跃维护 |
143+ 
155## FAQ144## FAQ
156 145 
157参见具体组件：146参见具体组件：
@@ -165,7 +154,7 @@ mxrec/ # 项目根目录
165贡献代码前，请先签署[开放项目贡献者许可协议（CLA）](https://clasign.osinfra.cn/sign/gitee_ascend-1611222220829317930)。154贡献代码前，请先签署[开放项目贡献者许可协议（CLA）](https://clasign.osinfra.cn/sign/gitee_ascend-1611222220829317930)。
166 155 
1671. 如果您遇到bug，请[提交issue](https://gitcode.com/Ascend/RecSDK/issues)。1561. 如果您遇到bug，请[提交issue](https://gitcode.com/Ascend/RecSDK/issues)。
168-2. 如果您计划贡献bug-fixes，请提交Pull Requests，参见[具体要求](./contributing.md#PullRequest)。157+2. 如果您计划贡献bug-fixes，请提交Pull Requests，参见[具体要求](./contributing.md#pullrequest)。
1693. 如果您计划贡献新特性、功能，请先创建issue与我们讨论。写明需求背景/目的，如何设计，对现有API等的影响。未经讨论提交PR可能会导致请求被拒绝，因为项目演进方向可能与您的想法存在偏差。1583. 如果您计划贡献新特性、功能，请先创建issue与我们讨论。写明需求背景/目的，如何设计，对现有API等的影响。未经讨论提交PR可能会导致请求被拒绝，因为项目演进方向可能与您的想法存在偏差。
170 159 
171## 联系我们160## 联系我们
@@ -197,6 +186,7 @@ Rec SDK docs目录下的文档适用CC-BY 4.0许可证，具体请参见[LICENSE
197## 致谢186## 致谢
198 187 
199Rec SDK由华为公司的下列部门联合贡献：188Rec SDK由华为公司的下列部门联合贡献：
189+ 
200* 昇腾计算应用使能开发部190* 昇腾计算应用使能开发部
201* 计算软件平台部191* 计算软件平台部
202* 灵衢算力集群开发部192* 灵衢算力集群开发部
@@ -204,4 +194,3 @@ Rec SDK由华为公司的下列部门联合贡献：
204* 泊松实验室194* 泊松实验室
205 195 
206感谢来自社区的每一个PR，欢迎贡献Rec SDK！196感谢来自社区的每一个PR，欢迎贡献Rec SDK！
207- 
Mdocs/zh/torch/torch_rec_v1/api/README.md+11-9
@@ -1,9 +1,11 @@
1-- [接口说明](api_description.md)1+# API列表
2-- [创表接口](table_creation_apis.md)2+ 
3-- [数据接口](data_apis.md)3+- [接口说明](api_description.md)
4-- [优化器接口](optimizers_apis.md)4+- [创表接口](table_creation_apis.md)
5-- [分表接口](subtable_apis.md)5+- [数据接口](data_apis.md)
6-- [pipeline接口](pipeline_apis.md)6+- [优化器接口](optimizers_apis.md)
7-- [多级缓存管理接口](multilevel_cache_management_apis.md)7+- [分表接口](subtable_apis.md)
8-- [准入淘汰管理接口](access_and_elimination_management_apis.md)8+- [pipeline接口](pipeline_apis.md)
9-- [自定义算子](specialized_operator.md)9+- [多级缓存管理接口](multilevel_cache_management_apis.md)
10+- [准入淘汰管理接口](access_and_elimination_management_apis.md)
11+- [自定义算子](specialized_operator.md)
Mdocs/zh/torch/torch_rec_v1/migration_and_training.md+282-4
@@ -20,10 +20,9 @@
20|get_default_sharders|get_default_hybrid_sharders|获取分表器|20|get_default_sharders|get_default_hybrid_sharders|获取分表器|
21|TrainPipelineSparseDist|HybridTrainPipelineSparseDist|查询稀疏表|21|TrainPipelineSparseDist|HybridTrainPipelineSparseDist|查询稀疏表|
22 22 
23- 
24接口示例：23接口示例：
25 24 
26-- TorchRec示例：25+- TorchRec示例：
27 26 
28 ```python27 ```python
29 import torch.distributed as dist28 import torch.distributed as dist
@@ -64,7 +63,7 @@
64 output = pipeline.progress(batched_iterator)63 output = pipeline.progress(batched_iterator)
65 ```64 ```
66 65 
67-- Rec SDK Torch示例：66+- Rec SDK Torch示例：
68 67 
69 ```python68 ```python
70 import torch.distributed as dist69 import torch.distributed as dist
@@ -109,11 +108,290 @@
109 output = pipeline.progress(batched_iterator)108 output = pipeline.progress(batched_iterator)
110 ```109 ```
111 110 
112- 
113## Rec SDK Torch迁移样例<a name="ZH-CN_TOPIC_0000002336268713"></a>111## Rec SDK Torch迁移样例<a name="ZH-CN_TOPIC_0000002336268713"></a>
114 112 
115Rec SDK Torch支持Torch开源推荐模型迁移适配，迁移样例可以参考如下：113Rec SDK Torch支持Torch开源推荐模型迁移适配，迁移样例可以参考如下：
116 114 
117[Rec SDK Torch DCNv2迁移样例](https://gitcode.com/Ascend/RecSDK/blob/develop_torch_benchmark/torch2.6.0_examples_benchmark/develop/dlrm/README.md)。115[Rec SDK Torch DCNv2迁移样例](https://gitcode.com/Ascend/RecSDK/blob/develop_torch_benchmark/torch2.6.0_examples_benchmark/develop/dlrm/README.md)。
118 116 
117+## 功能特性介绍
119 118 
119+Rec SDK Torch 支持纯显存模式和多级缓存模式两种训练模式。
120+ 
121+纯显存模式指在训练时，所有稀疏表Embedding数据都存储在Device内存中。
122+ 
123+多级缓存模式指在训练时，会以Device Memory + DDR（Host Memory）结合的方式存储Embedding。
124+ 
125+本章节将介绍纯显存模式和多级缓存模式的相关功能特性和代码使用示例。
126+ 
127+> [!NOTE]说明
128+>
129+> 本文档中的**约束**章节内容仅介绍主要使用场景下的约束信息，详细信息请参见对应的API文档。
130+ 
131+### 基于纯显存模式训练
132+ 
133+**纯显存模式对比原生TorchRec框架的API差异**
134+ 
135+Rec SDK Torch纯显存模式在配置稀疏表、创建稀疏表、稀疏表分表、创建pipeline时使用的API接口对比原生TorchRec框架有差异。
136+ 
137+|场景/API|原生TorchRec框架|Rec SDK Torch纯显存模式|
138+|--|--|--|
139+|配置稀疏表|EmbeddingBagConfig|HashEmbeddingBagConfig|
140+|创建稀疏表|EmbeddingBagCollection|HashEmbeddingBagCollection|
141+|稀疏表分表器|get_default_sharders()|get_default_hybrid_sharders()|
142+|创建pipeline|TrainPipelineSparseDist|HybridTrainPipelineSparseDist|
143+ 
144+**约束**
145+ 
146+- 仅支持EBC模式。
147+- 支持pipeline模式和非pipeline模式（直接调用分片后的稀疏表前向）进行训练。
148+- 不支持保存/加载稀疏表数据。
149+ 
150+**纯显存模式测试用例**
151+ 
152+纯显存模式的完整测试用例请参见[README](../../../../training/torch_rec_v1/hybrid_torchrec/test/st/README.md)。
153+ 
154+#### 基础使用<a id="basic_usage_device_memory"></a>
155+ 
156+训练流程上和原生TorchRec框架pipeline模式相同，仅在创建稀疏表、稀疏表分表、创建pipeline时使用的API有差异。
157+ 
158+**代码示例**
159+ 
160+```python
161+import logging
162+import os
163+ 
164+import torch
165+import torch.distributed as dist
166+from torch.utils.data import DataLoader
167+import torchrec
168+from torchrec.optim.keyed import CombinedOptimizer, KeyedOptimizerWrapper
169+from torchrec.optim.optimizers import in_backward_optimizer_filter
170+from torchrec.distributed import DistributedModelParallel
171+from torchrec.distributed.types import ShardingEnv
172+from torchrec.optim.apply_optimizer_in_backward import apply_optimizer_in_backward
173+from torchrec.distributed.planner import (
174+ EmbeddingShardingPlanner,
175+ Topology,
176+ ParameterConstraints,
177+)
178+from torchrec.distributed.embeddingbag import EmbeddingBagCollectionAwaitable
179+from hybrid_torchrec import HashEmbeddingBagConfig, HashEmbeddingBagCollection
180+from hybrid_torchrec.distributed.hybrid_train_pipeline import HybridTrainPipelineSparseDist
181+from hybrid_torchrec.distributed.sharding_plan import get_default_hybrid_sharders
182+ 
183+from dataset import RandomRecDataset, Batch
184+ 
185+logging.getLogger().setLevel(logging.INFO)
186+ 
187+BATCH_NUM: int = 20
188+DENSE_OUTPUT_DIM: int = 2
189+ 
190+ 
191+class DenseModel(torch.nn.Module):
192+ def __init__(self, input_dim, output_dim):
193+ super().__init__()
194+ # 定义dense layer
195+ self.linear = torch.nn.Linear(input_dim, output_dim)
196+ 
197+ def forward(self, x):
198+ # 定义dense层实现
199+ return self.linear(x)
200+ 
201+ 
202+class TestModel(torch.nn.Module):
203+ 
204+ def __init__(self, sparse_model: torch.nn.Module, dense_model: torch.nn.Module, feat_names: list[str]):
205+ super().__init__()
206+ self.sparse_model: torch.nn.Module = sparse_model
207+ self.dense_model: torch.nn.Module = dense_model
208+ self.feat_names: list[str] = feat_names
209+ self.loss_fn: torch.nn.Module = torch.nn.CrossEntropyLoss()
210+ 
211+ def forward(self, batch: Batch):
212+ # sparse前向
213+ sparse_output: EmbeddingBagCollectionAwaitable = self.sparse_model(batch.sparse_features)
214+ feat_embeddings: list[torch.Tensor] = list()
215+ for feat_name in self.feat_names:
216+ feat_embeddings.append(sparse_output[feat_name]) # type: ignore
217+ # 合并所有稀疏特征的embedding
218+ embeddings: torch.Tensor = torch.concat(feat_embeddings, dim=-1)
219+ 
220+ # dense前向
221+ dense_output: torch.Tensor = self.dense_model(embeddings)
222+ 
223+ # 计算loss
224+ loss: torch.Tensor = self.loss_fn(dense_output, batch.labels)
225+ 
226+ # 自行定义output输出内容
227+ output: dict[str, torch.Tensor] = dict()
228+ output["sparse"] = embeddings
229+ output["dense"] = dense_output
230+ 
231+ # 返回前向输出
232+ # 注意：forward必须返回loss和output两个值，且loss在前，output在后；该用法为TorchRec原生TrainPipelineSparseDist用法
233+ return loss, output
234+ 
235+ 
236+def weight_init(param: torch.nn.Parameter):
237+ if len(param.shape) != 2:
238+ return
239+ torch.manual_seed(param.shape[1])
240+ result = torch.linspace(0, 1, steps=param.shape[1]).repeat(param.shape[0], 1)
241+ param.data.copy_(result)
242+ 
243+ 
244+def set_distribute_env():
245+ rank = int(os.environ.get("LOCAL_RANK", 0))
246+ torch.npu.set_device(rank) # type: ignore
247+ os.environ["MASTER_ADDR"] = "127.0.0.1"
248+ os.environ["MASTER_PORT"] = "6000"
249+ os.environ["GLOO_SOCKET_IFNAME"] = "lo"
250+ dist.init_process_group(backend="hccl")
251+ 
252+ 
253+def train():
254+ # 0.设置分布式环境
255+ set_distribute_env()
256+ rank = dist.get_rank()
257+ world_size = dist.get_world_size()
258+ npu_device = torch.device("npu")
259+ 
260+ embedding_dims: list[int] = [64, 16, 32]
261+ num_embeddings: list[int] = [400, 4000, 400]
262+ table_num: int = len(num_embeddings)
263+ 
264+ # 1.创建数据集
265+ 
266+ batch_size: int = 128
267+ dataset = RandomRecDataset(BATCH_NUM, batch_size, num_embeddings, table_num)
268+ data_loader = DataLoader(
269+ dataset,
270+ batch_size=None,
271+ batch_sampler=None,
272+ pin_memory=True,
273+ pin_memory_device="npu",
274+ num_workers=1,
275+ )
276+ 
277+ # 2.创建稀疏表
278+ embedding_configs: list[HashEmbeddingBagConfig] = []
279+ table_names: list[str] = [f"table{i}" for i in range(len(num_embeddings))]
280+ feat_names: list[str] = [f"feat{i}" for i in range(table_num)]
281+ for i in range(table_num):
282+ emb_config = HashEmbeddingBagConfig(
283+ name=table_names[i],
284+ embedding_dim=embedding_dims[i],
285+ num_embeddings=num_embeddings[i],
286+ feature_names=[feat_names[i]],
287+ pooling=torchrec.PoolingType.MEAN,
288+ init_fn=weight_init, # type: ignore
289+ )
290+ embedding_configs.append(emb_config)
291+ sparse_ebc: HashEmbeddingBagCollection = HashEmbeddingBagCollection(device="meta", tables=embedding_configs)
292+ 
293+ # 3.创建模型：将稀疏表和Dense部分包装到一个模型中
294+ dense_model: torch.nn.Module = DenseModel(sum(embedding_dims), DENSE_OUTPUT_DIM)
295+ test_model: torch.nn.Module = TestModel(sparse_ebc, dense_model, feat_names)
296+ 
297+ # 4.定义稀疏表优化器
298+ embedding_optimizer_class: type[torch.optim.Optimizer] = torch.optim.Adagrad
299+ optimizer_kwargs = {"lr": 0.01, "eps": 0.1}
300+ apply_optimizer_in_backward(
301+ embedding_optimizer_class,
302+ test_model.sparse_model.parameters(),
303+ optimizer_kwargs=optimizer_kwargs,
304+ )
305+ 
306+ # 5.稀疏表分表
307+ host_gp = dist.new_group(backend="gloo")
308+ host_env = ShardingEnv(world_size=world_size, rank=rank, pg=host_gp)
309+ sharders = get_default_hybrid_sharders(host_env=host_env)
310+ constraints = {
311+ # 分表方式为row_wise，compute_kernels使用fused
312+ table_name: ParameterConstraints(sharding_types=["row_wise"], compute_kernels=["fused"])
313+ for table_name in table_names
314+ }
315+ planner = EmbeddingShardingPlanner(
316+ topology=Topology(world_size=world_size, compute_device="npu"),
317+ constraints=constraints,
318+ )
319+ plan = planner.collective_plan(test_model, sharders, dist.GroupMember.WORLD)
320+ # 此处分表会根据sharders参数匹配对应class类型：EmbeddingBagCollection/HashEmbeddingBagCollection，
321+ # 只会对稀疏表参数进行分表，不会对dense参数分表
322+ ddp_model = DistributedModelParallel(test_model, device=npu_device, plan=plan, sharders=sharders)
323+ 
324+ # 6.整合优化器
325+ dense_optimizer = KeyedOptimizerWrapper(
326+ dict(in_backward_optimizer_filter(ddp_model.named_parameters())),
327+ lambda params: torch.optim.Adagrad(params, lr=0.1),
328+ )
329+ optimizer = CombinedOptimizer([ddp_model.fused_optimizer, dense_optimizer])
330+ 
331+ # 7.创建pipeline
332+ pipeline = HybridTrainPipelineSparseDist(
333+ ddp_model, optimizer, npu_device, return_loss=True, execute_all_batches=True
334+ )
335+ 
336+ # 8.使用pipeline进行训练
337+ dataset_iterator = iter(data_loader)
338+ for step in range(BATCH_NUM):
339+ # 前面创建pipeline时，设置了return_loss=True，所以pipeline.progress()会返回output和loss两个值
340+ # 若创建pipeline时设置return_loss=False，则仅返回output
341+ output, loss = pipeline.progress(dataset_iterator)
342+ logging.info("rank: %d, step: %s, loss: %s, sparse output: %s", rank, step, loss, output["sparse"])
343+ 
344+ 
345+if __name__ == "__main__":
346+ train()
347+ # 脚本使用方式：
348+ # 1.将脚本写入到main.py文件中，并拷贝RecSDK/training/torch_rec_v1/hybrid_torchrec/test/st/dataset.py到py文件同一目录
349+ # 2.启动单卡： WORLD_SIZE=1 RANK=0 python3 main.py
350+ # 3.启动多卡（2卡）： torchrun --rdzv-backend=c10d --rdzv-endpoint=localhost:6000 --nnodes=1 --nproc-per-node=2 main.py
351+```
352+ 
353+更多demo样例请参见[Rec SDK Torch Little Demo样例](https://gitcode.com/Ascend/RecSDK/tree/develop_examples_and_tools/torch_examples/little_demo)。
354+ 
355+#### 稀疏表数据并行（DP）
356+ 
357+**约束**
358+ 
359+- DP模式仅支持单个稀疏表。
360+ 
361+**对比非DP模式**
362+ 
363+DP模式对比[非DP模式（基础使用）](#basic_usage_device_memory)，主要区别在于训练时稀疏表参数存储方式不同。
364+ 
365+DP模式下，稀疏表将不再切分到不同的Device，而是每个Device都持有完整的稀疏表参数。在反向传播时会聚合所有Device的梯度再统一更新。
366+ 
367+**代码示例**
368+ 
369+DP模式完整代码示例请参见[DP模式测试用例](../../../../training/torch_rec_v1/hybrid_torchrec/test/st/test_hybrid_hash_embeddingbag_dp.py)。
370+ 
371+简化代码示例（仅展示和基础使用模式差异部分）：
372+ 
373+```python
374+ # 差异点：DP模式仅支持单表，不支持多表模式。
375+ embedding_dims = [64]
376+ num_embeddings = [400]
377+ 
378+ ...
379+ 
380+ # 5.稀疏表分表
381+ host_gp = dist.new_group(backend="gloo")
382+ host_env = ShardingEnv(world_size=world_size, rank=rank, pg=host_gp)
383+ sharders = get_default_hybrid_sharders(host_env=host_env)
384+ constraints = {
385+ # 差异点：分表方式为data_parallel，compute_kernels使用dense
386+ table_name: ParameterConstraints(sharding_types=["data_parallel"], compute_kernels=["dense"])
387+ for table_name in table_names
388+ }
389+ planner = EmbeddingShardingPlanner(
390+ topology=Topology(world_size=world_size, compute_device="npu"),
391+ constraints=constraints,
392+ )
393+ plan = planner.collective_plan(test_model, sharders, dist.GroupMember.WORLD)
394+ dmp_model = DistributedModelParallel(test_model, device=npu_device, plan=plan, sharders=sharders)
395+ 
396+ ...
397+```
Mdocs/zh/torch/torch_rec_v1/recsdk_torch_installation_guide.md+259-217
@@ -2,263 +2,321 @@
2 2 
3## 安装说明<a name="ZH-CN_TOPIC_0000002302229632"></a>3## 安装说明<a name="ZH-CN_TOPIC_0000002302229632"></a>
4 4 
5-推荐Rec SDK Torch基于容器部署开发环境。如果需要查看Rec SDK Torch的历史安装记录，请参见[查看Rec SDK Torch安装与卸载记录](../../torch/torch_rec_v1/common_operations.md)。5+### 配套版本<a name="section146113514599"></a>
6 6 
7-## 安装依赖<a id="ZH-CN_TOPIC_0000002302389236"></a>7+当前Rec SDK Torch支持两种配套版本，后续安装时请安装对应配套版本的软件包。
8 8 
9-安装Rec SDK Torch软件包前需准备以下环境依赖及操作，请参见[表1](#table18461141184116)准备安装环境。9+| 配套版本 | Python | PyTorch | torch_npu | fbgemm_gpu | Rec SDK Torch |
10+| -------- | ------- | ------- | --------- | ---------- | ------------- |
11+| 方案一 | 3.11+ | 2.6.0 | 2.6.0 | 1.1.0+cpu | 1.1.0 |
12+| 方案二 | 3.11+ | 2.7.1 | 2.7.1 | 1.2.0+cpu | 1.2.0 |
10 13 
11-**表 1** Rec SDK Torch环境依赖14+> [!NOTE]说明
12-<a id="table18461141184116"></a>15+>
16+> - PyTorch：深度学习训练框架，相关资料请参见[PyTorch文档](https://docs.pytorch.org/docs/stable/index.html)。
17+> - torch_npu：PyTorch框架适配NPU设备的扩展插件，相关资料请参见[torch_npu](https://gitcode.com/Ascend/pytorch)。
18+> - fbgemm_gpu：TorchRec框架依赖的加速库，相关资料请参见[fbgemm_gpu](https://github.com/pytorch/FBGEMM)。
13 19 
14-| 依赖名称/操作 | 推荐版本 | 说明/获取方式 |20+### 依赖软件说明
21+ 
22+本章节为提前声明依赖软件列表和安装方式，请参见后续[安装Rec SDK Torch](#section182972951211)章节并按需安装。
23+ 
24+**依赖关系介绍**
25+ 
26+各层级软件依赖关系如下表，安装依赖软件时请按照从下到上的顺序进行安装。
27+ 
28+| 层级 | 组件名称 | 依赖项 | 说明 |
29+|------|----------|--------|------|
30+| **应用层** | Rec SDK Torch | hybrid_torchrec、torchrec_embcache | Rec SDK Torch组件 |
31+| **自定义算子层** | 自定义算子相关包 | Ascend-recsdk-npu-ops-*、libfbgemm_npu_api.so | 自定义算子实现 |
32+| **适配层** | Torchrec框架适配NPU | torchrec_npu | TorchRec的适配NPU版本 |
33+| **依赖层** | Torchrec依赖 | fbgemm_gpu | TorchRec依赖的底层加速库 |
34+| **框架层** | 训练框架 | PyTorch、torch_npu | 深度学习训练框架 |
35+| **使能层** | NPU使能 | CANN | 提供NPU底层支持 |
36+| **宿主机层** | 宿主机依赖 | NPU固件、驱动、Device配置 | 硬件层面的基础依赖 |
37+ 
38+#### 宿主机依赖
39+ 
40+Rec SDK Torch基于NPU环境运行，如下为宿主机依赖软件说明。若宿主机未安装相关软件，请根据说明安装。
41+ 
42+| 依赖名称/操作 | 推荐版本 | 获取方式/安装说明 |
15|-----------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|43|-----------------------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
16-| 昇腾硬件产品驱动和固件 | Ascend HDK 25.5.0 | 宿主机依赖，请在宿主机环境安装。<br>单击[获取链接](https://www.hiascend.com/developer/download/commercial/result?module=cann)，在左侧配套资源的“编辑资源选择”中进行配置，筛选配套的软件包，确认版本信息后获取所需软件包。<br>安装驱动与固件请参见相关硬件产品配套的《[驱动和固件安装升级指南](https://support.huawei.com/enterprise/zh/ascend-computing/ascend-hdk-pid-252764743)》。 |44+| 昇腾硬件产品驱动和固件 | Ascend HDK 25.5.0 | 单击[获取链接](https://www.hiascend.com/developer/download/commercial/result?module=cann)，在左侧配套资源的“编辑资源选择”中进行配置，筛选配套的软件包，确认版本信息后获取所需软件包。<br>安装驱动与固件请参见相关硬件产品配套的《[驱动和固件安装升级指南](https://support.huawei.com/enterprise/zh/ascend-computing/ascend-hdk-pid-252764743)》。 |
17-| Ascend Docker Runtime | MindCluster 7.3.0 | 宿主机依赖，请在宿主机环境安装。若宿主机未安装Docker，请参见[Docker社区或官网](https://docs.docker.com/engine/install/)先安装Docker。<br>请参见《MindCluster 集群调度用户指南》的“安装 > [安装部署](https://www.hiascend.com/document/detail/zh/mindcluster/730/clustersched/dlug/dlug_installation_009.html)”章节进行Ascend Docker Runtime软件包安装。 |45+| Ascend Docker Runtime | MindCluster 7.3.0 | 若宿主机未安装Docker，请参见[Docker社区或官网](https://docs.docker.com/engine/install/)先安装Docker。<br>请参见《MindCluster 集群调度用户指南》的“安装 > [安装部署](https://www.hiascend.com/document/detail/zh/mindcluster/730/clustersched/dlug/dlug_installation_009.html)”章节下载和安装`Ascend Docker Runtime`软件包。 |
18-| 配置Device网卡 | - | 宿主机依赖，请在宿主机环境操作。<br>请参考《Ascend Training Solution 23.0.0 组网指南 01》的“参数面网络配置示例->配置示例->[配置训练节点](https://support.huawei.com/enterprise/zh/doc/EDOC1100349028/f48f446c)”章节，通过HCCN_Tool配置NPU网口的Device IP。 |46+| 配置Device网卡 | - | 宿主机依赖，请在宿主机环境操作。<br>请参见《Ascend Training Solution 23.0.0 组网指南 01》的“参数面网络配置示例->配置示例->[配置训练节点](https://support.huawei.com/enterprise/zh/doc/EDOC1100349028/f48f446c)”章节，通过HCCN_Tool配置NPU网口的Device IP相关信息。 |
19-| CANN软件包 | CANN 8.5.0 | 容器内依赖，请在[启动容器](#section12808621121114)后安装。<br>单击[获取链接](https://www.hiascend.com/developer/download/commercial/result?module=cann)，在左侧配套资源的“编辑资源选择”中进行配置，筛选配套的软件包，确认版本信息后获取所需软件包。<br>根据设备架构获取`Ascend-cann-toolkit_{version}_linux-{arch}.run`和`Ascend-cann-{chip_type}-ops-{version}_linux-{arch}.run`，并参考《CANN 软件安装指南》的“[安装CANN](https://www.hiascend.com/document/detail/zh/canncommercial/850/softwareinst/instg/instg_0008.html?Mode=PmIns&InstallType=local&OS=Debian&Software=cannToolKit)”章节在容器内进行安装。 |
20-| PyTorch昇腾适配插件 | 2.6.0/2.7.1 | 容器内依赖，请在[启动容器](#section12808621121114)后安装。<br>根据[配套版本](#section146113514599)，可通过下述方式安装对应版本插件。<li>单击[获取链接](https://gitcode.com/Ascend/pytorch/releases/v7.1.0.2-pytorch2.6.0)，根据设备架构获取torch_npu-2.6.0*-cp311-\*.whl软件包并在容器内安装。</li><li>单击[获取链接](https://gitcode.com/Ascend/pytorch/releases/v7.2.0-pytorch2.7.1)，根据设备架构获取torch_npu-2.7.1*-cp311-*.whl软件包并在容器内安装。</li> |
21 47 
22->[!NOTE] 说明 48+#### 容器内训练框架依赖
23-> 对于用户集成的开源和第三方软件，漏洞和问题请自行跟踪社区并及时进行修复；可以并且不限于通过[CVE（通用漏洞字典）官网](https://www.cve.org/)确认对应开源软件版本的已知漏洞，并通过版本升级、使用patch补丁包更新等方式修复。
24 49 
50+| 依赖名称/操作 | 推荐版本 | 获取方式/安装说明 |
51+| ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
52+| CANN软件包 | CANN 8.5.0 | 容器内依赖，若容器内未安装，请在容器内安装。<br>单击[获取链接](https://www.hiascend.com/developer/download/commercial/result?module=cann)，在左侧配套资源的“编辑资源选择”中进行配置，筛选配套的软件包，确认版本信息后获取所需软件包。<br>根据设备架构获取`Ascend-cann-toolkit_{version}_linux-{arch}.run`和`Ascend-cann-{chip_type}-ops-{version}_linux-{arch}.run`。<br>请参见《CANN 软件安装指南》的“[安装CANN](https://www.hiascend.com/document/detail/zh/canncommercial/850/softwareinst/instg/instg_0008.html?Mode=PmIns&InstallType=local&OS=Debian&Software=cannToolKit)”章节在容器内进行安装。<br>如需卸载，请参考上述安装CANN资料中的“卸载-卸载CANN”章节。 |
53+| PyTorch和torch_npu | 2.6.0/2.7.1 | 容器内依赖，若容器内未安装，请在容器内安装。<br>根据[配套版本](#section146113514599)，请参见[安装PyTorch和PyTorch昇腾适配插件](https://gitcode.com/Ascend/pytorch/blob/v2.7.1/docs/zh/installation_guide/installation_via_binary_package.md)章节分别安装PyTorch框架和torch_npu插件安装。<br>请根据PyTorch版本、Python版本、设备架构选择对应的安装指令，Python版本建议使用Python 3.11。<br>如需卸载，可通过`pip3 uninstall -y torch_npu torch`指令进行卸载。|
25 54 
26-## 获取Rec SDK Torch软件包<a name="ZH-CN_TOPIC_0000002336148981"></a>55+#### 容器内训练加速库依赖<a name="section146113514600"></a>
27 56 
28-### 源码编译安装57+原生TorchRec框架依赖fbgemm_gpu库。基于NPU环境运行时，需安装fbgemm_gpu库的CPU版本。
29 58 
30-源码编译前，请参考[CANN 软件安装指南](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/900beta1/softwareinst/instg/instg_0000.html?Mode=PmIns&InstallType=local&OS=Ubuntu)安装CANN开发套件软件包；参考[Ascend Extension for PyTorch安装指南](https://www.hiascend.com/document/detail/zh/Pytorch/730/configandinstg/instg/docs/zh/installation_guide/installation_via_binary_package.md)安装PyTorch适配昇腾的框架插件包。 59+由于其CPU版本无法通过requirements依赖安装，因此需手动安装并在安装时指定安装源。
31- 60+ 
32-需要编译的源码包：61+根据[配套版本](#section146113514599)，安装对应版本的fbgemm_gpu软件包。
62+ 
63+| 软件版本 | 安装指令 |
64+| -------- | ------------------ |
65+| 1.1.0+cpu | `pip3 install fbgemm_gpu==1.1.0+cpu -i https://download.pytorch.org/whl/cpu` |
66+| 1.2.0+cpu | `pip3 install fbgemm_gpu==1.2.0+cpu -i https://download.pytorch.org/whl/cpu` |
67+ 
68+### Rec SDK Torch软件包说明
69+ 
70+Rec SDK Torch软件包如下表：
33 71 
34| 名称 | 说明 |72| 名称 | 说明 |
35|-------------------------------------------|----------------------|73|-------------------------------------------|----------------------|
36-| Ascend-mindxsdk-torchrec-\*-npu-\*.tar.gz | TorchRec昇腾适配包 |74+| Ascend-mindxsdk-torchrec-\*-npu-\*.tar.gz | TorchRec昇腾注册包 |
37-| Ascend-mindxsdk-hybrid-torchrec-*.tar.gz | Rec SDK Torch推荐算法框架包 |75+| Ascend-mindxsdk-hybrid-torchrec-*.tar.gz | Rec SDK Torch推荐算法框架包（包含hybrid_torchrec和 torchrec_embcache） |
38| Ascend-recsdk-npu-ops-\*-linux-\*.tar.gz | 自定义算子包 |76| Ascend-recsdk-npu-ops-\*-linux-\*.tar.gz | 自定义算子包 |
39| libfbgemm_npu_api.so | 自定义算子PyTorch框架适配层 |77| libfbgemm_npu_api.so | 自定义算子PyTorch框架适配层 |
40 78 
41-1. 编译环境79+## 安装Rec SDK Torch<a id="section182972951211"></a>
42-
43- 容器环境编译，参考[README](../build_torch_rec_images/README.md)。
44-
45-2. 编译Ascend-mindxsdk-torchrec-\*-npu-*.tar.gz
46-
47- 参考[README](../../../../training/torch_rec_v1/torchrec_npu/README.md)。
48-
49- 生成的tar包在 `RecSDK/training/torch_rec_v1/torchrec_npu/torchrec/` 路径下。
50-
51- **安装方法**
52-
53- ```shell
54- tar zxvf Ascend-mindxsdk-torchrec-*-npu-*.tar.gz
55- pip3 install torchrec-*+npu-py3-none-linux_*.whl
56- ```
57-
58-3. 编译Ascend-mindxsdk-hybrid-torchrec-*.tar.gz
59-
60- 参考对应[README](../../../../training/torch_rec_v1/hybrid_torchrec/README.md)。
61-
62- 生成的tar包在 `RecSDK/training/torch_rec_v1/hybrid_torchrec/` 路径下。
63-
64- **安装方法**
65-
66- ```shell
67- tar zxvf Ascend-mindxsdk-hybrid-torchrec-*.tar.gz
68- pip3 install hybrid_torchrec-*-py3-none-linux_*.whl
69- pip3 install torchrec_embcache-*-py3-none-linux_*.whl
70- ```
71-
72-4. 编译Ascend-recsdk-npu-ops-\*-linux-\*.tar.gz
73-
74- 参考对应[README](../../../../cust_op/ascendc_op/build/README.md)。
75-
76-5. 编译libfbgemm_npu_api.so
77-
78- ```shell
79- cd RecSDK/cust_op/framework/torch_plugin/torch_library/common/
80- bash build_ops.sh
81- ```
82-
83- 生成的so包在 `RecSDK/cust_op/framework/torch_plugin/torch_library/common/build` 路径下。
84-
85- **安装方法**
86-
87- 编译完成后，会在common/build下生成so，并自动拷贝到python默认site-packages路径下。
88-
89- hybrid_torchrec 软件包会自动加载python默认site-packages路径下libfbgemm_npu_api.so。
90 80 
81+可通过如下三种方案安装Rec SDK Torch软件包：
91 82 
92-**配套版本<a name="section146113514599"></a>**83+- 方案一：基于容器安装（宿主机+容器）
84+ - 基于宿主机配置、镜像制作，并在容器内安装Rec SDK Torch软件包。介绍宿主机环境配置、基础容器镜像制作、运行容器和安装Rec SDK Torch软件包的完整操作说明。
85+ - **推荐使用该方案**。
86+- 方案二：源码编译安装
87+ - 基于**容器内**安装Rec SDK Torch软件包，默认已配置完成宿主机环境并进入Docker容器内。介绍如何通过源码编译的方式安装Rec SDK Torch软件包。
88+ - 若使用的Docker容器镜像不是参考[基础镜像构建](../build_torch_rec_images/README.md)制作，**可能存在cmake、glibc等基础软件版本不兼容**的情况，需自行处理。
89+- 方案三：基于Release版本+源码编译安装
90+ - 基于**容器内**安装Rec SDK Torch软件包，默认已配置完成宿主机环境并进入Docker容器内，介绍如何通过下载Release版本的二进制包+部分源码编译的方式安装Rec SDK Torch软件包。
91+ - 若使用的Docker容器镜像不是参考[基础镜像构建](../build_torch_rec_images/README.md)制作，**可能存在cmake、glibc等基础软件版本不兼容**的情况，需自行处理。
93 92 
94-当前Rec SDK Torch支持两种配套版本，可根据需要获取对应配套版本包。93+如需查看Rec SDK Torch软件包的历史安装记录，请参见[查看Rec SDK Torch安装与卸载记录](../../torch/torch_rec_v1/common_operations.md)。
95 94 
96-|配套版本|PyTorch|PyTorch昇腾适配插件|Rec SDK Torch|95+>[!NOTE] 说明
97-|--|--|--|--|96+> 对于用户集成的开源和第三方软件，漏洞和问题请自行跟踪社区并及时进行修复；可以并且不限于通过[CVE（通用漏洞字典）官网](https://www.cve.org/)确认对应开源软件版本的已知漏洞，并通过版本升级、使用patch补丁包更新等方式修复。
98-|方案一|2.6.0|2.6.0|1.1.0|97+
99-|方案二|2.7.1|2.7.1|1.2.0|98+### 基于容器安装（宿主机+容器）<a id="ZH-CN_TOPIC_0000002302389237"></a>
100 99 
100+#### 简要步骤说明
101 101 
102-其他软件配套版本信息请参考[基础镜像构建](../build_torch_rec_images/README.md)。102+1. 配置宿主机环境。
103+2. 构建基础镜像。
104+3. 启动Docker容器。
105+4. 安装Rec SDK Torch。
103 106 
104-**下载软件包<a name="section1852417242717"></a>**107+#### 操作流程图
105 108 
106-请参考本章获取所需软件包和对应的数字签名文件，下载本软件即表示您同意[华为企业业务最终用户许可协议（EULA）](https://e.huawei.com/cn/about/eula)的条款和条件。109+基于容器部署Rec SDK Torch，操作流程图请参见[图1](#fig1345216415476)。
107 110 
108-| 组件名称 | 软件包 | 获取链接 |111+**图 1** 配置容器内的开发环境及训练镜像构建<a id="fig1345216415476"></a>
109-|----------------------|------------------------------------------|----------------------------------------------------|
110-| Rec SDK Torch推荐算法框架包 | Ascend-mindxsdk-hybrid-torchrec-*.tar.gz | [获取链接](https://gitcode.com/Ascend/RecSDK/releases) |
111 112 
112->[!NOTE]说明
113->当前提供的Rec SDK推荐算法框架包基于Python 3.11版本编译，请在相同的Python版本环境下安装使用。若需在其他Python版本环境下安装使用，请参见[README](https://gitcode.com/Ascend/RecSDK/blob/develop/training/torch_rec_v1/hybrid_torchrec/README.md)进行源码编译。
114- 
115-**软件包Hash值验证<a name="section10830205518487"></a>**
116- 
117-为了防止软件包在传递过程中或存储期间被恶意篡改，请在软件包下载之后使用`sha256sum`命令校验Hash值是否和软件包下载页的Hash值一致。
118- 
119-## 部署容器内的开发环境<a name="ZH-CN_TOPIC_0000002336148877"></a>
120- 
121-### 使用容器部署开发环境<a name="ZH-CN_TOPIC_0000002302229684"></a>
122- 
123-基于容器部署Rec SDK Torch开发环境，可参考如[图1](#fig1345216415476)完成配置。
124- 
125-**图 1** 配置容器内的开发环境及训练镜像构建<a id="fig1345216415476"></a>
126![](../../figures/torch_rec_v1/配置容器内的开发环境及训练镜像构建.png "配置容器内的开发环境及训练镜像构建")113![](../../figures/torch_rec_v1/配置容器内的开发环境及训练镜像构建.png "配置容器内的开发环境及训练镜像构建")
127 114 
128-**关键步骤说明<a name="section15488921175211"></a>**115+#### 详细操作步骤
129 116 
130-1. 准备宿主机环境。请参见[安装依赖](#安装依赖)完成宿主机环境的部署。117+1. 宿主机环境配置
131-2. 构建基础镜像，请参见[基础镜像构建](../build_torch_rec_images/README.md)。118+
132-3. 启动容器，请参见[启动容器](#section12808621121114)。119+ 请参见[宿主机依赖](#宿主机依赖)章节完成宿主机环境配置。
133-4. 安装Rec SDK Torch，请参见[安装Rec SDK Torch](#section182972951211)。
134 120 
121+2. 制作基础训练镜像<a id="section104919392501"></a>
122+
123+ 请参见[基础镜像构建](../build_torch_rec_images/README.md)里的Dockerfile和README制作镜像。
124+
125+ 制作基础镜像时，会同时安装[容器内训练框架依赖](#容器内训练框架依赖)和[容器内训练加速库依赖](#容器内训练加速库依赖)中的依赖软件（CANN、PyTorch、torch_npu、fbgemm_gpu）。后续安装Rec SDK Torch时可跳过`依赖软件安装`步骤。
135 126 
136-### 制作Rec SDK Torch训练镜像<a name="ZH-CN_TOPIC_0000002336268705"></a>127+3. 运行容器<a id="ZH-CN_TOPIC_0000002302389300"></a>
128+
129+ 创建启动脚本run_docker.sh，参考如下：
137 130 
138-#### 制作基础训练镜像<a id="section104919392501"></a>131+ ```bash
132+ #!/bin/bash
133+ container_name=$1
134+ image_name=$2
135+ docker run \
136+ -it \
137+ --name ${container_name} \
138+ --shm-size="300g" \
139+ -m 300g \
140+ -v /etc/localtime:/etc/localtime:ro \
141+ -e ASCEND_VISIBLE_DEVICES=0-7 \
142+ -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
143+ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
144+ ${image_name} \
145+ /bin/bash
146+ ```
139 147 
140-请参见[基础镜像构建](../build_torch_rec_images/README.md)里的Dockerfile和README制作镜像。148+ >[!NOTE]说明
149+ >部分参数含义：
150+ >- -m 300g 表示设置容器内可以使用的内存大小上限为300G，可根据实际情况进行配置。
151+ >- -e ASCEND\_VISIBLE\_DEVICES=0-7 表示将服务器上编号为device0~device7的NPU设备挂载到容器内，可根据实际情况进行配置。
141 152 
142-#### 启动容器<a id="section12808621121114"></a>153+ 执行如下命令新建容器并进入容器内：
143 154 
144-创建启动脚本run_docker.sh，参考如下：155+ ```shell
156+ bash run_docker.sh 容器名 镜像名称:镜像版本
157+ ```
145 158 
146-```bash159+ > [!NOTE]说明
147-#!/bin/bash160+ > 1. 上述指令中Docker容器为前台运行，退出交互后容器将停止。更多Docker容器使用请参见[Docker社区文档](https://docs.docker.com/)。
148-container_name=$1161+ > 2. 如需更新容器内依赖软件版本，请参见[容器内训练框架依赖](#容器内训练框架依赖)和[容器内训练加速库依赖](#容器内训练加速库依赖)中的说明，卸载依赖软件后重新安装。
149-image_name=$2
150-docker run \
151--it \
152---name ${container_name} \
153---shm-size="300g" \
154--m 300g \
155--v /etc/localtime:/etc/localtime:ro \
156--e ASCEND_VISIBLE_DEVICES=0-7 \
157--v /etc/ascend_install.info:/etc/ascend_install.info:ro \
158--v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
159-${image_name} \
160-/bin/bash
161-```
162 162 
163->[!NOTE]说明 163+4. 安装Rec SDK Torch软件包
164->部分参数说明如下：164+
165->- -m 300g 表示设置容器内可以使用的内存大小上限为300G，可根据实际情况进行配置。165+ 安装Rec SDK Torch可参考后文中[源码编译安装](#源码编译安装)或者[基于Release版本+源码编译安装](#基于release版本源码编译安装)章节，并可跳过其中的`依赖软件安装`步骤（制作基础镜像时已安装容器内的相关依赖）。
166->- -e ASCEND\_VISIBLE\_DEVICES=0-7 表示将服务器上编号为device0-device7的NPU设备挂载到容器内。可根据实际情况进行配置。
167 166 
168-执行如下命令新建容器并进入容器内：167+### 源码编译安装
169 168 
170-```shell169+该方案默认已配置完成宿主机环境并进入Docker容器内。
171-bash run_docker.sh 容器名 {镜像名称}:{版本名称}
172-```
173 170 
174-> [!NOTE]说明 171+1. 依赖软件安装
175-> 1. 上述指令中Docker容器为前台运行，退出交互后容器将停止。更多Docker容器使用请参见[Docker社区文档](https://docs.docker.com/)。
176-> 2. 如需更新容器内的CANN和PyTorch版本，可在进入容器后进行安装，请参见[安装依赖](#ZH-CN_TOPIC_0000002302389236)中的容器内依赖安装。
177 172 
178-#### 安装Rec SDK Torch<a id="section182972951211"></a>173+ 请参见[容器内训练框架依赖](#容器内训练框架依赖)和[容器内训练加速库依赖](#容器内训练加速库依赖)完成容器内的依赖软件安装。
179 174 
180-1. 请参见[获取Rec SDK Torch软件包](#获取rec-sdk-torch软件包)获取Rec SDK Torch软件包。175+2. 安装TorchRec昇腾注册包
181-2. 将软件包拷贝到容器中。可通过以下方式：176+
182- - 在启动容器时，指定一个宿主机目录挂载到容器内，并将下载的软件包放在其中，使容器可以访问到下载的软件包。177+ TorchRec昇腾注册包是基于TorchRec源码做的NPU设备适配。可通过Rec SDK Torch提供的patch文件和TorchRec源码的固定分支编译出该注册包。
178+
179+ 请参见[README](https://gitcode.com/Ascend/RecSDK/blob/develop/training/torch_rec_v1/torchrec_npu/README.md)进行源码编译和安装。
183 180 
184- 宿主机目录挂载到容器的docker参数示例：181+3. 安装Rec SDK Torch推荐算法框架包<a id="source_build_hybrid_torchrec"></a>
182+
183+ 请参见如下指令进行编译安装：
185 184 
186- ```bash185+ ```bash
187- -v /dir1:/dir1186+ git clone https://gitcode.com/ascend/RecSDK.git
188- ```187+ cd RecSDK/training/torch_rec_v1/hybrid_torchrec
188+ bash build_whl.sh
189+ cd dist
190+ pip3 uninstall -y hybrid_torchrec
191+ pip3 install hybrid_torchrec-*.whl
192+ pip3 install -r requirements.txt
193+ pip3 uninstall -y torchrec_embcache
194+ pip3 install torchrec_embcache-*-py3-none-linux*.whl
195+ ```
189 196 
190- - 在宿主机上，使用**docker cp**指令将软件包拷贝到容器内。197+4. 安装自定义算子相关包<a id="install_costom_op"></a>
198+
199+ 下载[RecSDK](https://gitcode.com/Ascend/RecSDK)源码，按如下指令进行算子相关包的编译和安装：
200+
201+ ```bash
202+ # 编译算子前，需使能CANN环境变量。默认路径安装CANN包时，使能CANN环境变量指令如下：
203+ source /usr/local/Ascend/cann/set_env.sh
majunwang_huawei
majunwang_huaweimajunwang_huawei3月23日

默认路径的cann包在 source /usr/local/Ascend/ascend-toolkit/set_env.sh吧

likedislike
P
penghuiyang
3月28日 评论：
204+ unset ASCEND_CUSTOM_OPP_PATH
205+
206+ # 编译并安装算子包（Ascend-recsdk-npu-ops-\*-linux-\*.tar.gz）。
207+ cd RecSDK/cust_op/ascendc_op/build
208+ bash build_ai_core_op.sh A2
209+
210+ # 可选：若仅需安装部分算子，可在其他容器内编译，并将build/output/recsdk_ops路径下所需算子包拷贝到当前环境，参考如下指令安装：
211+ # bash mxrec_opp_split_embedding_codegen_forward_unweighted.run
212+
213+ # 安装算子适配层（libfbgemm_npu_api.so）
214+ cd ../../framework/torch_plugin/torch_library/common/
215+ bash build_ops.sh
216+ ```
217+
218+ 安装算子run包的参数如[表1](#table14435173717221)所示。
219+
220+ **表 1** 参数说明
221+ <a id="table14435173717221"></a>
222+
223+ |输入参数|说明|
224+ |--|--|
225+ |--help \| -h|查询帮助信息。|
226+ |--info|查询安装包的信息。|
227+ |--list|查询安装包的文件列表。|
228+ |--check|查询压缩包完整性。|
229+ |--quiet|静默安装方式。|
230+ |--nox11|不启动xterm终端。|
231+ |--noexec|不执行嵌入的安装脚本。|
232+ |--extract=\<path>|直接解压到目标目录，通常与--noexec配合使用，仅解压文件而不运行脚本。|
233+ |--tar arg1 [arg2 ...]|通过**tar**命令访问压缩包内容。|
234+ |--install-path|安装到指定目录路径。|
191 235 
192- **docker cp**指令示例：236+ >[!NOTICE]须知
237+ >
238+ > 安装算子后，/usr/local/Ascend/cann/opp/vendors/目录下会生成split\_embedding\_codegen\_forward\_unweighted、backward\_codegen\_adagrad\_unweighted\_exact、asynchronous\_complete\_cumsum、permute2d\_sparse\_data等文件夹。如果没有相关文件夹，请使用**unset ASCEND\_CUSTOM\_OPP\_PATH**取消环境变量后重新安装算子。
193 239 
194- ```bash240+### 基于Release版本+源码编译安装
195- docker cp host_file_path container_name:container_file_path
196- ```
197 241 
198- 其中，host\_file\_path为宿主机文件路径，container\_name为待拷入的docker容器名称，container\_file\_path为待拷入的docker容器内的文件路径。242+该方案默认已配置完成宿主机环境并进入Docker容器内。
199 243 
200-3. 按照如下步骤进行编译和安装包。244+该方案的安装步骤和[源码编译安装](#源码编译安装)章节类似。区别在于Rec SDK Torch推荐算法框架包可直接从Release版本获取，无需从源码编译。
201 245 
202- 1. 安装TorchRec昇腾注册包246+1. 依赖软件安装
247+
248+ 请参见[容器内训练框架依赖](#容器内训练框架依赖)和[容器内训练加速库依赖](#容器内训练加速库依赖)完成容器内的依赖软件安装。
203 249 
204- TorchRec昇腾注册包是基于TorchRec源码做的NPU设备适配。可通过Rec SDK Torch提供的patch文件和TorchRec源码的固定分支编译出该注册包。250+2. 安装TorchRec昇腾注册包
251+
252+ TorchRec昇腾注册包是基于TorchRec源码做的NPU设备适配。可通过Rec SDK Torch提供的patch文件和TorchRec源码的固定分支编译出该注册包。
253+
254+ 请参见[README](https://gitcode.com/Ascend/RecSDK/blob/develop/training/torch_rec_v1/torchrec_npu/README.md)进行源码编译和安装。
205 255 
206- 具体的源码编译和安装可参考[README](https://gitcode.com/Ascend/RecSDK/blob/develop/training/torch_rec_v1/torchrec_npu/README.md)（该包的源码编译不区分PyTorch版本）。256+3. 安装Rec SDK Torch推荐算法框架包
257+
258+ **下载软件包<a name="section1852417242717"></a>**
259+
260+ 请参考本章获取所需软件包和对应的数字签名文件，下载本软件即表示您同意[华为企业业务最终用户许可协议（EULA）](https://e.huawei.com/cn/about/eula)的条款和条件。
261+
262+ | 组件名称 | 软件包 | 获取链接 |
263+ |----------------------|------------------------------------------|----------------------------------------------------|
264+ | Rec SDK Torch推荐算法框架包 | Ascend-mindxsdk-hybrid-torchrec-*.tar.gz | [获取链接](https://gitcode.com/Ascend/RecSDK/releases) |
265+
266+ >[!NOTE]说明
267+ >当前提供的Rec SDK推荐算法框架包基于Python 3.11版本编译，**请在相同的Python版本环境下安装使用**。若需在其他Python版本环境下安装使用，请参见[源码编译 - 安装Rec SDK Torch推荐算法框架包](#source_build_hybrid_torchrec)进行源码编译。
268+
269+ **软件包Hash值校验<a name="section10830205518487"></a>**
270+
271+ 为了防止软件包在传递过程中或存储期间被恶意篡改，请在软件包下载之后使用`sha256sum`命令校验Hash值是否和软件包下载页的Hash值一致。
207 272 
208- 2. 安装Rec SDK Torch推荐算法框架包273+ **安装软件包**
209 274 
210- ```bash275+ 将下载的软件包上传到Docker容器内，实现方式可参考:
211- # 安装Ascend-mindxsdk-hybrid-torchrec-*-linux-*.tar.gz276+
212- tar zxvf Ascend-mindxsdk-hybrid-torchrec-*-linux-*.tar.gz277+ - 方式1：在启动容器时，指定一个宿主机目录挂载到容器内，并将下载的软件包放在其中，使容器可以访问到下载的软件包。
213- pip3 install hybrid_torchrec-*-py3-none-linux_*.whl278+
214- pip3 install torchrec_embcache-*-py3-none-linux_*.whl279+ 将宿主机目录挂载到Docker容器内，在[启动容器](#ZH-CN_TOPIC_0000002302389300)时增加如下参数（`dirX`需改为实际使用的文件目录）：
215- ```280+
281+ ```bash
282+ -v /dir1:/dir1
283+ ```
284+
285+ - 方式2：在宿主机上，使用**docker cp**指令将软件包拷贝到容器内。
286+
287+ **docker cp**指令示例：
288+
289+ ```bash
290+ docker cp host_file_path container_name:container_file_path
291+ ```
292+
293+ 其中，host\_file\_path为宿主机文件路径，container\_name为待拷入的docker容器名称，container\_file\_path为待拷入的docker容器内的文件路径。
216 294 
217- 3. 安装Rec SDK Torch自定义算子相关包295+ 执行如下指令进行安装：
218 296 
219- 下载[RecSDK仓库](https://gitcode.com/Ascend/RecSDK)源码，进入源代码目录，按如下指令进行算子相关包的编译和安装（算子包的编译不区分PyTorch版本）：297+ ```shell
298+ tar zxvf Ascend-mindxsdk-hybrid-torchrec*.tar.gz
299+ # 如已安装，请先卸载
300+ pip3 uninstall -y hybrid_torchrec torchrec_embcache
301+ # 安装软件包
302+ pip3 install hybrid_torchrec-*-py3-none-linux*.whl
303+ pip3 install -r requirements.txt
304+ pip3 install torchrec_embcache-*-py3-none-linux*.whl
305+ ```
220 306 
221- ```bash307+4. 安装自定义算子相关包
222- # 注：编译算子前，需使能CANN环境变量。默认路径安装CANN包时，使能CANN环境变量指令如下：308+
223- source /usr/local/Ascend/cann/set_env.sh309+ 本节内容和“源码编译 - 安装自定义算子相关包”内容相同，请参见前文[安装自定义算子相关包](#install_costom_op)章节。
224- unset ASCEND_CUSTOM_OPP_PATH
225-
226- # 编译并安装算子包
227- cd cust_op/ascendc_op/build
228- bash build_ai_core_op.sh A2
229 310 
230- # 可选：若仅需安装部分算子，可在其他容器内编译，并将build/output/recsdk_ops路径下所需算子包拷贝到当前环境，参考如下指令安装：311+## 安装验证
231- bash mxrec_opp_split_embedding_codegen_forward_unweighted.run
232-
233- # 安装算子适配层 libfbgemm_npu_api.so
234- cd ../../framework/torch_plugin/torch_library/common/
235- bash build_ops.sh
236- ```
237 312 
238- 安装算子的参数如[表1](#table14435173717221)所示。313+可通过执行已有用例验证Rec SDK Torch是否安装成功。
239 314 
240- **表 1** 参数说明315+hybrid_torchrec用例列表和运行方式请参见[README](../../../../training/torch_rec_v1/hybrid_torchrec/test/st/README.md)。
241- <a id="table14435173717221"></a>
242- 
243- |输入参数|说明|
244- |--|--|
245- |--help \| -h|查询帮助信息。|
246- |--info|查询安装包的信息。|
247- |--list|查询安装包的文件列表。|
248- |--check|查询压缩包完整性。|
249- |--quiet|静默安装方式。|
250- |--nox11|不启动xterm终端。|
251- |--noexec|不执行嵌入的安装脚本。|
252- |--extract=\<path>|直接解压到目标目录，通常与--noexec配合使用，仅解压文件而不运行脚本。|
253- |--tar arg1 [arg2 ...]|通过**tar**命令访问压缩包内容。|
254- |--install-path|安装到指定目录路径。|
255- 
256- 
257->[!NOTICE]须知
258->
259-> 安装算子后，/usr/local/Ascend/cann/opp/vendors/目录下会生成split\_embedding\_codegen\_forward\_unweighted、backward\_codegen\_adagrad\_unweighted\_exact、asynchronous\_complete\_cumsum、permute2d\_sparse\_data等文件夹。如果没有相关文件夹，请使用**unset ASCEND\_CUSTOM\_OPP\_PATH**取消环境变量后重新安装算子。
260 316 
317+torchrec_embcache用例列表和运行方式请参见[README](../../../../training/torch_rec_v1/torchrec_embcache/tests/acc_test/README.md)。
261 318 
319+用例执行后，若显示`xx passed`且没有`xx failed`则说明用例执行通过，Rec SDK Torch安装成功。
262 320 
263## 配置环境变量<a name="ZH-CN_TOPIC_0000002336268805"></a>321## 配置环境变量<a name="ZH-CN_TOPIC_0000002336268805"></a>
264 322 
@@ -286,7 +344,7 @@ Rec SDK Torch环境变量的说明如[表1](#table126401659163820)所示。
286| DO_EC_LOCAL_UNIQUE | 多级缓存是否启用EC local unique | 可选 | 字符串，支持"true"、"1"、"yes"表示启用，其他值表示不启用。默认为false。 |344| DO_EC_LOCAL_UNIQUE | 多级缓存是否启用EC local unique | 可选 | 字符串，支持"true"、"1"、"yes"表示启用，其他值表示不启用。默认为false。 |
287| LOCAL_UNIQUE_PARALLEL_BATCH_NUM | EmbCacheTrainPipelineSparseDist中Local unique并行处理批次数 | 可选 | 整数，默认为2，取值范围：[1, 24]。 |345| LOCAL_UNIQUE_PARALLEL_BATCH_NUM | EmbCacheTrainPipelineSparseDist中Local unique并行处理批次数 | 可选 | 整数，默认为2，取值范围：[1, 24]。 |
288| ENABLE_PARALLEL_GLOBAL_UNIQUE | 是否启用并行Global Unique处理 | 可选 | 字符串，1表示启用，其他值表示不启用。默认为0，表示不启用。 |346| ENABLE_PARALLEL_GLOBAL_UNIQUE | 是否启用并行Global Unique处理 | 可选 | 字符串，1表示启用，其他值表示不启用。默认为0，表示不启用。 |
289-| GLOG_stderrthreshold | 设置多级缓存C++模块的日志级别。 | 可选 | 整数，默认为0。取值范围：<ul><li>-2：TRACE</li><li>-1：DEBUG</li><li>0：INFO</li><li>1：WARN</li><li>2：ERROR</li><ul> |347+| GLOG_stderrthreshold | 设置多级缓存C++模块的日志级别。 | 可选 | 整数，默认为0。取值范围：<ul><li>-2：TRACE</li><li>-1：DEBUG</li><li>0：INFO</li><li>1：WARN</li><li>2：ERROR</li></ul> |
290 348 
291## 卸载<a name="ZH-CN_TOPIC_0000002302389376"></a>349## 卸载<a name="ZH-CN_TOPIC_0000002302389376"></a>
292 350 
@@ -303,11 +361,11 @@ pip3 uninstall torchrec -y
303 361 
304用户如需移除Rec SDK Torch自定义算子相关包，可参考以下命令进行卸载。其中，362用户如需移除Rec SDK Torch自定义算子相关包，可参考以下命令进行卸载。其中，
305 363 
306-- 自定义算子在CANN中的默认安装路径为/usr/local/Ascend/cann/opp/vendors/364+- 自定义算子在CANN中的默认安装路径为/usr/local/Ascend/cann/opp/vendors/
307-- 卸载自定义算子时，删除vendors路径下自定义算子名称对应的文件夹即可。可以通过[ai\_core\_op](https://gitcode.com/Ascend/RecSDK/tree/develop/cust_op/ascendc_op/ai_core_op)查看Rec SDK的自定义算子目录。365+- 卸载自定义算子时，删除vendors路径下自定义算子名称对应的文件夹即可。可以通过[ai\_core\_op](https://gitcode.com/Ascend/RecSDK/tree/develop/cust_op/ascendc_op/ai_core_op)查看Rec SDK的自定义算子目录。
308 366 
309```bash367```bash
310-# 卸载算子指令示例368+# 卸载算子指令示例（仅列出部分，其他算子卸载指令同理）
311rm -rf /usr/local/Ascend/cann/opp/vendors/asynchronous_complete_cumsum369rm -rf /usr/local/Ascend/cann/opp/vendors/asynchronous_complete_cumsum
312rm -rf /usr/local/Ascend/cann/opp/vendors/backward_codegen_adagrad_unweighted_exact370rm -rf /usr/local/Ascend/cann/opp/vendors/backward_codegen_adagrad_unweighted_exact
313rm -rf /usr/local/Ascend/cann/opp/vendors/permute2d_sparse_data371rm -rf /usr/local/Ascend/cann/opp/vendors/permute2d_sparse_data
@@ -322,25 +380,9 @@ else
322fi380fi
323```381```
324 382 
325-部分自定义算子安装到CANN的vendors文件夹（CANN安装路径/opp/vendors）下时，原自定义算子名称与安装路径不同，卸载时需删除安装后的路径。存在差异的自定义算子如下表。
326- 
327-|自定义算子名称|安装到vendors文件夹下的名称|
328-|--|--|
329-|cust_op_by_addr|customize|
330-|pcie_through|customize|
331-|fused_lazy_adam|mxrec_fused_lazy_adam|
332-|fused_sgd|mxrec_sgd|
333- 
334- 
335->[!NOTE]说明
336->用户自定义算子在未配置安装文件夹名称时，默认安装在CANN的vendors/customize文件夹下。当删除的customize文件夹中存在用户自定义算子时，则对应算子需重新安装。
337- 
338- 
339## 升级<a name="ZH-CN_TOPIC_0000002302389340"></a>383## 升级<a name="ZH-CN_TOPIC_0000002302389340"></a>
340 384 
341用户如需将当前版本的Rec SDK Torch升级至最新版本，可将最新的Rec SDK Torch软件包上传至安装环境后，在软件包所在目录下使用命令进行升级，具体命令如下。385用户如需将当前版本的Rec SDK Torch升级至最新版本，可将最新的Rec SDK Torch软件包上传至安装环境后，在软件包所在目录下使用命令进行升级，具体命令如下。
342 386 
343-1. 升级Rec SDK Torch新版本时，需要先手动卸载旧版本。具体操作请参考[卸载](#卸载)。387+1. 升级Rec SDK Torch新版本时，需要先手动卸载旧版本。具体操作请参考[卸载](#卸载)。
344-2. 参考[安装Rec SDK Torch](#section182972951211)重新安装Rec SDK Torch。388+2. 参考[安装Rec SDK Torch](#section182972951211)重新安装Rec SDK Torch。
345- 
346- 
Mtraining/torch_rec_v1/hybrid_torchrec/README.md+15-10
@@ -1,5 +1,5 @@
1 1 
2-# Hybrid-torchrec NPU适配方案2+# Hybrid-Torchrec NPU适配方案
3 3 
4## 软件介绍4## 软件介绍
5 5 
@@ -11,11 +11,13 @@ Python版本要求：Python >= 3.11。
11 11 
12| 配套版本 | PyTorch | torch_npu | torchrec | fbgemm_gpu | hybrid_torchrec |12| 配套版本 | PyTorch | torch_npu | torchrec | fbgemm_gpu | hybrid_torchrec |
13|-------|---------|-----------|-----------|------------|-----------------|13|-------|---------|-----------|-----------|------------|-----------------|
14-| 配套版本1 | 2.6.0 | 2.6.0 | 1.1.0+npu | 1.1.0 | 1.1.0 |14+| 方案一 | 2.6.0 | 2.6.0 | 1.1.0+npu | 1.1.0 | 1.1.0 |
15-| 配套版本2 | 2.7.1 | 2.7.1 | 1.2.0+npu | 1.2.0 | 1.2.0 |15+| 方案二 | 2.7.1 | 2.7.1 | 1.2.0+npu | 1.2.0 | 1.2.0 |
16 16 
17说明：17说明：
18+ 
181. torch_npu是Ascend Extension for PyTorch插件，使昇腾NPU可以适配PyTorch框架。相关文档和**下载/安装**请参见[Ascend文档](https://www.hiascend.com/developer/software/ai-frameworks/pytorch)。191. torch_npu是Ascend Extension for PyTorch插件，使昇腾NPU可以适配PyTorch框架。相关文档和**下载/安装**请参见[Ascend文档](https://www.hiascend.com/developer/software/ai-frameworks/pytorch)。
20+
192. torchrec 1.1.0+npu/1.2.0+npu为基于开源torchrec适配NPU设备，增加NPU适配后编译的包。相关文档请参见[README](../torchrec_npu/README.md)。212. torchrec 1.1.0+npu/1.2.0+npu为基于开源torchrec适配NPU设备，增加NPU适配后编译的包。相关文档请参见[README](../torchrec_npu/README.md)。
20 22 
21## 使用方法23## 使用方法
@@ -29,6 +31,7 @@ Python版本要求：Python >= 3.11。
29请参见[Rec SDK文档](../../../docs/zh/torch/torch_rec_v1/recsdk_torch_installation_guide.md#section182972951211)中“安装Rec SDK Torch”章节。31请参见[Rec SDK文档](../../../docs/zh/torch/torch_rec_v1/recsdk_torch_installation_guide.md#section182972951211)中“安装Rec SDK Torch”章节。
30 32 
31#### 2.1 依赖软件安装33#### 2.1 依赖软件安装
34+ 
32- PyTorch： 容器内已包含torch软件包，若torch软件包版本不满足配套需求，可进行软件升级。升级PyTorch版本为2.7.1指令示例：`pip3 install torch==2.7.1+cpu -i https://download.pytorch.org/whl/cpu`35- PyTorch： 容器内已包含torch软件包，若torch软件包版本不满足配套需求，可进行软件升级。升级PyTorch版本为2.7.1指令示例：`pip3 install torch==2.7.1+cpu -i https://download.pytorch.org/whl/cpu`
33- torch_npu: 参考[Ascend文档](https://www.hiascend.com/developer/software/ai-frameworks/pytorch)，根据配套版本和环境架构下载软件包并解压安装。36- torch_npu: 参考[Ascend文档](https://www.hiascend.com/developer/software/ai-frameworks/pytorch)，根据配套版本和环境架构下载软件包并解压安装。
34- fbgemm_gpu:37- fbgemm_gpu:
@@ -38,6 +41,7 @@ Python版本要求：Python >= 3.11。
38 - 参考[README](../torchrec_npu/README.md) 进行源码编译安装。41 - 参考[README](../torchrec_npu/README.md) 进行源码编译安装。
39 42 
40#### 2.2 hybrid_torchrec安装43#### 2.2 hybrid_torchrec安装
44+ 
41- 基于软件包安装45- 基于软件包安装
42 46 
43从[RecSDK release版本](https://gitcode.com/Ascend/RecSDK/releases)，选择最新版本，下载Ascend-mindxsdk-hybrid-torchrec-*.tar.gz软件包。47从[RecSDK release版本](https://gitcode.com/Ascend/RecSDK/releases)，选择最新版本，下载Ascend-mindxsdk-hybrid-torchrec-*.tar.gz软件包。
@@ -45,12 +49,10 @@ Python版本要求：Python >= 3.11。
45```shell49```shell
46tar zxvf Ascend-mindxsdk-hybrid-torchrec*.tar.gz50tar zxvf Ascend-mindxsdk-hybrid-torchrec*.tar.gz
47# 如果已安装，请先卸载51# 如果已安装，请先卸载
48-pip3 uninstall -y hybrid_torchrec52+pip3 uninstall -y hybrid_torchrec torchrec_embcache
49# 安装软件包53# 安装软件包
50pip3 install hybrid_torchrec-*-py3-none-linux*.whl54pip3 install hybrid_torchrec-*-py3-none-linux*.whl
51pip3 install -r requirements.txt55pip3 install -r requirements.txt
52-# [可选] 若需使用多级缓存功能，则需安装torchrec_embcache软件包
53-pip3 uninstall -y torchrec_embcache
54pip3 install torchrec_embcache-*-py3-none-linux*.whl56pip3 install torchrec_embcache-*-py3-none-linux*.whl
55```57```
56 58 
@@ -61,17 +63,20 @@ git clone https://gitcode.com/ascend/RecSDK.git
61cd RecSDK/training/torch_rec_v1/hybrid_torchrec63cd RecSDK/training/torch_rec_v1/hybrid_torchrec
62bash build_whl.sh64bash build_whl.sh
63cd dist65cd dist
64-pip3 uninstall -y hybrid_torchrec66+pip3 uninstall -y hybrid_torchrec torchrec_embcache
65pip3 install hybrid_torchrec-*.whl67pip3 install hybrid_torchrec-*.whl
66pip3 install -r requirements.txt68pip3 install -r requirements.txt
67-# [可选] 若需使用多级缓存功能，则需安装torchrec_embcache软件包
68-pip3 uninstall -y torchrec_embcache
69pip3 install torchrec_embcache-*-py3-none-linux*.whl69pip3 install torchrec_embcache-*-py3-none-linux*.whl
70```70```
71 71 
72注：如果pip3 uninstall hybrid_torchrec提示file找不到，请换一个执行路径，不要在子目录有hybrid_torchrec的路径下执行该命令72注：如果pip3 uninstall hybrid_torchrec提示file找不到，请换一个执行路径，不要在子目录有hybrid_torchrec的路径下执行该命令
73 73 
74+### 3 运行测试
75+ 
76+请参见[hybrid_torchrec测试套件](./test/st/README.md)。
77+ 
74## 相关网站78## 相关网站
75-[TorchRec介绍](https://pytorch.org/torchrec)79+ 
80+[TorchRec介绍](https://meta-pytorch.org/torchrec/)
76 81 
77[TorchRec开源项目](https://github.com/pytorch/torchrec)82[TorchRec开源项目](https://github.com/pytorch/torchrec)
Atraining/torch_rec_v1/hybrid_torchrec/test/st/README.md+53-0
@@ -0,0 +1,53 @@
1+# hybrid_torchrec测试套件
2+ 
3+本目录包含hybrid_torchrec组件的多个测试用例，用于验证**NPU纯显存模式下**EmbeddingBagCollection，HashEmbeddingBagCollection的功能和精度正确性。
4+ 
5+> 说明
6+>
7+> EmbeddingBagCollection为开源TorchRec原生稀疏表实现。
8+>
9+> HashEmbeddingBagCollection为hybrid_torchrec组件新增的稀疏表实现，对应TorchRec原生的EmbeddingBagCollection，支持特征ID Hash映射、ID去重等功能。
10+ 
11+## 目录结构
12+ 
13+```shell
14+st/
15+├── README.md # 测试套件说明文档
16+├── dataset.py # 数据集定义和随机数据生成器
17+├── model.py # 测试模型定义
18+├── util.py # 工具函数（日志设置等）
19+├── test_all.sh # 执行全部测试用例的脚本
20+├── test_hybrid_embeddingbag.py # 测试TorchRec原生的EmbeddingBagCollection前反向查表
21+├── test_hybrid_hash_embeddingbag.py # 测试支持特征ID Hash映射的HashEmbeddingBagCollection前反向查表
22+├── test_hybrid_hash_embeddingbag_dp.py # 测试DP分表模式下的HashEmbeddingBagCollection
23+├── test_hybrid_pipeline_hash_embeddingbag.py # 测试pipeline场景下的HashEmbeddingBagCollection前反向查表
24+├── test_ids_process.py # 测试C++侧实现的特征ID去重分桶相关功能
25+├── test_module.py # 测试HashEmbeddingBagCollection的在CPU/NPU设备上功能/精度正确性
26+└── test_train_and_eval.py # 测试训练和评估功能
27+```
28+ 
29+## 运行测试
30+ 
31+### 环境准备
32+ 
33+请参见[hybrid_torchrec文档](../../README.md)安装hybrid_torchrec及其依赖项。
34+ 
35+### 运行单个测试
36+ 
37+```bash
38+# 运行单个测试文件
39+pytest test_hybrid_embeddingbag.py
40+```
41+ 
42+### 运行所有测试
43+ 
44+```bash
45+# 使用提供的脚本运行所有测试
46+bash test_all.sh
47+```
48+ 
49+## 注意事项
50+ 
51+1. 确保在NPU环境下运行测试
52+2. 分布式测试需要足够的NPU资源（2张NPU卡）
53+3. 测试数据是随机生成的，结果可能因种子而异
Rtraining/torch_rec_v1/hybrid_torchrec/test/st/test_hybrid_pipline_hash_embeddingbag.py→training/torch_rec_v1/hybrid_torchrec/test/st/test_hybrid_pipeline_hash_embeddingbag.py+0-0
文件重命名但无更改。
Mtraining/torch_rec_v1/torchrec_embcache/README.md+12-3
@@ -1,6 +1,7 @@
1# TorchRec-EmbCache NPU适配方案1# TorchRec-EmbCache NPU适配方案
2 2 
3## 软件介绍3## 软件介绍
4+ 
4本项目是基于开源项目TorchRec的1.1.0/1.2.0版本开发的embedding多级缓存扩展，助力开发者快速应用TorchRec框架并适配到NPU进行模型训练和推理。5本项目是基于开源项目TorchRec的1.1.0/1.2.0版本开发的embedding多级缓存扩展，助力开发者快速应用TorchRec框架并适配到NPU进行模型训练和推理。
5 6 
6Python版本要求：Python >= 3.11。7Python版本要求：Python >= 3.11。
@@ -9,8 +10,8 @@ Python版本要求：Python >= 3.11。
9 10 
10| 配套版本 | PyTorch | torch_npu | torchrec | fbgemm_gpu | hybrid_torchrec | torchrec_embcache |11| 配套版本 | PyTorch | torch_npu | torchrec | fbgemm_gpu | hybrid_torchrec | torchrec_embcache |
11|-------|---------|-----------|-----------|------------|-----------------|-------------------|12|-------|---------|-----------|-----------|------------|-----------------|-------------------|
12-| 配套版本1 | 2.6.0 | 2.6.0 | 1.1.0+npu | 1.1.0 | 1.1.0 | 1.1.0 |13+| 方案一 | 2.6.0 | 2.6.0 | 1.1.0+npu | 1.1.0 | 1.1.0 | 1.1.0 |
13-| 配套版本2 | 2.7.1 | 2.7.1 | 1.2.0+npu | 1.2.0 | 1.2.0 | 1.2.0 |14+| 方案二 | 2.7.1 | 2.7.1 | 1.2.0+npu | 1.2.0 | 1.2.0 | 1.2.0 |
14 15 
15### 1.环境准备16### 1.环境准备
16 17 
@@ -21,11 +22,13 @@ Python版本要求：Python >= 3.11。
21请参见[Rec SDK文档](../../../docs/zh/torch/torch_rec_v1/recsdk_torch_installation_guide.md#section182972951211)中“安装Rec SDK Torch”章节。22请参见[Rec SDK文档](../../../docs/zh/torch/torch_rec_v1/recsdk_torch_installation_guide.md#section182972951211)中“安装Rec SDK Torch”章节。
22 23 
23#### 2.1 前提条件24#### 2.1 前提条件
25+ 
24torchrec_embcache依赖于hybrid_torchrec包，请先参考[hybrid_torchrec README](../hybrid_torchrec/README.md)完成hybrid_torchrec及其依赖包安装。26torchrec_embcache依赖于hybrid_torchrec包，请先参考[hybrid_torchrec README](../hybrid_torchrec/README.md)完成hybrid_torchrec及其依赖包安装。
25 27 
26本章节仅介绍torchrec_embcache软件包安装。28本章节仅介绍torchrec_embcache软件包安装。
27 29 
28#### 2.2 torchrec_embcache安装30#### 2.2 torchrec_embcache安装
31+ 
29- 基于软件包安装32- 基于软件包安装
30 33 
31从[RecSDK release版本](https://gitcode.com/Ascend/RecSDK/releases)，选择最新版本，下载Ascend-mindxsdk-hybrid-torchrec-*.tar.gz软件包。34从[RecSDK release版本](https://gitcode.com/Ascend/RecSDK/releases)，选择最新版本，下载Ascend-mindxsdk-hybrid-torchrec-*.tar.gz软件包。
@@ -42,6 +45,7 @@ pip3 install -r requirements.txt
42```45```
43 46 
44- 基于源码编译安装47- 基于源码编译安装
48+ 
45```shell49```shell
46git clone https://gitcode.com/ascend/RecSDK.git50git clone https://gitcode.com/ascend/RecSDK.git
47cd RecSDK/training/torch_rec_v1/torchrec_embcache51cd RecSDK/training/torch_rec_v1/torchrec_embcache
@@ -52,7 +56,12 @@ pip3 uninstall -y torchrec_embcache
52pip3 install ./dist/torchrec_embcache-*.whl56pip3 install ./dist/torchrec_embcache-*.whl
53```57```
54 58 
59+### 3 运行测试
60+ 
61+请参见[torchrec_embcache测试套件](tests/acc_test/README.md)。
62+ 
55## 相关网站63## 相关网站
56-[TorchRec介绍](https://pytorch.org/torchrec)64+ 
65+[TorchRec介绍](https://meta-pytorch.org/torchrec/)
57 66 
58[TorchRec开源项目](https://github.com/pytorch/torchrec)67[TorchRec开源项目](https://github.com/pytorch/torchrec)
Mtraining/torch_rec_v1/torchrec_embcache/tests/acc_test/README.md+49-2
@@ -1,6 +1,53 @@
1-## 精度测试脚本1+# torchrec_embcache测试套件
2-### 执行脚本2+ 
3+本目录包含torchrec_embcache组件的多个测试用例，用于验证**多级缓存模式下**EmbcacheEmbeddingCollection，EmbcacheEmbeddingBagCollection的功能和精度正确性。
4+ 
5+> 说明
6+>
7+> EmbcacheEmbeddingCollection为torchrec_embcache组件新增的稀疏表实现，对应TorchRec原生的EmbeddingCollection。
8+>
9+> EmbcacheEmbeddingBagCollection为torchrec_embcache组件新增的稀疏表实现，对应TorchRec原生的EmbeddingBagCollection。
10+ 
11+## 目录结构
12+ 
13+```text
14+acc_test/
15+├── README.md # 测试用例说明文档
16+├── dataset.py # 数据集定义和随机数据生成器
17+├── model.py # 测试模型定义
18+├── run_test.sh # 执行所有测试用例的脚本
19+├── test_embedding_cache_pipeline.py # 测试多级缓存pipeline+EmbcacheBagEmbeddingCollection的功能和精度
20+├── test_embedding_ec_cache_aggregation.py # 测试多级缓存pipeline+EmbcacheEmbeddingCollection+梯度累积优化器的功能和精度
21+├── test_embedding_ec_cache_pipeline.py # 测试多级缓存pipeline+EmbcacheEmbeddingCollection的功能和精度
22+├── test_feature_filter.py # 测试（基于特征时间戳和计数）特征准入淘汰功能
23+├── test_kjt_with_time.py # 测试带时间戳的KeyedJaggedTensor功能
24+├── test_save_and_load.py # 测试保存和加载功能
25+├── test_show_click.py # 测试（基于特征展示次数和点击次数的加权分数）特征准入淘汰功能
26+└── util.py # 工具函数（日志设置等）
27+```
28+ 
29+## 运行测试
30+ 
31+### 环境准备
32+ 
33+请参见[README文档](../../README.md)安装torchrec_embcache及其依赖项。
34+ 
35+### 运行单个测试
3 36 
4```bash37```bash
38+# 运行单个测试文件示例
39+pytest test_embedding_cache_pipeline.py
40+```
41+ 
42+### 运行所有测试
43+ 
44+```bash
45+# 使用提供的脚本运行测试
5bash run_test.sh46bash run_test.sh
6```47```
48+ 
49+## 注意事项
50+ 
51+1. 确保在NPU环境下运行测试
52+2. 分布式测试需要足够的NPU资源（大部分用例需2张NPU卡，保存和加载测试用例需3张NPU卡）
53+3. 测试数据是随机生成的，结果可能因种子而异