发布研究代码的提示

💡 汇总了最受欢迎的机器学习研究仓库中的最佳实践——现已正式成为 NeurIPS 2021 的官方指南！

基于对200多个机器学习仓库的分析，这些建议有助于提高可重复性，并且与 GitHub 星数呈正相关。更多详情请参阅我们的博客文章。

对于 NeurIPS 2021 的代码提交，建议（但非强制）使用 README.md 模板，并尽可能勾选下方 ML 代码完整性检查清单中的各项内容。

📋 README.md 模板

我们提供了一个 README.md 模板，供您发布机器学习研究仓库时使用。该模板中的各部分内容是通过对现有仓库进行考察得出的：我们关注哪些仓库在社区中反响最好，并从中提炼出与受欢迎程度相关的常见组件。

✓ ML 代码完整性检查清单

我们通过梳理最受欢迎的机器学习研究仓库中的共性，编制了这份检查清单。此外，我们还优先考虑那些能够促进可重复性、便于他人在此基础上进一步开发研究代码的条目。

ML 代码完整性检查清单包含以下五项：

1. 依赖项说明
2. 训练代码
3. 评估代码
4. 预训练模型
5. README 文件，包含结果表格及用于运行或重现这些结果的精确命令

我们验证发现，勾选检查清单中更多项目的仓库，往往拥有更多的 GitHub 星数。这一结论是通过对 NeurIPS 2019 官方仓库的分析得出的——更多细节请参见博客文章。我们还提供了用于复现该分析的数据和笔记本。

NeurIPS 2019 中同时具备上述五个要素的仓库，其 GitHub 星数最高（中位数为196颗，平均值为2,664颗）。

下面我们详细解释检查清单中的每一项。

1. 依赖项说明

如果您使用的是 Python，这意味着需要提供 requirements.txt 文件（如果使用 pip 和 virtualenv），或者提供 environment.yml 文件（如果使用 Anaconda），又或者如果是库形式的代码，则需要提供 setup.py 文件。

良好的做法是在 README.md 中添加一个专门的部分，说明如何安装这些依赖项。假设用户只有最基本的背景知识，因此说明应清晰全面——如果用户无法成功设置您的依赖环境，他们很可能会放弃继续使用您的代码。

如果您希望提供完整的可复现环境，可以考虑使用 Docker，并将您的环境镜像上传至 Docker Hub。

2. 训练代码

您的代码应包含一个训练脚本，能够用于重现论文中所陈述的主要结果。这意味着您需要记录训练过程中使用的超参数以及任何技巧。为了最大化实用性，理想情况下，这段代码应具有一定的扩展性：例如，如果用户想将自己的数据集用于相同的训练流程，是否可行？

您可以提供一个文档化的命令行接口，如 train.py，作为用户使用代码的便捷入口。

3. 評估代码

模型评估和实验往往依赖于一些难以在论文中详尽描述的细微之处。因此，附上您实际用于评估或开展实验的完整代码，有助于全面展示实验流程。这不仅能让用户更信任、理解并在此基础上进一步开发您的研究成果。

同样地，您可以提供一个文档化的命令行接口，如 eval.py，作为用户使用代码的便捷入口。

4. 预训练模型

从头开始训练模型可能耗时且成本高昂。提升他人对您成果信任度的一种方式，就是提供一个预训练好的模型，供社区直接评估以获得最终结果。这样一来，用户无需重新训练即可验证结果的可信性。

另一个常见的应用场景是针对下游任务进行微调。在这种情况下，发布预训练模型可以让其他人基于此模型，结合自己的数据集开展应用开发。

此外，有些用户可能只是想简单试用一下您的模型，看看它在示例数据上的表现如何。提供预训练模型能够让用户轻松上手，从而更好地理解论文的核心贡献。

5. README 文件应包含结果表格，并附上用于重现这些结果的精确命令

在 README.md 中添加结果表格，可以帮助用户快速了解该仓库能提供什么（示例请参阅 README.md 模板）。同时，提供重现这些结果的具体步骤说明（包括相关脚本、预训练模型等的链接），可以为用户提供另一个切入点，直接促进代码的可重复性。有时，论文的主要成果可能是一张图表，但如果没有阅读论文，用户可能难以理解其含义。

为了帮助用户更好地理解和定位您的成果，还可以链接到包含其他论文最新结果的完整排行榜。目前有多种排行榜服务可用于存储此类信息。

🎉 发布研究代码的其他实用资源

预训练模型文件托管

