企业官网建设流程全解析

autoresearch-mlx是 Karpathy autoresearch 的 Apple Silicon（MLX）移植版：让 AI 智能体在 Mac 上自主运行「固定 5 分钟训练预算 → 保留或回滚」的自主研究循环，完全不需要 PyTorch 或 CUDA。本指南面向开发者，讲透三个扩展点：如何扩展实验循环、如何移植 Muon 优化器、如何自定义评估预算。

一、30 秒理解：一个四文件构成的自主研究循环

autoresearch-mlx 的设计极简——整个"实验室"就几个文件。先看懂这张表再动手扩展：

循环的核心规则只有一句：只改train.py、只看val_bpb（越低越好）、固定 5 分钟预算、赢则保留、输则回滚。

二、先跑起来：3 条命令启动实验循环

环境要求：Apple Silicon Mac、Python 3.10+、uv 包管理器。

git clone https://gitcode.com/gh_mirrors/au/autoresearch-mlx cd autoresearch-mlx uv sync # 安装依赖 uv run prepare.py # 一次性：下载数据分片 + 训练 BPE tokenizer uv run train.py # 跑一个 5 分钟训练实验

实验结束后会打印一段摘要（格式定义见 program.md 的 Output format 部分）：

--- val_bpb: 2.534000 training_seconds: 312.4 num_steps: 46 num_params_M: 50.3

📌重要：Apple Silicon 的吞吐量和绝对 val_bpb 与 NVIDIA 不同，只和同一台机器上的自己基线比较，不要拿别人的数字当参照。

三、扩展实验循环：加实验、记日志、做保留/回滚

3.1 标准循环的 9 步

program.md 的 "LOOP FOREVER" 一节定义了完整协议：

1. 查看 git 状态 → 2. 修改train.py→ 3.git commit→ 4.uv run train.py > run.log 2>&1→ 5.grep "^val_bpb:" run.log→ 6. 崩溃则看栈追踪 → 7. 记入results.tsv→ 8. 变好则git commit --amend→ 9. 变差则git reset --hard干净回滚。

三条关键纪律：

• ⏱️15 分钟超时：单次运行超过 15 分钟直接杀掉，按失败处理；
• 🚫绝不git add -A：仓库可能嵌在更大的 monorepo 里，只暂存autoresearch-mlx/路径；
• 🌙NEVER STOP：循环开始后不要问人类"要不要继续"——它设计就是整夜无人值守运行，每小时约 8–9 个实验。

3.2 三种扩展方式

① 想法扩展：改train.py顶部的超参数区

所有超参数集中在 train.py，无 CLI 参数，智能体直接改数值即可：

TOTAL_BATCH_SIZE = 2**16 # 总 batch MATRIX_LR = 0.04 # 矩阵参数学习率 DEPTH = 4 # 模型深度 WARMDOWN_RATIO = 0.5 # 学习率衰减尾部比例

训练循环（train.py）按TIME_BUDGET跑满为止，学习率曲线由 get_lr_multiplier 控制（warmup → 平台 → warmdown 三段）。

② 记录扩展：results.tsv的五列格式

commit val_bpb memory_gb status description 5efc7aa 1.807902 20.7 keep reduce depth from 8 to 4

注意必须是制表符分隔的 TSV，不是逗号 CSV——description 里的逗号会破坏解析。

③ 决策扩展：接入rigor.py做显著性门控

单次 5 分钟运行的噪声约0.03 val_bpb，"眼看 delta 决定保留"其实是在追噪声。rigor.py 用"多种子 + bootstrap 置信度"替代肉眼判断：

uv run rigor.py run "halve the batch size" # 跑 3 个种子，对比当前最优 uv run rigor.py run "..." --seeds 5 --confidence 0.9 uv run rigor.py best # 查看当前最优 uv run rigor.py log # 查看所有已评分配置

核心逻辑在 score：第一个种子明显劣于最优就快速放弃；20000 次 bootstrap 重采样下 P(better) ≥ 置信阈值才保留。决策写入rigor_ledger.jsonl，同一份train.py哈希永不重复评分，且它从不修改 train.py、不碰 git、不改评估函数。

3.3 公开基线：扩展循环能做出什么

公开的 results.tsv 初始走势是一个很好的例子：

最后一步尤其说明问题：固定 5 分钟预算内，更小更快的模型能赢过更大的模型——因为它塞进了更多优化步。这正是"步效率"思路，也是循环最擅长挖掘的方向。

四、移植 Muon 优化器：从参数分组设计入手

4.1 为什么 Muon 值得移植

