[cfg] refactor: Use omegaconf structured configuration system

docs/data/data_specification.md

@@ -236,7 +236,7 @@ python tests/data/check_verl_log.py data/verl_data/good_minimal_verl.log
 
 ## 5. GMM 专家负载dump数据
 
-GMM 热力图输入类型为 `DataEnum.GMM_DATA`（CLI：`--input-type gmm_data`、`--profiler-type gmm`）。**路径约定、参数与示意图**见 [`docs/overview/gmm_heatmap_quickstart.md`](../overview/gmm_heatmap_quickstart.md)。本节补充数据侧目录与文件格式说明。
+GMM 热力图输入类型为 `DataEnum.GMM_DATA`。**路径约定、参数与示意图**见 [`docs/overview/gmm_heatmap_quickstart.md`](../overview/gmm_heatmap_quickstart.md)。本节补充数据侧目录与文件格式说明。
 
 ### 5.1 目录结构
 

docs/developer_guides/extending_guide.md

@@ -18,14 +18,16 @@
 1. 新增模块，例如 `rl_insight/parser/my_parser.py`。
 2. 继承 `BaseClusterParser`，实现 `run()` 方法。
 3. `@register_cluster_parser("<name>")`，保证 `get_cluster_parser_cls("<name>")` 可用。
-4. 更新 `main.py` 中 `--profiler-type` 的 help 与相关用户文档。
+4. 若有配置参数，在 `rl_insight/config/config.py` 对应场景的 `ParserConfig` 中添加字段。
+5. 更新相关用户文档。
 
 **Visualizer**
 
 1. 新增模块，例如 `rl_insight/visualizer/my_visualizer.py`。
 2. 继承 `BaseVisualizer`，实现 `run()` 方法。
 3. `@register_cluster_visualizer("<name>")`，保证 `get_cluster_visualizer_cls("<name>")` 可用。
-4. 更新 `main.py` 中 `--vis-type` 的 help 与相关用户文档。
+4. 若有配置参数，在 `rl_insight/config/config.py` 对应场景的 `VisualizerConfig` 中添加字段。
+5. 更新相关用户文档。
 
 若输入或中间数据形态变化，需同步按上一节扩展 **DataRule**。
 
@@ -34,6 +36,5 @@
 适用于：全新的处理范式（跳过步骤、插入预处理、多产物、在线多进程流程等）。
 
 1. 在 `rl_insight/pipeline/` 新增类，实现 `__init__(self, config)`、`run(self)`，按需组合 `DataChecker`、`get_cluster_parser_cls`、`get_cluster_visualizer_cls` 等。
-2. 在 `main.py` 的 `SUPPORTED_PIPELINE_TYPES` 中注册，例如 `{"MyPipeline": MyPipeline}`。
-3. 更新 `--pipeline-type` 的 help，名称与 dict key 一致，并更新文档。
-4. 若数据解析或数据类型发生变化，同步扩展 **DataRule** / **Parser** / **Visualizer**。
+2. 在 `rl_insight/config/config.py` 的 `PipelineConfig.type` 默认值或 preset YAML 中注册新 pipeline 类型。
+3. 若数据解析或数据类型发生变化，同步扩展 **DataRule** / **Parser** / **Visualizer**。

docs/overview/RL_Timeline_quickstart.md

@@ -56,9 +56,9 @@ pip install -e .
 
 ```bash
 python -m rl_insight.main \
-   --input-path <profiling_data_path> \
-   --profiler-type mstx \
-   --output-path <output_path>
+   input.path=<profiling_data_path> \
+   timeline.parser.type=mstx \
+   output.path=<output_path>
 ```
 
 或修改并直接使用 `examples/mstx_exec.sh` 脚本:
@@ -73,9 +73,9 @@ bash examples/mstx_exec.sh
 
 ```bash
 python -m rl_insight.main \
-    --input-path <torch_profiling_data_path> \
-    --profiler-type torch \
-    --output-path <output_path>
+    input.path=<torch_profiling_data_path> \
+    timeline.parser.type=torch \
+    output.path=<output_path>
 ```
 
 或修改并直接使用 `examples/torch_profiler_exec.sh` 脚本:
@@ -90,9 +90,9 @@ bash examples/torch_profiler_exec.sh
 
 ```bash
 python -m rl_insight.main \
-    --input-path <nvtx_profiling_data_path> \
-    --profiler-type nvtx \
-    --output-path <output_path>
+    input.path=<nvtx_profiling_data_path> \
+    timeline.parser.type=nvtx \
+    output.path=<output_path>
 ```
 
 或修改并直接使用 `examples/nvtx_exec.sh` 脚本:
