auto-research

自动研究

针对用户提出的目标（例如准确率、奖励、吞吐量、延迟、稳定性或其他特定配方的指标），在此仓库中迭代运行 NeMo-RL 实验，并使用 git 记录研究过程。

将依赖项视为已就绪，但要审慎选择运行环境。以配方规定的权威指标为准。保持更改精简、可复现且简单。保留无关的用户工作。

**安全：**此技能会创建 git 分支、向磁盘写入文件，并执行包括可能消耗 GPU 资源的训练任务在内的 Shell 命令。创建分支或启动任务前，务必先与用户确认实验计划。未经用户明确批准，不得执行破坏性 git 操作（reset、force-push），也不得启动计算密集型任务。

每次自动研究实验都要使用 session-memory 技能。创建分支前，先开始或恢复会话记录；制定计划后、进行有意义的编辑或启动长时间运行的任务前后、用户改变方向时，以及交接或撰写最终总结前，都要保存检查点。

上下文压缩、交接、断开连接或长时间间隔后，重新加载此技能及已使用的任何配套技能，阅读最新的 session-memory 交接记录，并重述总体目标、停止规则、当前分支和最新结果。将后续指示视为补充，除非用户明确更改主要目标。

工作流

1. 检查当前 git 状态，并在创建分支前找出无关的用户更改。
2. 使用共享分支前缀。优先采用用户提供的前缀；否则创建一个描述性默认值，例如 autoresearch/2026-03-24-dapo-qwen2p5。
3. 阅读目标配方、其上级配方，以及 examples/run_grpo.py、nemo_rl/models/、nemo_rl/algorithms/、nemo_rl/environments/ 和 docs/ 中的相关代码路径。对于 NeMo-gym 配方，还要检查 examples/nemo_gym/ 中的入口点、配置和启动脚本。
4. 将用户提出的停止规则转换为可监控的明确值，例如将要求的实验次数设为 target_experiment_count，并设置 campaign_deadline、per_experiment_timeout 或 target_metric。
5. 验证所需数据、检查点、运行时输入和启动器。
6. 创建未跟踪的 TSV 日志和每个实验的日志目录。
7. 如果不存在基线，先在 <prefix>/baseline 上运行基线。

对于 GPU、CPU 密集型、分布式或长时间运行的任务，要审慎选择执行环境。当前机器具备适用的 GPU 和足够容量时，在本地运行；否则遵循用户指定的环境，使用 launch-nemo-rl 运行 nrl-k8s/Kubernetes 上的任务，使用 Slurm 环境自带的启动器，或在启动前向用户确认。仅将本地 CPU 运行用于轻量检查、试运行和短时非 GPU 检查。

如果用户提到 Brev，或者 /home/ubuntu/RL 存在且 /ephemeral 可用作卷，则将此机器视为 Brev 实例，并在创建实验目录、缓存、日志、检查点或已认证的运行时状态前使用 brev-etiquette。

分支管理

• 每个实验都在共享前缀下的独立分支上进行。
• 保留所有分支，包括失败或效果不佳的分支。
• 每个分支至少提交一次假设。
• 如果有充分理由重跑，则在同一分支上追加修复提交。
• 绝不能暗中暂存、重置或覆盖无关的用户更改。如果实验会涉及有未提交更改的文件，请使用单独的工作树，或先征求用户同意。

具体操作模式见 references/git-workflow.md。

循环

1. 选定一个具体假设。
2. 创建一个分支，例如 autoresearch/2026-03-24-dapo-qwen2p5/prompt-compact-schema。
3. 只编辑必要的最少文件。
4. 提交该假设。
5. 启动运行前，检查受监控的停止条件。除非某项条件已明确满足，否则不要提前停止。
6. 根据配方或日志代码确定权威指标来源，然后使用唯一的日志路径运行：

LOG_DIR=reports/auto_research/<campaign>/<experiment>
mkdir -p "$LOG_DIR"
uv run <entrypoint> > "$LOG_DIR/run.log" 2>&1

7. 如果用户为每次实验指定了墙钟时间限制，请明确执行。若配方中已有超时设置，优先使用；否则用外部超时命令包装运行命令。如果两者都有，则遵守更严格的限制。
8. 使用适用于实际日志格式的命令提取主要指标。如果提取结果为空，请检查日志末尾几行和配方的日志路径，然后再标记本次运行。
9. 在 TSV 中记录索引、分支、父提交、提交、配方、指标名称、指标值、内存（GB）、耗时（分钟）、启动器、作业 ID、命令、日志路径、状态和描述，并提供足够的计时或计数信息来评估停止规则。
10. 在整个实验过程中定期向用户发布进度更新。更新中应包含当前分支、最新已知结果、已尝试的实验数（如适用，还包括剩余实验数）、剩余实验时间（如适用），以及是否已满足任何停止条件。
11. 实验完成后重新检查受监控的停止条件，并明确说明结果，例如 stop condition not yet met: 17/24 attempted, 6h12m remaining 或 stop condition met: 24/24 attempted。
12. 将结果标记为 keep、discard 或 crash，然后转到下一个分支，除非已明确满足用户指定的停止条件。

对于基于次数的停止规则，统计已尝试的想法，而不只是成功或完整完成的运行。

对于实验活动时间预算，在活动开始时将用户设置的时限换算为绝对截止时间，并持续检查剩余时间。

对于单次实验预算，每次运行都要设置超时，并将超时视为失败。

示例：

• do 50 experiments：只有在 TSV 中存在 50 条已尝试实验记录后才停止
• 10h total, 1h each：每次运行限制为 1 小时；当 10 小时活动预算用尽，或剩余预算不足以启动另一次 1 小时运行时停止
• 50 experiments or 10h total, 1h each：监控所有三个数值，绝不超过单次运行上限；只有明确达到某项活动级停止条件时才停止

优先事项

优先选择预期目标增益高、复杂度成本低的想法：

• 正确性和后端兼容性
• 提示词和 rollout 格式
• 批次、序列和精度布局
• 优化器和调度器调优
• 奖励塑形、裁剪或缩放
• 数据集混合或验证变更
• 根据硬件选择同步或异步执行

其他条件相同的情况下，优先选择更简单的改进，避免脆弱的硬件专用技巧。

避免

• 不要根据未充分测试的冒烟运行断定某个训练想法失败。如果运行采用了极小的批次、极少的优化步骤，或其他不具代表性的设置，应将其视为仅验证流程；要以有意义的批次规模训练足够长时间来检验假设，然后再标记为 discard。
• 如果 Slurm 批处理作业的启动开销很大，且失败后需要快速迭代，不要反复为紧凑的“编辑—运行—调试”循环支付批处理调度开销。应使用文档中说明的交互式 Slurm 模式，或在重新提交更多批处理作业前询问用户。
• 不要让上下文压缩或后续引导问题抹去最初的活动目标。刷新 session-memory，重新加载当前启用的技能，并保留主要目标，除非用户明确更改目标。

停止

如果用户给出了明确的停止条件，则这些条件优先于通用规则。不要因为搜索感觉已经足够就停止；只有在明确满足所要求的数量、截止时间、预算或目标条件后才能停止。

在整个活动期间，明确告知用户是否已满足停止条件。如果尚未满足，请具体说明剩余数量、剩余时间或其他剩余阈值。

如果用户没有给出明确的停止条件，请先执行基线测试，再进行最多三次低风险实验，然后总结最佳结果并询问是否继续。

参考资料

• references/git-workflow.md，用于了解分支、工作区脏状态、父提交和基线规则。
• references/exploration-ideas.md，用于将症状转化为具体假设。
• references/experiment-log-template.md，用于了解 TSV 架构和可复现性字段。