From 06ddf1ddbfc805d5e032991652943a7ef5ea3c96 Mon Sep 17 00:00:00 2001
From: Dayuxiaoshui <792179245@qq.com>
Date: Fri, 21 Nov 2025 21:26:31 +0800
Subject: [PATCH 1/2] docs: Add PyTorch to Paddle conversion design document
- Add comprehensive design document for torch_to_paddle conversion task
- Document sample structure analysis and file conversion strategies
- Design modular architecture with convert.py, test.py, and utils.py
- Include risk assessment and mitigation strategies
- Define implementation phases and success criteria
---
docs/torch_to_paddle_conversion_design.md | 528 ++++++++++++++++++++++
1 file changed, 528 insertions(+)
create mode 100644 docs/torch_to_paddle_conversion_design.md
diff --git a/docs/torch_to_paddle_conversion_design.md b/docs/torch_to_paddle_conversion_design.md
new file mode 100644
index 000000000..aa403af5c
--- /dev/null
+++ b/docs/torch_to_paddle_conversion_design.md
@@ -0,0 +1,528 @@
+# PyTorch to Paddle 计算图转换设计方案
+
+## 1. 背景与目标
+
+### 1.1 背景
+GraphNet 项目包含大量从 PyTorch 提取的计算图样本（位于 `samples/` 目录），需要将这些样本转换为 PaddlePaddle 格式，以扩展 Paddle 样本库并支持跨框架对比分析。
+
+### 1.2 目标
+- 使用 PaConvert 工具将 `samples/` 中的 PyTorch 样本批量转换为 Paddle 格式
+- 转换后样本保存到 `torch_to_paddle_samples/` 目录
+- 对转换后的样本进行批量测试验证
+- 生成两个模型列表文件：
+ - `torch_to_paddle_samples_list_full.txt`: 仅剔除转换失败的样本
+ - `torch_to_paddle_samples_list.txt`: 剔除转换失败和测试失败的样本
+- 记录详细的转换和测试日志，分析失败原因
+
+## 2. 样本结构分析
+
+### 2.1 PyTorch 样本文件结构
+每个 PyTorch 样本目录包含以下文件：
+
+```
+samples/{source}/{model_name}/
+├── model.py # 必需：包含 GraphModule(torch.nn.Module) 类定义
+├── graph_net.json # 必需：元数据配置（framework: "torch"）
+├── graph_hash.txt # 必需：计算图哈希值（用于去重）
+├── input_meta.py # 必需：输入张量元数据（可能为空）
+└── weight_meta.py # 必需：权重张量元数据（包含 torch 类型字符串）
+```
+
+### 2.2 关键文件分析
+
+#### 2.2.1 model.py
+- **特点**：自动生成的计算图代码，包含大量低级 API 调用
+ - 使用 `torch.conv2d()`, `torch.nn.functional.batch_norm()` 等函数式 API
+ - 参数名自动生成（如 `L_self_modules_conv1_parameters_weight_`）
+ - 代码结构扁平，不是典型的 PyTorch 模型定义
+- **转换挑战**：PaConvert 主要针对标准 PyTorch 代码，可能无法完全处理这种格式
+- **处理策略**：
+ 1. 优先使用 PaConvert 自动转换
+ 2. 对于转换失败或部分转换的情况，需要手动修复或使用 AST 解析进行后处理
+ 3. 记录所有需要手动修复的案例
+
+#### 2.2.2 weight_meta.py
+- **特点**：包含元数据类定义，其中 `dtype` 字段为字符串（如 `"torch.float32"`）
+- **需要转换**：`"torch.float32"` → `"paddle.float32"`, `"torch.int64"` → `"paddle.int64"` 等
+- **处理策略**：使用正则表达式或 AST 解析进行批量替换
+
+#### 2.2.3 graph_net.json
+- **特点**：JSON 配置文件
+- **需要修改**：`"framework": "torch"` → `"framework": "paddle"`
+- **处理策略**：直接修改 JSON 文件
+
+#### 2.2.4 input_meta.py
+- **特点**：可能为空文件或包含输入元数据
+- **处理策略**：检查是否包含 torch 相关代码，如有则转换
+
+#### 2.2.5 graph_hash.txt
+- **特点**：计算图哈希值
+- **处理策略**：转换后重新生成（使用 `graph_net.paddle.validate` 的 `--no-dump-graph-hash-key` 选项）
+
+## 3. 系统架构设计
+
+### 3.1 目录结构
+
+```
+tools/torch_to_paddle/
+├── __init__.py
+├── convert.py # 转换主脚本
+├── test.py # 测试主脚本
+├── utils.py # 工具函数模块
+├── file_processors.py # 文件处理模块
+└── logs/ # 日志目录（gitignore）
+ ├── conversion/ # 转换日志
+ │ ├── {timestamp}_conversion_summary.json
+ │ └── {sample_name}_conversion.log
+ └── testing/ # 测试日志
+ ├── {timestamp}_testing_summary.json
+ └── {sample_name}_test.log
+```
+
+### 3.2 模块设计
+
+#### 3.2.1 utils.py - 工具函数模块
+
+**功能**：
+- 路径处理：相对路径 ↔ 绝对路径转换
+- 日志管理：统一日志格式、日志文件命名
+- 报告生成：统计转换/测试成功率、失败原因分析
+- 列表文件生成：生成模型列表文件
+
+**关键函数**：
+```python
+def get_torch_samples_list(config_path: str) -> list[str]:
+ """从 torch_samples_list.txt 读取所有样本路径"""
+
+def normalize_path(path: str, root_dir: str) -> str:
+ """标准化路径（相对路径转绝对路径）"""
+
+def setup_logging(log_dir: str, sample_name: str, log_type: str) -> logging.Logger:
+ """设置日志记录器"""
+
+def generate_summary_report(results: list[dict], output_path: str):
+ """生成汇总报告（JSON 格式）"""
+
+def generate_list_file(sample_paths: list[str], output_path: str):
+ """生成模型列表文件"""
+```
+
+#### 3.2.2 file_processors.py - 文件处理模块
+
+**功能**：
+- 处理不同类型的文件转换
+- 提供统一的文件处理接口
+
+**关键函数**：
+```python
+def convert_model_py(source_path: str, target_path: str, log: logging.Logger) -> dict:
+ """
+ 转换 model.py 文件
+ 返回: {
+ "status": "success|failed|partial",
+ "error": "错误信息（如有）",
+ "requires_manual_fix": bool
+ }
+ """
+
+def convert_weight_meta_py(source_path: str, target_path: str, log: logging.Logger) -> dict:
+ """转换 weight_meta.py 文件（替换 torch 类型字符串）"""
+
+def convert_input_meta_py(source_path: str, target_path: str, log: logging.Logger) -> dict:
+ """转换 input_meta.py 文件（如需要）"""
+
+def convert_graph_net_json(source_path: str, target_path: str, log: logging.Logger) -> dict:
+ """修改 graph_net.json（framework: torch -> paddle）"""
+
+def copy_other_files(source_dir: str, target_dir: str, log: logging.Logger):
+ """复制其他文件（如 graph_hash.txt，转换后需要重新生成）"""
+```
+
+#### 3.2.3 convert.py - 转换主脚本
+
+**功能**：
+- 读取 `torch_samples_list.txt` 获取所有样本路径
+- 对每个样本调用文件处理模块进行转换
+- 记录转换日志和失败案例
+- 生成转换报告和 `torch_to_paddle_samples_list_full.txt`
+
+**工作流程**：
+```
+1. 读取配置和样本列表
+2. 创建输出目录结构
+3. 对每个样本：
+ a. 创建目标目录
+ b. 转换 model.py（使用 PaConvert + 后处理）
+ c. 转换 weight_meta.py
+ d. 转换 input_meta.py（如需要）
+ e. 修改 graph_net.json
+ f. 复制其他文件
+ g. 记录转换结果
+4. 生成汇总报告
+5. 生成 torch_to_paddle_samples_list_full.txt
+```
+
+**命令行接口**：
+```bash
+python -m tools.torch_to_paddle.convert \
+ --torch-samples-list graph_net/config/torch_samples_list.txt \
+ --output-dir torch_to_paddle_samples \
+ --log-dir tools/torch_to_paddle/logs/conversion \
+ [--paconvert-path /path/to/paconvert] \
+ [--parallel-workers 4] \
+ [--dry-run]
+```
+
+#### 3.2.4 test.py - 测试主脚本
+
+**功能**：
+- 读取转换后的样本目录
+- 对每个样本运行 Paddle 验证测试
+- 记录测试日志和失败案例
+- 生成测试报告和 `torch_to_paddle_samples_list.txt`
+
+**工作流程**：
+```
+1. 扫描转换后的样本目录
+2. 对每个样本：
+ a. 运行 graph_net.paddle.validate
+ b. 捕获测试结果（成功/失败）
+ c. 记录测试日志
+3. 生成汇总报告
+4. 生成 torch_to_paddle_samples_list.txt（剔除失败样本）
+```
+
+**命令行接口**：
+```bash
+python -m tools.torch_to_paddle.test \
+ --samples-dir torch_to_paddle_samples \
+ --log-dir tools/torch_to_paddle/logs/testing \
+ [--parallel-workers 4] \
+ [--timeout 300] \
+ [--skip-validation]
+```
+
+## 4. 详细设计
+
+### 4.1 PaConvert 集成策略
+
+#### 4.1.1 使用方式
+PaConvert 支持两种使用方式：
+1. **命令行方式**：`paconvert --in_dir --out_dir