@@ -103,17 +103,26 @@ bash examples/nvtx_exec.sh
 
 ## 4. 命令行参数
 
-以下说明与 `python -m rl_insight.main --help` 保持一致；若有出入以命令行帮助为准。
+以下说明与 `python -m rl_insight.main -h` 保持一致；若有出入以命令行帮助为准。
+
+### 4.1 公共参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `input.path` | （必填） | Profiling 数据的根目录路径 |
+| `input.rank_list` | `all` | Rank ID 列表，如 `0,1,2` 或 `all` |
+| `output.path` | `output` | 输出目录 |
+| `preset` | 自动推断 | 预设名称：`timeline`、`heatmap`（根据 CLI 参数自动推断） |
+| `config_path` | 无 | YAML 配置文件路径 |
+
+### 4.2 Timeline 专属参数
 
 | 参数 | 默认值 | 说明 |
-|------|--------|----|
-| `--input-path` | （必填，无默认值） | Profiling 数据的根目录路径 |
-| `--input-type` | `multi_json` | 输入数据类型（多目录 JSON 布局等）|
-| `--profiler-type` | `mstx` | 性能数据种类：`mstx`、`torch`、`nvtx` |
-| `--output-path` | `output` | 输出目录 |
-| `--vis-type` | `html` | 可视化类型（当前支持 `html`、`png`） |
-| `--rank-list` | `all` | Rank ID 列表（当前仅支持 `all`） |
-| `--pipeline-type` | `OfflineInsightPipeline` | 流水线实现类型 |
+|------|--------|------|
+| `timeline.parser.type` | `mstx` | 数据源类型：`mstx`、`torch`、`nvtx` |
+| `timeline.visualizer.type` | `html` | 可视化类型：`html`、`png` |
+| `timeline.visualizer.width` | `2000` | 图片宽度（仅 png） |
+| `timeline.visualizer.scale` | `2` | 图片缩放因子（仅 png） |
 
 ## 5. 输出说明
 
@@ -145,7 +154,7 @@ bash examples/nvtx_exec.sh
 
 ## 6. 注意事项
 
-1. RL 分析功能当前仅支持处理所有 Rank（`--rank-list` 参数暂不支持过滤功能）
+1. RL 分析功能当前仅支持处理所有 Rank（`input.rank_list` 参数暂不支持过滤功能）
 2. 至少采集 level0 及以上数据（不支持 level_none 级数据）
 3. 采用离散模式采集 `discrete=True`
 4. MSTX 数据满足以下要求：

docs/overview/architecture.md

@@ -20,7 +20,8 @@
 
 | Concept | Location | Role |
 |---------|----------|------|
-| Entry | `rl_insight/main.py`, `rl_insight/pipeline/` | `main` 对接 CLI；`pipeline` 定义业务流程并选择 **Parser** / **Visualizer**。 |
+| Entry | `rl_insight/main.py`, `rl_insight/pipeline/` | `main` 对接 CLI（`key=value` 格式）；`pipeline` 定义业务流程并选择 **Parser** / **Visualizer**。 |
+| Config | `rl_insight/config/config.py`, `rl_insight/config/config_loader.py` | 基于 OmegaConf 的结构化配置，dataclass 定义 schema 与默认值，支持YAML preset场景化覆盖。 |
 | DataRule | `rl_insight/data/data_checker.py`, `rl_insight/data/rules.py` | `DataEnum` 区分数据阶段；`DataChecker` 按类型执行对应的 `ValidationRule`。 |
 | Parser | `rl_insight/parser/parser.py`, `rl_insight/parser/*_parser.py` | 基于约定的 `input_type` 做解析；字段约定见 `rl_insight/utils/schema.py`（`DataMap`、`EventRow`、`Constant` 等）。 |
 | Visualizer | `rl_insight/visualizer/visualizer.py`, `rl_insight/visualizer/timeline_visualizer.py`, … | 消费 **Parser** 输出，基于约定的 `input_type` 做可视化。 |

docs/overview/gmm_heatmap_quickstart.md

@@ -59,25 +59,24 @@ gmm_dump/
 
 路径字段含义：
 
