源码导读：XTuner + MMEngine

XTuner 核心 ~6 万行（不算 configs），主要在 model wrapper + dataset processor + hooks。本章给阅读路线。

13.1仓库结构

xtuner/                            https://github.com/InternLM/xtuner
├── xtuner/
│   ├── tools/                     ★ CLI 入口
│   │   ├── train.py
│   │   ├── chat.py
│   │   ├── test.py
│   │   ├── model_converters/
│   │   │   ├── pth_to_hf.py
│   │   │   ├── merge.py
│   │   │   └── ...
│   │   └── ...
│   ├── configs/                   ★ 100+ 内置 config
│   ├── model/                     ★ wrapper（SFT / DPO / VL）
│   │   ├── sft.py                  SupervisedFinetune
│   │   ├── dpo.py
│   │   ├── orpo.py
│   │   ├── reward.py
│   │   ├── llava.py                LLaVA
│   │   ├── internvl.py             InternVL
│   │   └── utils.py
│   ├── dataset/                   数据集
│   │   ├── huggingface.py          process_hf_dataset
│   │   ├── preference_dataset.py
│   │   ├── intern_repo.py
│   │   ├── llava.py / internvl/
│   │   ├── map_fns/                 20+ map_fn
│   │   └── samplers/
│   ├── engine/
│   │   ├── hooks/                   EvaluateChatHook 等
│   │   └── runner.py
│   ├── parallel/
│   │   └── sequence/                 Ulysses SP
│   ├── utils/
│   │   ├── templates.py             ★ 30+ chat template
│   │   └── stop_criteria.py
│   ├── apis/                       Python API（少用）
│   └── version.py
├── docs/
└── tests/

13.2建议阅读顺序

13.3调度链

xtuner train cfg.py
   │
   ├── tools/train.py: parse args + load config
   ├── 用 MMEngine Runner 构造
   │       ├── 解析 model dict → SupervisedFinetune(llm=..., lora=...)
   │       ├── 解析 dataset dict → process_hf_dataset(...)
   │       │       └── 调 map_fn 转 conversation
   │       │       └── 调 template 拼 prompt
   │       │       └── tokenize + pack
   │       ├── 解析 optim / scheduler
   │       └── 注册 hooks
   └── Runner.train()
           └── 每 iter: forward / backward / step / hooks

13.4关键 commit 时间线

13.5对照其他

13.6社区入口

• GitHub: https://github.com/InternLM/xtuner（5k+ ⭐）
• 官方文档（中英）: https://xtuner.readthedocs.io/
• InternLM Discord / 飞书群
• 书生·浦语社区

13.7这章你需要带走的

• XTuner 调度链：CLI → MMEngine Runner → wrapper + dataset → Runner.train；
• 核心目录：model/ + dataset/ + engine/hooks/；
• InternLM / InternVL 用户首选 XTuner + LMDeploy 全家桶；
• 读源码先看 sft.py + huggingface.py + evaluate_chat_hook.py。

13.8 真实源码树（v0.2.0 + V1）

xtuner/
├── entry_point.py:12-253      ★ CLI 13 子命令 dispatcher
├── registry.py                 BUILDER / MAP_FUNC 注册表
├── version.py                  __version__ = "0.2.0"
│
├── configs/                   ★ 594 个 config，27 个模型家族
│   ├── llama/ internlm/ qwen/ deepseek/ gemma/ baichuan/ chatglm/ mixtral/ qwen_moe/
│   ├── llava/ internvl/        VLM
│   ├── dpo/ orpo/ reward_model/
│   └── deepspeed/              ZeRO-2/3 preset
│
├── model/                     ★ wrapper
│   ├── sft.py:36-105           SupervisedFinetune
│   ├── dpo.py:44-60            DPO（持 reference model）
│   ├── orpo.py / reward.py
│   ├── llava.py / internvl.py
│   ├── modules/                projectors / dispatch / 自定义层
│   ├── transformers_models/    Mixtral / DeepSeek 等定制版
│   └── utils.py
│
├── dataset/                   ★ 17 个 loader
│   ├── huggingface.py:23-40    process_hf_dataset
│   ├── json_dataset.py / preference_dataset.py / concat_dataset.py
│   ├── llava.py / internvl_dataset.py
│   ├── map_fns/                alpaca_map_fn / template_map_fn_factory
│   ├── collate_fns/             默认 + preference collate
│   └── utils.py                 Packer / encode_fn
│
├── engine/
│   ├── runner/loops.py:8-42     TrainLoop（IterBasedTrainLoop wrapper）
│   ├── hooks/                    DatasetInfoHook / EvaluateChatHook / VarlenAttnArgsToMessageHubHook
│   └── _strategy/deepspeed.py    DeepSpeed strategy
│
├── parallel/sequence/         ★ Ulysses SP（6 文件）
│   ├── setup_distributed.py / comm.py / attention.py
│   ├── sampler.py / reduce_loss.py
│   └── __init__.py:37-63
│
├── tools/ (32 个)
│   ├── train.py:162-309         主训练入口
│   ├── chat.py / test.py / list_cfg.py / copy_cfg.py / log_dataset.py
│   ├── model_converters/        pth_to_hf / merge / split
│   ├── data_preprocess/         arxiv / refcoco
│   └── mmbench.py / eval_refcoco.py
│
├── evaluation/                  benchmark
└── v1/                         ★ V1 引擎（2025-09 新）
    ├── engine/                   FSDP + DeepSpeed
    ├── model/                    V1 模型类
    ├── datasets/                 21 个 V1 loader
    ├── train/                    V1 训练 loop
    ├── loss/                     GRPO / DPO / SFT loss
    ├── rl/                       RL 子系统（参考 verl）
    ├── float8/                   ★ FP8 训练
    ├── ops/                      自定义 CUDA
    └── utils/

13.9 XTuner V1（2025-09）：为 200B+ MoE 而生

13.10 与 LLaMA-Factory / ms-swift 比较