OpenResearch 实验证据包设计指南：以 nanochat demo evidence 为例解读可审计、可复现的轻量实验产物管理

OpenResearch 实验证据包设计指南：以 nanochat demo evidence 为例解读可审计、可复现的轻量实验产物管理

【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch

在 OpenResearch 的 demo 项目中，demo/nanochat是一个完整的 nanoGPT 风格小模型训练演示，而demo/nanochat/evidence则是它沉淀下来的"证据包"（evidence pack）。本文围绕 demo/nanochat/evidence/README.md 展开，系统讲解这套证据包的设计初衷、目录结构、文件语义、生成机制与复现路径：读完本文，你将掌握"如何在不打包数 GB 训练工作区的前提下，保存一份可审计、可复现、可被后续分析直接消费的实验证据"。

一、为什么需要"证据包"：问题背景与设计目标

一次完整的 nanochat 实验会产生多种产物：模型权重、优化器状态、训练日志、评估结果、分词器、推理转录等。其中模型权重（model_*.pt）与优化器状态（optim_*_rank0.pt）单个文件即可达到数百 MB——以 run-manifest.json 的记录为例，一个 base checkpoint 的model_005000.pt为 294,145,379 字节，对应的optim_005000_rank0.pt为 545,905,413 字节，加上 SFT 阶段的两份同类文件，仅权重与优化器就接近 1.7 GB；再叠加base_data_climbmix（9 个文件，约 826 MB）、task_data（24 个文件，约 1.02 GB）与eval_bundle（77 个文件，约 169 MB），整个工作区高达数 GB。

把这些大文件全部提交进 Git 仓库或项目制品既无必要也不现实。因此 evidence 包遵循一个明确的分层策略：

• 打包进证据包：体积小、信息密度高、能支撑"查看实验结论"的小型产物——训练指标、评估指标、checkpoint 元数据、分词器、推理转录、产物清单；
• 留在运行工作区：模型权重、优化器状态、数据集、评测语料、Python 环境与包缓存——它们体积巨大且可由脚本重新生成。

这套设计让任何人 clone 仓库后无需下载数 GB 文件，即可快速检视实验的关键结论；同时通过run-manifest.json保留了大文件的路径、字节数与哈希，保证"哪些文件被有意排除"这一点完全透明、可追溯。

二、证据包目录结构与文件语义

demo/nanochat/evidence下的完整结构如下：

evidence/ ├── README.md # 证据包说明（本文主体） ├── training-metrics.csv # 逐 step 训练指标 ├── evaluation-metrics.json # 评估与最终指标 ├── final-inference.txt # 最终 SFT 检查点推理转录 ├── run-manifest.json # 产物清单（含哈希） ├── checkpoints/ │ ├── base/ │ │ └── meta_005000.json # 最终 base 检查点元数据 │ └── sft/ │ └── meta_001499.json # 最终 SFT 检查点元数据 └── tokenizer/ ├── tokenizer.pkl # 分词器对象（pickle 格式） └── token_bytes.pt # 分词器字节表（PyTorch tensor）

2.1training-metrics.csv：逐 step 的训练轨迹

CSV 首行为表头phase,step,loss,validation_bpb,tokens_per_second,total_minutes，phase取base或sft，按 phase 与 step 升序排列。以 base 阶段第 0、100、5000 步为例：

phase	step	loss	validation_bpb	tokens_per_second	total_minutes
base	0	10.397551	3.195800	6072	0.00
base	100	6.374492	1.940739	10513	2.30
base	5000	3.751467	1.165758	11048	131.55

其中validation_bpb仅在每个eval_every步（base 为 100，SFT 为 200）记录一次，SFT 阶段 step 0 的1.0174来自 SFT 开始前的初始验证。整份 CSV 共 6502 行，覆盖 base 5000 步与 SFT 1500 步。它直观展示了 base 阶段 loss 从约 10.4 平滑下降至 3.75、吞吐稳定在 1 万 token/秒左右的完整过程，是检查训练健康度、复现曲线的主力数据源。

2.2evaluation-metrics.json：评估结论的单一入口

该文件把三块结论浓缩为一个 JSON：

• baseEvaluation：base 阶段训练的trainBpb（1.152185）与validationBpb（1.119301）；
• core：base 检查点在 CORE 任务集上的逐项结果，包含bigbench_qa_wikidata（accuracy 0，耗时 0.82s）、openbook_qa（0.25，1s）、winogrande（0.5625，centered 0.125，0.79s）、bigbench_operators（0，1.2s）四项，字段为task、accuracy、centered、seconds；
• final：最终结论——baseValidationBpb为 1.165758，sftValidationBpb为 0.7389，chatAnswer为"Paris"（即 SFT 后模型对"法国首都"提问的回答）。

