👋 您好,欢迎向 MindStudio Probe 提交 Issue！
我们已收到您的反馈，感谢你对开源社区的支持。🎉

📅处理时效： 维护团队将在24小时内 查看并回复您的问题（工作日）。
🔍自助查询： 在等待期间，建议您先查阅以下资料，可能已有解决方案：

📖 MindStudio Probe官方文档
📝 贡献者指南

请确保 Issue 描述清晰，包含复现步骤和日志，这将帮助我们更快定位问题。谢谢！

/label add triaged

认领这个任务

认领这个任务

@asdf1998

您好， 感谢认领本任务。为了方便任务跟进和奖励发放，请将您的联系方式和对应issue ID，发至邮箱 jiandaobao19@163.com

认领这个任务

RFC v0.1：趋势可视化 dump 数据多进程解析设计

1. 背景

趋势可视化工具通过 msprobe data2db 命令，将 msProbe 采集的 dump 或 monitor 数据解析并写入 SQLite 格式的 .trend.db 文件。

当前 --process_num 参数已经支持 monitor 数据的并行处理，但 dump 数据仍采用单进程方式，按照 step、rank 依次读取和处理 dump.json。当 dump 数据包含较多 step 或 rank 时，处理时间会随文件数量增加。

本设计拟为 dump 数据解析增加多进程能力，在保证处理结果正确且与单进程一致的前提下，提高多 dump 文件场景的处理性能。

2. 设计目标

1. msprobe data2db --format dump 支持通过 --process_num 指定并行解析进程数。
2. --format auto 检测到 dump 数据时，--process_num 同样生效。
3. process_num=1 时保持现有单进程行为。
4. 单进程与多进程生成的数据库 schema 和各表数据保持一致。
5. 支持多 step、多 rank 以及 micro-step 场景。
6. 不修改现有 dump 数据目录格式、mapping 规则和 .trend.db 数据库格式。
7. 子进程异常能够反馈给主进程，避免静默生成不完整的数据库。

3. 非目标

1. 不修改趋势可视化前端。
2. 不修改 monitor 数据现有的多进程处理逻辑。
3. 不修改 dump 数据采集逻辑。
4. 不对最终 SQLite 写入过程进行多进程并发写。

4. 当前实现分析

当前 dump 数据解析的主要调用链如下：

msprobe data2db
  -> DBImporter.import_dump_data()
  -> scan_files()
  -> DumpRecordBuilder.import_data()
  -> DumpRecordBuilder._process_dump_file()
  -> DumpDB 写入 SQLite

涉及的主要文件：

python/msprobe/core/compare/data2db.py
python/msprobe/core/dump/dump2db/dump2db.py
python/msprobe/core/dump/dump2db/db_utils.py

当前实现存在以下特点：

1. data2db.py 已经解析和校验 process_num，但该参数只传递给 monitor 数据解析流程。
2. DumpRecordBuilder.import_data() 按照 step、rank 串行调用 _process_dump_file()。
3. _process_dump_file() 同时承担 JSON 解析、target 缓存以及数据库写入。
4. micro_step=True 时，下一 step 的起始位置依赖当前 step 下所有 rank 的最大 micro-step 数量。
5. DumpDB 在内存中维护 target 缓存，并依赖稳定的处理顺序分配 target ID。

因此，不适合直接让多个子进程同时使用 DumpDB 写入同一个 SQLite 文件。这样可能产生 SQLite 写锁竞争、target ID 顺序不稳定以及缓存不一致等问题。

5. 总体方案

采用“子进程并行解析，主进程确定性写库”的两阶段方案。

扫描 dump 文件
      |
      v
生成并排序解析任务
      |
      v
计算各 step 的全局 step 偏移
      |
      v
子进程并行解析 dump.json
      |
      v
返回不包含数据库 ID 的规范化记录
      |
      v
主进程按照固定顺序写入 SQLite
      |
      v
生成 global_stats 和 tag 映射

子进程只负责文件解析和数据转换，不直接访问最终数据库；主进程负责 target ID 分配、批量写库和最终统计，保证数据库内容和写入顺序稳定。

6. 详细设计

6.1 参数传递

