【Bug已解决】[docs] GRPO model name mismatch across docs + missing GRPO tab in OOM troubleshooting 解决方案

【Bug已解决】[docs] GRPO model name mismatch across docs missing GRPO tab in OOM troubleshooting 解决方案一、现象长什么样在维护项目文档时我们发现两处不一致读者很容易 confuse模型名前后不一同一篇文档集里GRPO 相关 trainer 被写成各种形态——GRPOTrainer、GRPO Trainer、grpo、GRPO、GRPOConfig、GRPO config。用户搜索GRPO时有的页面命中、有的页面用别的写法文档站内搜索和 SEO 都受影响。OOM 排查缺 GRPO 标签OOM troubleshooting 这篇文档是按 trainer 分 tab 的SFT / DPO / PPO ...但没有 GRPO 这一 tab。用户训 GRPO 爆显存时点进 OOM 文档找不到对应章节只能看别的 trainer 的不完全适用因为 GRPO 还有 vLLM 引擎、rollout 显存等特殊项。现象特征不报错、不影响代码运行纯文档体验问题但名字不一会让新手搜不到、看错 API缺 tab会让 GRPO 用户卡 OOM 时少一份针对性指南这类问题因为是 markdown 文案CI 的 pytest 完全覆盖不到容易长期存在。二、背景文档一致性问题通常来自多人协作 没有命名规范有的人写代码类名GRPOTrainer代码真实名有的人写中文叙述用GRPO Trainer带空格有的人缩写grpo文档站若用静态生成器如 mkdocs/docusaurustab 是用特定语法如 GRPO声明的新增一个 trainer 时忘记同步加 tab于是 OOM 文档的 tab 列表落后于实际支持的 trainer 集合没有术语表/命名约定做单一真源每篇文档作者自行发挥。具体到 GRPO它既是一个算法名Group Relative Policy Optimization也是一个 trainer 类名GRPOTrainer和一个 config 类名GRPOConfig。文档里应当代码/类名一律用真实标识符GRPOTrainer、GRPOConfig叙述里首次出现写全称之后可用 GRPO 简称但不要用GRPO Trainer这种空格写法容易和类名混淆OOM 文档为它单独开一个 tab。三、根因根因两句话命名无规范文档没有GRPO 相关术语单一真源作者自由发挥导致GRPOTrainer/GRPO Trainer/grpo混用搜索与引用不一致。tab 列表落后OOM troubleshooting 的 tab 是手写声明的新增 GRPO 支持时没同步补 GRPO tab导致文档结构与实际 trainer 集合脱节。两者都是文档结构与代码演进不同步 缺少约定与校验的典型代码加了 GRPO文档没跟上名字、tab 都漏。四、最小可运行复现下面用纯 Python 模拟文档里命名不一致如何用简单检查抓出来以及tab 列表缺项如何检测import re def find_name_variants(text: str) - set: 找出文档里 GRPO 相关的各种写法。 patterns [rGRPOTrainer, rGRPO Trainer, r\bgrpo\b, r\bGRPO\b, rGRPOConfig] found set() for p in patterns: if re.search(p, text): found.add(p) return found def check_oom_tabs(tabs_declared: list, trainers_supported: list): OOM 文档的 tab 是否覆盖所有支持的 trainer。 missing [t for t in trainers_supported if t not in tabs_declared] return missing def demo(): doc 使用 GRPO Trainer 时grpo 的 GRPOTrainer 配置见 GRPOConfig print(文档里的命名变体, find_name_variants(doc)) missing check_oom_tabs([SFT, DPO, PPO], [SFT, DPO, PPO, GRPO]) print(OOM 文档缺失的 tab, missing) if __name__ __main__: demo()输出文档里的命名变体 {GRPOTrainer, GRPO Trainer, grpo, GRPO, GRPOConfig} 文档缺失的 tab [GRPO]第一行说明一篇文档里就出现了 5 种写法不一致第二行说明 OOM 文档的 tab 漏了 GRPO。复现了命名混乱 tab 缺项两个文档问题。五、解决方案第一层统一命名约定术语表单一真源第一层建立命名规范作为文档的单一真源# 命名约定文档 CONTRIBUTING 或 glossary | 概念 | 代码/类名写法 | 叙述中写法 | 禁止使用 | |----------------|------------------|---------------------|------------------| | GRPO 算法 | - | GRPO全大写 | grpo全小写叙述| | GRPO trainer | GRPOTrainer | GRPO trainer | GRPO Trainer空格| | GRPO 配置 | GRPOConfig | GRPOConfig | - |然后批量修正文档把GRPO Trainer→ GRPO trainer把叙述里的grpo→ GRPO保留GRPOTrainer/GRPOConfig作为代码标识符。这样搜索GRPOTrainer和GRPO都能稳定命中术语一致。修正脚本示例局部替换def normalize_grpo_names(text: str) - str: # 叙述里的 GRPO Trainer空格- GRPO trainer text text.replace(GRPO Trainer, GRPO trainer) # 全小写 grpo 作为叙述词 - GRPO保留代码标识符 GRPOTrainer/GRPOConfig import re text re.sub(r(?![\w])grpo(?![\w]), GRPO, text) return text def demo(): doc GRPO Trainer 的 grpo 训练用 GRPOTrainer print(normalize_grpo_names(doc)) # - GRPO trainer 的 GRPO 训练用 GRPOTrainer if __name__ __main__: demo()六、解决方案第二层给 OOM 文档补 GRPO tab第二层补齐结构缺失——在 OOM troubleshooting 文档里加 GRPO tab包含 GRPO 特有的显存项vLLM 引擎显存、rollout 峰值、参考模型常驻等 GRPO GRPO 的显存由三部分叠加爆显存时优先查 1. **vLLM 推理引擎**GRPO 用 vLLM 做 rollout引擎本身常驻一份权重副本 占总显存的大头。若 vLLM 与训练模型不在同卡注意分卡同卡则预留余量。 2. **rollout 峰值**max_completion_length 越大、group 内样本越多 generate 时的 past_key_values 峰值越高参见 max_completion_length 相关调优。 3. **参考模型ref_model**GRPO 虽不需 ref_model用旧策略 logps 但若启用 KL 约束会引入额外副本注意关掉或共卡。 4. **梯度检查点 FSDP**长序列下务必开梯度检查点并用 FSDP 分片优化器状态。 通用项同 SFT/DPOPYTORCH_CUDA_ALLOC_CONFexpandable_segments:True、 降低 per_device_train_batch_size、开 gradient_checkpointing。这样 GRPO 用户在 OOM 文档里有了专属章节且覆盖它特有的 vLLM/rollout 显存来源而不是去看不适用的 SFT 指南。七、解决方案第三层CI 文档 lint防回归前两层修好了当下但要防止以后又写乱。第三层加 CI 文档 lint把命名与 tab 覆盖变成可回归的检查import re, pathlib, sys def lint_grpo_naming(path: str) - list: text pathlib.Path(path).read_text(encodingutf-8) problems [] if re.search(rGRPO Trainer, text): problems.append(出现 GRPO Trainer空格应写 GRPO trainer) if re.search(r(?![\w])grpo(?![\w]), text) and GRPOTrainer not in text: # 全小写 grpo 作为叙述词提示改为 GRPO此检查需结合上下文仅示例 pass return problems def lint_oom_tabs(oom_doc: str, trainers: list) - list: missing [t for t in trainers if f {t} not in oom_doc] return [fOOM 文档缺少 {t} tab for t in missing] def demo(): issues lint_grpo_naming(docs/grpo.md) tabs lint_oom_tabs( \SFT\\n \DPO\, [SFT, DPO, GRPO]) for i in issues tabs: print([doc-lint], i) sys.exit(1 if (issues or tabs) else 0) if __name__ __main__: demo()把doc-lint接进 CI和 ruff 检查并列以后任何文档出现GRPO Trainer或 OOM 文档漏了新 trainer 的 tabCI 直接红把文档一致性从靠人自觉变成靠门禁。八、落地建议如果你在维护文档时发现命名/tab 问题建议建术语表在 CONTRIBUTING 里写明 GRPO 相关术语的规范写法。批量归一用脚本把GRPO Trainer→ GRPO trainer、叙述grpo→ GRPO。补 OOM tab为 GRPO 加专属 tab覆盖 vLLM/rollout 显存项。CI 文档 lint检查禁用写法与 tab 覆盖防回归。同步清单新增 trainer 时维护一份所有文档 tab 必须同步的 checklist。本地预览mkdocs serve/docusaurus start看渲染后的 tab 是否正常。九、排查清单如果你发现文档里 GRPO 名字乱/缺 tab按顺序查搜变体GRPO Trainer/grpo/GRPOTrainer/GRPOConfig是否混用。建术语表规定代码用GRPOTrainer/GRPOConfig叙述用 GRPO/GRPO trainer。批量修正脚本替换禁用写法。查 OOM 文档 tab是否覆盖所有支持的 trainer缺 GRPO 就补。GRPO tab 内容应包含 vLLM 引擎显存、rollout 峰值、ref_model 等特有项。加 CI doc-lint禁用写法 tab 覆盖检查防回归。本地预览验证确认 tab 渲染正常。十、小结文档里GRPO 名字前后不一 OOM 排查缺 GRPO tab根因是文档缺少命名规范术语单一真源和 tab 同步机制作者自由发挥导致GRPOTrainer/GRPO Trainer/grpo混用且新增 GRPO 支持时 OOM 文档的 tab 列表没同步补上。它不影响代码运行但让新手搜不到正确 API、GRPO 用户卡 OOM 时缺针对性指南且因是 markdown 文案、pytest 覆盖不到而长期存在。修复分三层第一层建立命名术语表代码用GRPOTrainer/GRPOConfig、叙述用 GRPO/GRPO trainer并批量归一禁用写法第二层给 OOM troubleshooting 补 GRPO tab覆盖 vLLM 引擎显存、rollout 峰值、ref_model 等 GRPO 特有项第三层加 CI 文档 lint检查禁用写法与 tab 覆盖把文档一致性从靠人自觉变成靠门禁防回归。核心心法是文档里的术语和结构与代码演进必须同步——用语术语表做单一真源、用 CI 检查防漂移否则文档会在协作中悄悄失焦误导每一个新来的读者。