注意final.baseValidationBpb（1.165758）与baseEvaluation.validationBpb（1.119301）数值不同，前者来自训练日志中 base 最后一轮验证（即 CSV 中 base step 5000 的 1.165758），后者来自base_eval的独立评估，二者口径不同，在分析时不可混用。

2.3 checkpoint 元数据：复现训练配置的权威记录

• checkpoints/base/meta_005000.json 记录 base 阶段第 5000 步：val_bpb1.16576、模型结构（sequence_len512、vocab_size32768、n_layer6、n_head6、n_kv_head6、n_embd384、window_pattern"L"），以及完整的user_config——包括学习率分策略（embedding_lr0.3、unembedding_lr0.008、matrix_lr0.02、scalar_lr0.5）、批量配置（device_batch_size32、total_batch_size16384）、warmup/warmdown 计划（warmup_steps40、warmdown_ratio0.65、final_lr_frac0.05）、数据流状态（pq_idx2、rg_idx48、epoch1）与循环状态（min_val_bpb、smooth_train_loss3.75147、total_training_time7893.22 秒）。
• checkpoints/sft/meta_001499.json 记录 SFT 第 1499 步：val_bpb0.73887，user_config中load_optimizer为 0（SFT 使用全新优化器）、init_lr_frac0.8、warmup_ratio0.0、warmdown_ratio0.5、final_lr_frac0.0、eval_every200、mmlu_epochs3、gsm8k_epochs4。

这两份元数据不依赖权重即可完整描述"模型长什么样、用什么配置训练的"，是对外复现与审计的核心证据。

2.4final-inference.txt：推理结论的原始转录

final-inference.txt 记录了最终 SFT 检查点的一次真实推理：

Command: python -m scripts.chat_cli -p "What is the capital of France?" Checkpoint: chatsft_checkpoints/d6/model_001499.pt Checkpoint step: 1499 Device: mps Prompt: What is the capital of France? Response: Paris Paris is a city known for its historical and cultural significance. ... Run status: completed successfully

它保留了设备（mps，即 Apple Silicon 的 Metal 后端）与运行状态，其含义是：一个在 MacBook 上训练 131 分钟的小模型确实能回答出"Paris"——但后续文本出现大量重复数字串，也如实暴露了小模型在长文本生成上的缺陷。转录如实保存，不美化结果，这正是证据应有的姿态。

2.5run-manifest.json：包内与包外的分界清单

清单（schemaVersion 1）记录了本次运行的命令、设备（mps）、状态（completed）、base 目录（$ORX_RUN_DIR/repo/.cache/nanochat）以及每个产物的四元信息：path（工作区相对路径）、kind（checkpoint_metadata/model_checkpoint/optimizer_checkpoint/tokenizer）、bytes、sha256，并用bundledAt标明是否打包进 evidence 及目标位置。例如base_checkpoints/d6/meta_005000.json的bundledAt为evidence/checkpoints/base/meta_005000.json，而 294 MB 的model_005000.pt的bundledAt为null。末尾的omittedDirectories精确列出被排除的三个目录及其文件数与总字节数。

这份清单的价值在于："哪些文件是证据包主动排除的"不再依赖口头约定，而是机器可读的事实，后续分析可以据此区分"仓库里有的文件"与"本地才有的文件"。

三、生成机制：generate-demo-evidence.mjs是如何工作的

README 明确指出：training-metrics.csv与evaluation-metrics.json并非手工整理，而是由 scripts/generate-demo-evidence.mjs 从 demo/nanochat/run-output.txt 重新生成；checkpoint 元数据、分词器文件、推理转录与清单则是从真实运行中直接保留。

该脚本的解析逻辑如下：

• 以=== Supervised fine-tuning ===为分界切换phase（base → sft）；
• 用正则^step (\d+)(?:\/\d+)? .*?\| loss: ([\d.]+).*?\| tok\/sec: ([\d,]+).*?\| total time: ([\d.]+)m解析每步训练日志，写入loss、tokensPerSecond、totalMinutes；
• 用^Step (\d+) \| Validation bpb: ([\d.]+)解析周期性验证的 BPB；
• base 阶段另用^train bpb:/^val bpb:解析baseEvaluation，用^Evaluating: ([^ ]+).*?accuracy: ([\d.]+) \| centered: ([\d.]+) \| time: ([\d.]+)s解析 CORE 任务逐项结果；
• 最终通过findLast取两个 phase 各自最后一轮验证 BPB 作为final.baseValidationBpb与final.sftValidationBpb，chatAnswer固定记录为"Paris"（对应推理转录中的回答）。

