docs: 修正ATB_BUILD_DEPENDENCY_PATH及ABI判断说明(含README/FAQ/测试框架指南)-ascend-transformer-boost-AtomGit

已合并

docs: 修正ATB_BUILD_DEPENDENCY_PATH及ABI判断说明(含README/FAQ/测试框架指南) #2136

zouyanlong创建于 6月24日从ninihihi/ascend-transformer-boost： fix/readme-abi-version-clarify 合入到 cann/ascend-transformer-boost： master

docs: 修正ATB_BUILD_DEPENDENCY_PATH及ABI判断说明(含README/FAQ/测试框架指南) #2136

已合并

zouyanlong创建于 6月24日

从ninihihi/ascend-transformer-boost fix/readme-abi-version-clarify合入到cann/ascend-transformer-boost master

共 3 个文件变更+26-27

MREADME.md+2-2

	@@ -134,13 +134,13 @@ chmod +x Ascend-cann-${chip_type}-ops_${VERSION}_linux-$(arch).run #其中${chi
134		134
135	您可自行选择需要的分支。	135	您可自行选择需要的分支。
136	- 环境变量设置	136	- 环境变量设置
137	- 在编译前，需要安装nnal软件包（安装方法请查看[常见问题与回答](docs/常见问题与回答.md#run-package-usage)），并根据nnal安装路径设置环境变量`ATB_BUILD_DEPENDENCY_PATH`：	137	+ 在编译前，需要安装nnal软件包。若 nnal 安装在默认位置（`/usr/local/Ascend/nnal/...`），无需设置`ATB_BUILD_DEPENDENCY_PATH`，脚本会按检测到的 ABI 自动使用该路径。若安装在非默认位置，需手动设置（其中`{cxx_abi_version}`取`0`或`1`）。详见[常见问题与回答](docs/常见问题与回答.md)。
138		138
139	```sh	139	```sh
140	export ATB_BUILD_DEPENDENCY_PATH={nnal install path}/nnal/atb/latest/atb/cxx_abi_{cxx_abi_version}	140	export ATB_BUILD_DEPENDENCY_PATH={nnal install path}/nnal/atb/latest/atb/cxx_abi_{cxx_abi_version}
141	```	141	```
142		142
143	- 注：未设置将使用默认路径`/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_{cxx_abi_version}`	143	+ 注：若此前已用其他 ABI 编译过，切换 ABI 后须执行`bash scripts/build.sh --clean-first`清理编译缓存再重新编译，否则残留的 CMake 缓存与已拷贝的`libtbe_adapter.so`会导致 ABI 不匹配或链接错误。同样，若安装或更换 PyTorch 导致 ABI 判别结果改变，也需重新设置`ATB_BUILD_DEPENDENCY_PATH`并`--clean-first`全量重编译。
144	- 加速库编译	144	- 加速库编译
145	编译加速库，设置加速库环境变量：	145	编译加速库，设置加速库环境变量：
146		146

Mdocs/常见问题与回答.md+22-14

	@@ -1,28 +1,36 @@
1		1
2	# 常见问题与回答	2	# 常见问题与回答
3		3
4	-1. 提示`libtbe_adapter.so does not exit`	4	+1. 提示`libtbe_adapter.so does not exist`
5	- 您可通过安装nnal软件包并设置正确的`ATB_BUILD_DEPENDENCY_PATH`解决该问题	5	+ 您可通过安装nnal软件包解决该问题，`ATB_BUILD_DEPENDENCY_PATH`设置方式见下：
6	- 安装步骤可参考[run包使用](#run-package-usage)	6	- 安装步骤可参考[run包使用](#run-package-usage)
7	- 代码及软件包版本对应关系：	7	- 代码及软件包版本对应关系：
8	nnal软件包需保持和toolkit及kernels软件包版本一致	8	nnal软件包需保持和toolkit及kernels软件包版本一致
9	- - 执行	9	+ - 设置`ATB_BUILD_DEPENDENCY_PATH`（以下二选一）：
		10	+ - 不设置：仅当 nnal 安装在默认位置（`/usr/local/Ascend/nnal/...`，即 root 默认安装路径）时适用；此时脚本会按检测到的 ABI 自动使用默认路径`/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_0`或`cxx_abi_1`，ABI 与编译保持一致，无需手动指定。
		11	+ - 手动设置（nnal 安装在其他位置时）：须保证`cxx_abi_{cxx_abi_version}`与编译实际使用的 ABI 一致。
10		12
11	- ```sh	13	+ ```sh
12	- export ATB_BUILD_DEPENDENCY_PATH={nnal install path}/nnal/atb/latest/atb/cxx_abi_{cxx_abi_version}	14	+ export ATB_BUILD_DEPENDENCY_PATH={nnal install path}/nnal/atb/latest/atb/cxx_abi_{cxx_abi_version}
13	- ```	15	+ ```
14		16
15	- 其中`{cxx_abi_version}`为`0`或`1`，确定方法：	17	+ `{cxx_abi_version}`的确定方法：先判断是否安装 PyTorch——下面命令报错（如`ModuleNotFoundError: No module named 'torch'`）即未安装，正常打印版本号即已安装：
16		18
17	- ```sh	19	+ ```sh
18	- python3 -c "import torch; print(1 if torch.compiled_with_cxx11_abi() else 0)"	20	+ python3 -c "import torch; print(torch.__version__)"
19	- ```	21	+ ```
20		22
21	- - 输出`1`→ 使用`cxx_abi_1`	23	+ - 未安装 PyTorch：使用`cxx_abi_1`
22	- - 输出`0`→ 使用`cxx_abi_0`	24	+ - 已安装 PyTorch：运行下面命令，输出`1`用`cxx_abi_1`，输出`0`用`cxx_abi_0`
23	- - 若未安装PyTorch，默认使用`cxx_abi_1`
24		25
25	- 注：未设置将使用默认路径`/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_{cxx_abi_version}`	26	+ ```sh
		27	+ python3 -c "import torch; print(1 if torch.compiled_with_cxx11_abi() else 0)"
		28	+ ```
		29	+
		30	+ 示例（nnal 安装在`/home/user/Ascend/nnal`）：
		31	+
		32	+ - 未安装 PyTorch：`export ATB_BUILD_DEPENDENCY_PATH=/home/user/Ascend/nnal/atb/latest/atb/cxx_abi_1`
		33	+ - 已安装 PyTorch 且输出`0`：`export ATB_BUILD_DEPENDENCY_PATH=/home/user/Ascend/nnal/atb/latest/atb/cxx_abi_0`
26	- run包使用<a id="run-package-usage"></a>	34	- run包使用<a id="run-package-usage"></a>
27	- run包获取	35	- run包获取
28	1. 进入网址：https://www.hiascend.com/developer/download/community	36	1. 进入网址：https://www.hiascend.com/developer/download/community

Mdocs/测试框架指南.md+2-11

	@@ -38,17 +38,6 @@ PyTorch及torch_npu的安装请参考[昇腾PyTorch安装指南](https://www.hia
38		38
39	其他Python三方库依赖见`tests/framework/python/CsvOpsTestTool/requirements.txt`。	39	其他Python三方库依赖见`tests/framework/python/CsvOpsTestTool/requirements.txt`。
40		40
41	-### CXX ABI版本确定
42	-
43	-`testframework`编译产物路径依赖正确的ABI版本（`cxx_abi_0`或`cxx_abi_1`），判断方法：
44	-
45	-```shell
46	-python3 -c "import torch; print(torch.compiled_with_cxx11_abi())"
47	-```
48	-
49	-- 输出`True`或torch未安装 → 使用`--cxx_abi=1`（`--use_cxx11_abi=1`）
50	-- 输出`False` → 使用`--cxx_abi=0`（`--use_cxx11_abi=0`）
51	-
52	### 常见编译失败	41	### 常见编译失败
53		42
54	\| 错误信息 \| 原因 \| 解决方法 \|	43	\| 错误信息 \| 原因 \| 解决方法 \|
	@@ -86,6 +75,8 @@ bash scripts/build.sh testframework
86	```	75	```
87		76
88	> 注意：不要删除`build/`目录，不要加`--clean-first`，增量编译即可。仅在CMake配置变更或算子内核文件（`.cce`）变动时才需要`--clean-first`，因为CMake无法自动检测内核文件变更。	77	> 注意：不要删除`build/`目录，不要加`--clean-first`，增量编译即可。仅在CMake配置变更或算子内核文件（`.cce`）变动时才需要`--clean-first`，因为CMake无法自动检测内核文件变更。
		78	+>
		79	+> 特别地，若环境发生变动（如安装或更换 PyTorch 版本）导致 ABI 判别结果改变（例如从未装 PyTorch 的 `cxx_abi_1` 变为已装旧 ABI PyTorch 的 `cxx_abi_0`），需重新设置`ATB_BUILD_DEPENDENCY_PATH`为匹配的 ABI 路径，并执行`bash scripts/build.sh --clean-first testframework`全量重编译。
89		80
90	### 编译产物	81	### 编译产物
91		82