-- `step_<n>`：训练 step（对应 `--step` 过滤）
-- `<role>`：角色名（对应 `--role` 过滤）
-- `rank<n>`：rank id（对应 `--rank-list` 过滤）
+- `step_<n>`：训练 step（对应 `heatmap.parser.step` 过滤）
+- `<role>`：角色名（对应 `heatmap.parser.role` 过滤）
+- `rank<n>`：rank id（对应 `input.rank_list` 过滤）
 - `dump_tensor_data/*.group_list.pt`：MoE grouped_matmul 的专家负载；典型为一维整型张量，第 `i` 个元素表示第 `i` 个 expert 分到的 **token 数**
 
 ### 2.2 执行分析脚本
 
-#### GMM 热力图使用示例
+#### 热力图使用示例
 
 ```bash
-python -m rl_insight.main
-    --input-path <gmm_data_path>
-    --input-type gmm_data
-    --profiler-type gmm
-    --vis-type gmm_heatmap
-    --rank-list all
-    --step 1
-    --role actor_compute_log_prob
-    --output-path <output_path>
+python -m rl_insight.main \
+    input.path=<gmm_data_path> \
+    input.rank_list=all \
+    heatmap.parser.type=gmm \
+    heatmap.visualizer.type=gmm_heatmap \
+    heatmap.parser.step=1 \
+    heatmap.parser.role=actor_compute_log_prob \
+    output.path=<output_path>
 ```
 
 或修改并直接使用 `examples/gmm_exec.sh` 脚本:
@@ -88,22 +87,29 @@ bash examples/gmm_exec.sh
 
 ## 三、命令行参数
 
-以下说明与 `python -m rl_insight.main --help` 保持一致；若有出入以命令行帮助为准。
+以下说明与 `python -m rl_insight.main -h` 保持一致；若有出入以命令行帮助为准。
+
+### 3.1 公共参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `input.path` | （必填） | GMM 数据的根目录路径 |
+| `output.path` | `output` | 输出路径，若为文件夹则在其中生成 `gmm_heatmap.png` |
+| `input.rank_list` | `all` | Rank ID 列表，默认 `all` 表示所有 rank，可指定多个 rank 用逗号分隔 |
+| `preset` | 自动推断 | 预设名称：`timeline`、`heatmap`（根据 CLI 参数自动推断） |
+| `config_path` | 无 | YAML 配置文件路径 |
+
+### 3.2 Heatmap 专属参数
 
 | 参数 | 默认值 | 说明 |
-|------|--------|----|
-| `--input-path` | （必填，无默认值） | GMM 数据的根目录路径 |
-| `--input-type` | `multi_json_mstx` | 输入数据类型，GMM 功能需设置为 `gmm_data` |
-| `--profiler-type` | `mstx` | 性能数据种类，GMM 功能需设置为 `gmm` |
-| `--output-path` | `output` | 输出路径，若为文件夹则在其中生成 `gmm_heatmap.png` |
-| `--vis-type` | `html` | 可视化类型，GMM 功能需设置为 `gmm_heatmap` |
-| `--rank-list` | `all` | Rank ID 列表，默认 `all` 表示所有 rank,可指定多个 rank 用逗号分隔 |
-| `--pipeline-type` | `OfflineInsightPipeline` | 流水线实现类型 |
-| `--step` | 无默认值 | 特定的 step 进行可视化（可选，支持 `1` 或 `1,2`） |
-| `--role` | 无默认值 | 特定的 role 进行可视化（可选） |
-| `--gmm-per-layer` | 3 | 每个 MoE layer 前向阶段预期的 grouped_matmul 次数，用于 actor_update 前向截断判定 |
-| `--dpi` | 150 | 热力图输出的 DPI（默认 150） |
-| `--cmap` | viridis | 热力图的颜色映射（默认 viridis） |
+|------|--------|------|
+| `heatmap.parser.type` | `gmm` | 解析器类型：`gmm` |
+| `heatmap.visualizer.type` | `gmm_heatmap` | 可视化类型 |
+| `heatmap.parser.step` | 无 | 特定的 step 进行可视化（可选，支持 `1` 或 `1,2`） |
+| `heatmap.parser.role` | 无 | 特定的 role 进行可视化（可选） |
+| `heatmap.visualizer.dpi` | `200` | 热力图输出的 DPI |
+| `heatmap.visualizer.cmap` | `viridis` | 热力图的颜色映射 |
+| `heatmap.visualizer.gmm_per_layer` | `3` | 每个 MoE layer 前向阶段预期的 grouped_matmul 次数 |
 
 ## 四、输出说明
 
