# PR #6606 完整报告

- 仓库：`verl-project/verl`
- 标题：[tool] fix: update npu profiling test scrip
- 合并时间：2026-06-04 19:13
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6606

---

# 执行摘要

- 一句话：NPU 性能分析测试脚本参数灵活化
- 推荐动作：值得快速浏览但不需深度精读。主要学习点是 ' 将硬编码参数环境变量化 ' 的测试脚本重构模式，以及双引号包裹变量防止 globbing 的 Bash 最佳实践。对于其他测试脚本有借鉴意义。

# 功能与动机

PR body 中说明是 'update npu profiling test script'，核心是修改测试脚本里的传参方式以支持灵活传参。原脚本中 `LEVEL`、`CONTENTS`、`ANALYSIS` 等参数是硬编码常量，无法通过外部覆盖，导致无法灵活适配不同 profiling 场景。

# 实现拆解

1. **将硬编码参数改为环境变量 + 默认值**：在 `tests/special_npu/run_qwen3_8b_grpo_profiling.sh` 中，原硬编码的 `LEVEL=level0`、`CONTENTS=['npu','cpu']`、`ANALYSIS=False` 等变量被替换为 `${LEVEL:-level0}`、`${CONTENTS:-['npu','cpu']}` 等带默认值的形式，新增 `TRAIN_FILE`、`TEST_FILE`、`total_training_steps` 三个可覆盖变量。这样用户可以通过设置环境变量来自定义参数，无需修改脚本。
2. **双引号包裹变量引用**：在 Python 命令中，所有 `$PROFILE_RANKS_ALL`、`$PROFILE_RANKS` 等变量引用都加上了双引号，例如 `actor_rollout_ref.actor.profiler.all_ranks="$PROFILE_RANKS_ALL"`，避免 Bash globbing 意外展开类似 `[2,4]` 的值。
3. **调整默认值**：`ANALYSIS` 默认值从 `False` 改为 `True`，`PROFILE_RANKS` 从 `[0]` 改为 `[2,4]`，`SAVE_PATH` 从硬编码 `tests/utils/ci/profiler_data` 改为 `./profiler_data-dis`。
4. **CI 工作流补充后验证与清理**：在 `.github/workflows/e2e_ascend.yml` 中，在运行 profiling 脚本后显式添加了调用 `test_check_profiler_output.py` 验证输出并清理临时目录的步骤。原来这些步骤在脚本内，但脚本已移除了这些后处理逻辑。

关键文件：
- `tests/special_npu/run_qwen3_8b_grpo_profiling.sh`（模块 测试脚本；类别 test；类型 test-coverage）: 核心改动文件：将所有 profiling 参数从硬编码改为环境变量带默认值，并增加双引号保护，提升脚本灵活性。
- `.github/workflows/e2e_ascend.yml`（模块 CI 配置；类别 infra；类型 infrastructure）: 在 CI 工作流中补充了后验证和清理步骤，确保 profiling 数据被验证并清理。

关键符号：未识别

## 关键源码片段

### `tests/special_npu/run_qwen3_8b_grpo_profiling.sh`

核心改动文件：将所有 profiling 参数从硬编码改为环境变量带默认值，并增加双引号保护，提升脚本灵活性。