从实现可见两个设计要点：其一，CSV 与 JSON 是日志的可复算派生品，只要保留原始日志，任何一步都可以重新推导，防止人工转录错误；其二，JSON 里final段的 BPB 与 CSV 中对应 step 的validation_bpb完全一致（1.165758 / 0.7389），两处数据互相印证。这也提示读者：复现证据包时，只需保证run-output.txt中这几类日志行的格式稳定，生成脚本即可直接复用。

四、有意省略的内容与复现路径

README 明确列出"不打包"的部分：模型权重、优化器状态、下载的数据集、评估语料、Python 环境与包缓存。这些内容体积达数 GB，且正常保留在运行本地工作区（即$ORX_RUN_DIR/repo/.cache/nanochat），不应进入 Git 仓库或项目制品。

若要在全新环境中完整复现这套工作区，README 给出的命令是bash runs/runcpu.sh。该脚本位于 demo/nanochat/experiment/runs/runcpu.sh（demo/nanochat/base/runs/runcpu.sh亦存在同源版本），其关键流程为：

1. 环境准备：设置NANOCHAT_BASE_DIR与UV_CACHE_DIR到.cache下；若无uv则按平台安装（Windows 用 PowerShell 安装脚本，其余用curl | sh）；uv sync --extra cpu安装 CPU 依赖，并激活虚拟环境；
2. 分词器训练：python -m nanochat.dataset -n 8准备数据，python -m scripts.tok_train --max-chars=2000000000在约 20 亿字符上训练分词器（脚本注释提到在 MacBook Pro M3 Max 上约 34 秒），随后python -m scripts.tok_eval校验；
3. base 阶段：python -m scripts.base_train以--depth=6 --head-dim=64 --window-pattern=L --max-seq-len=512 --device-batch-size=32 --total-batch-size=16384 --eval-every=100 --eval-tokens=524288 --core-metric-every=-1 --sample-every=100 --num-iterations=5000训练 6 层小模型（注释称该配置在 M3 Max 上约 30 分钟完成），随后python -m scripts.base_eval --device-batch-size=1 --split-tokens=16384 --max-per-task=16做 CORE 评估；
4. SFT 阶段：python -m scripts.chat_sft --load-optimizer=0 --eval-every=200 --eval-tokens=524288 --chatcore-every=-1 --num-iterations=1500使用全新优化器继续训练 1500 步；
5. 对话验证：python -m scripts.chat_cli -p "What is the capital of France?"，脚本注释提示模型应能答出 Paris，也提示"先打招呼再提问效果可能更好"。

脚本开头的注释也对预期做了坦诚限定："训练 LLM 需要 GPU 算力与预算，在 MacBook 上你不会走太远，请把这个运行当作教育/娱乐演示，而不是预期能跑出很好效果的东西"——这与 demo/nanochat/base/README.md 的定位一致。证据包记录的mps设备与约 1.1 万 token/秒的吞吐，也正是这套 CPU/MPS 演示环境的真实写照。

五、安全注意事项：pickle 格式的加载边界

README 特别强调：tokenizer/tokenizer.pkl使用 Python 的 pickle 格式，必须只通过 nanochat 可信的分词器代码加载。pickle 反序列化存在任意代码执行风险，直接pickle.load不可信文件等同于执行其中嵌入的任意代码。实际使用时，应当走 nanochat 自身的分词器入口（如 demo/nanochat/base/nanochat/tokenizer.py 提供的加载路径），由训练代码在同一环境下保存、同一套代码加载，形成可信闭环。配合 run-manifest.json 中记录的tokenizer.pkl（412,105 字节，SHA-256387cfc08...）与token_bytes.pt（132,649 字节，SHA-256409e71bd...）的哈希值，可以校验文件完整性后再加载。

六、小结：把"证据"做成工程资产

回顾 nanochat 的 evidence 包，可以提炼出四条可迁移到任何研究项目中的工程原则：

1. 分层打包：按体积与信息密度划分"入包"与"留本地"，避免仓库被数 GB 二进制撑爆；
2. 派生数据可复算：CSV/JSON 由原始日志经 generate-demo-evidence.mjs 确定性生成，任何一步结论都能回溯推导；
3. 清单即审计接口：run-manifest.json用路径 + 字节数 + SHA-256 +bundledAt四元组划清"打包/未打包"边界，哈希可校验、可区分；
4. 结论与局限并陈：既保留"答出 Paris"的成功转录，也如实保留长文本重复的原始输出，不修饰证据。

对于使用 OpenResearch 管理实验的用户而言，这套 evidence 模式同样适用于 agent-skills/orx-evidence 所倡导的证据留存实践——把小型、高信息密度、可复算的产物沉淀为仓库内的一等公民，而把可再生的巨型产物留给运行工作区，是让实验结论长期可查、可引、可复现的最经济方案。

【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch