项目结构¶

顶层目录¶

DL-Hub/
├── dlhub/              # 统一训练/评估脚手架（seed/device/训练循环/日志）
├── tracks/             # 课程内容（多轨统一结构）
│   ├── foundations/    #   基础赛道
│   ├── vision/        #   视觉赛道
│   ├── nlp/           #   NLP 赛道
│   ├── gnn/           #   GNN 赛道
│   ├── pointcloud/    #   点云赛道
│   ├── generative/    #   生成模型赛道
│   ├── llm/           #   LLM 赛道
│   └── multimodal/    #   多模态赛道
├── ml_algorithms/      # 纯 NumPy ML 算法（当前 31 个）
├── optimization/       # 优化工具箱（Optimizer/Scheduler/Loss/Metric + 元启发式）
├── scripts/            # 辅助脚本（冒烟验证、Zoo CLI）
├── docs/               # MkDocs 文档源文件
├── resources/          # 保留资料（PDF 论文笔记）
├── tests/              # pytest 测试与仓库契约
├── .github/            # CI、文档部署与依赖更新配置
├── pyproject.toml      # 打包、依赖和 Python 工具配置的事实源
├── mkdocs.yml          # 文档配置
├── Makefile            # 常用命令入口
└── requirements*.txt   # 指向 pyproject extras 的兼容入口

wheel 中可导入的项目包仅包含 dlhub*。sdist 还会携带 README、许可证、构建元数据和测试源码，用于从源码重建与校验，但安装后仍只暴露 dlhub*；tracks/、Llms/、scripts/ 等仓库内容需要从仓库根目录运行。边界由 pyproject.toml 的 package discovery 配置定义。

课程目录结构¶

训练型 lesson 通常采用下面的四文件结构；基础演示或特殊任务可以精简，但必须保留可发现的入口：

tracks/<track>/lesson_XX_<name>/
├── model.py        # 模型定义
├── data.py         # 数据加载（显式 fake 或内置 synthetic 数据）
├── train.py        # 训练脚本（入口）
└── README.md       # 课程说明文档

示例：MNIST LeNet

tracks/vision/lesson_01_mnist_lenet/
├── model.py        # LeNet-5 定义
├── data.py         # MNIST 数据加载 + fake 模式
├── train.py        # 训练循环
└── README.md       # 课程说明

关键约定¶

文件	职责	要求
`model.py`	模型架构定义	纯 PyTorch `nn.Module`
`data.py`	数据集和 DataLoader	必须提供不联网的数据路径；`--dataset fake` 仅用于可选真实数据集
`train.py`	训练入口脚本	使用 `dlhub/` 脚手架
`README.md`	课程文档	包含原理说明和运行方式

输出目录约定¶

所有训练输出统一存放在 outputs/ 目录下：

outputs/
└── <track>/
    └── <lesson>/
        └── <run_name>/
            ├── checkpoints/    # 模型权重
            ├── logs/           # 训练日志
            └── config.json     # 运行配置

输出路径管理

dlhub/ 脚手架会自动创建和管理输出目录结构，开发者只需在 train.py 中指定 run_name 即可。

scripts/ 辅助脚本¶

脚本	功能
`smoke_check.py`	覆盖 8 个 track 的精选离线冒烟测试；`--list` 查看覆盖范围
`lesson_contracts.py`	静态检查课程入口、核心 CLI、文档命令与 Smoke 覆盖
`narrative_check.py`	检查命名边界与文档/导入中的 lesson 路径
`model_fidelity.py`	查询并校验 Model Zoo 源码保真度台账
`run_lesson.py`	统一发现和运行 lesson；实际参数由各 lesson 定义
`new_lesson.py`	脚手架生成新 lesson 模板
`doctor.py`	环境诊断工具
`benchmark_cpu.py`	CPU 基准测试
`*_zoo.py`	各赛道 Zoo CLI 脚本（`vision_zoo.py`、`nlp_zoo.py` 等）