文档维护规范¶
本项目把文档视为实验系统的一部分。代码入口、配置、评测口径和论文事实变化时,文档必须能指出“哪一层发生了变化”。
信息来源优先级¶
- 当前仓库代码与测试:解释“本项目实际做什么”;
- 当前 Gin 配置:解释默认可运行实验,不把 Python 默认值误写成实验默认值;
results.json、日志和BENCHMARKS.md:解释本仓库实际结果;- 论文原文及附录:解释作者提出了什么;
- 作者/机构官方代码:补足论文未写清的实现细节;
- 二手文章只用于发现线索,不作为关键数字的唯一证据。
当论文与本仓库不一致时,必须并列写清“论文设定”和“本仓库实现”,不能为追求叙述平滑而混为一体。
模型页固定结构¶
每个模型页至少包含:
- 一句话定位与状态卡;
- 论文与官方实现来源;
- 输入、输出和 item 表示;
- 核心机制及必要公式;
- 从数据集到指标的端到端流程;
- 代码文件、类和函数映射;
- 当前配置与可直接复制的命令;
- checkpoint、缓存和外部模型依赖;
- 评测口径;
- 与论文差异、已知限制和失败证据;
- 调试/扩展建议;
- 参考文献。
新页面可复制模型文档模板。
状态声明¶
不要只写“支持”。使用可验证的状态组合,例如:
禁止以下写法:
- “SOTA”“显著提升”但没有数据集、口径和来源;
- “与论文一致”但未列出核验项;
- 把 SID-level、sampled-negative、in-batch 与 full-catalog 指标放进同一列;
- 把 tokenizer 当作独立推荐模型计数;
- 用当前默认配置解释历史 checkpoint,却不记录历史配置;
- 从旧日志复制结果但不保留来源路径。
时间与版本¶
- 领域目录首页记录**资料检索截止日期**,避免“最新”成为永久承诺;
- 模型页只在行为发生变化时更新“最近核验”,不为无内容改动刷日期;
- 不稳定结论写“截至 YYYY-MM-DD”;
- 未来论文或尚未公开工作标为 preprint,不提前写会议接收状态;
- 代码行号容易漂移,文档优先链接文件、类与函数名。
结果变更检查表¶
结果进入文档前检查:
-
model / split / seed / protocol / metric level完整; - checkpoint 与精确源码 provenance 可定位;
- valid 选择规则与 test 报告规则明确;
- SID 模型已报告 collision,并使用 item-level headline;
- 多 seed 的均值/标准差没有跨协议聚合;
- 论文数字明确标“论文报告”,本项目数字明确标“本仓库复现”;
- 失败实验保留诊断与下一步,不只留下最好数字。
文档验证¶
本地建议执行:
提交前还应搜索陈旧状态词和缺失页面:
rg -n "待补充|TODO|训练中|7 种模型|8 种模型" docs/zh
rg -n "^# " docs/zh/models docs/zh/architecture docs/zh/landscape
如果只维护中文,中文是事实的 canonical 版本;英文页允许暂时 fallback,但导航和状态页必须明确英文覆盖不完整,不能宣称双语完全同步。