NN 模板

“我们要求严格界定怀疑与不确定性的领域。”

用于快速启动你的 PyTorch 项目的通用模板， 更多信息请参阅 文档。

开始使用

如果你已经熟悉 cookiecutter，只需通过以下命令生成你的项目：

cookiecutter https://github.com/grok-ai/nn-template

pip install cookiecutter

更多详细信息请参阅 文档。

优势

• 确实适用于研究！
• 引导式设置，可自定义项目初始化；
• 快速原型化新想法，无需从头构建代码库；
• 减少样板代码，且不会影响学习曲线（只要你熟悉集成工具）；
• 确保实验的可重复性；
• 通过 GitHub Actions 自动化测试、部署美观文档以及上传 PyPI；
• 强制执行 Python 最佳实践；
• 更多功能请参阅 文档；

集成

避免编写样板代码即可集成：

• PyTorch Lightning，轻量级 PyTorch 封装，专为高性能 AI 研究设计。
• Hydra，优雅地配置复杂应用的框架。
• Hugging Face Datasets，轻松访问和共享数据集的库。
• Weights and Biases，组织和分析机器学习实验。(提供教育账号)
• Streamlit，可在几分钟内将数据脚本转化为可共享的 Web 应用。
• MkDocs 和 Material for MkDocs，快速、简单且美观的静态网站生成器。
• DVC，跟踪大型文件、目录或 ML 模型。可将其视为“数据版 Git”。
• GitHub Actions，用于自动运行测试、发布文档和上传到 PyPI。
• Python 最佳实践，适用于研究项目的开发和发布。

维护者

• 瓦伦蒂诺·马约尔卡 @Flegyas
• 卢卡·莫谢拉 @lucmos

nn-template 快速上手指南

nn-template 是一个通用的项目模板，旨在帮助开发者快速搭建基于 PyTorch 的深度学习研究项目。它集成了 PyTorch Lightning、Hydra、Weights & Biases 等主流工具，消除了重复的样板代码，确保实验的可复现性，并强制遵循 Python 最佳实践。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (推荐 Linux/macOS 以获得最佳体验)
• Python: 3.8 或更高版本
• 前置依赖:
  • pip (Python 包管理工具)
  • git (版本控制工具)
  • cookiecutter (项目生成工具)

提示：如果您尚未安装 cookiecutter，可以通过以下命令安装：

pip install cookiecutter

(国内用户建议使用清华或阿里镜像源加速安装：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple cookiecutter)

安装步骤

nn-template 无需传统意义上的“安装”，而是通过 cookiecutter 直接生成一个个性化的、可立即运行的项目结构。

执行以下命令生成新项目：

cookiecutter https://github.com/grok-ai/nn-template

执行后，终端会交互式地询问您项目名称、作者信息等配置项。根据提示输入完成后，系统将自动在当前目录生成完整的项目文件夹。

基本使用

生成项目后，您将拥有一个包含完整 CI/CD 流程、文档系统和实验管理配置的深度学习项目框架。

1. 进入项目目录

cd <your-project-name>

2. 安装项目依赖

生成的项目中通常包含 requirements.txt 或 pyproject.toml，请安装所需依赖：

pip install -e .

(国内用户加速：pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple)

3. 运行示例训练

模板通常预置了简单的训练脚本以验证环境。您可以直接使用 Hydra 配置系统启动训练（具体命令视生成时的配置而定，通常如下）：

python src/train.py

或者指定配置文件运行：

python src/train.py +experiment=example

4. 查看文档

项目内置了基于 MkDocs 的文档系统。若要查看本地文档或了解更详细的特性（如如何集成 DVC 管理数据、如何使用 Streamlit 构建 UI），可运行：

mkdocs serve

然后在浏览器访问 http://127.0.0.1:8000 查看完整文档。

现在，您可以直接在 src/ 目录下开始编写您的模型代码，无需再为配置日志、实验追踪或代码规范操心。