kali20gakki/msAgent / skills/accuracy/uwc-verify
uwc-verify
Verified自动验证 veRL + Megatron-core + vLLM 训推权重转换一致性(UWC)的 5 项检查:Bridge P0/P2、传输 P2_sender/P5、data_ptr 覆盖、G0/G1 前向、dummy vs safetensors 差分。注入采集钩子、采集权重/指针/日志,生成 report.md / report.html / report.json。当用户要验证 RL 训练与推理权重同步、排查 rollout 输出乱码/漏同步、或复现《RL 权重一致性验证》文档时使用。
uwc-verify
把《权重转换一致性验证》文档里的 5 项手工检查变成可执行的 skill:向 veRL 源码注入 best-effort 采集钩子,按阶段运行用户命令,离线比对并生成报告。
适用场景
- veRL(Megatron-core 训练 + vLLM 推理)升级后,验证 HF↔mcore↔推理进程的权重链路。
- RL rollout 输出乱码、怀疑某些层漏同步、shared-memory / IPC 传输异常。
- 需要一份可归档的权重一致性报告(Markdown/HTML/JSON)。
- 仅支持 veRL;vLLM 单机/共置(colocate)与 agent-loop 异步路径均可埋点。
五项检查
| # | 检查 | 采集物 | 判定 |
|---|---|---|---|
| 1 | Bridge 往返 | P0_hf_original_*.pt、P2_hf_exported_*.pt | 逐张量 atol=1e-3(可配),缺 key/形状不符即失败 |
| 2 | 传输一致性 | P2_sender_*.pt、P5_receiver_*.pt | 默认逐位一致(共享内存/IPC 不应改变数值) |
| 3 | data_ptr 覆盖 | ptr_before_after_*.json | 同步轮开始/结束各快照一次:data_ptr 或内容采样变化即视为已同步(vLLM 原地 copy_ 时指针不变,只看指针会全员误报) |
| 4 | 前向一致性 | G0_logits_gt.pt、G1_logits_mcore.pt | 逐位置 cosine:均值 >0.99 且最小 ≥0.95 |
| 5 | dummy vs safetensors | dummy_/safetensors_rl_first_step_output.json | 2×2 乱码矩阵(token ids 用 model.hf_path 的 tokenizer 离线解码):dummy 乱码+safetensors 正常=漏同步;均乱码=值错误;均正常=通过。两次输出完全相同是正常的,只有两次记录的 load_format 也相同才判“覆盖未生效” |
报告状态:pass / fail / partial(部分项缺数据)/ skip。
工作流
# 0) 环境与配置自检
python scripts/uwc_verify.py doctor --config uwc.yaml
# 1) 注入钩子(幂等;可先 --dry-run)
python scripts/uwc_verify.py prepare --config uwc.yaml --dry-run
python scripts/uwc_verify.py prepare --config uwc.yaml
# 2) 按阶段运行训练/推理命令(命令写在 uwc.yaml 的 commands 里)
python scripts/uwc_verify.py run --config uwc.yaml --stage 1,2,3,4,5
# 已有 dump 时只跑缺失阶段:--reuse;stop_when 只认本次运行新写入的文件
# 3) 离线比对 + 报告
python scripts/uwc_verify.py compare --config uwc.yaml
python scripts/uwc_verify.py report --config uwc.yaml
# 4) 撤销所有源码改动
python scripts/uwc_verify.py prepare --config uwc.yaml --restore
一步式:python scripts/uwc_verify.py all --config uwc.yaml。
演示(合成数据,无需 verl/NPU):python scripts/uwc_verify.py demo --out /tmp/uwc_demo。
配置
复制 uwc.example.yaml 为 uwc.yaml,至少填写:
verl.path:veRL 仓库根目录(含verl/包)。model.hf_path:HF 权重目录(阶段 1/前向验证用)。dump_dir:采集输出目录。commands:五个阶段各自要执行的命令。skill 会用UWC_*环境变量包裹后执行,并在stop_when指定的文件出现或超时后停止进程组。
环境变量优先级:UWC_VERL_PATH、UWC_DUMP_DIR、UWC_MODEL_PATH 可覆盖配置。
采集开关(由 skill 自动注入)
UWC_ENABLE=1:总开关。UWC_STAGE1/2/3=1:阶段开关(默认开)。UWC_DUMP_DIR、UWC_STEP、UWC_DIFF_TAG=dummy|safetensors。UWC_PTR_CHECK=1:阶段 3 在同步轮前后快照data_ptr+ 内容采样。UWC_LOAD_FORMAT=dummy|safetensors:阶段 5 写入采集记录,差分时用来判断两次运行的加载格式是否真的不同。VERL_FORCE_USE_SHM=1:强制走共享内存路径(会同时改写self.use_shm = ...)。
故障注入(仅用于验证 skill 自身,默认关闭)
以下变量只在做负向验证时显式设置,正常使用不要设置:
UWC_FAULT_STAGE1=<子串>:<增量>:Bridge load 后扰动 mcore 参数,使 P2 与 P0 不一致(R1)。UWC_FAULT_STAGE2=<子串>:<增量>:P2_sender 落盘后扰动实际发送的张量,使 P5 与 P2_sender 不一致(R2)。UWC_FAULT_STAGE3_SKIP=<子串,...>:记录 P5 后从发给 vLLM 的权重里丢弃匹配层,制造漏同步(R3)。UWC_FAULT_STAGE4=<子串>:<增量>:mcore 前向前对命中参数的整个张量做偏移,使 G1 与 G0 的 cosine 下降(R4;只改单个元素通常不足以影响 cosine)。UWC_FAULT_STAGE5_SAME_FORMAT=1:强制两次 stage 5 都以 dummy 运行并记录load_format=dummy(R5)。
关键文件
scripts/uwc_verify.py:CLI(doctor/prepare/run/compare/report/all/demo)。runtime/uwc/hooks.py:运行时埋点,按模块角色包装 Bridge load/export、_update_weights、bucket send、generate_sequences。runtime/uwc/collectors/:P0/P2/P2_sender/P5/data_ptr/首步输出采集。runtime/uwc/offline/:比对、2×2 差分、前向验证、报告渲染。../../../tests/skills/uwc-verify/:离线比对、钩子注入/恢复、demo 端到端测试。- references/reference.md:dump 目录布局、各阶段环境变量、判定阈值与参数说明。
真实环境(Ascend + veRL 0.9.1)
在 8×910B4(32 GiB/卡)容器里实测:TP=4/DP=2、GPU_MEMORY_UTILIZATION=0.25;显存更紧时可用 4 卡 TP=4/DP=1,并适当降低 vLLM 显存比例。各阶段启动命令直接填用户自己的脚本。
veRL 0.9.1 差异:sender 入口是 async_send_weights(0.8 及以前叫 send,两个都包装);Bridge 从 HF 初始化依赖 use_mbridge=True + use_dist_checkpointing=False,否则阶段 1 不经过 load_hf_weights。
报告怎么读
- 先看
overall.status与每项status。 - 第 1 项失败:Bridge 转换问题,看
report.json的worst/ missing keys。 - 第 2 项失败:传输层改变了数值,优先检查
use_shm、bucket 边界、dtype 转换。 - 第 3 项失败:
not_synced列出的参数就是漏同步层;结合第 5 项定位 vLLM 覆盖范围。 - 第 4 项失败:训练侧 mcore 权重或前向配置不一致(dtype/并行切分/输入不一致)。
- 第 5 项失败但前几项通过:vLLM 加载格式覆盖参数未生效,或只同步了部分层。
限制
- 埋点是 best-effort:collector 异常只打印
[UWC] WARNING,不会中断训练。 - 只覆盖 per-tensor 同步路径;若 veRL 使用 shard/delta 路径,会打印警告,需强制切回 per-tensor。
- 阶段 2 会把整份导出权重复制到主机内存用于
P2_sender落盘(Qwen3-4B bf16 约 8 GB/rank,逐个张量拷贝,不额外占用设备显存);与 vLLM 共置、显存紧张时同步阶段仍可能 OOM,可降低GPU_MEMORY_UTILIZATION重试。 - 阶段 4 的 mcore 前向验证需要单卡可加载的 mcore 权重与 Megatron-Bridge(自动兼容旧
mbridge包);多卡并行模型需先转换/合并。 run通过文件出现判断阶段完成,超时与命令需按实际训练时长配置。- 修改 veRL 源码前建议提交/备份;
prepare --restore可逐字节还原(依赖 manifest)。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |