用途 本技能用于把 ocms（Octopus Metrics Summary）训练指标库接入 PyTorch 训练脚本，使训练指标能够上报到华为 Octopus 平台。它提供框架无关的记录器模块，并给出常见训练框架的集成方式。
主要能力
- 提供独立的 OcmsRecorder 模块，无 ocms 与标准库之外的依赖。
- 可按谓词函数把指标分组到最多 6 个图表（ocms 硬性上限），默认分组覆盖 loss、learning_rate、epoch、timing、eval_score、grad_norm，也支持自定义 chart_groups。
- 自动清理 y 轴名称：把 learning_rate/vision_tower、timing/data 之类键名转换为仅含 [a-zA-Z0-9_-] 的形式。
- 日志目录优先使用平台设置的 METRICS 环境变量，平台外回退到 <output_dir>/ocms_metrics，同一份代码可同时用于平台与本地。
- 提供自检与训练后指标文件校验脚本，ocms 缺失时走优雅降级路径。
使用方式
- 用 python3 scripts/verify_ocms.py 检查 ocms 是否安装并自检记录器；若可获得 ocms，从官方 octopus-courses README 获取当前有效的签名链接，下载 wheel 后执行 python3 -m pip install ./ocms-*.whl；在平台上可用 --require-ocms 让缺失包报错。
- 在训练脚本中定位指标记录点（如 wandb.log、logger.info、add_scalar、print 等），识别可用指标项。
- 把 scripts/ocms_recorder.py 复制到项目的 migrate_to_cloudrobo/ 目录。
- 按框架集成：自定义 PyTorch 循环在 _log_metrics 等处直接调用 recorder.log()；HuggingFace Trainer 用 TrainerCallback.on_log；PyTorch Lightning 用 Callback.on_train_batch_end；Accelerate 在训练循环加 rank-0 保护；MMEngine 用 Hook.after_train_iter；共享基类增加 _init_ocms 与 _ocms_log。通用做法是在现有日志语句后追加 recorder.log(step=step, metrics=metrics)，且仅在 rank-0 上报以避免文件冲突。
- 运行短训练后，用 python3 scripts/verify_ocms.py --output-dir "$OUTPUT_DIR" 校验 metrics.json 与各图表 CSV；CSV 每行格式为 [step, val1, val2, ...]，无表头。
适用场景 适用于需要把 PyTorch 训练指标接入华为 Octopus 平台的项目，涵盖自定义循环、主流训练框架及共享基类等结构。
限制
- ocms 是 Octopus 平台专有包，不在 PyPI，只能通过限时签名链接获取，过期需重新获取；无法获取的环境（如部分评测环境）停留在优雅降级路径，此时不产生指标文件，属于预期结果。
- 图表分组最多 6 个。
- 集成本身是代码修改，OcmsRecorder、recorder.log() 和框架回调均为 Python API 而非命令。
前置条件 需要待集成的 PyTorch 训练脚本、Python 3.8+ 且已激活训练环境、以及训练输出目录。集成前需与用户确认训练环境、PROJECT_DIR、OUTPUT_DIR、METRICS 环境变量、chart_groups、step/metrics 参数和 rank-0 上报等参数。IAM 权限方面无需额外权限。