Flow Matching 教学 Notebook

这个项目用一个中文 Jupyter notebook 讲解 Flow Matching，并采用统一的时间约定：

• x_0 是噪声分布中的样本。
• x_1 是数据分布中的样本。
• 时间 t 从 0 到 1，ODE 采样把噪声逐步流向数据。

核心文件是 flow_matching_tutorial.ipynb。它包含 PyTorch 基础回顾、Flow Matching 数学推导、2D toy 数据实验，以及 MNIST 上的完整训练和采样流程。

从零开始运行

1. 安装 uv

如果本机还没有安装 uv，可以使用官方安装脚本：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后，重新打开一个终端，检查 uv 是否可用：

uv --version

如果你使用 Homebrew，也可以这样安装：

brew install uv

2. 进入项目目录

git clone https://github.com/sdt201909/Flow_Matching_Tutorial_For_Beginner.git
cd Flow_Matching_Tutorial_For_Beginner

3. 安装项目依赖

项目使用 pyproject.toml 和 uv.lock 管理 Python 环境。运行：

uv sync

这会在当前目录创建 .venv/，并安装 PyTorch、TorchVision、JupyterLab、ipywidgets、Matplotlib 等依赖。

4. 启动 JupyterLab

uv run jupyter lab flow_matching_tutorial.ipynb

打开 notebook 后，从上到下运行即可。第一次运行 MNIST 章节时，torchvision 会自动下载 MNIST 到 ./data。训练和可视化图片会保存到 ./outputs。

运行建议

Notebook 默认开启 FAST_MODE = True，用于在可接受时间内跑完整个流程。2D toy 和 MNIST 部分都保留了相对充分的训练步数，以便生成结果能稳定呈现主要结构。

如果想看到更清楚的 2D checkerboard 或更像数字的 MNIST 样本，可以在第一个代码单元里把：

FAST_MODE = True

改成：

FAST_MODE = False

然后重新运行训练相关单元。MacBook 上建议先用 fast mode，确认流程跑通后再增加训练步数；MNIST 的 FAST_MODE=False 会明显更久，但通常能得到更清晰的样本。

项目结构

.
├── README.md
├── LICENSE
├── pyproject.toml
├── uv.lock
├── flow_matching_tutorial.ipynb
├── data/       # 运行时自动生成，存放 MNIST
└── outputs/    # 运行时自动生成，存放可视化结果

data/、outputs/、checkpoints/、runs/ 以及常见模型权重文件不会提交到仓库；它们会在本地运行 notebook 时按需生成。

许可证

本项目采用 MIT License，详见 LICENSE。

常见问题

如果 Jupyter 里找不到当前环境，可以运行：

uv run python -m ipykernel install --user --name flow-matching-tutorial --display-name "Flow Matching Tutorial"

然后在 Jupyter 的 kernel 菜单里选择 Flow Matching Tutorial。

如果 MacBook 使用 MPS 时遇到个别算子报错，可以在第一个代码单元中把设备临时改成 CPU：

device = torch.device("cpu")

CPU 会慢一些，但本 notebook 的 fast mode 仍然可以跑通。