MiniMind 快速上手(一):环境准备与项目结构

MiniMind 快速上手(一):环境准备与项目结构

对于一个项目,最好的学习办法就是最快地把它跑起来。先不纠结细节,把环境搭好、把代码跑起来,再慢慢理解它的细节和原理。本文是 MiniMind 学习笔记的开篇------环境准备与项目结构。

文章目录

• [MiniMind 快速上手(一):环境准备与项目结构](#MiniMind 快速上手(一):环境准备与项目结构)
• • 前言
  • 一、项目结构
  • • [1.1 原始 MiniMind 仓库的核心目录](#1.1 原始 MiniMind 仓库的核心目录)
    • [1.2 学习仓库采用的 src layout](#1.2 学习仓库采用的 src layout)
  • 二、项目管理工具:uv
  • • [2.1 基本用法](#2.1 基本用法)
    • [2.2 两套接口的区别](#2.2 两套接口的区别)
    • [2.3 查看当前环境依赖](#2.3 查看当前环境依赖)
  • [三、用 uv 配置 PyTorch(CPU / CUDA)](#三、用 uv 配置 PyTorch(CPU / CUDA))
  • • [3.1 问题:直接 `uv add torch` 装的是 CPU 版](#3.1 问题:直接 uv add torch 装的是 CPU 版)
    • [3.2 解决:optional-dependencies + tool.uv.sources](#3.2 解决:optional-dependencies + tool.uv.sources)
    • [3.3 一个容易踩的坑:extra 的包会被 uv sync "卸掉"](#3.3 一个容易踩的坑:extra 的包会被 uv sync "卸掉")
    • [3.4 简化理解:uv 在这里做了什么](#3.4 简化理解:uv 在这里做了什么)
    • [3.5 检查当前 PyTorch 是否支持 CUDA](#3.5 检查当前 PyTorch 是否支持 CUDA)
  • [四、登录 SwanLab](#四、登录 SwanLab)
  • 总结
  • 参考

前言

MiniMind 是一个非常流行的开源小型 LLM 训练项目,非常适合用来从零理解大模型的训练全流程。而学习一个训练框架类项目,第一步往往不是读模型代码,而是:

1. 看懂项目结构,知道"东西都在哪";
2. 搭好环境,让训练脚本能跑起来;
3. 记录实验,方便后续观察训练效果。

本文围绕这三点展开,核心内容包括:src layout 项目结构 、uv 包管理工具 、PyTorch 的 CPU/CUDA 双源配置 ,以及一个 uv extra 机制的经典"踩坑"分析。

一、项目结构

1.1 原始 MiniMind 仓库的核心目录

原始项目里比较核心的部分大致如下:

目录	作用
model	模型定义
trainer	不同训练阶段的脚本
dataset	数据集与数据加载逻辑
scripts	转换、评估等辅助脚本

1.2 学习仓库采用的 src layout

学习仓库在原始项目的基础上,改成了更适合 Python 工程化维护的 src layout,并补充了学习笔记和测试目录:

目录	作用
src	项目核心代码:模型定义、训练代码、数据集实现等
scripts	辅助脚本:转换、评估和实验工具
notes	学习笔记,后续组织成 mdBook
minimind_upstream	上游参考代码,用 submodule 管理
configs	配置文件
tests	测试代码

如果是第一次进入这个仓库,建议把注意力集中在 src 、notes 和 minimind_upstream 三个目录上:

• src:当前可运行代码;
• notes:学习记录;
• minimind_upstream:对照原始实现。

一句话:可运行代码看 src,学习思路看 notes,原始实现看 minimind_upstream。

二、项目管理工具:uv

2.1 基本用法

项目推荐使用 uv 作为依赖管理工具,并配合 src layout 组织代码:

# 同步项目依赖
uv sync

# 以开发模式安装当前项目
uv pip install -e .

uv 是一个现代的 Python 包管理工具,安装速度快,依赖解析也更稳定。

2.2 两套接口的区别

uv 同时提供了两套常见接口,这是初学者最容易混淆的地方:

接口	是否修改 pyproject.toml	适用场景
uv add / uv remove	✅ 会修改	把依赖正式加入项目
uv pip install / uv pip uninstall	❌ 不修改	临时试验某个包,只操作当前环境

简单记:想把包正式纳入项目用 uv add,只是临时试试用 uv pip install(把传统 pip 换成 uv pip 即可)。

# 正式修改项目依赖
uv add package_name
uv remove package_name
uv add -r requirements.txt

# 仅操作当前环境(传统 pip 换成 uv pip)
uv pip install package_name
uv pip install -r requirements.txt
uv pip uninstall package_name

用下面的决策流程图来辅助记忆:
是,写进项目声明
否,只是临时试验
想安装一个包
是否要正式纳入项目依赖?
uv add / uv remove

修改 pyproject.toml
uv pip install / uv pip uninstall

只操作当前环境
依赖进入 lockfile

团队成员 uv sync 后一致
环境即用即弃

不影响项目声明

2.3 查看当前环境依赖

uv tree                      # 依赖树
uv pip list                  # 列出已安装的包
uv pip show package_name     # 查看某个包的详情

三、用 uv 配置 PyTorch(CPU / CUDA)

3.1 问题:直接 uv add torch 装的是 CPU 版

PyTorch 的安装和一般 Python 包不完全一样 :很多 CUDA 版本的 PyTorch 已不再支持 torch==2.2.0+cu121 这种版本后缀写法,而是通过**不同的软件源(index)**来区分。

也就是说,直接执行:

uv add torch

默认通常会从 PyPI 安装 CPU 版本 。想装 CUDA 版本,需要在 pyproject.toml 里为 torch、torchvision 单独指定源------这和 PyTorch 官网用 pip --index-url 安装 CUDA 版本的思路本质相同。

安装选择可以概括为:
否 / 只跑推理验证
是 / 需要训练模型
安装 PyTorch
需要 GPU 加速?
uv sync --extra cpu

从 pytorch-cpu 索引下载
uv sync --extra cuda

从 pytorch-cu126 索引下载
uv add torch 默认走 PyPI

通常也是 CPU 版

3.2 解决:optional-dependencies + tool.uv.sources

本项目采用 optional-dependencies + tool.uv.sources 的方式,分别适配 CPU 和 CUDA 环境:

# 安装 CPU 版本
uv sync --extra cpu

# 安装 CUDA 版本
uv sync --extra cuda

完整配置如下:

dependencies = [
    "swanlab>=0.6.13",
    "transformers>=4.57.1",
    "torch>=2.9.0",
    "torchvision>=0.24.0",
]

[tool.uv]
conflicts = [
    [
        { extra = "cpu" },
        { extra = "cuda" },
    ],
]

[project.optional-dependencies]
cpu = [
    "torch>=2.9.0",
    "torchvision>=0.24.0",
]
cuda = [
    "torch>=2.9.0",
    "torchvision>=0.24.0",
]

[[tool.uv.index]]
name = "pytorch-cu126"
url = "https://download.pytorch.org/whl/cu126"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu126_c"
url = "https://mirrors.nju.edu.cn/pytorch/whl/cu126"
explicit = true

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[tool.uv.sources]
torch = [
    { index = "pytorch-cu126_c", extra = "cuda" },
    { index = "pytorch-cpu", extra = "cpu" },
]
torchvision = [
    { index = "pytorch-cu126_c", extra = "cuda" },
    { index = "pytorch-cpu", extra = "cpu" },
]

配置要点:

• conflicts 声明 cpu 与 cuda 两个 extra 互斥,只能二选一;
• 通过 tool.uv.sources 指定:cuda extra 从 PyTorch cu126 源(国内走南大镜像 pytorch-cu126_c)下载,cpu extra 从 CPU 源下载;
• explicit = true 表示该索引只服务于显式声明了它的包,不会干扰其他依赖的解析。

3.3 一个容易踩的坑:extra 的包会被 uv sync "卸掉"

uv 的 extra 机制有一个容易让人困惑的地方:

如果你之前通过 uv sync --extra cuda 安装了 CUDA 相关依赖,之后再执行普通的 uv sync,而默认依赖(dependencies)里又没有包含这些包 ,那么 extra 对应的依赖可能会被移除。

也就是会出现"看起来没报错,但包没了"的现象:
没有
有
uv sync --extra cuda
CUDA 版 torch 装入 .venv
之后执行 uv add / uv sync
dependencies 中

是否声明了 torch?
extra 依赖被移除!

需重新执行 uv sync --extra cuda
torch 是最小依赖的一部分

环境保留,不会丢

解决办法 :把 CPU 和 CUDA 共有的核心依赖版本同时写进 dependencies (即上面配置中 torch、torchvision 同时出现在 dependencies 和两个 extra 里),再通过 sources 控制不同平台实际从哪个索引下载。这是目前实践下来比较稳的写法。

3.4 简化理解:uv 在这里做了什么

uv 处理依赖时大致做三件事:

1. 配置校验(Configuration Validation) :检查 extras 是否互斥、conflicts 是否自洽、pyproject.toml 结构是否正确、index 配置是否冲突;

2. 依赖解析(Dependency Resolution) :合并依赖(合并已启用的 extras;dependencies 默认启用,extra 中的默认不启用,只有加 extra flag 才启用)→ 选择版本 → 生成锁定图(类似 uv pip compile pyproject.toml);

3. 执行安装(Installation) :下载 wheel/sdist,安装到 .venv。

4. 配置校验

extras 互斥? conflicts 自洽?

index 冲突?
2. 依赖解析

合并 dependencies + 启用的 extra

选版本, 生成锁定图
3. 执行安装

下载 wheel/sdist

装入 .venv

而 uv remove 和 uv sync 的差异,恰好解释了 3.3 的"坑":

命令	是否修改 pyproject.toml	配置校验	extra 处理
uv remove	✅ 会修改	必须先做完整校验(即使 extras 没启用,也会检查 conflicts 是否自洽,可能报错但不影响安装)	---
uv sync	❌ 不修改	不需要重新验证配置	默认不启用 extras ,若 dependencies 中无 torch,则 extra 中的 torch 会被移除

官方的 extra 机制确实有点混乱(也许以后会改),总而言之:核心依赖写进 dependencies + sources 控制索引,是目前的最佳实践。

3.5 检查当前 PyTorch 是否支持 CUDA

环境装好后,用两行代码验证:

import torch

print(torch.cuda.is_available())  # True 表示 CUDA 可用
print(torch.version.cuda)         # CUDA 版本号

四、登录 SwanLab

训练脚本里虽然保留了 --use_wandb 这个参数名,但实际导入和使用的是 swanlab(一个国产实验追踪平台)。因此同步完依赖后,建议先完成登录:

swanlab login

这样后续运行训练脚本时,实验日志才能正常记录。

总结

本文完成了 MiniMind 学习的第一步,核心要点回顾:

1. 项目结构 :学习仓库采用 src layout,重点看 src(可运行代码)、notes(学习笔记)、minimind_upstream(原始实现)三个目录;
2. uv 工具 :区分两套接口------uv add/uv remove 修改项目声明,uv pip install/uninstall 只操作当前环境;
3. PyTorch 双源配置 :CUDA 版本要走独立索引,采用 optional-dependencies + tool.uv.sources 的方式,uv sync --extra cpu / uv sync --extra cuda 二选一;
4. extra 的坑 :普通 uv sync 可能移除 extra 安装的包,解决办法是把共有核心依赖写进 dependencies;
5. 实验追踪 :训练前先 swanlab login。

环境准备好后,就可以开始跑通第一个训练脚本了。下一篇将进入数据预处理与模型定义部分,敬请期待。

参考

• llm-notes-all-in-one: 环境准备与项目结构(0.GettingStarted)
• uv 官方文档:Configuring accelerators with environment markers
• MiniMind 上游仓库