修改 DBImporter.import_dump_data()，将 self.process_num 传递给 DumpRecordBuilder。

process_num 继续复用现有校验规则：

• 必须为正整数；
• 最大值为 128；
• 实际 worker 数量取 min(process_num, dump_file_count)。

process_num=1 时继续使用现有串行路径，避免小数据场景产生额外的进程创建和进程间通信开销。

6.2 任务生成

scan_files() 的返回结果保持不变。

在 DumpRecordBuilder.import_data() 中，将扫描结果转换为解析任务。每个任务对应一个 dump 文件，包含：

original_step
rank
dump_json_path
construct_json_path

所有任务在提交给进程池前按照以下顺序排序：

original_step ASC, rank ASC

该顺序同时作为主进程后续消费结果和分配 target ID 的确定顺序。

6.3 micro-step 全局偏移

当 micro_step=False 时，数据库中的 step 继续使用原始 step 编号。

当 micro_step=True 时：

1. 读取各任务对应的 construct.json；
2. 计算每个 (step, rank) 对应的 micro-step 数量；
3. 对同一个原始 step，取所有 rank 中的最大 micro-step 数量；
4. 按原始 step 排序计算前缀和；
5. 得到每个原始 step 对应的全局起始 step。

示例：

step0 最大 micro-step 数：2
step1 最大 micro-step 数：3
step2 最大 micro-step 数：1

对应的全局起始位置为：

step0 -> 0
step1 -> 2
step2 -> 5

子进程在解析记录时，根据全局起始位置和记录所属的本地 micro-step 计算最终 step：

global_step = step_start_offset + local_micro_step

6.4 子进程解析

将 _process_dump_file() 中不依赖数据库的逻辑抽取为模块级 worker 函数，确保可以被 ProcessPoolExecutor 调用。

worker 负责：

1. 加载 dump.json；
2. 加载和处理必要的 construct 信息；
3. 应用 mapping；
4. 判断数据所属的 metric 类型：
   • forward；
   • backward；
   • recompute；
   • parameters_grad；
5. 解析 input、output、parameters 等 tensor 数据；
6. 执行现有的数值转换逻辑；
7. 返回规范化记录。

规范化记录不携带 target_id 和 metric_id，至少包含：

rank
global_step
metric_name
target_name
vpp_stage
target_micro_step
norm
max
min
mean

worker 不创建 DumpDB，不共享 SQLite 连接，也不写最终数据库。

6.5 主进程写库

主进程按照任务的 (original_step, rank) 顺序消费 worker 结果。

对于每一个解析结果，主进程复用现有 DumpDB 能力：

1. 根据 metric_name 获取 metric_id；
2. 调用 cache_targets() 缓存 target；
3. 批量调用 batch_insert_targets() 分配并刷新 target_id；
4. 调用 batch_insert_data() 写入 trend_data；
5. 全部文件处理完成后写入 global_stats；
6. 调用 extract_tags_from_processed_targets() 生成 tag 及 target 映射。

由于 target 只在主进程中按照固定顺序处理，单进程和多进程可以保持稳定的 target ID 和数据顺序。

6.6 内存控制

单个 dump.json 可能包含较多记录。如果一次提交全部任务，已经完成但尚未消费的结果可能占用较多内存。

计划采用有界的 in-flight 任务窗口，例如：

max_in_flight = max_workers * 2

执行过程：

1. 最多提交 max_in_flight 个任务；
2. 主进程消费下一个应处理任务的结果；
3. 结果完成写库并释放后，再提交后续任务；
4. 始终限制同时保留在内存中的解析结果数量。

数据库写入继续使用现有 Data2DBConst.BATCH_SIZE 进行分批处理。

6.7 异常处理

1. worker 解析失败时，将异常和对应文件路径反馈给主进程。
2. 主进程记录具体失败的 step、rank 和文件路径。
3. 任一任务失败时，取消尚未执行的任务，并使本次转换明确失败。
4. 不将部分写入的数据库报告为成功结果。
5. 空目录、缺少 dump 文件、非法字段和不支持 dtype 等场景保持现有行为。

7. 兼容性

以下行为保持不变：