1. Zenodo - 版本控制，50GB 存储空间，免费带宽，DOI，长期保存
2. GitHub Releases - 版本控制，文件大小上限 2GB，免费带宽
3. OneDrive - 版本控制，2GB（免费）/ 1TB（需 Office 365），免费带宽
4. Google Drive - 版本控制，15GB 存储空间，免费带宽
5. Dropbox - 版本控制，2GB（付费版无限制），免费带宽
6. AWS S3 - 版本控制，仅限付费用户，需支付带宽费用
7. huggingface_hub - 版本控制，无大小限制，免费带宽
8. DAGsHub - 版本控制，无大小限制，免费带宽
9. CodaLab Worksheets - 10GB 存储空间，免费带宽

模型文件管理工具

1. RClone - 提供对多种云存储服务的统一访问接口

标准化模型接口

1. PyTorch Hub
2. TensorFlow Hub
3. Hugging Face NLP 模型
4. ONNX

结果排行榜

1. Papers with Code 排行榜 - 拥有超过 4000 个排行榜
2. CodaLab 竞赛 - 拥有超过 450 个排行榜
3. EvalAI - 拥有超过 100 个排行榜
4. NLP Progress - 拥有超过 90 个排行榜
5. Collective Knowledge - 拥有超过 40 个排行榜
6. Weights & Biases - 基准测试 - 拥有 9 个以上的排行榜

创建项目页面

1. GitHub Pages
2. FastPages

制作演示、教程和可执行论文

1. Google Colab
2. Binder
3. Streamlit
4. CodaLab 工作表

贡献说明

如果您希望贡献内容，或对这些指南有任何建议，欢迎通过 hello@paperswithcode.com 联系我们，或在此 GitHub 仓库中提交问题。

我们欢迎所有贡献！本仓库中的所有内容均采用 MIT 许可证授权。

releasing-research-code 快速上手指南

本指南基于 NeurIPS 2021 官方推荐的机器学习研究代码发布最佳实践，旨在帮助开发者构建高可复现性、易用的开源项目。

环境准备

在开始整理和发布代码前，请确保满足以下基础要求：

• 操作系统：Linux, macOS 或 Windows (推荐 Linux 环境以保证复现性)
• 版本控制：已安装 Git
• 编程语言：Python (主流 ML 研究语言)
• 依赖管理工具：根据项目需求选择以下任一：
  • pip + virtualenv
  • conda (Anaconda/Miniconda)
  • Docker (用于提供完整的可复现环境)

提示：若需提升国内下载速度，建议配置清华源或阿里源：

• Pip: pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package>
• Conda: 配置 .condarc 使用 https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/

安装步骤

本项目并非一个直接运行的软件库，而是一套代码组织规范。请按照以下步骤将您的研究代码整理为符合标准的仓库：

1. 创建依赖说明文件

根据您使用的包管理器，在项目根目录生成对应的依赖文件：

• 使用 pip:

  pip freeze > requirements.txt
  

• 使用 conda:

  conda env export > environment.yml
  

• 作为库发布: 编写 setup.py 文件。

2. 整合核心代码脚本

确保仓库中包含以下两个关键入口脚本（若缺失请补充）：

• train.py: 包含复现论文主要结果所需的训练逻辑及超参数。
• eval.py: 包含评估模型和运行实验的确切代码。

3. 准备预训练模型

将训练好的模型文件上传至稳定的托管平台（推荐国内访问速度较好的方案）：

• Hugging Face Hub: huggingface_hub (无大小限制，带宽免费)
• DAGsHub: 无大小限制，带宽免费
• 其他选项: Zenodo, GitHub Releases (限 2GB), 或对象存储 (AWS S3, 阿里云 OSS)

4. 应用 README 模板

复制并修改官方提供的 README.md template。务必在 README 中包含：

• 依赖安装说明
• 结果表格 (Table of Results)
• 复现结果的精确命令

基本使用

遵循此规范后，您的仓库应具备清晰的“开箱即用”体验。以下是用户（或您自己测试）的标准使用流程示例：

1. 安装环境

# 方式 A: 使用 pip
pip install -r requirements.txt

# 方式 B: 使用 conda
conda env create -f environment.yml
conda activate <your-env-name>

2. 运行训练 (复现结果)

使用提供的封装脚本启动训练，确保能复现论文中的核心指标：

python train.py --config configs/my_experiment.yaml

3. 运行评估

加载预训练模型或直接评估刚训练好的模型：

python eval.py --model_path checkpoints/best_model.pth --data test_set

4. 验证结果

对照 README.md 中的结果表格，确认输出的指标（如 Accuracy, F1 Score 等）与文档一致。

---

注：本指南内容源自 Papers With Code 整理的 ML 代码完整性清单 (ML Code Completeness Checklist)，遵循 MIT 协议。