Skip to content

[Feature] Log driver memory at RL train step boundaries - #2316

Open
PengchengShi00 wants to merge 1 commit into
InternLM:mainfrom
PengchengShi00:debug_mem
Open

PengchengShi00 wants to merge 1 commit into
InternLM:mainfrom
PengchengShi00:debug_mem

Conversation

@PengchengShi00

@PengchengShi00 PengchengShi00 commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

本次改动把 RL 训练的 driver 内存观测统一到既有模块 xtuner/v1/utils/memory_watch.py:

  • 新增公开函数 log_memory_event(tag, marker),按训练事件输出一行 [MemReport]...(进程内存拆分),不受周期采样开关控制、默认始终输出。
  • 在共用消费路径 produce_utils.take_train_batch 返回前打点(共卡/非共卡模式统一覆盖),以及 BaseRLTrainer._log_step 末尾打点(每个训练步)。
  • RL CLI main() 用 monitor_rank_memory(cfg.trainer.work_dir) 包住 build()+fit(),复用既有周期 JSONL 采样(需 XTUNER_MEMORY_WATCH_ENABLED=1)。
  • 原先未提交的临时模块 xtuner/v1/utils/mem_report.py 已并入 memory_watch.py 并删除。

改动规模:代码 5 个文件 +108/−3;最终提交 ea0e9eb2 共 6 个文件 +274/−3(含 skill 文档
.claude/skills/rl-memory-diagnosis/SKILL.md)。

ProduceBatchResult impact: not affected(仅新增日志,不改任何字段与统计路径;打点在 take_train_batch 组装结果之后,不影响 group_gen_* 计时)
RoutedExperts impact: not affected(不触碰 rollout response、extra_fields、ObjectRef 生命周期)
Ray concurrency impact: not affected(未修改任何 Ray actor 方法、装饰器或 concurrency group)

Review 意见处理状态

意见 级别 状态
事件打点无条件输出,建议共用开关 Warning ❌ 不采纳:事件行保持始终输出,周期采样仍由 XTUNER_MEMORY_WATCH_ENABLED 控制
disagg 模式缺失 produce 侧打点,建议下沉公共消费路径 Warning ✅ 已下沉到 produce_utils.take_train_batch
周期采样默认 1 s 写共享存储 Warning ❌ 不采纳:未改原有功能,不修改原有注释(用户决定),开销为已知取舍
event 与 MemoryEvent 枚举同名不同义 Nit ✅ 改名 marker,docstring 说明二者无关
I/O 与格式化耦合,不利于测试 Nit ❌ 不采纳:合并为单函数(用户决定);测试改为 monkeypatch _read_status/get_logger
缺少 log_memory_event 单测 建议 ✅ 新增 TestLogMemoryEvent 4 个用例
异常捕获面(IndexError) Nit ⏸ 维持现状(与 _read_process_sections 一致,/proc 格式稳定)
marker 内含空格 Nit ⏸ 未改(grep 不受影响)
skill 目录提交方式 Info ⚠️ 实际已随 ea0e9eb2 与代码同一 commit 提交;若仓库要求拆分可后续拆出

Main Flowchart before this PR

flowchart TD
    subgraph SFT["xtuner/v1/train/cli/sft.py :: main()"]
        S1["monitor_rank_memory(trainer_cfg.work_dir)"]
        S2["Trainer.from_config(...) / Trainer.fit()"]
    end

    subgraph RLC["xtuner/v1/train/cli/rl.py :: main()"]
        R1["ray.init(address='auto')"]
        R2["Config.fromfile(config) + work_dir 覆盖"]
        R3["cfg.trainer.build()"]
        R4["BaseRLTrainer.fit()"]
        R1 --> R2 --> R3 --> R4
    end

    subgraph TRAIN["xtuner/v1/train/rl_trainer.py :: BaseRLTrainer"]
        T1["fit() 每步循环"]
        T2["AgentLoopManager.produce_batch(...) / DisaggAgentLoopManager.get_batch(...)"]
        T3["BaseRLTrainer._log_step(...)"]
        T1 --> T2
        T1 --> T3
    end

    subgraph MW["xtuner/v1/utils/memory_watch.py"]
        W1["monitor_rank_memory(work_dir)"]
        W2["_MemoryWatch.__enter__ / _sample / __exit__"]
        W3["MemoryEvent: START / PERIODIC / STOP"]
        W1 --> W2 --> W3
    end

    S1 --> W1
    S2 -. 在 monitor 上下文内执行 .-> S1
    R4 -. 未接入 .-x W1
    T2 -. 无内存观测 .-> T2
    T3 -. 无内存观测 .-> T3