@@ -132,11 +138,11 @@ bash examples/gmm_exec.sh
 
 ## 五、注意事项
 
-1. GMM 热力图功能需要使用 `--input-type gmm_data` 和 `--profiler-type gmm` 参数
-2. 当 `--output-path` 只指定文件夹路径时，会在该文件夹中生成 `gmm_heatmap.png` 文件
-3. 当不指定 `--step`、`--role` 或 `--rank-list` 参数时，默认显示所有数据
+1. 热力图功能使用 `preset=heatmap` 或在 CLI 中指定 `heatmap.` 开头的参数即可启用
+2. 当 `output.path` 只指定文件夹路径时，会在该文件夹中生成 `gmm_heatmap.png` 文件
+3. 当不指定 `heatmap.parser.step`、`heatmap.parser.role` 或 `input.rank_list` 参数时，默认显示所有数据
 4. 对于大量数据，工具会自动调整图表大小和标签显示密度，确保可读性
 5. 数据文件需包含有效的专家负载数据，包括 step、role、rank_id、stage、expert_index 和 load 等字段
-6. 若你的模型实现中每层 grouped_matmul 次数不等于 3，请显式设置 `--gmm-per-layer` 以获得更准确的 actor_update 前向阶段截断结果
+6. 若你的模型实现中每层 grouped_matmul 次数不等于 3，请显式设置 `heatmap.visualizer.gmm_per_layer` 以获得更准确的 actor_update 前向阶段截断结果
 
-目录与 JSON 字段的集中说明另见 [数据规格与格式说明](../data/data_specification.md)。运行时校验逻辑以 `rl_insight.data.DataChecker` 及 [`rl_insight/data/rules.py`](../../rl_insight/data/rules.py) 中的规则定义为准。
+目录与 JSON 字段的集中说明另见 [数据规格与格式说明](../data/data_specification.md)。运行时校验逻辑以 `rl_insight.data.DataChecker` 及 [`rl_insight/data/rules.py`](../../rl_insight/data/rules.py) 中的规则定义为准。

examples/gmm_exec.sh

@@ -28,25 +28,23 @@ echo "=========================================="
 
 # Build command
 cmd="python -m rl_insight.main \
-    --input-path \"${GMM_DATA_PATH}\" \
-    --input-type \"gmm_data\" \
-    --profiler-type \"gmm\" \
-    --vis-type \"gmm_heatmap\" \
-    --output-path \"${OUTPUT_PATH}\" \
-    --rank-list \"${RANK_LIST}\" \
-    --dpi \"${DPI}\" \
-    --cmap \"${CMAP}\" \
-    --gmm-per-layer \"${GMM_PER_LAYER}\""
+    input.path=\"${GMM_DATA_PATH}\" \
+    output.path=\"${OUTPUT_PATH}\" \
+    input.rank_list=\"${RANK_LIST}\" \
+    heatmap.parser.type=gmm \
+    heatmap.visualizer.type=gmm_heatmap \
+    heatmap.visualizer.dpi=\"${DPI}\" \
+    heatmap.visualizer.cmap=\"${CMAP}\" \
+    heatmap.visualizer.gmm_per_layer=\"${GMM_PER_LAYER}\""
 
-# Add step and role parameters if specified
 if [ -n "${STEP}" ]; then
     cmd="${cmd} \
-    --step \"${STEP}\""
+    heatmap.parser.step=\"${STEP}\""
 fi
 
 if [ -n "${ROLE}" ]; then
     cmd="${cmd} \
-    --role \"${ROLE}\""
+    heatmap.parser.role=\"${ROLE}\""
 fi
 
 # Execute the command
@@ -64,4 +62,4 @@ else
     echo ">>> Failed to generate heatmap"
     echo "=========================================="
     exit 1
-fi
+fi

examples/mstx_exec.sh

@@ -4,7 +4,6 @@ set -euo pipefail
 
 MSTX_PROFILER_DATA_PATH="${MSTX_PROFILER_DATA_PATH:-}"
 OUTPUT_PATH="${OUTPUT_PATH:-./output}"
-PROFILER_TYPE="${PROFILER_TYPE:-mstx}"
 VIS_TYPE="${VIS_TYPE:-html}"
 RANK_LIST="${RANK_LIST:-all}"
 
@@ -13,7 +12,6 @@ echo "MSTX Profiler Cluster Analysis"
 echo "=========================================="
 echo "Input Path:    ${MSTX_PROFILER_DATA_PATH}"
 echo "Output Path:   ${OUTPUT_PATH}"
