OpenResearch 运行证据链用orx logs设计、校验与解读实验证据【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch运行日志是 OpenResearch 实验的证据通道一个 run 的终端输出在运行时被实时捕获、运行结束后持久化之后通过orx logs按需回读。本指南讲解如何把“judge a run判定一次运行的结果”这件事做成工程化流程——在 launch 之前设计 stdout 应输出的指标与摘要在 run 结束后用orx logs读回持久化结果并在汇报任何由运行推导的结论之前完成一套可重复的证据校验。读完本文你将掌握orx logs的四种读取模式与字节窗口语义、证据型 run 命令的撰写规范以及一套“截断不等于不存在”的取证式排查方法可直接套用到 nanochat 这类真实 demo 实验的复盘与汇报中。一、为什么日志是证据捕获与持久化机制OpenResearch 把一个实验的判定依据收敛为一条原则如果 run 的结果没有出现在它的日志里事后就无法再检视。因此 run 命令必须把“判定结果所需的全部信息”打印到 stdout——最终指标、紧凑摘要、关键配置——日志被截断或丢失都不可接受。从源码实现看这一机制在本地平面LocalPlane中落为read_log日志按 run 持久化到数据目录下的run-logs/runId.log文件路径由 src/store.rs 中的log_path()计算其中 run id 会被过滤为仅 ASCII 字母数字与-/_防止异常数据逃逸出日志目录。读取时通过std::fs::metadata获取文件总字节数再按请求模式在文件中定位窗口见 src/plane/local_plane.rs。字节窗口的三种定位模式本地实现定义了三种窗口计算方式对应orx logs的三种读取形态模式窗口计算语义tail默认(total - max).max(0)到total读末尾通常是判定结果最关心的部分head0到max.min(total)从开头读起rangestart.clamp(0,total)到end.clamp(0,total)精确字节窗口[start, end)默认字节上限为 64 KB常量LOCAL_DEFAULT_BYTES 64 * 1024这也是原文档默认值的来源。当文件不存在时返回missing_local标记CLI 层打印[local file] no log captured yet for this run.src/commands/logs.rs。stdout 与 stderr 的分流设计日志正文写入stdout而[source] bytes a–b of N状态行写入stderrsrc/commands/logs.rs。这是刻意的管道友好设计状态行不会污染| grep或重定向。状态行由RunLog::footer()生成src/plane.rs当窗口上下被截断时会追加(more above)、(more below)提示。source字段表明日志来源本地平面固定为local file。run id 从哪里来run id 由orx runs projectId列出。src/commands/runs.rs 以表格形式ID / STATUS / EXPERIMENT / COMMIT / DURATION / UPDATED按最新优先列出项目下所有 run可用--experiment expId过滤到单个实验。注意runs命令不仅是 id 的来源也是整个自动研究循环中的source of truth每次orx exp wait唤醒后都要重新读取它并核对所有新终态的 run。二、orx logs四种读取方式详解核心命令的完整用法orx logs runId # tail默认通常是你想要的末尾 orx logs runId --head # 改为从头读取 orx logs runId --bytes 200000 # 提高字节上限默认 64 KB最大 1 MB orx logs runId --range 4096:8192 # 精确字节窗口 [start, end)参数定义见 src/main.rs--head布尔开关--bytes与--range均为字符串。--range必须满足end start否则 CLI 报错退出src/commands/logs.rs--bytes必须是整数src/commands/logs.rs。--head读开头从头读取。在本地实现中等价于窗口(0, min(max, total))即最多取文件前 64 KB可调。适合查看 run 的启动阶段环境准备、依赖安装、配置回显。示例demo 的端到端日志 demo/nanochat/run-output.txt 开头即回显了command: bash runs/runcpu.sh python -m scripts.chat_cli ...与“Tokenizer, base training, and base evaluation”的分段标记。--bytes提高字节上限默认 64 KB 对单次读取可能不够例如一个训练日志单行就 100 字节、动辄数千行。--bytes 200000将窗口扩到 200 KB最大 1 MB。注意上限用于定位窗口tail模式下是“从末尾往前取 N 字节”head模式下是“从开头往后取 N 字节”。--range精确字节窗口--range 4096:8192精确读取第 4096 到 8191 字节。它是长程轨迹取证的关键工具先 tail 拿到末尾摘要发现需要核对中间某个 step 时不必重新拉全文直接按字节定位。窗口端点会clamp到[0, total]范围内越界不报错。状态行解读每次读取stderr 都会出现形如[local file] bytes 0–65536 of 131072 (more below)含义source日志来源本地为local filebytes a–b of N本次返回的字节区间与文件总大小(more above)/(more below)本次窗口上/下仍有未读内容即truncated_before/truncated_after为真。这正是“截断提示”的可读形式——截断不是终点而是继续读取的信号。三、让 run 自己打印证据run 命令设计规范OpenResearch 要求 run 命令按以下规范组织 stdout使日志成为“自含的证据包”结尾打印最终指标 紧凑摘要块而不是训练过程中零散输出。判定一个 run 时你只读末尾几 KB 就能得到结论不必扫描全程。回显实际使用的配置让日志能标识出“变体”variant。多实验并行时日志本身必须能自证它属于哪个配置否则无法区分结果来源。长 run 定期打印单行指标使其轨迹能通过字节窗口读取恢复。训练中间的过程值loss、lr、tok/sec 等是判断收敛、发散与归因的原料。对照真实案例nanochat demo 的证据型日志仓库内的端到端 demo 恰好演示了这一规范的效果。demo/nanochat/run-output.txt 7355 行结构如下开头命令回显与环境准备前 ~200 行主体step 0XXXX (xx.xx%) | loss: x.xxxxxx | lrm: x.xx | dt: xxxx.xxms | tok/sec: x,xxx | mfu: x.xx | epoch: 1 | total time: xx.xxm的单行周期指标step 01499 结尾处见 demo/nanochat/run-output.txt结尾Minimum validation bpb: 0.7389等最终摘要随后是 chat 确认与run completed successfully收尾demo/nanochat/run-output.txt。对应的结构化解读结果落在 demo/nanochat/evidence/evaluation-metrics.jsonbaseEvaluationtrainBpb 1.152185 / validationBpb 1.119301、core任务准确率、finalbaseValidationBpb 1.165758 / sftValidationBpb 0.7389 / chatAnswer Paris。demo/nanochat/evidence/final-inference.txt 则以人类可读形式记录了最终推理的命令、检查点、设备与回答。日志里的最终数字0.7389、Paris与持久化的证据文件完全对齐——这正是“最终指标 紧凑摘要”设计的落点。触发点什么时候加载 orx-evidence根据技能的 frontmatter 描述应在以下时机使用启动一个“其输出将被判定”的 run 之前——先设计好 stdout 证据再 launchrun 结束之后——用orx logs读回结果分析或汇报 run 结果之前——先完成证据校验再下结论。这与 agent-skills/orx-experiment-tree/SKILL.md 的自动研究循环衔接步骤 4 明确要求“launch 前加载 orx-evidence确保提交的代码输出足以判定该节点”步骤 7 要求在每次完成时用orx logs runId真正读取结果而不是从状态推断。四、汇报前的校验清单四步确认法在接收或汇报任何由 run 推导的结论之前禁止凭运行状态或记忆推断结果。必须逐项确认日志标识了变体与有效配置——回显的配置与当前节点branch/commit对应最终指标与紧凑摘要存在——末尾有完整的判定材料长 run 的相关轨迹可恢复——周期性单行指标可被定位读取返回的字节窗口确实包含支撑输出——你读到的内容覆盖了结论所依赖的那一段。关键原则截断不是“不存在”的证据“Truncated output is not evidence of absence”截断的输出不是不存在的证据。当状态行显示(more above)或(more below)时应继续用--head、--bytes或--range读取直到相关部分被完整读到。反过来一次只读 64 KB 就断言“日志里没有该指标”同样属于证据误判。失败 run 的取证路径orx runs对 failed run 会额外打印reason:行。若失败信息未记录会提示reason: — (no message recorded — see orx logs runId)src/plane.rs——明确把日志定位为失败归因的唯一途径。按 agent-skills/orx-compute/SKILL.md 的指引provider 容量类失败通常可重试而启动后的失败必须读取orx logs归因一个 failed run 不构成新节点应修复后重跑同一实验见 orx-experiment-tree 的“repair, dont branch”。汇报格式evidence-and-links 契约校验通过后按会话 playbook 的evidence-and-links 契约格式化聊天回复每个由运行推导的结论都要链接到对应的证据文件含完整嵌套路径例如报告中的插图链接到figures/下可复现脚本旁的 SVG。这条契约由 agent-skills/orx-reports/SKILL.md 定义其中明确“当报告包含由 run 结果推导的声明时加载 orx-evidence”并由测试在 src/local/agent_skills.rs 中强制校验evidence 技能必须包含“Validate before reporting”与“Truncated output is not evidence of absence”且与 reports 技能保持职责边界。五、完整工作流从设计证据到汇报把前述要素串成一个可复用的闭环launch 前加载 orx-evidence检查 run 命令是否会打印最终指标、紧凑摘要与有效配置长 run 确认有周期单行输出。需要时用orx project edit projectId --run-command cmd设定 run 命令见 agent-skills/orx-create/SKILL.md。run 结束后orx runs projectId拿到 run id 与状态对 failed run 先读reason:再决定是否需要取证。读证据orx logs runIdtail 读末尾摘要摘要不足时按需--head、--bytes、--range补充直到状态行不再提示截断、且目标字节窗口确实包含支撑输出。校验核对四步确认法清单——变体标识、最终指标、轨迹可恢复、窗口覆盖。汇报按 evidence-and-links 契约把每个结论链接到持久化证据文件参考 demo 的 demo/nanochat/evidence/evaluation-metrics.json 与 demo/nanochat/evidence/final-inference.txt 的组织方式。六、常见误区与边界把 run 状态当结果statusdone只说明进程退出码不代表“答案正确”结论必须来自日志内容。把记忆当证据多轮会话中容易凭印象汇报数字任何 run 推导的声明都要回到日志与持久化证据核对。一次 tail 就下结论64 KB 默认窗口可能漏掉中部轨迹(more above/below)提示出现时继续读。截断视为缺失截断只是窗口限制不是内容不存在用--head/--bytes/--range追读。stderr 状态行被忽略或误当正文状态行进 stderr 是刻意的| grep或重定向时它不会混入正文但阅读完整输出时不要漏掉它传达的截断信息。--range写反必须end start否则 CLI 直接报错退出。边界方面需要说明本文描述的字节语义、默认 64 KB 上限与 1 MB 上限、stderr 状态行格式均以当前仓库的本地平面实现src/plane/local_plane.rs为准不同 compute 后端hf、modal、k8s、ssh、slurm、ray、openresearch、tinker的日志来源字段与具体行为可能不同但orx logs的 CLI 契约与证据校验原则一致。跨后端运行日志的读取均通过统一的LogRequest结构下发src/plane.rs保证了命令层的一致性。【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
