# 多模态学习

**Repository Path**: pulind/multimodal-learning

## Basic Information

- **Project Name**: 多模态学习
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Multimodal Learning

视觉 + 大模型(多模态)落地工程师 6 个月学习计划的代码仓库。

配套计划:`知识库/2-areas/AI/多模态大模型学习路径.md`

## 环境

- Python 3.11(uv 管理)
- **PyTorch CPU 版(默认,约 200MB,无需显卡,任何电脑都能装)**

训练脚本会**自动检测设备**:有 NVIDIA 显卡就用 GPU 加速,没有就用 CPU。同一个脚本两种机器都能跑。

```bash
# 首次:uv 会自动根据 pyproject.toml 装好依赖(默认 CPU 版 torch)
uv sync
# 加新包:uv add <package>
```

### 可选:用 GPU 加速(CUDA 版)

Windows 上 PyPI(阿里云镜像)提供的 torch 是 **CPU 版**,不含 GPU 依赖。若你的电脑有 NVIDIA 显卡、
想用 GPU 加速训练,需要改用 PyTorch 官方的 CUDA wheel:

1. 编辑 `pyproject.toml`,把 torch/torchvision 指向 CUDA 索引(版本见 https://pytorch.org/get-started/locally/):
   ```toml
   [[tool.uv.index]]
   name = "pytorch-cu121"
   url = "https://download.pytorch.org/whl/cu121"
   explicit = true

   [tool.uv.sources]
   torch = { index = "pytorch-cu121" }
   torchvision = { index = "pytorch-cu121" }
   ```
2. 重新执行 `uv sync`,会装 CUDA 版并自动下载驱动依赖

> 不切换也完全能用:脚本自动检测,没有 NVIDIA 显卡就用 CPU 跑。

## 目录

### 基础层 (Week 1-4): 从张量到多模态

- `week1-foundations/` — PyTorch 基础
  - `01-mnist-mlp.py` 从零写 MLP 分类 MNIST(DataLoader/Module/autograd/训练循环)
  - `02-mnist-cnn.py` 换成 CNN,对比准确率(卷积/池化/感受野)
  - `03-understanding-totensor.py` 拆解 `ToTensor`/`Normalize` 的每一步
  - `04-color-pixel-rgb.py` 用 2x2 彩图理解 RGB 通道
  - `05-understanding-conv.py` 手动实现卷积,对比 PyTorch `conv2d`
  - `06-understanding-kernels.py` 直观理解卷积核(手工核 vs 学出来的核)
- `week2-nanogpt/` — 从零实现 nanoGPT(字符级语言模型)
  - `01-self-attention-basics.py` 手算自注意力公式
  - `02-multihead-causal-attn.py` 多头 + 因果掩码
  - `03-transformer-block.py` 组装完整 Transformer block
  - `04-nanogpt-train.py` 训练 nanoGPT 并生成莎士比亚风格文本
- `week3-transformer-encoder-decoder/` — 完整 Encoder-Decoder Transformer(原始 Transformer + 交叉注意力)
  - `01-cross-attention.py` 手算交叉注意力(Q 来自文本、K/V 来自图像,与自注意力对照)
  - `02-encoder-decoder.py` 从零实现 Encoder(双向)+ Decoder(掩码 + 交叉注意力)完整架构,含 3 个数值自检
  - `03-seq2seq-translation.py` 训练最小翻译模型(数字串逆序),验证 Encoder-Decoder + 交叉注意力对齐
  - `04-annotated-transformer.py` 《Attention Is All You Need》精读伴侣(架构图 / 位置编码可视化 / 参数量估算)
- `week4-vit-clip/` — ViT 与 CLIP
  - `01-vision-transformer.py` 理解 ViT(图片切成 patch + Transformer)
  - `02-clip-contrastive.py` 用最小 toy 理解 CLIP 对比学习
  - `03-clip-zero-shot.py` 真实预训练 CLIP 做 zero-shot 分类
  - `04-clip-retrieval.py` CLIP 图文检索(以文搜图 / 以图搜文)

### 核心范式 (Week 5-8): VLM → 数据 → 微调 → 部署

- `week5-vlm/` — VLM 图文生成
  - `01-vlm-architecture.py` 理解 VLM 三段式架构(ViT → Projector → LLM)
  - `02-captioning-toy.py` 训练最小 VLM 做图像 captioning
  - `03-vqa-toy.py` 扩展到视觉问答 VQA
  - `04-cross-attention-fusion.py` 交叉注意力多模态融合
- `week6-data-engineering/` — 数据工程(博物馆项目驱动) **[新增]**
  - `01-data-curation.py` 多模态数据收集、清洗、去重、质量过滤、版本管理
  - `02-synthetic-data.py` LLM 合成训练数据:prompt 工程、质量控制、多样性、陷阱
  - `03-multimodal-dataset.py` 图文对数据集:文本锚点、负采样策略、数据增强、划分
- `week7-lora-eval/` — LoRA 微调与评估体系 **[新增]**
  - `01-lora-from-scratch.py` 从零实现 LoRA:低秩分解、rank 选择、LoRA vs 全量微调
  - `02-clip-hard-negative.py` CLIP 微调:InfoNCE loss、硬负样本、检索评估
  - `03-evaluation-framework.py` 评估体系:分类/检索指标、A/B 测试、统计显著性
  - `04-real-model-sft.py` 真实模型 SFT:chat 模板、loss mask、训练监控、生成对比
- `week8-deploy-production/` — 模型部署与生产服务 **[新增]**
  - `01-fastapi-serving.py` 模型服务化:生命周期管理、线程安全、SSE 流式、错误处理
  - `02-multi-model-orchestration.py` 多模型编排:CLIP→VL→LLM 管线、显存预算、置信度降级
  - `03-caching-monitoring.py` 缓存与监控:LRU/TTL 缓存、健康检查、性能指标、告警
  - `04-ab-testing.py` A/B 测试:实验设计、置换检验、效应量、样本量估算

### 模态扩展 (Week 9-13): 视频/扩散/音频/部署/文档

- `week9-video/` — 视频多模态理解
  - `01-video-as-frames.py` 理解视频=帧序列+时间维度
  - `02-temporal-modeling.py` 时序聚合方法(均值/注意力/Transformer)
  - `03-video-captioning.py` 视频描述生成(Video VLM)
  - `04-video-retrieval.py` 文本搜视频/视频搜视频(视频 RAG)
- `week10-diffusion/` — 扩散模型与文生图
  - `01-diffusion-basics.py` 前向扩散/逆向去噪/噪声预测原理
  - `02-unet-mnist.py` 从零构建 UNet + DDPM 训练(MNIST 生成)
  - `03-text-to-image.py` CFG 无分类器引导 + CLIP 文本条件生成
  - `04-stable-diffusion-concepts.py` SD 完整架构(VAE+CLIP+UNet+DDPM)
- `week11-audio/` — 音频与语音多模态
  - `01-audio-basics.py` 音频基础:波形/频谱/CNN音频分类
  - `02-speech-commands.py` 语音命令识别(YESNO数据集)
  - `03-clap-audio-text.py` CLAP:对比学习对齐音频与文本(CLIP的音频版)
  - `04-audio-visual-fusion.py` 视听融合:早期/晚期融合策略对比
- `week12-deploy/` — 模型导出与量化
  - `01-model-export.py` ONNX/TorchScript导出与推理速度对比
  - `02-quantization.py` 动态/静态INT8量化:4x压缩+2-4x加速
  - `03-api-serving.py` HTTP推理服务:模型加载/预处理/后处理/健康检查
  - `04-production-pipeline.py` 端到端生产管线:训练→评估→导出→量化→缓存→监控
- `week13-documents/` — 文档理解与结构化提取
  - `01-document-layout.py` 文档布局分析:区域检测+分类(文本/表格/图表)
  - `02-ocr-basics.py` OCR原理:字符分割+CNN识别+字体泛化
  - `03-visual-document-qa.py` 文档问答:表格QA/表单QA/空间感知答案提取
  - `04-structured-extraction.py` 结构化提取:发票→JSON, 模板vs学习式提取

### 前沿与对齐 (Week 14-15): RLHF + Agent

- `week14-rlhf/` — RLHF与AI对齐
  - `01-reward-model.py` 奖励模型:从偏好对训练Bradley-Terry评分模型
  - `02-ppo-alignment.py` PPO对齐:用奖励模型+KL惩罚微调策略
  - `03-dpo-direct.py` DPO直接偏好优化:无需奖励模型,一步到位
  - `04-grpo-concepts.py` GRPO组相对策略优化:DeepSeek-R1的核心算法
- `week15-agents/` — 多智能体协作系统
  - `01-agent-architecture.py` 智能体架构:ReAct/Plan-Execute/Reflection对比
  - `02-agent-communication.py` 通信协议:消息传递/共享黑板/辩论协议
  - `03-multi-agent-orchestration.py` 编排模式:流水线/扇出并行/投票共识
  - `04-agent-tools-grounding.py` 多模态工具:视觉/搜索/代码/记忆全部接地

### 工具脚本

- `check_env.py` — 检查运行环境(torch 版本 / 当前用 CPU 还是 GPU)
- `download_data.py` — 下载数据集(优先 Gitee Release,国内快;回退官方源带重试/断点续传)

## 运行

```bash
uv run python check_env.py                 # 先看环境是否正常(CPU/GPU)

# 国内用户建议先下载数据(从 Gitee Release 拉,快;失败自动回退官方源)
uv run python download_data.py

uv run python week1-foundations/01-mnist-mlp.py
uv run python week1-foundations/02-mnist-cnn.py
uv run python week1-foundations/05-understanding-conv.py

# 多训几轮
uv run python week1-foundations/01-mnist-mlp.py --epochs 5

# nanoGPT:纯 CPU 上约 6~10 秒/步,先用小步数快速体验
uv run python week2-nanogpt/04-nanogpt-train.py --iters 100
# 跑完整 3000 步:CPU 要数小时,建议有 NVIDIA 显卡换成 CUDA 版 PyTorch 再跑
uv run python week2-nanogpt/04-nanogpt-train.py

# Week 3 Encoder-Decoder Transformer:交叉注意力 + 完整架构 + 翻译训练 + 论文精读
uv run python week3-transformer-encoder-decoder/01-cross-attention.py       # 交叉注意力手算
uv run python week3-transformer-encoder-decoder/02-encoder-decoder.py       # 完整 Encoder-Decoder(含 3 个自检)
uv run python week3-transformer-encoder-decoder/03-seq2seq-translation.py   # 训练最小翻译模型(CPU 约 1 分钟)
uv run python week3-transformer-encoder-decoder/04-annotated-transformer.py # 《Attention Is All You Need》精读

# Week 5 VLM:图文生成
uv run python week5-vlm/01-vlm-architecture.py      # 架构原理(无需训练)
uv run python week5-vlm/02-captioning-toy.py --quick # 快速体验图像 captioning
uv run python week5-vlm/03-vqa-toy.py --quick        # 快速体验视觉问答
uv run python week5-vlm/04-cross-attention-fusion.py # 交叉注意力融合

# Week 6 数据工程:收集→清洗→合成→数据集构建
uv run python week6-data-engineering/01-data-curation.py        # 数据收集与清洗
uv run python week6-data-engineering/02-synthetic-data.py        # 合成训练数据
uv run python week6-data-engineering/03-multimodal-dataset.py    # 图文对数据集构建

# Week 7 LoRA微调与评估:从零LoRA→CLIP微调→评估体系→真实SFT
uv run python week7-lora-eval/01-lora-from-scratch.py     # 从零实现 LoRA
uv run python week7-lora-eval/02-clip-hard-negative.py     # CLIP 微调 + 硬负样本
uv run python week7-lora-eval/03-evaluation-framework.py   # 评估体系 + A/B 测试
uv run python week7-lora-eval/04-real-model-sft.py         # 真实模型 SFT

# Week 8 模型部署与生产:服务化→多模型编排→缓存监控→A/B测试
uv run python week8-deploy-production/01-fastapi-serving.py        # 模型服务化
uv run python week8-deploy-production/02-multi-model-orchestration.py # 多模型编排管线
uv run python week8-deploy-production/03-caching-monitoring.py     # 缓存与监控
uv run python week8-deploy-production/04-ab-testing.py             # A/B 测试

# Week 9 视频理解:帧序列 + 时序建模 + 视频描述 + 视频检索
uv run python week9-video/01-video-as-frames.py       # 视频=帧序列
uv run python week9-video/02-temporal-modeling.py      # 时序聚合方法
uv run python week9-video/03-video-captioning.py --quick # 视频描述 VLM
uv run python week9-video/04-video-retrieval.py         # 视频检索

# Week 10 扩散模型:文生图与生成式AI
uv run python week10-diffusion/01-diffusion-basics.py      # 扩散原理
uv run python week10-diffusion/02-unet-mnist.py --quick     # UNet+DDPM 生成 MNIST
uv run python week10-diffusion/03-text-to-image.py --quick  # 文本条件生成
uv run python week10-diffusion/04-stable-diffusion-concepts.py # SD 架构全览

# Week 11 音频理解:波形/语音/CLAP/视听融合
uv run python week11-audio/01-audio-basics.py       # 音频基础+CNN分类
uv run python week11-audio/02-speech-commands.py     # 语音命令识别
uv run python week11-audio/03-clap-audio-text.py     # CLAP 音频-文本对齐
uv run python week11-audio/04-audio-visual-fusion.py # 视听多模态融合

# Week 12 模型导出与量化
uv run python week12-deploy/01-model-export.py      # ONNX导出+速度对比
uv run python week12-deploy/02-quantization.py       # INT8量化
uv run python week12-deploy/03-api-serving.py        # HTTP推理服务
uv run python week12-deploy/04-production-pipeline.py # 端到端生产管线

# Week 13 文档理解:布局/OCR/文档问答/结构化提取
uv run python week13-documents/01-document-layout.py      # 文档布局分析
uv run python week13-documents/02-ocr-basics.py            # OCR字符识别
uv run python week13-documents/03-visual-document-qa.py    # 文档问答
uv run python week13-documents/04-structured-extraction.py # 结构化提取

# Week 14 AI对齐:奖励模型/PPO/DPO/GRPO
uv run python week14-rlhf/01-reward-model.py    # 奖励模型(Bradley-Terry)
uv run python week14-rlhf/02-ppo-alignment.py    # PPO策略对齐
uv run python week14-rlhf/03-dpo-direct.py       # DPO直接偏好优化
uv run python week14-rlhf/04-grpo-concepts.py    # GRPO组相对优化

# Week 15 多智能体:架构/通信/编排/工具
uv run python week15-agents/01-agent-architecture.py   # ReAct/Plan-Execute/Reflection
uv run python week15-agents/02-agent-communication.py  # 消息/黑板/辩论协议
uv run python week15-agents/03-multi-agent-orchestration.py # 流水线/扇出/投票
uv run python week15-agents/04-agent-tools-grounding.py    # 多模态工具接地
```

结果图存到各周的 `outputs/`,数据集自动下载到各周的 `data/`。

## 数据获取

clone 后**不需要手动准备数据**。推荐先运行下载脚本,它优先从 Gitee Release 拉取(国内快),失败自动回退官方源:

```bash
uv run python download_data.py
```

| 数据集 | 用到的脚本 | 获取方式 |
|--------|-----------|----------|
| MNIST | week1 全部、week4/01 | 4 个 `.gz` 解压后放 `data/MNIST/raw/` |
| CIFAR10 | week4/03、04 | 7 个批次文件放 `data/cifar-10-batches-py/` |
| tiny-shakespeare | week2/04 | 已随仓库分发(`data/tinyshakespeare.txt`,无需下载) |

数据体积较大(MNIST+CIFAR 约 180MB)且脚本可自动下载,因此**不入库**(`.gitignore` 已忽略 `data/`)。
`download_data.py` 支持**重试、断点续传、MD5 校验**,即使官方源中断也能续传。

### 数据托管到 Gitee Release(owner 做一次,之后国内用户都从这里快速下载)

torchvision 默认的国外下载源国内很慢且易断。把数据上传到 Gitee 发行版后,`download_data.py` 会**优先从 Gitee 拉取**:

```bash
# 1. 从官方下载并整理好 11 个待上传文件(只需这一次)
uv run python download_data.py --prepare-release

# 2. 在仓库「发行版」新建 Release,Tag 填 datasets-v1
#    把 release-assets/ 里的 11 个文件(MNIST 4 个 .gz + CIFAR10 7 个批次)作为附件上传
# 3. 之后 download_data.py 默认就会先从 Gitee 下载(可用 --gitee-release 或 GITEE_RELEASE_URL 换地址)
```

> 注:数据未上传到 Gitee 时,`download_data.py` 也能用,只是会回退到较慢的官方源。

## 学习周次概览

| 周次 | 主题 | 核心概念 | 技术栈 |
|------|------|---------|--------|
| Week 1 | PyTorch + CNN 基础 | 张量/自动求导/训练循环/卷积 | MLP, CNN, MNIST |
| Week 2 | nanoGPT | 自注意力/多头/因果掩码/Transformer/GPT | 字符级语言模型 |
| Week 3 | Encoder-Decoder Transformer | 双向编码器/掩码解码器/交叉注意力/机器翻译 | 完整 Transformer, Seq2Seq |
| Week 4 | ViT + CLIP | patch embedding/双向注意力/对比学习/InfoNCE | ViT, CLIP, 跨模态检索 |
| **Week 5** | **VLM 图文生成** | **三段式架构(ViT→Projector→LLM)/前缀融合/VQA/交叉注意力** | **CLIP+GPT-2, LLaVA-like** |
| **Week 6** | **数据工程** | **数据收集/清洗/去重/合成训练数据/图文对构建/负采样** | **PIL, hashlib, 合成数据** |
| **Week 7** | **LoRA 微调与评估** | **LoRA从零实现/InfoNCE/硬负样本/Recall@K/A/B测试/SFT** | **LoRA, 对比学习, 评估体系** |
| **Week 8** | **模型部署与生产** | **模型服务化/多模型编排/缓存监控/置信度降级/A/B测试** | **FastAPI模式, SSE, 缓存** |
| **Week 9** | **视频多模态理解** | **帧序列/时序Transformer/视频VLM/视频检索** | **CLIP + Temporal Pooling** |
| **Week 10** | **扩散模型与文生图** | **DDPM/UNet/CFG/CLIP引导—从噪声到图像的生成式AI** | **UNet, DDPM, Stable Diffusion** |
| **Week 11** | **音频与语音多模态** | **波形/频谱/CNN音频分类/CLAP对比学习/视听融合** | **torchaudio, CLAP** |
| **Week 12** | **模型导出与量化** | **ONNX导出/INT8量化/HTTP API/端到端生产管线** | **ONNX Runtime, Quantization** |
| **Week 13** | **文档理解** | **布局分析/OCR/Document QA/结构化提取** | **Layout Analysis, OCR, Donut** |
| **Week 14** | **RLHF与AI对齐** | **奖励模型/PPO/DPO/GRPO—从人类偏好到对齐AI** | **Bradley-Terry, PPO, DPO** |
| **Week 15** | **多智能体协作** | **Agent架构/通信协议/编排/多模态工具** | **ReAct, LangGraph** |

## 学习要点对照

### Week 1 基础概念

| 概念 | 在代码里的位置 | 后续在哪里出现 |
|------|--------------|--------------|
| `nn.Module` / `forward` | `class MLP` / `class CNN` | 所有模型,包括 nanoGPT、VLM |
| 训练三连 `zero_grad/backward/step` | `train_one_epoch` | 每个训练循环 |
| `DataLoader` / `Dataset` | `get_dataloaders` | Week 6-7 微调时加载自己的多模态数据 |
| `.to(device)` | 多处 | CPU/GPU 自动选择,有 GPU 就自动用 |
| `@torch.no_grad()` | `evaluate` | 推理/验证时都要加 |
| `CrossEntropyLoss` | `criterion` | 分类任务通用 |

### Week 5 VLM 概念

| 概念 | 在代码里的位置 | 核心理解 |
|------|--------------|---------|
| VLM 三段式架构 | `01-vlm-architecture.py` | ViT 编码视觉 → Projector 对齐空间 → LLM 解码生成 |
| 前缀式融合 (Prefix Fusion) | `02-captioning-toy.py` | 视觉 token 拼在文本前,共享因果自注意力(LLaVA 方案) |
| 只对文本算 loss | `02/03` 训练循环 | 视觉 token 是"上下文",不参与生成 loss |
| 指令跟随 | `03-vqa-toy.py` | 图像+问题→答案,视觉 Agent 的基础 |
| 交叉注意力融合 | `04-cross-attention-fusion.py` | Q=文本查 K/V=图像,与 Flamingo 方案对比 |

### Week 6 数据工程概念

| 概念 | 在代码里的位置 | 核心理解 |
|------|--------------|---------|
| 数据清洗流水线 | `01-data-curation.py` | PIL解码校验→感知哈希去重→元数据验证→质量过滤 |
| 合成数据质量控制 | `02-synthetic-data.py` | 长度过滤→格式校验→模糊去重→多样性度量 |
| 文本锚点设计 | `03-multimodal-dataset.py` | 结构化模板 vs 自由文本,锚点质量直接影响检索效果 |
| 负采样策略 | `03-multimodal-dataset.py` | 随机负样本 vs 硬负样本,hard negative 显著加速收敛 |

### Week 7 微调与评估概念

| 概念 | 在代码里的位置 | 核心理解 |
|------|--------------|---------|
| LoRA 低秩分解 | `01-lora-from-scratch.py` | W'=W+B×A,r<<d,训练<1%参数达全量微调效果 |
| InfoNCE Loss | `02-clip-hard-negative.py` | 对称交叉熵,温度参数控制分布锐度 |
| 硬负样本 | `02-clip-hard-negative.py` | 画廊干扰图:最相似的非正样本,比随机负样本更有效 |
| 评估指标 | `03-evaluation-framework.py` | Recall@K/mAP/MRR/精确率/召回率,不同任务选不同指标 |
| A/B 测试 | `03-evaluation-framework.py` | 置换检验→p值→置信区间,统计显著性 ≠ 实际显著性 |
| SFT loss mask | `04-real-model-sft.py` | 只对 assistant 部分算 loss, user/system 用 -100 掩码 |

### Week 8 部署与生产概念

| 概念 | 在代码里的位置 | 核心理解 |
|------|--------------|---------|
| 模型生命周期 | `01-fastapi-serving.py` | 懒加载→引用计数→显存估算→线程安全访问 |
| 多模型级联 | `02-multi-model-orchestration.py` | CLIP粗筛(50ms)→VL精比对(2s)→LLM生成,总延迟~3s |
| 置信度降级 | `02-multi-model-orchestration.py` | >=0.7确认/0.4-0.7警告/<0.4降级为CLIP-only |
| 缓存策略 | `03-caching-monitoring.py` | LRU+TTL,内容哈希做key,版本变更自动失效 |
| A/B 测试 | `04-ab-testing.py` | 置换检验,效应量Cohen's h,最小样本量估算 |