fix&docs: fix and optimize some features and update ci

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,13 @@
 <!-- Demo: https://github.com/PaddlePaddle/PaDiff/pull/2 -->
+
 ### PR types
+
 <!-- One of [ New features | Bug fixes | Function optimization | Performance optimization | Breaking changes | Others ] -->
 
 ### PR changes
+
 <!-- One of [ APIs | Docs | Others ] -->
 
 ### Description
+
 <!-- Describe what this PR does -->

.github/workflows/docs-check.yml

@@ -13,48 +13,28 @@ on:
       - '**.rst'
 
 jobs:
-  link-check:
-    name: Check Links
+  docs-check:
+    name: Validate Documentation
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Check Markdown Links
-        uses: gaurav0/markdown-link-check@v1
+      - name: Check Markdown Links (Rust)
+        uses: lycheeverse/lychee-action@v2.6.1
         with:
-          use-quiet-mode: 'yes'
-          use-verbose-mode: 'no'
+          args: --verbose docs/**/*.md *.md
 
-  spell-check:
-    name: Spell Check
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Spell Check
-        uses: streetsidesoftware/action-spellcheck@v0
+      - name: Run Spell Check (cspell)
+        uses: streetsidesoftware/cspell-action@v2
         with:
-          check-co-authored-commits: true
+          files: docs/**/*.md *.md
 
-  format-check:
-    name: Format Check
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-
-      - name: Install Prettier
-        run: npm install --global prettier
+      - name: Cleanup temporary files
+        run: |
+          rm -rf lychee/
 
-      - name: Check Markdown Format
+      - name: Format Check with Prettier
         run: |
-          # 使用 prettier 检查格式，但不自动修改
+          npm install -g prettier
           npx prettier --check "docs/**/*.md" "**/*.md"
-          # 如果格式不正确，此命令会失败，CI 将标记为失败

README.md

@@ -1,58 +1,18 @@
 # PaDiff ![](https://img.shields.io/badge/version-v0.1-brightgreen) ![](https://img.shields.io/badge/docs-latest-brightgreen) ![](https://img.shields.io/badge/PRs-welcome-orange) ![](https://img.shields.io/badge/pre--commit-Yes-brightgreen)
 
+**P**addle **A**utomatically **Diff** precision toolkits.
 
-**P**addle  **A**utomatically  **Diff**  precision toolkits.
-
-
-## 最近更新（latest 9.8）
+## 最近更新（latest 9.11）
 
 ### 使用单行命令对齐（支持前反向对齐）
 
-运行命令前，请运行 `python -m padiff.cli -h` 获取更详细的参数说明。
-
-直接通过命令行运行
-
-```sh
-python -m padiff.cli \
-  --pt_cmd "python torch_project/run.py" \
-  --pd_cmd "python paddle_project/run.py" \
-  --pt_model_name "pt_model" \
-  --pd_model_name "pd_model" \
-  --pt_optim_name "pt_optimizer" \
-  --pd_optim_name "pd_optimizer" \
-  --log_dir "./padiff_log" \
-  --align_depth 1 \
-  --single_step_mode "forward" \
-  --atol 1e-4 \
-  --rtol 1e-5 \
-  --compare_mode mean \
-  --action_name equal
-```
-
-或将命令写入 .yaml 文件后，运行
+将命令写入配置文件后，通过如下命令运行：
 
 ```sh
 python -m padiff.cli --config padiff_config.yaml
 ```
 
-yaml 文件样例
-
-```python
-# padiff_config.yaml
-pt_cmd: "python transformer4sr/train_transformer.py"
-pd_cmd: "python paddle_project/train_transformer.py"
-pt_model_name: "transformer_pt"
-pd_model_name: "transformer_pd"
-pt_optim_name: "optimizer_pt"
-pd_optim_name: "optimizer_pd"
-log_dir: "./padiff_log"
-align_depth: 2
-single_step_mode: "forward"
-atol: 1.0e-04
-rtol: 1.0e-05
-compare_mode: "mean"
-action_name: "equal"
-```
+完整文件示例请参考 [配置文件说明文档](docs/CLIConfig.md)，同时，运行命令前，请运行 `python -m padiff.cli -h` 获取更详细的参数说明。
 
 ### log 设置
 
@@ -62,37 +22,31 @@ action_name: "equal"
 
 #### 开启静默模式
 
-或者为了保持控制台信息简洁，可以设置环境变量 `PADIFF_SILENT=1`，以便仅保存 log 文件，不在控制台输出 log 信息
-
+为了保持控制台信息简洁，可以设置环境变量 `PADIFF_SILENT=1`，此模式下仅保存 log 文件，不在控制台输出 log 信息
 
 ## 简介
 
 PaDiff 是基于 PaddlePaddle 与 PyTorch 的模型精度对齐工具。传入 Paddle 或 Torch 模型，对齐训练中间结果以及训练后的模型权重，并提示精度 diff 第一次出现的位置。
 