Loading

改动前,memory_watch 只服务 SFT 入口;RL 路径没有任何进程级内存观测。

Main Flowchart after this PR

flowchart TD
    subgraph RLC["xtuner/v1/train/cli/rl.py :: main()"]
        R1["ray.init(address='auto')"]
        R2["Config.fromfile(config) + work_dir 覆盖"]
        R3["cfg.trainer.build()"]
        R4["BaseRLTrainer.fit()"]
        R5["with monitor_rank_memory(cfg.trainer.work_dir)"]
        R1 --> R2 --> R5 --> R3 --> R4
    end

    subgraph TRAIN["xtuner/v1/train/rl_trainer.py / agent_loop_manager/produce_utils.py"]
        T1["fit() 每步循环"]
        T2["produce_utils.take_train_batch(...)"]
        T3["BaseRLTrainer._log_step(...)"]
        T1 --> T2
        T1 --> T3
    end

    subgraph MW["xtuner/v1/utils/memory_watch.py"]
        G0{"XTUNER_MEMORY_WATCH_ENABLED == 1 ?"}
        W1["monitor_rank_memory(work_dir)"]
        W2["_MemoryWatch 周期采样"]
        W3["log_memory_event(tag, marker) 始终执行"]
        W4["_read_status(Path('/proc/self/status'))"]
        W5["格式化 + get_logger().info(line)"]
        W1 --> G0
        G0 -- "yes" --> W2
        W3 --> W4 --> W5
    end

    R5 --> W1
    T2 -- "take_train_batch done" --> W3
    T3 -- "train_step 结束" --> W3
    W2 --> JSONL[("<work_dir>/memory/rank_*.jsonl")]
    W6 --> DRIVERLOG[("driver.log / stderr")]

    classDef changed fill:#ffe082,stroke:#f57f17,stroke-width:2px
    class R5,T2,W3,W4,W5,W6,G0 changed
Loading

文字说明(高亮部分为本次修改):

  • xtuner/v1/train/cli/rl.py:build()+fit() 移入 with monitor_rank_memory(...),与 SFT 入口写法一致;开关关闭时直接透传。
  • xtuner/v1/rl/agent_loop_manager/produce_utils.py::take_train_batch:在组装并返回 ProduceBatchResult 前打点一次。该函数是共卡 AgentLoopManager.produce_batch 与 DisaggAgentLoopManager.get_batch 的共同消费路径,一处接入覆盖两种模式;AgentLoopManager 类本身已无改动。
  • xtuner/v1/train/rl_trainer.py::_log_step:每个训练步结束时打点(三条训练路径共用该方法)。
  • xtuner/v1/utils/memory_watch.py:log_memory_event 单函数完成"读 /proc/self/status → 格式化 → 写日志";事件打点不受任何开关控制,周期采样仍由 XTUNER_MEMORY_WATCH_ENABLED=1 控制。

核心原理

  1. /proc/self/status 是内核按需合成的虚拟文件,每次 read 返回读取时刻的进程状态;VmRSS/RssAnon/RssShmem/VmHWM 来自 mm 的 per-CPU 计数,读取只需汇总,不遍历 VMA/页表,成本为微秒级,可安全放在每步路径上。
  2. 与周期采样中的 smaps_rollup/numa_maps(O(VMA),被限流到 30 s 一次)相比,事件打点只取便宜字段,二者互补。
  3. RSS 语义是"已驻留物理页",不等于 Python 存活对象字节数(glibc/pymalloc 可能持有已释放 arena),因此该指标用于曲线趋势与突增定位,而非精确对象统计。
  4. _read_status 返回字节数;log_memory_event 按 _GIB 换算为 GiB,rss 带 GiB 后缀,其余字段沿用原 mem_report 输出习惯,[MemReport] 前缀保持与既有诊断命令兼容。
  5. 事件打点始终输出,周期采样由 XTUNER_MEMORY_WATCH_ENABLED=1 控制:默认即可在训练日志中按 step 观察 driver 堆;需要 JSONL 曲线时再打开开关。

核心实现与对应的单测

核心实现:

  • xtuner/v1/utils/memory_watch.py:501 log_memory_event:单函数完成读 /proc/self/status → 按固定字段顺序格式化为 GiB → get_logger().info;缺失字段与非内存字段自动跳过;读取失败(OSError/ValueError)静默降级,无环境开关。
  • 接入点:
    • xtuner/v1/rl/agent_loop_manager/produce_utils.py:660(take_train_batch 返回前,共卡/非共卡共用);
    • xtuner/v1/train/rl_trainer.py:1242(_log_step 末尾)。