公开的train.py目前只有 AdamW，train.py 里有明确注释："v0.1: AdamW only. Muon port is future work."。而 README.md 记录了 Mac Mini 长跑的获胜配方正是Muon + 更锐利的注意力 + 更小 MLP + 更低标量 LR，且该配方无法干净地迁移到 Max 级机器——说明硬件相关的收益只能在自己的硬件上跑循环发现。移植 Muon 是第一个高价值扩展。

4.2 先读懂现有 AdamW 的三层结构

train.py自实现的 AdamW 分三层，移植思路就是"换中间层"：

1. 参数路由（__init__）：用tree_flatten遍历全部参数，按路径分组——blocks里的二维矩阵参数用matrix_lr+ 权重衰减；wte/value_embeds用embedding_lr；lm_head用unembedding_lr；resid_lambdas/x0_lambdas是标量参数，各有独立学习率；
2. 更新（_step）：梯度、参数、状态全部提升为 float32 计算再写回——注意 bf16/fp32 类型提升陷阱，train.py 的注释解释了残差流为什么必须保持 bf16；
3. 接口：训练循环只依赖update(model, grads)和set_lr_multiplier(multiplier)两个方法（见 train.py）。

4.3 Muon 移植四步法

第 1 步：保留路由，只换更新规则。矩阵（2D）参数改用 Muon 更新；embedding、lm_head、标量继续用 AdamW——这是 Muon 的标准用法。

第 2 步：用 MLX 写 Newton-Schulz 正交化。Muon 的核心是对梯度矩阵做几步多项式迭代（Y ← a·Y + b·Y·Yᵀ + c·(Y·Yᵀ)·Y），关键细节：

• 迭代全程用float32（mx.array.astype(mx.float32)），收敛后再写回 bf16；
• 非方阵（如n_embd × 4·n_embd）要按形状选 Y·Yᵀ 或 Yᵀ·Y 分支；
• 用mx.linalg做矩阵乘，mx.eval及时触发求值，避免计算图累积。

第 3 步：保持接口。新类同样暴露update(model, grads)、set_lr_multiplier(multiplier)和initial_lrs机制（保存初始学习率，按 multiplier 整体缩放）——这样训练循环一行都不用改。

第 4 步：重调学习率并验证。Muon 的矩阵学习率与 AdamW 的 0.04 通常差异明显：先跑单 run 观察 loss 曲线健康度，再用rigor.py run做 3 种子确认真实收益。README 的 Mac Mini 经验是 Muon 与"更低标量 LR"搭配出现，建议一次只动一个变量以便归因。

4.4 常见坑清单

五、自定义评估预算：三个常量与一个 OOM 保护

5.1 控制评估开销的三个常量

固定常量集中在 prepare.py：

EVAL_TOKENS直接决定最终评估的耗时：评估步数 =EVAL_TOKENS ÷ (batch × 序列长)。本项目相对上游版刻意调小了这个值，换取 Apple Silicon 上更快的迭代（见 README.md 的 "Differences from upstream"）。

评估 batch 是另一个常量：train.py 的FINAL_EVAL_BATCH_SIZE = 256。调小省峰值显存，调大缩评估时间。

5.2 2 GiB logits 预算：别删的 OOM 保护

prepare.py 的evaluate_bpb有个不显眼但关键的设计：单次前向会物化一个行 × 2048 × 8192的 float32 logits 张量，按默认 batch 一次要16 GiB——会超过 24GB Mac 上 Metal 的最大 buffer 直接 OOM。因此代码把单次前向的 logits 限制在2 GiB以内自动切分 micro-batch（见 prepare.py）；由于 BPB 是纯求和指标，切分在数值上完全等价。

5.3 ⚠️ 修改评估预算的铁律

prepare.py是循环协议中的只读边界：

• 改EVAL_TOKENS或TIME_BUDGET后，新旧val_bpb不可比，必须重跑基线重新建立参照（program.md Setup 第 5 步）；
• 评估函数evaluate_bpb是 ground truth 指标，循环协议禁止修改评估框架；
• 只想加快迭代时，优先降EVAL_TOKENS（评估耗时同比下降），同时留意噪声下限略有升高——配合rigor.py使用。

六、总结：扩展速查表

这个项目最有价值的习惯是：把"固定预算 + keep/revert"当成科学方法——想法空间可以很狂野（架构、优化器、batch、深度都行），但判定纪律不能松。无论你扩展循环、移植 Muon 还是调整评估预算，按这个节奏把任务交给 AI 智能体整夜运行，早上醒来就能收获新的最佳结果 🎯