[v1] update docs (#10684)

2026-09-27 01:45:42 +08:00 · 2026-09-14 16:09:48 +08:00
parent 100e9a42c6
commit 97b32d3133
68 changed files with 2071 additions and 2152 deletions
--- a/docs/zh/feature-guide/batching.md
+++ b/docs/zh/feature-guide/batching.md
@@ -0,0 +1,42 @@
+# 批处理策略
+
+`batching_strategy` 决定每个 micro-batch 包含多少条样本，以及这些样本是通过 padding 组成矩形张量还是拼接为一条连续序列。
+
+| 策略 | 样本数 | 序列组织方式 |
+|------|--------|--------------|
+| `normal` | 固定 | 按 batch 内最长序列 padding |
+| `padding_free` | 固定 | 将多条样本拼接为一条连续序列 |
+| `dynamic_batching` | 动态 | 按最长序列 padding |
+| `dynamic_padding_free` | 动态 | 按 token 预算选择样本并拼接 |
+
+例如设置 `cutoff_len: 2048`、`micro_batch_size: 4` 时，动态策略的 token 预算为 `2048 × 4 = 8192`。假设依次读到的样本长度为 2048、512、512、512：
+
+- `normal` 固定选择 4 条样本，并将每条样本 padding 到 2048，最终处理 8192 个 token 位置。
+- `padding_free` 仍选择 4 条样本，但将它们拼接为长度 3584 的序列，从而移除 padding。
+- `dynamic_batching` 在 `最长样本长度 × 样本数` 不超过 8192 的范围内决定样本数，然后按最长样本进行 padding。
+- `dynamic_padding_free` 在样本总长度不超过 8192 的范围内决定样本数，并将所选样本拼接起来。
+
+因此，动态策略中的 `micro_batch_size` 用于计算 token 预算，并不表示最终 batch 一定包含相同数量的样本。
+
+## 配置示例
+
+`batching_strategy` 是训练 YAML 的顶层字段。以下片段配置 `dynamic_padding_free`，每个 micro-batch 的 token 预算为 `2048 × 4 = 8192`：
+
+```yaml
+batching_strategy: dynamic_padding_free
+micro_batch_size: 4
+cutoff_len: 2048
+max_steps: 100
+flash_attn: flash_attention_2
+```
+
+仓库在 `examples/v1/train_batching_strategy/` 下为四种策略提供了完整示例。
+
+## 使用约束
+
+- `dynamic_batching` 必须设置正数 `max_steps`。
+- `dynamic_batching` 不支持 `save_epochs`，应使用 `save_steps`。
+- `padding_free` 和 `dynamic_padding_free` 需要设置 `flash_attn: flash_attention_2`。
+- `normal` 以外的策略仅支持纯文本数据；使用其他策略处理多模态数据时，BatchGenerator 会在生成 batch 时抛出 `NotImplementedError`。
+
+内部 collate 和状态恢复流程见[BatchGenerator](../developer-guide/core/batch_generator.md)。
--- a/docs/zh/feature-guide/data_preparation.md
+++ b/docs/zh/feature-guide/data_preparation.md
@@ -0,0 +1,89 @@
+# 数据准备
+
+v1 将训练样本统一为 Messages 结构。`DataEngine` 根据 `train_dataset` 指向的路径加载数据，并在存在 `converter` 时转换原始字段。
+
+## 配置训练数据集
+
+训练 YAML 的 `train_dataset` 指定数据来源。数据文件路径或 Hub ID 对应单个 Messages 格式数据集；数据集 YAML 则通过条目描述数据路径、split、converter 和采样配置，并支持组合多个数据集。
+
+训练 YAML 包含 `model`、`train_dataset` 等训练字段；数据集 YAML 以数据集名称为键，包含 `path`、`source`、`converter` 等字段。下文“组合多个数据集”展示数据集 YAML 的结构。
+
+`train_dataset` 接受以下形式：
+
+- 本地数据集 YAML，例如 `data/v1_sft_demo.yaml`
+- 本地数据文件或目录
+- Hugging Face Hub 数据集 ID
+- Hub 数据集仓库中的 YAML
+
+`eval_dataset` 字段已定义，评估流程尚未实现。完整字段见[数据参数](../configuration/data.md#dataarguments)。
+
+## SFT 数据格式
+
+```json
+{
+  "messages": [
+    {
+      "role": "user",
+      "content": [{"type": "text", "value": "介绍一下你自己。"}],
+      "loss_weight": 0.0
+    },
+    {
+      "role": "assistant",
+      "content": [{"type": "text", "value": "我是一个 AI 助手。"}],
+      "loss_weight": 1.0
+    }
+  ]
+}
+```
+
+`content` 是内容块列表；文本使用 `text`，多模态内容可以使用 `image_url`、`audio_url` 或 `video_url`。`loss_weight` 是该 assistant turn 的监督权重，并应用到该回复的每个监督 token。`0.0` 不参与损失计算，`1.0` 使用完整权重，也可以设置 `0.5` 等中间值调整不同回复的相对权重。
+
+多轮对话会按每个受监督的 assistant turn 展开为多条训练样本，每条样本只监督最后一个 assistant turn。
+
+多模态 SFT 示例位于 `data/v1_multimodal_demo.yaml`，对应训练配置为 `examples/v1/train_full/train_multimodal.yaml`。
+
+## DPO/RM 数据格式
+
+DPO 和 RM 使用 `chosen_messages` 与 `rejected_messages`：
+
+```json
+{
+  "chosen_messages": [
+    {"role": "user", "content": [{"type": "text", "value": "问题"}], "loss_weight": 0.0},
+    {"role": "assistant", "content": [{"type": "text", "value": "更优回答"}], "loss_weight": 1.0}
+  ],
+  "rejected_messages": [
+    {"role": "user", "content": [{"type": "text", "value": "问题"}], "loss_weight": 0.0},
+    {"role": "assistant", "content": [{"type": "text", "value": "较差回答"}], "loss_weight": 1.0}
+  ]
+}
+```
+
+## 组合多个数据集
+
+```yaml
+identity:
+  path: data/identity.json
+  source: local
+  converter: alpaca
+
+demo:
+  path: organization/dataset
+  source: hf_hub
+  split: train
+  size: 1000
+  weight: 0.5
+  streaming: false
+```
+
+同一个 YAML 中的 streaming 配置必须一致；当前训练路径不支持 streaming 数据集。多个条目会组成一个全局数据索引；`size` 与 `weight` 用于控制每个数据集的采样规模，计算顺序与有放回抽样的含义见[采样规模的计算](../configuration/data.md#采样规模的计算)。
+
+## 转换现有数据格式
+
+| 名称 | 原始数据 |
+|------|----------|
+| `alpaca` | `instruction`、`input`、`output` |
+| `sharegpt` | `conversations` |
+| `pair` | chosen/rejected 偏好对 |
+
+扩展 converter 的接口见[数据插件](../developer-guide/plugins/data_plugins.md)。
--- a/docs/zh/feature-guide/distributed_training.md
+++ b/docs/zh/feature-guide/distributed_training.md
@@ -0,0 +1,103 @@
+# 分布式训练
+
+训练命令检测到多设备后会自动通过 `torchrun` 启动。拓扑字段属于 `TrainingArguments`，后端专属字段放在 `dist_config`。
+
+本页列出后端和拓扑配置，完整任务配置见 [SFT](sft.md)、[DPO](dpo.md)和 [RM](rm.md)。设备安装与支持范围见 [NPU 说明](../multi-backend/npu/index.md)。
+
+## 数据并行
+
+未设置 `dist_config` 时，多个 DP 进程使用 DDP，每个进程持有完整模型；单设备直接训练。
+
+## FSDP2
+
+FSDP2 通过分片降低每个设备上的模型状态内存开销，配置入口为 `dist_config.name: fsdp2`。
+
+```yaml
+dist_config:
+  name: fsdp2
+  reshard_after_forward: true
+  offload_params: false
+  pin_memory: true
+  dcp_path: null
+```
+
+## FSDPTurbo
+
+FSDPTurbo 在 FSDP2 基础上提供 MoE 专家并行和专家参数分片。先安装 FSDPTurbo 依赖：
+
+```bash
+python -m pip install -r requirements/fsdpturbo.txt
+```
+
+FSDPTurbo 的配置入口为 `dist_config.name: fsdpturbo`：
+
+```yaml
+dist_config:
+  name: fsdpturbo
+  ep_size: 16
+  ep_dispatcher: eager
+```
+
+`ep_size` 必须能够整除 data parallel size。完整示例见 `examples/v1/train_full/train_full_qwen3_moe_fsdpturbo_ep_fsdp.yaml`。
+
+## DeepSpeed
+
+DeepSpeed 后端从 `config_file` 读取 ZeRO 等配置，该字段必填。
+
+```yaml
+dist_config:
+  name: deepspeed
+  config_file: examples/deepspeed/ds_z3_config.json
+```
+
+## Ulysses Context Parallel
+
+Ulysses CP 跨设备切分序列计算，由顶层 `cp_mode` 和 `cp_size` 启用：
+
+```yaml
+flash_attn: flash_attention_2
+cp_mode: ulysses
+cp_size: 2
+
+dist_config:
+  name: fsdp2
+```
+
+设置 `cp_size > 1` 后，训练使用 Ulysses 通信和 Sequence Parallel loss 完成跨 CP 进程的损失聚合。Ulysses 需要 `flash_attention_2` 和 FSDP2，不要求特定的 `batching_strategy`，支持 `normal` 和符合[批处理约束](batching.md)的 padding-free 策略。
+
+`cp_size` 需要能够整除 world size。模型的 attention head 数必须能被 `cp_size` 整除，即 `num_attention_heads % cp_size == 0`；例如 32 个 attention head 可以使用 `cp_size: 2`。KV head 数与 `cp_size` 则要求其中一个能被另一个整除，即 `num_key_value_heads % cp_size == 0` 或 `cp_size % num_key_value_heads == 0`。当前只有 SFT 支持 `cp_size > 1`；DPO 和 RM 要求 `cp_size: 1`。
+
+当前训练器不支持 `model_type: qwen3_5` 的 CP 路径。
+
+## 配置并行拓扑
+
+```yaml
+dp_size: 4
+cp_size: 2
+cp_mode: ulysses
+mp_replicate_size: 2
+mp_shard_size: 4
+dist_timeout: 18000
+```
+
+上例使用 8 个进程，并同时构造两套 DeviceMesh：
+
+- Data Mesh 的形状为 `dp_size × cp_size = 4 × 2`，分别用于 Data Parallel 和 Context Parallel。
+- Model Mesh 的形状为 `mp_replicate_size × mp_shard_size = 2 × 4`。FSDP 在 4 个进程间分片参数，并在 2 个分片组间复制参数。
+
+`mp_replicate_size` 和 `mp_shard_size` 描述 FSDP 的二维参数 Mesh，不是额外的 Tensor Parallel 配置。未显式指定时，`dp_size` 默认为 `world_size / cp_size`，`mp_shard_size` 默认为 `world_size / mp_replicate_size`。后端完整配置见[训练参数](../configuration/training.md#dist_config)。
+
+## 配置多机启动
+
+CLI 读取 `NNODES`、`NODE_RANK`、`NPROC_PER_NODE`、`MASTER_ADDR` 和 `MASTER_PORT`。例如使用 4 台机器、每台机器 8 个设备时，在每台机器上执行：
+
+```bash
+NNODES=4 \
+NODE_RANK=<0到3，各节点不同> \
+NPROC_PER_NODE=8 \
+MASTER_ADDR=<rank 0 节点的 IP> \
+MASTER_PORT=29500 \
+llamafactory-cli sft config.yaml
+```
+
+4 个节点需要使用相同的 `NNODES`、`NPROC_PER_NODE`、`MASTER_ADDR` 和 `MASTER_PORT`，并分别设置 `NODE_RANK=0`、`1`、`2`、`3`。
--- a/docs/zh/feature-guide/dpo.md
+++ b/docs/zh/feature-guide/dpo.md
@@ -0,0 +1,53 @@
+# 偏好优化（DPO）
+
+v1 通过统一的 `dpo` 入口运行偏好优化，`pref_loss` 支持 `sigmoid`、`orpo` 和 `simpo`。数据必须是 chosen/rejected 偏好对。
+
+## 运行 DPO
+
+```bash
+llamafactory-cli dpo examples/v1/train_lora/train_lora_dpo.yaml
+```
+
+## 训练配置
+
+`peft_config.name: lora` 启用 LoRA，未配置 `peft_config` 时进行全参训练。以下是完整的 LoRA DPO 配置，保存为 `config.yaml` 后运行 `llamafactory-cli dpo config.yaml`：
+
+```yaml
+model: Qwen/Qwen3-4B
+model_class: llm
+train_dataset: data/v1_dpo_demo.yaml
+
+peft_config:
+  name: lora
+  r: 16
+  lora_alpha: 32
+  target_modules: all
+
+pref_loss: sigmoid
+pref_beta: 0.1
+pref_ftx: 0.0
+dpo_label_smoothing: 0.0
+
+dist_config:
+  name: fsdp2
+
+output_dir: outputs/qwen3_dpo
+micro_batch_size: 1
+cutoff_len: 2048
+learning_rate: 1.0e-5
+max_steps: 10
+```
+
+## 偏好损失
+
+`pref_loss` 指定偏好损失：
+
+- `sigmoid`：标准 DPO，相对参考策略进行偏好优化，`pref_beta` 控制偏好项缩放。
+- `orpo`：无参考策略的 odds-ratio 偏好目标，基于回答的平均 log-prob 计算。
+- `simpo`：无参考策略的平均 log-prob 差值目标，通过 `simpo_gamma` 设置 margin。
+
+`pref_ftx` 加入 SFT 损失，`dpo_label_smoothing` 用于 cDPO。设置 `ld_alpha` 后，LD-DPO 会将 chosen 和 rejected 中超出较短响应长度的尾部 token log-prob 乘以该系数。参数定义见[训练参数](../configuration/training.md#trainingarguments)。
+
+## 参考模型
+
+标准 DPO 需要 reference log-prob：全参训练会建立独立的 reference model；LoRA 训练复用 policy model 的基座权重，并在计算 reference log-prob 时禁用 adapter。ORPO 和 SimPO 的目标计算不使用 reference log-prob。
--- a/docs/zh/feature-guide/index.md
+++ b/docs/zh/feature-guide/index.md
@@ -0,0 +1,29 @@
+# 功能指南
+
+功能指南面向使用 v1 完成训练与推理任务的用户。配置结构、默认值和可用选项统一放在[参数配置](../configuration/index.md)。
+
+## 训练任务
+
+| 页面 | 内容 |
+|------|------|
+| [数据准备](data_preparation.md) | Messages 格式、数据集 YAML 和 converter |
+| [SFT](sft.md) | 全参、LoRA、Freeze、QLoRA |
+| [DPO](dpo.md) | DPO、ORPO、SimPO 与偏好数据 |
+| [RM](rm.md) | 奖励模型训练 |
+
+## 训练效率与扩展
+
+| 页面 | 内容 |
+|------|------|
+| [批处理](batching.md) | 四种 batching strategy |
+| [分布式训练](distributed_training.md) | FSDP2、FSDPTurbo、DeepSpeed、Ulysses |
+| [优化器](optimizer.md) | AdamW 与 Muon 配置 |
+| [融合算子加速](kernel_acceleration.md) | Liger、融合算子和组合配置 |
+
+## 模型保存与使用
+
+| 页面 | 内容 |
+|------|------|
+| [模型保存与恢复](model_saving.md) | 最终模型、checkpoint、断点续训 |
+| [模型导出](model_export.md) | LoRA 合并和 HF 格式导出 |
+| [推理](inference.md) | CLI 对话与 adapter 加载 |
--- a/docs/zh/feature-guide/inference.md
+++ b/docs/zh/feature-guide/inference.md
@@ -0,0 +1,53 @@
+# 推理
+
+v1 已实现基于 Hugging Face 后端的 `chat` 入口，可以在命令行中进行流式对话。模型对话格式来自 tokenizer 自带的 Hugging Face chat template；没有模板时回退到内置 ChatML。
+
+当前 `chat` 入口支持 `sample_backend: hf` 的交互式单条推理。批量推理和 `vllm` 采样后端尚未接入该入口；交互式配置中不设置 `train_dataset`。
+
+## 启动 CLI 对话
+
+`model` 指定模型 Hub ID 或包含完整权重的 HF 模型目录。LoRA adapter 的加载方式见下文。
+
+以下对话配置保存为 `chat.yaml`，使用与 [SFT 示例](sft.md)相同的基座：
+
+```yaml
+model: Qwen/Qwen3-0.6B
+sample_backend: hf
+max_new_tokens: 512
+```
+
+```bash
+llamafactory-cli chat chat.yaml
+```
+
+## 覆盖模型 Chat Template
+
+`custom_chat_template` 接收一段 Jinja2 模板字符串，并覆盖 tokenizer 自带模板：
+
+```yaml
+model: path/to/model
+custom_chat_template: >-
+  {% for message in messages %}
+  {{ message['role'] + ': ' + message['content'] }}
+  {% endfor %}
+```
+
+v1 使用模板字符串，不接受 `template: <name>` 字段。
+
+## 使用 LoRA Adapter
+
+LoRA 推理通过 `model` 指定训练时的基座，通过 `peft_config.adapter_name_or_path` 指定 adapter。以下片段加入 `chat.yaml`，加载 [SFT 的 LoRA 示例](sft.md#lora)产生的 `outputs/qwen3_lora`；对应基座为 `Qwen/Qwen3-0.6B`：
+
+```yaml
+peft_config:
+  name: lora
+  adapter_name_or_path: outputs/qwen3_lora
+```
+
+推理模式会依次合并 `adapter_name_or_path` 中的 adapter。[模型导出](model_export.md)说明合并结果的持久化保存。
+
+## 使用训练或合并后的模型
+
+完成 [SFT 全参示例](sft.md#全参训练)后，将 `chat.yaml` 中的 `model` 改为 `outputs/qwen3_full`；完成[模型导出示例](model_export.md#导出配置)后，改为 `outputs/qwen3_merged`。这两种目录都包含完整模型权重，加载时移除此前的 `peft_config`，保留采样参数并运行 `llamafactory-cli chat chat.yaml`。
+
+完整字段见[推理参数](../configuration/inference.md)。
--- a/docs/zh/feature-guide/kernel_acceleration.md
+++ b/docs/zh/feature-guide/kernel_acceleration.md
@@ -0,0 +1,53 @@
+# 融合算子加速
+
+`kernel_config` 统一配置模型侧的融合算子加速。它可以替换单个算子，也可以像 Liger Kernel 一样同时应用多个融合实现和训练优化。
+
+`kernel_config.name` 接受一个加速实现名称，也接受逗号分隔的多个名称。未设置 `kernel_config` 或设为 `null` 时，此入口不替换算子。以下为算子配置片段，完整训练配置见 [SFT](sft.md)。
+
+## 自动配置
+
+`name: auto` 根据当前设备应用默认组合。当前仅 [NPU](../multi-backend/npu/index.md) 配置了默认组合，CUDA 上不会自动启用 Liger 或 CUDA Fused MoE。
+
+## Liger Kernel
+
+Liger Kernel 依赖 `liger-kernel`，并要求模型具有对应适配。
+
+```yaml
+kernel_config:
+  name: liger_kernel
+```
+
+Liger Kernel 根据模型类型调用 `liger_kernel.transformers` 中对应的应用函数，可融合 RMSNorm、RoPE、SwiGLU、Cross Entropy 等训练路径。具体启用项由模型支持范围和 Liger Kernel 版本决定。
+
+## CUDA Fused MoE
+
+```yaml
+kernel_config:
+  name: cuda_fused_moe
+```
+
+该方案依赖 CUDA 和 Triton，并要求模型结构匹配，使用融合实现替换 MoE 计算路径。模型架构不匹配时保留原模型。
+
+## Flash Linear Attention
+
+`flash-linear-attention` 通过 FSDPTurbo 的算子注册表替换模型中已有的 FLA 实现，支持 CUDA 和 NPU。它依赖 FLA 和 FSDPTurbo，不会将普通 attention 模型转换成线性注意力模型。
+
+```yaml
+kernel_config:
+  name: flash-linear-attention
+  include_kernels: chunk_gated_delta_rule,fused_recurrent_gated_delta_rule
+  chunk_size: 64
+```
+
+`include_kernels` 可以设置为 `auto` 或逗号分隔的算子名称；`chunk_size` 支持 `16`、`32` 和 `64`。使用前需要安装 `requirements/fsdpturbo.txt`。
+
+## 组合多个加速实现
+
+多个名称以逗号分隔。以下为语法示意，`first_kernel` 和 `second_kernel` 是占位符，运行时替换为实际注册的实现名称：
+
+```yaml
+kernel_config:
+  name: first_kernel,second_kernel
+```
+
+多个实现按书写顺序应用，后一个接收前一个处理后的模型；所有实现共享同一份 `kernel_config`。设备与依赖检查在应用前执行，模型匹配由各实现负责。组合入口不自动处理重复替换或顺序冲突。内部调用关系见[开发者指南](../developer-guide/plugins/kernel-acceleration/overview.md)，字段定义见[模型参数](../configuration/model.md#kernel_config)。
--- a/docs/zh/feature-guide/model_export.md
+++ b/docs/zh/feature-guide/model_export.md
@@ -0,0 +1,44 @@
+# 模型导出
+
+`merge` 命令将一个或多个 LoRA adapter 依次合并到基座模型，并保存为 Hugging Face 格式目录。
+
+导出目录包含合并后的模型权重。基座与 adapter 的直接加载见[推理](inference.md)，训练状态的保存和续训见[模型保存与恢复](model_saving.md)。
+
+## 导出配置
+
+以下配置保存为 `merge.yaml`，接续 [SFT 的 LoRA 示例](sft.md#lora)：基座为 `Qwen/Qwen3-0.6B`，adapter 位于 `outputs/qwen3_lora`，合并结果保存到 `outputs/qwen3_merged`。`model` 必须与 adapter 训练时的基座一致。
+
+```yaml
+model: Qwen/Qwen3-0.6B
+peft_config:
+  name: lora
+  adapter_name_or_path: outputs/qwen3_lora
+  export_dir: outputs/qwen3_merged
+  export_size: 5
+  infer_dtype: auto
+  export_legacy_format: false
+```
+
+```bash
+llamafactory-cli merge merge.yaml
+```
+
+导出完成后，可以将推理配置的 `model` 设置为 `outputs/qwen3_merged`，按[推理指南](inference.md#使用训练或合并后的模型)加载。
+
+`export_size` 的单位为 GB。`infer_dtype` 支持 `auto`、`float16`、`float32` 和 `bfloat16`。完整字段见[模型参数](../configuration/model.md#peft_config)。
+
+## 合并多个 Adapter
+
+`adapter_name_or_path` 可以使用列表。系统按照列表顺序将每个 LoRA adapter 合并到前一步得到的模型中：
+
+```yaml
+model: Qwen/Qwen3-0.6B
+peft_config:
+  name: lora
+  adapter_name_or_path:
+    - outputs/domain_adapter
+    - outputs/task_adapter
+  export_dir: outputs/qwen3_merged
+```
+
+上例先合并 `domain_adapter`，再合并 `task_adapter`。这两个目录是独立训练的 adapter 示例，均须与 `Qwen/Qwen3-0.6B` 基座匹配；使用时替换为实际目录。
--- a/docs/zh/feature-guide/model_saving.md
+++ b/docs/zh/feature-guide/model_saving.md
@@ -0,0 +1,61 @@
+# 模型保存与恢复
+
+训练结束时 `save_model()` 保存最终模型；训练过程中可以按 step 或 epoch 保存 checkpoint。
+
+## 保存训练 Checkpoint
+
+`save_steps` 按更新步数触发保存，`save_epochs` 按数据遍历进度触发保存。同时设置时，训练器根据 `save_epochs` 重新计算并覆盖 `save_steps`。纯 `dynamic_batching` 只支持按 step 保存。
+
+以下字段位于训练 YAML 的顶层：
+
+```yaml
+save_steps: 500
+save_epochs: null
+save_total_limit: 3
+save_ckpt_as_hf: false
+```
+
+`save_steps` 与 `save_epochs` 控制触发时机。`save_total_limit` 删除最旧的完整 checkpoint。
+
+## 从 Checkpoint 恢复训练
+
+`resume_from_checkpoint` 恢复训练状态。以下配置从当前 `output_dir` 中自动查找 checkpoint：
+
+```yaml
+resume_from_checkpoint: auto
+```
+
+`auto` 在 `output_dir` 下寻找最新的完整 checkpoint，也可以直接填写 checkpoint 路径。未设置 `resume_from_checkpoint` 时，即使 `output_dir` 中存在 checkpoint，也不会触发续训。
+
+## 不同后端的保存格式
+
+| 训练后端 | 默认 checkpoint | `save_ckpt_as_hf: true` |
+|----------|-------------------|--------------------------|
+| FSDP2 / FSDPTurbo | 保存用于续训的分布式 checkpoint | 额外在 checkpoint 中生成 `hf_model` 目录 |
+| DeepSpeed | 保存 DeepSpeed 训练状态 | 额外在 checkpoint 中生成 `hf_model` 目录 |
+| 单设备 / DDP | 模型权重使用 HF 格式保存 | 不生成额外的 `hf_model` 目录 |
+
+FSDP2、FSDPTurbo 和 DeepSpeed 启用 `save_ckpt_as_hf` 后，仍会保留用于恢复训练的原始 checkpoint，同时额外保存 HF 格式模型。聚合完整模型权重会提高保存时的内存占用。
+
+`save_ckpt_as_hf: false` 是默认值，保存中间 checkpoint 时不额外聚合 HF 格式权重。
+
+## 初始化权重与恢复训练
+
+| 配置 | 用途 | 加载时机 | 恢复内容 |
+|------|------|----------|----------|
+| `dist_config.dcp_path` | 使用 DCP 权重初始化模型 | FSDP2/FSDPTurbo 模型分片阶段 | 仅模型权重 |
+| `resume_from_checkpoint` | 从训练 checkpoint 继续训练 | Trainer 初始化阶段 | 模型、优化器、学习率调度器、批次进度、训练步数及可用的随机数状态 |
+
+以下配置使用已有 DCP 模型权重初始化新训练：
+
+```yaml
+dist_config:
+  name: fsdp2
+  dcp_path: path/to/dcp_model
+```
+
+以下配置从 `output_dir` 中最新的完整 checkpoint 恢复训练状态：
+
+```yaml
+resume_from_checkpoint: auto
+```
--- a/docs/zh/feature-guide/optimizer.md
+++ b/docs/zh/feature-guide/optimizer.md
@@ -0,0 +1,39 @@
+# 优化器
+
+`optim_config` 未设置或为 `null` 时，v1 使用 AdamW，并从顶层 `learning_rate` 读取学习率。
+
+## Muon
+
+设置 `optim_config.name: muon` 启用 Muon。Muon 对适合正交化更新的二维权重使用 Muon，并将偏置、归一化参数、embedding、输出层和 LoRA 参数交给内部 AdamW。
+
+以下为完整的 SFT 配置（`config.yaml`）：
+
+```yaml
+model: Qwen/Qwen3-0.6B
+model_class: llm
+train_dataset: data/v1_sft_demo.yaml
+
+dist_config:
+  name: fsdp2
+
+optim_config:
+  name: muon
+  wd: 0.1
+  momentum: 0.95
+  nesterov: true
+  ns_steps: 5
+  adamw_betas: [0.9, 0.95]
+  adamw_eps: 1.0e-8
+
+output_dir: outputs/qwen3_muon
+micro_batch_size: 1
+cutoff_len: 2048
+learning_rate: 1.0e-5
+max_steps: 10
+```
+
+```bash
+llamafactory-cli sft config.yaml
+```
+
+学习率统一由顶层 `learning_rate` 控制。仓库示例见 `examples/v1/train_full/train_full_muon.yaml`，完整字段见[训练参数](../configuration/training.md#optim_config)。
--- a/docs/zh/feature-guide/rm.md
+++ b/docs/zh/feature-guide/rm.md
@@ -0,0 +1,38 @@
+# 奖励模型训练（RM）
+
+`rm` 入口训练回答评分模型，使 chosen 回答的评分高于 rejected 回答。
+
+RM 与 [DPO](dpo.md) 使用相同的偏好对数据结构，输出模型用于回答评分，不作为普通聊天模型使用。
+
+## 训练配置
+
+`peft_config.name: lora` 启用 LoRA，未配置 `peft_config` 时进行全参训练。分布式后端由 `dist_config` 配置，支持条件见[分布式训练](distributed_training.md)。以下为完整的 LoRA RM 配置（`config.yaml`）：
+
+```yaml
+model: Qwen/Qwen3-0.6B
+train_dataset: data/v1_dpo_demo.yaml
+
+peft_config:
+  name: lora
+  r: 16
+  target_modules: all
+
+dist_config:
+  name: fsdp2
+
+output_dir: outputs/qwen3_rm
+micro_batch_size: 1
+cutoff_len: 2048
+learning_rate: 1.0e-5
+max_steps: 10
+```
+
+```bash
+llamafactory-cli rm config.yaml
+```
+
+入口会将 `model_class` 设置为 `cls`，初始化 score head，并在训练开始前检查首个样本是否包含 `chosen_messages` 和 `rejected_messages`。
+
+## 训练约束
+
+RM 当前要求 `cp_size` 为 `1`。`cutoff_len` 需要保留 chosen 和 rejected 的有效 token；否则当前 micro-batch 无法组成偏好对。
--- a/docs/zh/feature-guide/sft.md
+++ b/docs/zh/feature-guide/sft.md
@@ -0,0 +1,91 @@
+# 监督微调（SFT）
+
+`llamafactory-cli sft` 启动监督微调。下文依次说明全参训练、LoRA、Freeze 和量化 LoRA 的配置。
+
+## 全参训练
+
+全参训练更新全部模型参数，配置中不设置 `peft_config`。以下完整配置保存为 `config.yaml`，使用 `Qwen/Qwen3-0.6B` 和 FSDP2：
+
+```yaml
+model: Qwen/Qwen3-0.6B
+model_class: llm
+train_dataset: data/v1_sft_demo.yaml
+
+output_dir: outputs/qwen3_full
+micro_batch_size: 1
+cutoff_len: 2048
+learning_rate: 1.0e-4
+max_steps: 10
+
+dist_config:
+  name: fsdp2
+```
+
+```bash
+llamafactory-cli sft config.yaml
+```
+
+## LoRA
+
+LoRA 冻结基座权重并训练 adapter，通过 `peft_config.name: lora` 配置。在上述训练配置中加入以下块，并将 `output_dir` 改为 `outputs/qwen3_lora`；基座仍为 `Qwen/Qwen3-0.6B`：
+
+```yaml
+peft_config:
+  name: lora
+  r: 16
+  lora_alpha: 32
+  lora_dropout: 0.05
+  target_modules: all
+```
+
+训练结束后，adapter 保存到 `outputs/qwen3_lora`。[推理](inference.md#使用-lora-adapter)和[模型导出](model_export.md#导出配置)示例沿用这一基座与目录。
+
+继续训练已有 adapter 时设置 `adapter_name_or_path`。训练只允许一个 adapter；LoRA 参数从 adapter 自身恢复。
+
+## Freeze
+
+Freeze 直接更新指定层或模块的权重，其余参数保持冻结。以下 `peft_config` 替换 LoRA 配置，模型、数据与训练字段沿用全参示例：
+
+```yaml
+peft_config:
+  name: freeze
+  freeze_trainable_layers: 2
+  freeze_trainable_modules: all
+  freeze_extra_modules: null
+  cast_trainable_params_to_fp32: true
+```
+
+正数表示最后 N 层，负数表示最前 N 层。
+
+## QLoRA
+
+量化 LoRA 在量化后的基座上训练 adapter，分别由 `quant_config` 和 `peft_config` 控制。当前 v1 的量化插件入口为 `bnb` 和 `auto`：`bnb` 提供 bitsandbytes 的 4-bit、8-bit 加载分支；`auto` 在指定有效位宽时转交 `bnb` 处理。
+
+下面是使用 bitsandbytes 4-bit 的 QLoRA 示例，运行环境需安装 bitsandbytes。将以下字段加入全参示例，模型、数据与 FSDP2 配置保持一致：
+
+```yaml
+output_dir: outputs/qwen3_qlora
+
+peft_config:
+  name: lora
+  r: 16
+  target_modules: all
+
+quant_config:
+  name: bnb
+  quantization_bit: 4
+  quantization_type: nf4
+  double_quantization: true
+```
+
+`quantization_bit` 表示加载位宽，`quantization_type` 表示 4-bit 量化格式，`double_quantization` 控制 4-bit double quant。位宽分支与字段默认行为见[量化参数](../configuration/model.md#quant_config)，后端限制见 [NPU 说明](../multi-backend/npu/index.md)。
+
+## 激活值重算
+
+`enable_activation_checkpointing` 默认为 `true`。启用后，训练在反向传播时重新计算部分前向结果，以减少激活值占用的显存或设备内存，并增加计算量。设置为 `false` 关闭重计算：
+
+```yaml
+enable_activation_checkpointing: false
+```
+
+分布式后端、批处理与算子配置分别见[分布式训练](distributed_training.md)、[批处理](batching.md)和[融合算子加速](kernel_acceleration.md)。