AI 开源复现清单：README 跑通只是最低标准

AI 开源复现清单：README 跑通只是最低标准

一、复现不是只跑 demo

AI 开源项目很多都有 README、示例命令和预训练权重。能跑通 demo 是好事，但离严谨复现还差很远。论文指标是否一致，数据处理是否相同，依赖版本是否稳定，训练脚本是否完整，评测是否可重复，都需要检查。

开源复现清单的目标，是判断项目能不能被可靠使用，而不是只看它能不能启动。

二、先看项目结构

flowchart TD A[开源项目] --> B[安装说明] A --> C[数据处理] A --> D[训练脚本] A --> E[评测脚本] A --> F[模型权重] A --> G[实验配置]

缺训练脚本的项目只能复用推理，缺评测脚本的项目很难验证指标，缺配置的项目难以复现论文结果。

reproduction_checklist: install_reproducible: true dataset_script: true train_script: true eval_script: true config_files: true

清单比主观印象可靠。

三、环境要锁定

pip freeze > requirements.lock

很多复现失败来自依赖版本。README 写pip install -r requirements.txt，但依赖里没有锁版本，半年后可能完全跑不起来。

Dockerfile、conda env、CUDA 版本、PyTorch 版本都要记录。GPU 相关项目尤其敏感。

四、指标要重新跑

不要只相信 README 里的分数。下载权重后，用项目提供的评测脚本重新跑一次，确认指标接近。

reported_metric: paper: 85.2 reproduced: 84.9 tolerance: 0.5

如果差距很大，要检查数据版本、预处理、随机种子和评测参数。也可能是项目文档不完整。

还要记录修改。复现过程中改了代码、依赖或配置，都要写进日志。否则后续别人无法知道你跑通的是原项目还是修改版。

最后，复现清单要给结论：可直接使用、需要修补、只适合参考、暂不建议使用。开源项目评估要能服务选型。

复现过程中还要记录补丁。为了跑通项目改了哪些文件，是否提交 PR，是否影响指标，都要写清楚。否则团队内部会形成一个没人敢升级的私有魔改版本。

reproduction_patch_log: changed_files: true reason: true upstream_issue: optional metric_impact: required

还要看许可证。模型权重、代码、数据集可能分别有不同许可证。能复现不代表能商用，选型前必须确认使用边界。

最后，开源复现结果要沉淀成内部知识库。环境坑、数据下载、指标差异、补丁记录都保存下来，下一次团队评估同类项目会快很多。

安全检查也不能省。复现开源项目经常需要执行安装脚本、下载权重、运行自定义算子或加载 pickle 文件。对来源不明的产物，要在隔离环境中运行，并记录外部下载地址和校验值。

security_review: run_in_container: true verify_checksums: true avoid_untrusted_pickle: true scan_dependencies: true

还要看项目维护状态。最近一次提交、issue 响应、release 节奏、关键依赖升级记录，都能反映项目是否适合长期使用。一个指标漂亮但无人维护的项目，进入生产链路后维护成本会很高。

如果项目提供 model card 或 data card，也要纳入清单。模型适用场景、训练数据来源、已知限制和风险说明，会直接影响能否在具体业务中使用。

五、总结

AI 开源复现清单要检查安装、数据处理、训练、评测、配置、环境锁定和指标复跑。

README 跑通只是最低标准。真正可用的开源项目，要经得起完整复现实验。