对应单测:tests/utils/test_memory_watch.py::TestLogMemoryEvent

用例 覆盖点
test_line_converts_bytes_to_gib 字节 → GiB 换算、字段顺序、rss 单位后缀
test_missing_and_non_memory_keys_are_skipped 缺失字段与非内存字段跳过
test_logs_without_periodic_switch XTUNER_MEMORY_WATCH_ENABLED=0 时仍输出一行
test_unreadable_status_is_silent 读取失败静默降级、不打断训练

未运行任何代码或测试(本地无 GPU 环境);以上仅为静态检查(ruff check / format 通过)。

抽象与信息隐藏评估

  • 没有新增类,只向既有 util 模块增加一个无状态函数与一个私有纯格式化函数,符合"尽量少增加类"。
  • 复用既有私有 _read_status,没有复制 /proc 解析逻辑;周期采样、cgroup/NUMA 等复杂细节仍封装在 _MemoryWatch 内。
  • log_memory_event 与 MemoryEvent 的语义区分已写入 docstring(marker 为自由文本,MemoryEvent 仅用于 JSONL 记录)。
  • 事件函数保持单函数线性流程(读 → 格式化 → 打日志),没有额外抽象;单测通过 monkeypatch _read_status 与 get_logger 注入合成数据,不依赖真实 /proc,测试成本可接受。

剩余可选优化(非阻塞):

  • 格式化循环使用 (name, key, suffix) 三元组、空字符串后缀表达"仅 rss 带 GiB",略隐晦;若后续要扩展字段可改为显式格式表。

新增功能守则

规则 评估
R1 既有类接触点 ≤ 1 字段 + 1~2 次具名调用 ✅ produce_utils.take_train_batch(函数)增加 1 次调用;BaseRLTrainer._log_step 增加 1 次调用;rl.py::main 增加 1 个 with。AgentLoopManager/DisaggAgentLoopManager 均零改动,无新增字段。
R2 既有类不出现新特性实现细节 ✅ 字段名、格式、开关全部留在 memory_watch;调用点只有 tag/marker 两个标签。
R3 既有类不出现按新特性分叉的条件 ✅ 无新增分支。

改动符合"既有类零污染"。

公开接口的线性业务流程评估

  • log_memory_event:读状态 → 格式化 → 打日志,三步同层级,符合 Composed Method;未再拆分纯函数(用户决定),避免无价值转发 wrapper。
  • rl.py::main 的接入是 2 行 with,不引入额外私有函数。

单测建议(已落实)

新增的 4 个用例已覆盖输出格式、开关独立性与异常降级。后续如需更完整:

  • 可为 take_train_batch 增加轻量测试,断言其返回前调用了 log_memory_event(monkeypatch 该函数即可,无需真实 replay buffer 之外的重依赖);
  • _log_step 的打点属于集成路径,建议依赖现有 RL 端到端用例覆盖,不单独构造。

其他 issues

  1. [Info] 开关语义。 事件日志默认始终输出,不需要设置环境变量;XTUNER_MEMORY_WATCH_ENABLED=1 只控制周期 JSONL 采样。若后续担心主干日志噪声,可再评估是否加独立开关(本次明确不加)。
  2. [Nit] marker 内含空格(take_train_batch_done train_step=3)被包进 [...]。 grep 不受影响;若希望机器解析更容易,可用 : 连接。
  3. [Nit] 异常捕获面。 _read_status 中 value.split()[0] 可能抛 IndexError,调用处只捕 (OSError, ValueError);与 _MemoryWatch._read_process_sections 一致,实际风险很低,维持现状。
  4. [Warning→未处理] 周期采样默认 1 s 写 work_dir。 未修改原有 docstring(本次不改变既有功能语义),共享存储场景由使用者自行设置较大的 XTUNER_MEMORY_WATCH_INTERVAL;smaps_rollup/numa_maps 每 30 s 的开销为已知取舍。
  5. [Info] .claude/skills/rl-memory-diagnosis/SKILL.md 已随 ea0e9eb2 与代码同一 commit 提交。 文档与代码无耦合,若仓库偏好 [SKILL] 独立 commit(已有先例),可后续拆分。
  6. [Info] 文档范围。 模块 docstring 与 monitor_rank_memory 的原有注释保持原样(未改动既有功能语义);仅新增的 log_memory_event 带 docstring,说明事件打点与周期采样开关相互独立。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant