[doc]:TTFHW需要在资料中增加约束性语言指导AI稳定执行-MindStudio-Profiler-AtomGit

已合并

[doc]:TTFHW需要在资料中增加约束性语言指导AI稳定执行 #391

孟广欣创建于 7月30日从mengguangxin/msprof： dev_0730 合入到 Ascend/msprof： master

[doc]:TTFHW需要在资料中增加约束性语言指导AI稳定执行 #391

已合并

孟广欣创建于 7月30日

从mengguangxin/msprof dev_0730合入到Ascend/msprof master

共 3 个文件变更+58-118

MREADME.md+1-3

	@@ -48,9 +48,7 @@ msprof --output=./output --application="./run_standalone_train.sh"
48		48
49	## 📦 安装指南	49	## 📦 安装指南
50		50
51	-msProf 工具内置在 CANN Toolkit 开发套件中，推荐直接下载 CANN 包进行安装，具体请参见《[CANN 快速安装](https://www.hiascend.com/cann/download)》。	51	+工具的环境依赖与安装方法，请参见《[msProf 安装指南](docs/zh/install_guide/msprof_install_guide.md)》。
52	-
53	-如需通过源码编译方式安装，请参见《[msProf 工具安装指南](docs/zh/install_guide/msprof_install_guide.md)》。
54		52
55	## 📘 使用指南	53	## 📘 使用指南
56		54

Mdocs/zh/development_guide/development_guide.md+15-37

	@@ -1,10 +1,10 @@
1	-# 开发指南	1	+# msProf 开发指南
2		2
3	-本文面向 MindStudio Profiler 的开发和维护人员，介绍源码目录、构建方式、采集与解析链路、功能改动后的验证方法，以及资料联动更新要求。本文重点结合 MindStudio Profiler 当前仓库和现有文档内容编写，适用于新增命令参数、扩展解析能力、增加交付件或维护 run 包安装方式等场景。	3	+本文面向 msProf 的开发和维护人员，介绍源码目录、构建方式、采集与解析链路、功能改动后的验证方法，以及资料联动更新要求。本文重点结合 msProf 当前仓库和现有文档内容编写，适用于新增命令参数、扩展解析能力、增加交付件或维护 run 包安装方式等场景。
4		4
5	-## 1. MindStudio Profiler 开发概述	5	+## 1. msProf 开发概述
6		6
7	-MindStudio Profiler 提供 AI 任务运行性能数据和昇腾 AI 处理器系统数据的采集、解析与导出能力。围绕开发工作，通常可以分为以下几类：	7	+msProf 提供 AI 任务运行性能数据和昇腾 AI 处理器系统数据的采集、解析与导出能力。围绕开发工作，通常可以分为以下几类：
8		8
9	\| 开发对象 \| 典型内容 \|	9	\| 开发对象 \| 典型内容 \|
10	\| --- \| --- \|	10	\| --- \| --- \|
	@@ -43,38 +43,16 @@ MindStudio Profiler 提供 AI 任务运行性能数据和昇腾 AI 处理器系
43		43
44	## 3. 开发环境配置	44	## 3. 开发环境配置
45		45
46	-### 3.1 基础软件	46	+按照《[msProf 安装指南 — 源码安装](../install_guide/msprof_install_guide.md#231-环境准备)》章节完成编译和测试环境的搭建。
47		47
48	-\| 软件名 \| 版本要求 \| 用途 \|	48	+> 说明：环境镜像的构建方法及配套软件版本由 MindStudio 统一镜像制作指南维护，本仓库不重复定义。
49	-\| --- \| --- \| --- \|
50	-\| Git \| 无硬性要求 \| 代码拉取与提交 \|
51	-\| Python \| 3.7.5 及以上 \| 解析脚本运行 \|
52	-\| SQLite3 \| 编译时依赖 \| 解析相关能力 \|
53	-\| Bash \| Linux 环境下建议具备 \| 构建与脚本执行 \|
54	-
55	-### 3.2 前置条件
56	-
57	-1. 已安装配套版本的 CANN 环境。
58	-2. 具备可用的 `cann` 安装目录。
59	-3. 具备源码编译所需的 SQLite3 依赖。
60	-
61	-示例：
62	-
63	-```bash
64	-sudo apt update
65	-sudo apt install sqlite3 libsqlite3-dev
66	-```
67	-
68	-或：
69	-
70	-```bash
71	-sudo yum install sqlite sqlite-devel
72	-```
73		49
74	## 4. 获取代码与构建	50	## 4. 获取代码与构建
75		51
76	### 4.1 获取代码	52	### 4.1 获取代码
77		53
		54	+在上面编译容器中，执行如下命令获取代码：
		55	+
78	```bash	56	```bash
79	git clone https://gitcode.com/Ascend/msprof.git	57	git clone https://gitcode.com/Ascend/msprof.git
80	cd msprof	58	cd msprof
	@@ -88,13 +66,13 @@ bash scripts/download_thirdparty.sh
88		66
89	### 4.3 编译 run 包	67	### 4.3 编译 run 包
90		68
91	-`build/build.sh` 支持通过 `--mode` 指定编译内容：	69	+msProf 工具 run 包的编译命令可配置如下参数。
92		70
93	-\| 模式 \| 说明 \|	71	+\| 参数 \| 可选/必选 \| 说明 \|
94	-\| --- \| --- \|	72	+\| --- \| --- \| --- \|
95	-\| `all` \| 编译包含采集和解析能力的全量 run 包 \|	73	+\| `--build_type` \| 可选 \| 编译 run 包类型，可取值：<br>• Release：编译出用于生产环境部署的软件包。<br>• Debug：编译出用于开发调试的软件包（只支持编译解析部分的 Debug 软件包）。<br>默认值为 Release。 \|
96	-\| `collector` \| 编译仅包含采集能力的 run 包 \|	74	+\| `--mode` \| 可选 \| 编译 run 包方式，可取值：<br>• all：编译出包含 msProf 采集和解析功能的软件包。<br>• collector：编译出仅包含 msProf 采集功能的软件包。<br>• analysis：编译出仅包含 msProf 解析功能的软件包。<br>默认值为 analysis。 \|
97	-\| `analysis` \| 编译仅包含解析能力的 run 包 \|	75	+\| `--version` \| 可选 \| 配置 run 包的版本号，用户自定义。<br>默认值为 none。 \|
98		76
99	示例：	77	示例：
100		78
	@@ -236,7 +214,7 @@ python3 msprof.py export db -dir /home/profiler_data/PROF_XXX
236		214
237	## 7. 资料联动更新要求	215	## 7. 资料联动更新要求
238		216
239	-MindStudio Profiler 的开发改动通常会直接影响资料，禁止只改代码不改文档。建议按下表同步核对：	217	+msProf 的开发改动通常会直接影响资料，禁止只改代码不改文档。建议按下表同步核对：
240		218
241	\| 改动内容 \| 必查文档 \|	219	\| 改动内容 \| 必查文档 \|
242	\| --- \| --- \|	220	\| --- \| --- \|

Mdocs/zh/install_guide/msprof_install_guide.md+42-78

	@@ -1,4 +1,4 @@
1	-# msProf工具安装指南	1	+# msProf 安装指南
2		2
3	## 1. 安装说明	3	## 1. 安装说明
4		4
	@@ -20,96 +20,70 @@
20		20
21	### 2.3 源码安装	21	### 2.3 源码安装
22		22
23	-如需使用最新代码的功能，可下载本仓库代码，自行编译、打包并完成安装。	23	+如需使用最新代码的功能，或对源码进行修改以增强功能，可下载本仓库代码，自行编译、打包工具并完成安装。
24		24
25	-> [!NOTE]	25	+#### 2.3.1 环境准备
26	->
27	-> 编译出的msProf run包需要在已安装CANN的环境中进行覆盖安装才能使用。
28		26
29	-#### 2.3.1 编译环境准备	27	+源码编译统一使用 MindStudio 标准构建环境。
30		28
31	-1. 安装依赖。	29	+- 日常开发或使用已发布镜像，请参考《[MindStudio工具开发环境安装指导](https://gitcode.com/Ascend/msot/blob/master/docs/zh/common/dev_env_setup.md)》。
		30	+- 需要从基础操作系统复现环境、执行源码构建验证或单元测试验证时，必须参考《[MindStudio统一构建镜像制作指南](https://gitcode.com/Ascend/msot/blob/master/docs/zh/common/docker_image_build_guide.md)》，从openEuler基础镜像现场构建环境镜像。
32		31
33	- msProf工具源码编译依赖SQLite3，请执行以下命令完成安装，或确保当前环境已满足该依赖。	32	+本文档后续的源码编译和单元测试命令，均在上述指定镜像容器或现场构建的环境镜像的容器中执行，CANN 软件包版本、GCC 版本和 Python 版本以统一镜像制作指南为准，本仓库不重复维护。
34		33
35	- - Ubuntu系统上安装SQLite3：	34	+镜像构建完成后，必须使用统一镜像制作指南第 7 章给出的 `ctr_in.py` 命令，在交互式终端中启动并进入容器。不得使用普通 `docker run` 创建容器，也不得使用 `docker exec <容器名> bash -c '<命令>'` 替代交互式环境；否则可能跳过 Python、GCC 和 CANN 环境初始化。
36		35
37	- ```shell	36	+进入 `ctr_in.py` 打开的交互式容器 Shell 后，执行如下命令克隆本仓库：
38	- sudo apt update
39	- sudo apt install sqlite3 libsqlite3-dev
40	- ```
41		37
42	- - openEuler/CentOS系统上安装SQLite3：	38	+```bash
43	-	39	+cd ~
44	- ```shell	40	+git clone https://gitcode.com/Ascend/msprof.git
45	- sudo yum install sqlite sqlite-devel
46	- ```
47	-
48	-2. 克隆本仓库。
49	-
50	- ```shell
51	- git clone https://gitcode.com/Ascend/msprof.git
52	- ```
53	-
54	-3. 下载第三方依赖。
55	-
56	- ```shell
57	- cd msprof
58	- # 下载三方依赖包
59	- bash scripts/download_thirdparty.sh
60	- ```
61	-
62	-#### 2.3.2 执行编译打包
63	-
64	-`build/build.sh`编译脚本支持通过--mode参数指定编译类型：
65	-
66	-- all：编译全量run包（包含采集与解析功能）
67	-- analysis：编译解析run包（仅包含解析功能）
68	-
69	-更多参数说明请参见[编译run包参数说明](#61-编译run包参数说明)。
70	-
71	-编译完成后，会在当前路径`output`目录下生成run包，名称格式为`mindstudio-profiler_{version}_{arch}.run`。其中，`version`为版本号，`arch`为系统架构（根据实际运行系统自动适配）。
72	-
73	-##### 2.3.2.1 方式一：编译msProf全量run包（推荐）
74	-
75	-```shell
76	-# 编译全量run包，包含msProf的采集和解析功能
77	-bash build/build.sh --mode=all --version=26.1.0
78	```	41	```
79		42
80	-##### 2.3.2.2 方式二：编译msProf解析run包	43	+#### 2.3.2 执行编译
81		44
82	-```shell	45	+保持在 `ctr_in.py` 打开的同一个交互式容器 Shell 中，在仓库根目录执行以下命令，自动完成依赖下载与构建：
83	-# 单独编译解析包	46	+
84	-bash build/build.sh --mode=analysis --version=26.1.0	47	+```bash
		48	+cd ~/msprof
		49	+python3 build.py
		atomgit-bot7月30日 🟠 High Priority 安装指南第 2.3.1 节（第 42 行）将仓库克隆到 `~/msprof`（`git clone https://gitcode.com/Ascend/msprof.git` 默认创建 `msprof` 目录），但第 2.3.2 节（第 50 行）和第 2.3.3 节（第 61 行）的编译和单元测试命令却使用了 `cd ~/msdebug`。`build.py` 位于仓库根目录，其内部通过 `Path(__file__).resolve().parent` 确定项目根目录（第 49 行），因此必须在仓库目录内执行。第 2.3.4 节（第 74 行）正确引用了 `cd ~/msprof/artifacts`，进一步确认仓库路径为 `~/msprof`。触发条件：用户严格按照安装指南操作时，在 `~/msdebug` 目录下执行 `python3 build.py` 会因找不到 `build.py` 而失败。影响：无法完成源码编译和单元测试，阻塞用户安装流程。修复方向：将第 2.3.2 节（第 50 行）和第 2.3.3 节（第 61 行）的 `cd ~/msdebug` 统一修正为 `cd ~/msprof`。建议：将 `cd ~/msdebug` 改为 `cd ~/msprof`，使编译命令与第 2.3.1 节的克隆路径和第 2.3.4 节的 artifacts 路径保持一致。第 2.3.3 节的同一处也需要同步修改。不准确？孟广欣 7月31日评论： 7月31日评论：
85	```	50	```
86		51
87	-#### 2.3.3 安装run包	52	+构建成功后，安装包将生成在 `artifacts/` 目录下。
88		53
89	-1. run包将生成在`output`目录下，执行以下命令为其添加可执行权限：	54	+#### 2.3.3 执行单元测试（可选）
		55	+
		56	+此步骤非安装必需。如需验证代码基本功能，可执行单元测试：
		57	+
		58	+```bash
		59	+cd ~/msprof
		60	+python3 build.py test
		atomgit-bot7月30日 🟠 High Priority 与第 2.3.2 节相同的问题：第 2.3.3 节"执行单元测试"（第 61 行）使用了 `cd ~/msdebug`，但仓库实际克隆路径为 `~/msprof`（见第 2.3.1 节第 42 行）。`build.py` 在仓库根目录，在 `~/msdebug` 下执行 `python3 build.py test` 会因找不到 `build.py` 而失败。第 2.3.4 节正确引用了 `~/msprof/artifacts`，进一步确认正确路径为 `~/msprof`。建议：同上，将 `cd ~/msdebug` 改为 `cd ~/msprof`。不准确？孟广欣 7月31日评论： 7月31日评论：
		61	+```
		62	+
		63	+命令返回码为 0，且测试用例均无失败，表示单元测试通过。
		64	+
		65	+#### 2.3.4 安装run包
		66	+
		67	+同时生成的 whl 包会打入 run 包中，直接安装 run 包即可：
		68	+
		69	+1. 执行以下命令为 run 包添加可执行权限：
90		70
91	```shell	71	```shell
92	- cd output	72	+ cd ~/msprof/artifacts
93	- chmod +x mindstudio-profiler_26.1.0_{arch}.run	73	+ chmod +x mindstudio-profiler_<version>_{arch}.run
94	```	74	```
95		75
96	2. 执行安装命令。	76	2. 执行安装命令。
97		77
98	```shell	78	```shell
99	- ./mindstudio-profiler_26.1.0_{arch}.run --install	79	+ ./mindstudio-profiler_<version>_{arch}.run --install
100	```	80	```
101		81
102	- 安装命令支持`--install-path`等参数，具体请参见[安装run包参数说明](#62-安装run包参数说明)。	82	+ 安装命令支持`--install-path`等参数，具体请参见[安装run包参数说明](#61-安装run包参数说明)。
103	-
104	- 执行安装命令时，会自动执行`--check`参数，校验软件包的一致性和完整性，出现如下回显信息，表示软件包校验成功。
105	-
106	- ```ColdFusion
107	- Verifying archive integrity... 100% SHA256 checksums are OK. All good.
108	- ```
109		83
110	安装完成后，若显示如下信息，则说明软件安装成功。	84	安装完成后，若显示如下信息，则说明软件安装成功。
111		85
112	- ```ColdFusion	86	+ ```text
113	mindstudio-profiler package install success.	87	mindstudio-profiler package install success.
114	```	88	```
115		89
	@@ -150,7 +124,7 @@ msprof --help
150		124
151	卸载成功打印如下信息：	125	卸载成功打印如下信息：
152		126
153	- ```ColdFusion	127	+ ```text
154	Successfully uninstalled 1 tool ({tools_name})	128	Successfully uninstalled 1 tool ({tools_name})
155	```	129	```
156		130
	@@ -162,17 +136,7 @@ msprof --help
162		136
163	## 6. 附录	137	## 6. 附录
164		138
165	-### 6.1 编译run包参数说明	139	+### 6.1 安装run包参数说明
166	-
167	-msProf工具run包的编译命令可配置如下参数。
168	-
169	-\| 参数 \| 可选/必选 \| 说明 \|
170	-\| ------------ \| --------- \|--------------------------------------------------------------------------------------------------------------------------\|
171	-\| --build_type \| 可选 \| 编译run包类型，可取值：<br>• Release：编译出用于生产环境部署的软件包。<br>• Debug：编译出用于开发调试的软件包（只支持编译解析部分的Debug软件包）。<br>默认值为Release。 \|
172	-\| --mode \| 可选 \| 编译run包方式。可取值：<br>• all：编译出包含msProf采集和解析功能的软件包。<br>• analysis：编译出仅包含msProf解析功能的软件包。<br>默认值为analysis。 \|
173	-\| --version \| 可选 \| 配置run包的版本号，用户自定义。<br>默认值为none。 \|
174	-
175	-### 6.2 安装run包参数说明
176		140
177	msProf工具run包的安装命令可配置如下参数。	141	msProf工具run包的安装命令可配置如下参数。
178		142