[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/configuration/data.md
+++ b/docs/zh/configuration/data.md
@@ -0,0 +1,37 @@
+# 数据参数
+
+## DataArguments
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `train_dataset` | `str \| None` | `None` | 训练数据集路径、YAML 或 Hub ID |
+| `eval_dataset` | `str \| None` | `None` | 字段已定义；评估流程尚未实现 |
+
+## DatasetInfo
+
+数据集 YAML 的每个顶层条目使用以下字段：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `path` | `str` | 必填 | 本地路径或 Hub ID |
+| `source` | `local \| hf_hub` | `hf_hub` | 数据来源 |
+| `split` | `str` | `train` | 数据集 split |
+| `converter` | `str \| None` | `None` | `alpaca`、`sharegpt`、`pair` 或已注册名称 |
+| `size` | `int \| None` | 全部 | 重采样后的目标索引数量 |
+| `weight` | `float` | 不设置 | 索引数量的缩放倍率 |
+| `streaming` | `bool` | `false` | 字段已定义；当前训练路径不支持 streaming 数据集 |
+
+### 采样规模的计算
+
+`size` 和 `weight` 作用于数据集展开后的训练索引。多轮 SFT 中，每个受监督的 assistant turn 对应一个索引条目，因此索引数量可能大于原始数据的行数；偏好对数据则以一组 chosen/rejected 为一个条目。
+
+使用正数 `size`、`weight` 时，按以下顺序计算：
+
+1. 设置 `size` 后，先从展开后的索引中有放回抽取 `size` 个条目；省略时保留完整索引。
+2. 设置 `weight` 后，再从上一步结果中有放回抽取 `int(当前条目数 × weight)` 个条目，小数部分向下取整；省略时保留上一步结果。
+
+例如，`size: 1000` 与 `weight: 0.5` 同时设置时，先抽取 1000 个条目，再抽取其中的 500 个条目。最终规模为 500，但可能包含重复条目，也可能没有覆盖某些原始记录。
+
+`weight` 控制每个数据集贡献的索引数量，不是各数据集之间归一化后的抽样概率，也不改变样本的损失权重。`weight > 1` 可以增加索引数量。显式设置 `weight: 1.0` 仍会执行有放回重采样；省略 `size` 和 `weight` 才会直接保留全部展开后的索引。
+
+数据格式和多数据集组合方式见[数据准备](../feature-guide/data_preparation.md)。
--- a/docs/zh/configuration/index.md
+++ b/docs/zh/configuration/index.md
@@ -0,0 +1,30 @@
+# 参数说明
+
+v1 使用一份 YAML 同时描述数据、模型、训练和推理配置。顶层字段来自四个参数类。`peft_config`、`quant_config`、`kernel_config`、`dist_config` 等插件配置通过 `name` 选择具体实现，其余字段由对应实现解析；可用名称和字段统一列在所属的参数页面中。
+
+```yaml
+model: Qwen/Qwen3-0.6B
+train_dataset: data/v1_sft_demo.yaml
+
+output_dir: outputs/qwen3_sft
+micro_batch_size: 1
+learning_rate: 1.0e-4
+max_steps: 10
+
+dist_config:
+  name: fsdp2
+
+kernel_config:
+  name: liger_kernel
+```
+
+## 参数分类
+
+| 页面 | 参数 |
+|------|------|
+| [数据参数](data.md) | `DataArguments`、`DatasetInfo` |
+| [模型参数](model.md) | `ModelArguments`、PEFT、量化、初始化和 Kernel |
+| [训练参数](training.md) | `TrainingArguments`、分布式和优化器 |
+| [推理参数](inference.md) | `SampleArguments` |
+
+功能指南中的示例只列出完成对应任务所需的字段。字段类型、默认值和可用选项以本目录为准。
--- a/docs/zh/configuration/inference.md
+++ b/docs/zh/configuration/inference.md
@@ -0,0 +1,10 @@
+# 推理参数
+
+## SampleArguments
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `sample_backend` | `str` | `hf` | 采样后端；可用值为 `hf` |
+| `max_new_tokens` | `int` | `128` | 单次最多生成 token 数 |
+
+使用方法见[推理](../feature-guide/inference.md)。
--- a/docs/zh/configuration/model.md
+++ b/docs/zh/configuration/model.md
@@ -0,0 +1,119 @@
+# 模型参数
+
+## ModelArguments
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `model` | `str` | `Qwen/Qwen3-4B-Instruct-2507` | 本地模型路径或 Hub ID |
+| `custom_chat_template` | `str \| None` | `None` | 覆盖 tokenizer/processor 的 Jinja2 chat template |
+| `trust_remote_code` | `bool` | `false` | 是否加载 Hub 远端代码 |
+| `flash_attn` | `str` | `sdpa` | `eager`、`sdpa` 或 `flash_attention_2` |
+| `model_class` | `str` | `llm` | `llm`、`cls` 或 `other` |
+| `init_config` | `dict \| None` | `None` | 模型初始化配置 |
+| `peft_config` | `dict \| None` | `None` | LoRA 或 Freeze 配置 |
+| `kernel_config` | `dict \| None` | `None` | 融合算子加速配置 |
+| `quant_config` | `dict \| None` | `None` | 量化配置 |
+
+`llm` 加载因果语言模型或 image-to-text 模型，`cls` 加载单标签 token
+classification 模型，`other` 使用 `AutoModel`。
+
+## peft_config
+
+### LoRA
+
+设置 `name: lora`：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `r` | `int` | `8` | LoRA rank |
+| `lora_alpha` | `int` | `16` | LoRA alpha |
+| `lora_dropout` | `float` | `0.05` | LoRA dropout |
+| `target_modules` | `list[str] \| str` | `all` | 目标模块 |
+| `use_rslora` | `bool` | `false` | 是否启用 RS-LoRA |
+| `use_dora` | `bool` | `false` | 是否启用 DoRA |
+| `modules_to_save` | `list[str] \| None` | `None` | 额外保存模块 |
+| `adapter_name_or_path` | `list[str] \| str \| None` | `None` | adapter 路径 |
+| `export_dir` | `str \| None` | `None` | 合并导出目录 |
+| `export_size` | `int` | `5` | 导出分片大小，GB |
+| `export_hub_model_id` | `str \| None` | `None` | Hub 仓库 ID |
+| `infer_dtype` | `str` | `auto` | `auto`、`float16`、`float32` 或 `bfloat16` |
+| `export_legacy_format` | `bool` | `false` | 是否使用旧式权重格式 |
+
+### Freeze
+
+设置 `name: freeze`：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `freeze_trainable_layers` | `int` | `2` | 正数选择最后 N 层，负数选择最前 N 层 |
+| `freeze_trainable_modules` | `list[str] \| str` | `all` | 层内可训练模块 |
+| `freeze_extra_modules` | `list[str] \| str \| None` | `[]` | 额外可训练模块 |
+| `cast_trainable_params_to_fp32` | `bool` | `true` | 是否将可训练参数转换为 fp32 |
+
+## quant_config
+
+当前 v1 注册了 `bnb` 和 `auto` 两个量化插件入口。`bnb` 使用 bitsandbytes；`auto` 在指定有效位宽后也转交 `bnb`，当前没有按模型或环境切换到其他量化后端的逻辑。
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `name` | `str` | 必填 | `bnb` 或 `auto` |
+| `quantization_bit` | `int \| None` | `None` | 量化加载位宽，4 或 8 |
+| `compute_dtype` | `str \| torch.dtype` | `float16` | 4-bit 计算和存储 dtype |
+| `double_quantization` | `bool` | `true` | 是否启用 4-bit double quant |
+| `quantization_type` | `str` | `nf4` | 4-bit 量化格式，`nf4` 或 `fp4` |
+
+4-bit 分支将 `compute_dtype`、`double_quantization` 和 `quantization_type` 传给 [Hugging Face BitsAndBytesConfig](https://huggingface.co/docs/transformers/main_classes/quantization#transformers.BitsAndBytesConfig)，其中 NF4 和 FP4 是 bitsandbytes 的两种 4-bit 格式。8-bit 分支设置 `load_in_8bit=True`，不使用这三个 4-bit 专属字段。
+
+`quantization_bit` 的字段默认值为 `None`，实际行为取决于 `name`：
+
+- 不设置 `quant_config` 或将其设为 `null` 时，不通过此插件添加量化加载配置。
+- `name: auto` 且省略 `quantization_bit`（或设为 `null`）时，保持模型加载参数不变。
+- `name: bnb` 且省略 `quantization_bit`（或设为 `null`）时，使用 4-bit 量化。
+- `name: auto` 且指定 `quantization_bit` 为 `4` 或 `8` 时，转交 `bnb` 实现处理，仍需满足该实现的依赖和运行条件。
+
+以上描述插件构造量化加载配置的行为。[SFT 的 QLoRA 示例](../feature-guide/sft.md#qlora)展示 `bnb`、4-bit、NF4 与 LoRA 的组合。
+
+## init_config
+
+`init_config` 当前只使用 `name` 选择模型初始化设备：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `name` | `str` | 必填 | 初始化插件名称 |
+
+| `name` 取值 | 初始化设备 |
+|-------------|------------|
+| `init_on_default` | 当前分布式设备 |
+| `init_on_meta` | meta device |
+| `init_on_rank0` | rank 0 使用 CPU，其余 rank 使用 meta |
+
+meta 初始化不能与量化同时使用。
+
+## kernel_config
+
+`kernel_config` 可以配置单个融合算子，也可以启用 Liger Kernel 这类包含多项优化的外部加速库。
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `name` | `str` | 必填 | `auto`、单个实现名称或逗号分隔的多个名称 |
+
+可用名称：
+
+- `liger_kernel`
+- `cuda_fused_moe`
+- `flash-linear-attention`
+- `npu_fused_moe`
+- `npu_fused_rmsnorm`
+- `npu_fused_rope`
+- `npu_fused_swiglu`
+
+### Flash Linear Attention
+
+当 `name` 包含 `flash-linear-attention` 时，可以使用以下专属字段：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `include_kernels` | `str` | `auto` | `auto` 或逗号分隔的 FLA 算子名称 |
+| `chunk_size` | `int` | `64` | chunk size；可选 `16`、`32`、`64` |
+
+用法见[融合算子加速](../feature-guide/kernel_acceleration.md)。
--- a/docs/zh/configuration/training.md
+++ b/docs/zh/configuration/training.md
@@ -0,0 +1,125 @@
+# 训练参数
+
+## TrainingArguments
+
+### 训练过程与精度
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `output_dir` | `str` | `outputs/<uuid>` | 输出目录 |
+| `micro_batch_size` | `int` | `1` | 基础 micro-batch 大小 |
+| `global_batch_size` | `int \| None` | `None` | 默认 `dp_size × micro_batch_size` |
+| `cutoff_len` | `int` | `2048` | 最大序列长度 |
+| `learning_rate` | `float` | `1e-4` | 训练及优化器插件使用的学习率 |
+| `num_train_epochs` | `int` | `3` | 训练轮数 |
+| `max_steps` | `int \| None` | `None` | 设置后使用 step 作为终止条件 |
+| `max_grad_norm` | `float` | `1.0` | 梯度裁剪阈值 |
+| `bf16` | `bool` | `true` | 是否使用 bf16 |
+| `seed` | `int` | `42` | 随机种子 |
+| `full_determinism` | `bool` | `false` | 是否启用完整确定性模式 |
+
+`global_batch_size` 与 `micro_batch_size` 共同决定每次参数更新需要累积多少个 micro-batch。省略 `global_batch_size` 时，每个 DP 进程每次更新处理一个 micro-batch；显式设置时，它必须能被 `dp_size × micro_batch_size` 整除，每个进程的累积次数为 `global_batch_size / (dp_size × micro_batch_size)`。
+
+例如，`dp_size: 4`、`micro_batch_size: 2`、`global_batch_size: 32` 对应每个 DP 进程累积 4 个 micro-batch。固定样本数策略下，一次更新共使用 32 条样本；动态策略中的实际样本数随长度变化，`global_batch_size` 仍决定累积次数，token 预算见[批处理策略](../feature-guide/batching.md)。
+
+### 批处理配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `batching_strategy` | `str` | `normal` | `normal`、`padding_free`、`dynamic_batching` 或 `dynamic_padding_free` |
+| `batching_workers` | `int` | `16` | 数据加载 worker 数 |
+| `enable_activation_checkpointing` | `bool` | `true` | 是否启用激活值重算 |
+
+各策略的 token 预算和使用约束见[批处理策略](../feature-guide/batching.md)。
+
+### 分布式与优化器
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `dist_config` | `dict \| None` | `None` | FSDP2、FSDPTurbo 或 DeepSpeed 配置 |
+| `dp_size` | `int \| None` | `None` | 默认由 world size 和 `cp_size` 推导 |
+| `cp_size` | `int` | `1` | Context Parallel 大小 |
+| `cp_mode` | `str` | `ulysses` | Context Parallel 实现 |
+| `mp_replicate_size` | `int` | `1` | FSDP 二维 Mesh 的参数复制维度大小 |
+| `mp_shard_size` | `int \| None` | `None` | FSDP 二维 Mesh 的参数分片维度大小；默认由 world size 推导 |
+| `dist_timeout` | `int` | `18000` | 进程组初始化超时，秒 |
+| `optim_config` | `dict \| None` | `None` | 优化器插件 |
+| `lr_scheduler_config` | `dict \| None` | `None` | 学习率调度插件；当前没有内置实现 |
+
+### Checkpoint 与日志配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `resume_from_checkpoint` | `str \| None` | `None` | checkpoint 路径或 `auto` |
+| `save_steps` | `int \| None` | `None` | 每 N 个全局 step 保存 |
+| `save_epochs` | `float \| None` | `None` | 每 N 个 epoch 保存 |
+| `save_ckpt_as_hf` | `bool` | `false` | 是否在中间 checkpoint 中额外保存 HF 格式模型 |
+| `save_total_limit` | `int \| None` | `None` | 最多保留数量 |
+| `logging_steps` | `int` | `1` | 日志间隔 |
+
+### 偏好优化参数
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `pref_loss` | `str` | `sigmoid` | `sigmoid`、`orpo` 或 `simpo` |
+| `pref_beta` | `float` | `0.1` | DPO beta |
+| `pref_ftx` | `float` | `0.0` | SFT 损失系数 |
+| `simpo_gamma` | `float` | `0.5` | SimPO reward margin |
+| `dpo_label_smoothing` | `float` | `0.0` | cDPO label smoothing |
+| `ld_alpha` | `float \| None` | `None` | LD-DPO 长度差异权重 |
+
+## dist_config
+
+### FSDP2
+
+设置 `name: fsdp2`：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `reshard_after_forward` | `bool` | `true` | forward 后是否重新分片 |
+| `offload_params` | `bool` | `false` | 是否 offload 参数 |
+| `pin_memory` | `bool` | `true` | 是否使用 pinned memory |
+| `dcp_path` | `str \| None` | `None` | 初始化 DCP 权重路径 |
+
+### DeepSpeed
+
+设置 `name: deepspeed`：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `config_file` | `str` | 必填 | DeepSpeed JSON 配置 |
+
+### FSDPTurbo
+
+设置 `name: fsdpturbo`：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `reshard_after_forward` | `bool` | `true` | forward 后是否重新分片 |
+| `offload_params` | `bool` | `false` | 是否 offload 参数 |
+| `pin_memory` | `bool` | `true` | 是否使用 pinned memory |
+| `dcp_path` | `str \| None` | `None` | 初始化 DCP 权重路径 |
+| `ep_size` | `int` | `1` | 专家并行组大小 |
+| `ep_dispatcher` | `str` | `eager` | 专家 token dispatcher |
+| `fsdp_ignored_modules` | `list[str]` | `[]` | 外层 FSDP2 忽略的额外模块 |
+| `hook_modules` | `list[str]` | `[]` | EFSDP hook 的模块模式 |
+| `fsdp_implementation` | `str` | `native` | `native` 或 `custom` |
+
+`dp_size`、`cp_size`、`mp_replicate_size` 和 `mp_shard_size` 是 `TrainingArguments` 字段，不放在 `dist_config` 中。
+
+## optim_config
+
+设置 `name: muon`：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `wd` | `float` | `0.1` | weight decay |
+| `momentum` | `float` | `0.95` | Muon momentum |
+| `nesterov` | `bool` | `true` | 是否启用 Nesterov |
+| `ns_steps` | `int` | `5` | Newton-Schulz 步数 |
+| `adamw_betas` | `list[float]` | `[0.9, 0.95]` | 内部 AdamW betas |
+| `adamw_eps` | `float` | `1e-8` | 内部 AdamW epsilon |
+
+学习率统一使用顶层 `learning_rate`。
+
+Muon 的完整配置示例见[优化器](../feature-guide/optimizer.md)。