1. rankN 和 procN 目录的扫描及映射规则；
2. mapping 替换规则；
3. forward、backward、recompute、parameters_grad 的识别规则；
4. 支持的 Tensor 类型和 dtype；
5. micro_step=False 时使用原始 step 编号；
6. .trend.db 文件名和数据库 schema；
7. --format auto、dump、monitor 的命令行使用方式。

8. 测试方案

8.1 单元测试

新增或补充以下测试：

1. DBImporter 正确向 dump builder 传递 process_num；
2. process_num=1 使用串行路径；
3. process_num=2/4 使用多进程路径；
4. process 数量大于 dump 文件数量；
5. worker 任务生成和排序；
6. micro-step 数量合并和全局偏移计算；
7. 同一 step 下不同 rank 的 micro-step 数量不同；
8. step 编号不连续；
9. mapping 生效；
10. procN 目录映射；
11. forward、backward、recompute、parameters_grad 数据解析；
12. 空数据和非法字段；
13. worker 异常能够传递到主进程；
14. 失败时不会报告转换成功。

8.2 单进程与多进程等价性测试

准备包含多个 step、rank 和 metric 类型的固定测试数据，分别执行：

msprobe data2db \
  --data <dump_path> \
  --db <single_process_output> \
  --format dump \
  --process_num 1

msprobe data2db \
  --data <dump_path> \
  --db <multi_process_output> \
  --format dump \
  --process_num 2

msprobe data2db \
  --data <dump_path> \
  --db <multi_process_output_4> \
  --format dump \
  --process_num 4

对生成的数据库逐表比较：

global_stats
monitoring_metrics
monitoring_targets
trend_data
monitoring_tags
tag_target_mapping

比较时按照确定字段排序，验证：

1. 表结构一致；
2. 记录数量一致；
3. 全字段数据一致；
4. target、metric 和 tag 的关联关系一致；
5. micro_step=True/False 两种模式均一致。

8.3 性能测试

准备以下测试场景：

1. 多 rank：1 step × 32 rank；
2. 多 step：32 step × 1 rank；
3. 多 step、多 rank：32 step × 4 rank。

分别使用：

process_num=1
process_num=2
process_num=4
process_num=8

每组运行三次，记录：

1. 测试机器 CPU、内存和 Python 版本；
2. dump 文件数量和总大小；
3. 数据库最终记录数量；
4. 三次运行的中位耗时；
5. 相对单进程的加速比；
6. 峰值内存占用；
7. 单进程和多进程输出一致性结果。

9. 文档修改

更新以下文档：

docs/zh/user_guide/accuracy_compare/trend_visualization_instruct.md
docs/en/accuracy_compare/trend_visualization_instruct.md

修改内容：

1. 删除 --process_num “仅用于 monitor 数据”的限制说明；
2. 说明 dump 和 monitor 数据均支持该参数；
3. 增加 dump 数据多进程解析示例；
4. 说明小数据场景建议保持默认值 1。

同时修改 data2db.py 中 --process_num 的 CLI help，使其不再只描述 monitor 数据。

10. 预计修改文件

python/msprobe/core/compare/data2db.py
python/msprobe/core/dump/dump2db/dump2db.py
python/msprobe/core/dump/dump2db/db_utils.py（如需要）
test/msprobe_test/core_ut/compare/test_data2db.py
test/msprobe_test/core_ut/dump/dump2db/test_dump2db.py
docs/zh/user_guide/accuracy_compare/trend_visualization_instruct.md
docs/en/accuracy_compare/trend_visualization_instruct.md

11. 当前进度

• 完成需求分析；
• 完成现有代码调用链分析；
• 完成多进程方案设计；
• 完成测试方案设计；
• 补充单进程/多进程数据库等价性测试；
• 实现 dump 文件多进程解析；
• 执行性能测试；
• 更新中英文用户文档；
• 提交 PR。

12. 后续计划

1. 构造多 step、多 rank 的固定测试数据；
2. 优先完成单进程与多进程数据库逐表等价性测试；
3. 拆分 _process_dump_file() 中的纯解析逻辑和数据库写入逻辑；
4. 实现多进程任务调度及有界任务窗口；
5. 完成功能测试和性能测试；
6. 更新中英文文档并提交 PR。

我要认领这个任务