-echo "Profiler Type: ${PROFILER_TYPE}"
 echo "Vis Type:      ${VIS_TYPE}"
 echo "Rank List:     ${RANK_LIST}"
 echo "=========================================="
@@ -27,11 +25,11 @@ python -m rl_insight.utils.mstx_preprocessing "${MSTX_PROFILER_DATA_PATH}"
 echo ">>> Mstx data preprocessing completed."
 
 python -m rl_insight.main \
-    --input-path "${MSTX_PROFILER_DATA_PATH}" \
-    --profiler-type "${PROFILER_TYPE}" \
-    --output-path "${OUTPUT_PATH}" \
-    --vis-type "${VIS_TYPE}" \
-    --rank-list "${RANK_LIST}"
+    input.path="${MSTX_PROFILER_DATA_PATH}" \
+    timeline.parser.type=mstx \
+    input.rank_list="${RANK_LIST}" \
+    output.path="${OUTPUT_PATH}" \
+    timeline.visualizer.type="${VIS_TYPE}"
 
 echo "=========================================="
 echo ">>> Analysis completed successfully!"

examples/nvtx_exec.sh

@@ -4,7 +4,6 @@ set -euo pipefail
 
 NVTX_PROFILER_DATA_PATH="${NVTX_PROFILER_DATA_PATH:-}"
 OUTPUT_PATH="${OUTPUT_PATH:-./output}"
-PROFILER_TYPE="${PROFILER_TYPE:-nvtx}"
 VIS_TYPE="${VIS_TYPE:-html}"
 RANK_LIST="${RANK_LIST:-all}"
 
@@ -13,17 +12,16 @@ echo "Nvtx Profiler Cluster Analysis"
 echo "=========================================="
 echo "Input Path:    ${NVTX_PROFILER_DATA_PATH}"
 echo "Output Path:   ${OUTPUT_PATH}"
-echo "Profiler Type: ${PROFILER_TYPE}"
 echo "Vis Type:      ${VIS_TYPE}"
 echo "Rank List:     ${RANK_LIST}"
 echo "=========================================="
 
 python -m rl_insight.main \
-    --input-path "${NVTX_PROFILER_DATA_PATH}" \
-    --profiler-type "${PROFILER_TYPE}" \
-    --output-path "${OUTPUT_PATH}" \
-    --vis-type "${VIS_TYPE}" \
-    --rank-list "${RANK_LIST}"
+    input.path="${NVTX_PROFILER_DATA_PATH}" \
+    timeline.parser.type=nvtx \
+    input.rank_list="${RANK_LIST}" \
+    output.path="${OUTPUT_PATH}" \
+    timeline.visualizer.type="${VIS_TYPE}"
 
 echo "=========================================="
 echo ">>> Analysis completed successfully!"

examples/torch_profiler_exec.sh

@@ -4,7 +4,6 @@ set -euo pipefail
 
 TORCH_PROFILER_DATA_PATH="${TORCH_PROFILER_DATA_PATH:-}"
 OUTPUT_PATH="${OUTPUT_PATH:-./output}"
-PROFILER_TYPE="${PROFILER_TYPE:-torch}"
 VIS_TYPE="${VIS_TYPE:-html}"
 RANK_LIST="${RANK_LIST:-all}"
 
@@ -13,17 +12,16 @@ echo "Torch Profiler Cluster Analysis"
 echo "=========================================="
 echo "Input Path:    ${TORCH_PROFILER_DATA_PATH}"
 echo "Output Path:   ${OUTPUT_PATH}"
-echo "Profiler Type: ${PROFILER_TYPE}"
 echo "Vis Type:      ${VIS_TYPE}"
 echo "Rank List:     ${RANK_LIST}"
 echo "=========================================="
 
 python -m rl_insight.main \
-    --input-path "${TORCH_PROFILER_DATA_PATH}" \
-    --profiler-type "${PROFILER_TYPE}" \
-    --output-path "${OUTPUT_PATH}" \
-    --vis-type "${VIS_TYPE}" \
-    --rank-list "${RANK_LIST}"
+    input.path="${TORCH_PROFILER_DATA_PATH}" \
+    timeline.parser.type=torch \
+    input.rank_list="${RANK_LIST}" \
+    output.path="${OUTPUT_PATH}" \
+    timeline.visualizer.type="${VIS_TYPE}"
 
 echo "=========================================="
 echo ">>> Analysis completed successfully!"