--   文档目录 [Guides](docs/README.md)
--   使用教程 [Tutorial](docs/Tutorial.md)
--   对齐ViTPose流程 [ViTPose](docs/CheckViTPose.md)
--   接口参数说明 [Interface](docs/Interfaces.md)
--   常见问题解答 [FAQs](docs/FAQs.md)
-
-
-
+- 文档目录 [Guides](docs/README.md)
+- 使用教程 [Tutorial](docs/Tutorial.md)
+- 对齐ViTPose流程 [ViTPose](docs/CheckViTPose.md)
+- 接口参数说明 [Interface](docs/Interfaces.md)
+- 常见问题解答 [FAQs](docs/FAQs.md)
 
 ## 安装
 
-  PaDiff v0.2 版本已发布，可通过如下命令安装：
+PaDiff v0.2 版本已发布，可通过如下命令安装：
 
-  ```
+```
 pip install padiff
-  ```
+```
 
-  尝鲜版或开发者推荐clone源码并使用如下命令安装：
+尝鲜版或开发者推荐clone源码并使用如下命令安装：
 
-  ```
+```
 python setup.py install
-  ```
-
-
+```
 
 ## 快速开始
 
@@ -129,8 +83,6 @@ inp = ({'x': torch.as_tensor(inp) },
 auto_diff(module, layer, inp, atol=1e-4, auto_init=True)
 ```
 
-
-
 ### 离线对齐
 
 ```py
@@ -202,7 +154,8 @@ for i in range(6):
 ```
 
 ### 框架与编译器对齐
-使用文档 [CINN](padiff/cinn_diff/README.md)
+
+使用文档 [CINN](padiff/experimental/cinn_diff/README.md)
 
 ```python
 import os
@@ -223,6 +176,6 @@ if __name__ == '__main__':
 
 ## 已支持 `Special Init` 的组件
 
--   MultiHeadAttention
--   LSTM
--   BatchNorm2D
+- MultiHeadAttention
+- LSTM
+- BatchNorm2D

docs/CLIConfig.md

@@ -0,0 +1,162 @@
+# PaDiff 配置文件参考（命令行运行）
+
+本工具支持代码自动注入，通过命令行运行，运行时通过 YAML 配置文件接收所有参数。
+配置文件分为三个主要部分：`CLI`, `PaDiffGuard`, 和 `COMPARE`。
+
+完整文件示例请参考 [config_example](./config_example.yaml)
+
+## CLI 部分
+
+定义与脚本执行相关的参数。
+
+| 参数            | 类型   | 必需 | 默认值         | 说明                             |
+| --------------- | ------ | ---- | -------------- | -------------------------------- |
+| `pt_cmd`        | string | 是   | -              | 运行 PyTorch 脚本的完整命令      |
+| `pd_cmd`        | string | 是   | -              | 运行 PaddlePaddle 脚本的完整命令 |
+| `pt_model_name` | string | 否   | "model"        | PyTorch 模型实例的变量名         |
+| `pd_model_name` | string | 否   | "model"        | PaddlePaddle 模型实例的变量名    |
+| `pt_optim_name` | string | 否   | null           | PyTorch 优化器实例的变量名       |
+| `pd_optim_name` | string | 否   | null           | PaddlePaddle 优化器实例的变量名  |
+| `log_dir`       | string | 否   | "./padiff_log" | 日志和报告的输出目录             |
+
+## PaDiffGuard 部分
+
+定义模型对齐的核心行为。
+
+| 参数                | 类型         | 必需 | 默认值 | 说明                                                 |
+| ------------------- | ------------ | ---- | ------ | ---------------------------------------------------- |
+| `align_depth`       | int or "inf" | 否   | "inf"  | 对齐的深度。"inf" 表示最细粒度                       |
+| `single_step_mode`  | string       | 否   | null   | 单步对齐模式 ("forward", "backward", "both")         |
+| `load_init_weights` | bool         | 否   | false  | 是否自动对齐初始化权重，若已手动对齐，请设置为 false |
+| `load_first_inputs` | bool         | 否   | false  | 是否自动第一次的输入，若已手动对齐，请设置为 false   |
+| `max_calls`         | int          | 否   | 1      | 最大前反向调用次数                                   |
+| `black_list`        | list         | 否   | []     | 不参与对齐的层名列表，列表内元素为 str 类型          |
+| `keys_mapping`      | dict         | 否   | null   | 模型参数名映射字典                                   |
+
+## COMPARE 部分
+
+定义结果对比的精度和逻辑。
+
+| 参数           | 类型   | 必需 | 默认值  | 说明                                    |
+| -------------- | ------ | ---- | ------- | --------------------------------------- |
+| `atol`         | float  | 否   | 1e-6    | 绝对误差容忍度                          |
+| `rtol`         | float  | 否   | 1e-6    | 相对误差容忍度                          |
+| `compare_mode` | string | 否   | "mean"  | 对比模式 ("mean", "strict", "abs_mean") |
+| `action_name`  | string | 否   | "equal" | 对比动作 ("equal", "loose_equal")       |
+
+## 示例和详细说明
+
+#### 命令参数 (pt_cmd, --pd_cmd)
+
+- 这些参数是您运行原始模型的完整命令
+- 通常以 'python' 开头
+- 必须指向包含您模型代码的 Python 脚本
+- 必需被包含在 config 文件中，或通过命令行传入
+
+```
+pt_cmd: "python torch_project/run.py"
+pd_cmd: "python paddle_project/run.py"
+```
+
+#### 模型变量名参数 (pt_model_name, pd_model_name)
+
+- 这些参数指定您在脚本中创建模型实例的**变量名**
+- 它们不是类名，也不是文件名
+- 它们是模型实例化时 `=` 左边的标识符
+
+```
+# 如果您的 PyTorch 脚本中有：
+my_torch_model = MyNet()
+output = my_torch_model(input_tensor)
+# 那么应该使用：
+pt_model_name: "my_torch_model"
+
+# 如果您的 Paddle 脚本中有：
+net = SimplePaddle()
+out = net.generate(input_tensor)
+# 那么应该使用：
+pd_model_name: "net"
+
+# 如果您的 Paddle 脚本中有：
+trainer = SFTTrainer(
+    args=training_args,
+    model="Qwen/Qwen2.5-0.5B-Instruct",
+    train_dataset=dataset,
+)
+trainer.train()
+那么应该使用：
+pd_model_name: "trainer.model"
+```
+
+#### 优化器名参数 (pt_optim_name, pd_optim_name)
+
+- 这些参数指定您在脚本中创建优化器实例的**变量名**。
+- 它们不是类名，也不是文件名。
+- 它们是优化器实例化时 `=` 左边的标识符。
+- 该参数为非必须参数，默认值: None (不传递优化器)
+
+```
+# 如果您的 PyTorch 脚本中有：
+optim = torch.optim.Adam(
+    transformer.parameters(),
+    lr=1.0,
+    betas=(0.9, 0.98),
+    eps=1e-9,
+)
+# 那么应该使用：
+pt_optim_name: "optim"
+
+# 如果您的 Paddle 脚本中有：
+trainer = SFTTrainer(
+    args=training_args,
+    model="Qwen/Qwen2.5-0.5B-Instruct",
+    train_dataset=dataset,
+)
+trainer.train()
+# 由于 trainer.train() 中通常已经包含了完整的前反向过程，因此不需要传递此参数
+```
+
+#### 日志目录参数 (log_dir)
+
+- 指定生成报告和日志的目录
+- 默认值: ./padiff_log
+
+```
+log_dir: "./padiff_log"
+```
+
+#### 对齐深度参数 (align_depth)
+
+- 控制对齐的粒度。通过指定一个深度值，可以忽略该深度以下的所有子模块
+- 值为整数: 指定一个具体的深度。例如，--align_depth 1 会忽略深度为1及以下的所有子模块
+- 默认值: 'inf' ，即无限深度，会对齐到最细粒度的层（如 Linear, ReLU）
+- 值为整数，当数值超过模型最大迭代深度时，相当于 'inf'
+
+```
+align_depth: 0   # 只对齐顶层模块
+align_depth: 1   # 对齐到第一层子模块
+align_depth: "inf" # 对齐到最细粒度
+```
+
+#### 单步对齐模式参数 (single_step_mode)
+
+- 启用逐层对齐模式
+- 可选值: forward, backward, both
+- 默认值: None (不启用)
+- 当启用时，工具会从自动加载基准模型的输出，并用其替换对齐模型的相应层输出
+
+#### 结果对比参数（COMPARE）
+
+- 控制模型输出结果的对比精度和模式
+- atol: 绝对误差容忍度 (default: 1e-6)
+- rtol: 相对误差容忍度 (default: 1e-6)
+- compare_mode: 对比模式，具体内容请看对应文档。可选值: mean, strict, abs_mean, 默认值: "mean"
+- action_name: 对比行为，具体内容请看对应文档。可选值: equal, loose_equal, 默认值: "equal"
+
+```
+COMPARE:
+    atol: 1e-4
+    rtol: 1e-5
+    compare_mode: "mean"
+    action_name: "loose_equal"
+```