```bash
# 修改后的脚本片段：所有参数通过环境变量传入，带默认值
set -x

MODEL_ID=${MODEL_ID:-Qwen/Qwen3-8B}
MODEL_PATH=${MODEL_PATH:-${HOME}/.cache/models/${MODEL_ID}}
SAVE_PATH=${SAVE_PATH:-./profiler_data-dis}
rm -rf "$SAVE_PATH"

# 注意：以下方括号默认值（如 ['npu','cpu']、[1]）
# 建议外层加双引号以避免 Bash globbing，但当前写法在无匹配文件时安全
LEVEL=${LEVEL:-"level0"}
CONTENTS=${CONTENTS:-['npu','cpu']}
ANALYSIS=${ANALYSIS:-True}
PROFILE_STEPS=${PROFILE_STEPS:-[1]}
PROFILE_RANKS_ALL=${PROFILE_RANKS_ALL:-False}
PROFILE_RANKS=${PROFILE_RANKS:-[2,4]}
DISCRETE=${DISCRETE:-True}
TRAIN_FILE=${TRAIN_FILE:-${HOME}/data/gsm8k/train.parquet}
TEST_FILE=${TEST_FILE:-${HOME}/data/gsm8k/test.parquet}
total_training_steps=${total_training_steps:-1}

# Python 命令中所有变量引用均加双引号以防止 globbing
trainer.total_training_steps="$total_training_steps" \
    actor_rollout_ref.actor.profiler.enable=True \
    actor_rollout_ref.actor.profiler.all_ranks="$PROFILE_RANKS_ALL" \
    actor_rollout_ref.actor.profiler.ranks="$PROFILE_RANKS" \
    actor_rollout_ref.actor.profiler.tool_config.npu.discrete="$DISCRETE" \
    actor_rollout_ref.actor.profiler.tool_config.npu.contents="$CONTENTS" \
    actor_rollout_ref.actor.profiler.tool_config.npu.level="$LEVEL" \
    actor_rollout_ref.actor.profiler.tool_config.npu.analysis="$ANALYSIS" \
    ...

```

### `.github/workflows/e2e_ascend.yml`

在 CI 工作流中补充了后验证和清理步骤，确保 profiling 数据被验证并清理。

```yaml
# .github/workflows/e2e_ascend.yml 片段
- name: Running qwen3 8b grpo profiling test on ASCEND NPU
  run: |
    ray stop --force
    bash tests/special_npu/run_qwen3_8b_grpo_profiling.sh
    # 新增：运行后验证，并清理临时目录
    python3 "tests/utils/test_check_profiler_output.py" --profiler_dir="./profiler_data-dis" --device="npu"
    rm -rf ./profiler_data-dis
    rm -rf $HOME/ckpts

```

# 评论区精华

唯一的 review 评论来自 `gemini-code-assist[bot]`，指出在 Bash 中未加引号的方括号（如 `['npu','cpu']`、`[1]`、`[2,4]`）会被当作 globbing 模式，如果当前目录存在匹配的文件，shell 可能会意外展开导致语法错误。建议用双引号包裹默认值，例如 `CONTENTS=${CONTENTS:-"['npu','cpu']"}`。截至 PR 合并时，该建议未被确认采纳，但 PR 已由 `wucong25` 批准合并，说明可能已在其他提交中处理或认为当前写法风险可控（因为 `set -x` 且通常无匹配文件）。

- 未加引号的方括号默认值存在 globbing 风险 (correctness): 未被确认采纳，但 PR 已合并。可能因为实际运行环境极少存在匹配文件，风险可接受。

# 风险与影响

- 风险：**低风险**。主要改动在测试脚本和 CI 配置，不涉及核心逻辑。潜在风险包括：
 - 如果用户滥用环境变量传入非法值，可能导致 Python 命令参数格式错误；但已有双引号保护。
 - 默认值 `PROFILE_RANKS=${PROFILE_RANKS:-[2,4]}` 未加额外引号，在极端条件下可能受 globbing 影响，但实际运行时目录很少存在名为 `[2,4]` 的文件。
 - `SAVE_PATH` 默认值改为 `./profiler_data-dis`，与 CI 中清理路径一致，但若用户自定义覆盖，需确保清理逻辑匹配。
 - 影响：**影响范围小**：只影响 NPU profiling 测试脚本及其 CI 调用。受益用户是需要在 NPU 上执行 profiling 的开发者，现在可以外部覆盖参数，无需修改脚本。团队 CI 流程增加了一次显式验证和清理，提升了可维护性。
 - 风险标记：缺少测试覆盖 , 潜在 Bash globbing 问题

# 关联脉络

- PR #6816 [ci] fix: fix Megatron-Bridge version in e2e_ppo_trainer_megatron_sglang_ascend.yml and update megatron for sglang ascend: 同为修改 Ascend CI 配置的 PR，涉及同一 CI 文件或类似测试脚本。
- PR #6572 [rollout, reward] feat: add full determinism support for vLLM rollout and reward model: 同为针对 NPU 测试的改进，增加测试覆盖。