# Diffusion Language Baselines

这是一个面向 Linux GPU 服务器的可复现实验框架，用于比较连续、离散、混合扩散语言模型及其少步蒸馏版本。当前 Mac/worktree 只保存代码、锁文件、脚本和文档；数据、源码仓库快照、checkpoint、Conda 环境、训练和推理都必须在服务器执行。

## 实验范围

- 多步生成：FLM、LangFlow、Duo、MDLM、CANDI、RDLM。
- 少步/单步蒸馏：FMLM、Duo+DCD、Duo+Di4C、MDLM+SDTT、MDLM+Di4C。
- LM1B 使用 `bert-base-uncased`、长度 128；OWT 使用 `gpt2`、长度 1024。
- 多步步数：多数 many-step 方法使用 `1 2 4 8 16 32 1024`；RDLM 只使用官方默认 `1000` 和本项目原保留的 `1024`；少步步数：`1 2 4 8 16 32`。
- 每个受支持配置生成 1,024 个样本，seed 固定为 42。
- 质量指标：GPT-2 Large Generative PPL、平均 unigram entropy、Self-BLEU；主延迟指标：独立 CUDA timing 的 seconds/sample。

132 个受支持 generation cell 会写入 `results/matrix/generation.tsv`。RDLM/OWT 不会伪造任务，原因写入 `results/matrix/unsupported.tsv`。RDLM 的 `1/2/4/8/16/32` 不作为主 baseline：原始方法是约 1000 步 SDE 采样，低步数只是强行截断迭代次数，已在服务器诊断中表现出非规范 token 与异常低 PPL。

## 服务器最短路径

在 Linux GPU 服务器上执行：

```bash
git clone <你的 GitHub 仓库地址> diffusion_baseline
cd diffusion_baseline
conda create -n dlb-bootstrap python=3.11 -y
conda activate dlb-bootstrap
export DLB_ROOT="$PWD"
export DLB_PYTHON="$CONDA_PREFIX/bin/python"
```

先准备一个能导入 `PyYAML`、`pydantic` 的 bootstrap Python；它只用于解析 manifest 和启动下载脚本：

```bash
"$DLB_PYTHON" -m pip install -e ".[dev,data,checkpoints]"
```

同步本仓库代码到 Linux GPU 服务器后，严格按以下顺序执行：

```bash
bash scripts/fetch_sources.sh
"$DLB_PYTHON" scripts/verify_sources.py --root "$DLB_ROOT"
"$DLB_PYTHON" scripts/fetch_data.py --root "$DLB_ROOT"
"$DLB_PYTHON" scripts/preprocess_data.py --root "$DLB_ROOT" --dataset all
"$DLB_PYTHON" scripts/verify_data.py --root "$DLB_ROOT" --dataset all
"$DLB_PYTHON" scripts/fetch_checkpoints.py --root "$DLB_ROOT" --all-public
"$DLB_PYTHON" scripts/verify_checkpoints.py --root "$DLB_ROOT"
bash envs/create_all.sh
bash envs/verify_all.sh
bash scripts/smoke_all.sh
bash scripts/run_all.sh
bash scripts/evaluate_all.sh
bash scripts/benchmark_all.sh
"$DLB_PYTHON" scripts/aggregate_results.py --root "$DLB_ROOT"
```

单机 4 卡服务器可使用本仓库的本地并行入口，默认绑定 GPU `0,1,2,3`：

```bash
export DLB_GPUS=0,1,2,3
export DLB_MAX_JOBS=4
bash scripts/smoke_4gpu.sh
bash scripts/run_4gpu.sh
bash scripts/evaluate_4gpu.sh
bash scripts/benchmark_4gpu.sh
"$DLB_PYTHON" scripts/aggregate_results.py --root "$DLB_ROOT"
```

这条路径仍要求先补齐 `reference_reproduction` checkpoint。更多说明见
[4-GPU 本地并行运行](docs/09_four_gpu_local.md)。

`smoke_all.sh` 使用独立的 `results/smoke/`，不会被正式汇总接受。若只需先验证一个方法，可运行：

```bash
bash scripts/run_one.sh --model flm --dataset lm1b --steps 1 \
  --num-samples 1 --seed 42
```

严格汇总失败时，不要删除失败目录；先查看 `results/summary/failures.csv`，修复后重跑对应阶段。需要先查看当前可用结果时：

```bash
"$DLB_PYTHON" scripts/aggregate_results.py --root "$DLB_ROOT" --partial
```

`--partial` 只用于诊断，不是论文主结果。

## 文档索引

- [源码与可用性](docs/01_sources_and_availability.md)
- [数据下载与预处理](docs/02_datasets.md)
- [Conda 环境](docs/03_environments.md)
- [Checkpoint 下载与校验](docs/04_checkpoints.md)
- [训练与蒸馏](docs/05_training.md)
- [生成、评测与 timing](docs/06_generation_and_evaluation.md)
- [Slurm](docs/07_slurm.md)
- [故障排查](docs/08_troubleshooting.md)
- [4-GPU 本地并行运行](docs/09_four_gpu_local.md)
- [实验矩阵](docs/EXPERIMENT_MATRIX.md)
- [ELF：OWT、前缀续写、WMT14/XSum 与服务器 timing 方案](docs/10_elf_server_runbook.md)（独立入口；先用公开权重建立基线）
- [ELF：GPU 0、1 自动核验并补齐质量实验](docs/15_elf_gpu01_queue.md)（最新执行入口；复用已完成配置）
- [ELF：32格质量结果归档与GPU 0、1正式timing](docs/16_elf_results_and_timing.md)（质量已完成；当前执行入口）
- [ELF：条件4步/8步短输出补评分](docs/19_elf_short_response_rescore.md)（只评分两格，保留全部样本，另存最多64-token结果）
- [ELF：OWT公开权重，对齐旧baseline评分与timing](docs/18_elf_owt_public_baseline.md)（当前执行入口；不训练，复用样本，条件2048条重评分）
- [ELF：OWT 64-token prompt、512-token response](docs/20_elf_owt_c64r512.md)（独立C64-R512实验；重新生成2048条样本）
- [ELF：LM1B/OWT四类任务严格对齐方案](docs/17_elf_matched_baseline_plan.md)（历史设计，已停止执行）
- [ELF：DS210029 数据就绪后的单张 H200 逐步执行清单](docs/11_elf_h200_next_steps.md)
- [ELF：正式条件实验空输入故障、数据诊断与恢复](docs/12_elf_condition_recovery.md)
- [ELF：条件输入 EOS 修复、validation/test 与 timing 恢复](docs/13_elf_eos_fix.md)
- [ELF：9 月 13 日结果总览与剩余质量实验（timing 暂缓）](docs/14_elf_quality_remaining.md)

所有可复现输入均在 `artifacts/` 和 `configs/` 中锁定。不要把 `data/`、`checkpoints/`、`upstreams/`、`results/` 或 Conda archive 提交到 Git。