[v1] update docs (#10684)

docs/zh/developer-guide/plugins/data_plugins.md

@@ -0,0 +1,57 @@
+# 数据插件
+
+数据插件把数据来源和原始字段格式从 DataEngine 的索引逻辑中分离。Loader 负责获得可读取的数据集，Converter 负责解释其中的一条记录；两者由不同配置字段选择，可以组合使用。
+
+## 与 DataEngine 的交接
+
+```text
+DatasetInfo.source
+  → hf_hub：DataEngine 直接调用 datasets.load_dataset
+  → 其他来源：DataLoaderPlugin(source).load(dataset_info)
+      → Dataset
+Dataset 中的一条原始记录 + DatasetInfo.converter
+  → DataConverterPlugin(converter)(raw_sample)
+      → 标准 SFTSample / DPOSample
+```
+
+相同的本地 loader 可以配合 `alpaca` 或 `sharegpt` converter；数据已经是标准消息结构时省略 converter。分词与标签生成发生在后续 Renderer 中。
+
+## DataLoaderPlugin
+
+接口定义在 `plugins/data_plugins/loader.py`。DataEngine 调用 `DataLoaderPlugin(source).load(dataset_info)`，而 `load` 会从 DatasetInfo 中提取 `path`、`split` 和 `streaming`，再将这三个位置参数传给注册函数。
+
+因此，注册函数接收的是以下参数，不是整个 DatasetInfo：
+
+```python
+@DataLoaderPlugin("example").register()
+def load_example(path, split, streaming):
+    ...
+```
+
+当前注册的 `local` 根据文件扩展名选择 Hugging Face dataset builder，再加载文件或目录。Hub 数据由 DataEngine 直接分派，当前没有通过一个名为 `hf_hub` 的 loader 注册项加载。
+
+返回的数据集由 DataEngine 持有并用于建立索引。新增 loader 必须保持调用参数与返回数据集的约定；当前训练链路要求可按索引读取的数据集，具体 streaming 边界见 [DataEngine](../core/data_engine.md#处理-streaming-dataset)。
+
+## DataConverterPlugin
+
+接口定义在 `plugins/data_plugins/converter.py`。Converter 接收单条原始样本字典，返回一个 v1 `SFTSample` 或 `DPOSample`，不是输入或返回整个 batch。当前注册：
+
+- `alpaca`
+- `sharegpt`
+- `pair`
+
+```python
+@DataConverterPlugin("example").register()
+def convert_example(raw_sample):
+    return {"messages": ...}
+```
+
+返回字段必须符合 `utils/types.py` 中的 Messages 类型。SFT 返回 `messages`，偏好数据返回 `chosen_messages` 和 `rejected_messages`；图片等媒体也在这一阶段转为标准内容块，实际媒体特征由 Renderer 的 processor 生成。
+
+DataEngine 在建立多轮索引和实际取样时都会调用 converter。它应稳定地转换一条记录，避免在函数中随机选择对话轮次或维护读取进度。轮次展开、采样规模和读取顺序分别由 DataEngine 与 sampler 管理。
+
+## 调整数据索引
+
+`adjust_data_index` 根据 `size`、`weight` 调整某个数据集的索引，`select_data_sample` 处理索引选择。两者是 `loader.py` 中的普通函数，不通过插件名称注册或路由。改变来源、格式时扩展 loader/converter；改变共用索引语义时，应检查这些函数及 DataEngine 的调用位置。
+
+注册在模块导入时生效，机制见[插件注册机制](../baseplugin_mechanism.md)。使用配置见[数据准备](../../feature-guide/data_preparation.md)。

docs/zh/developer-guide/plugins/index.md

@@ -0,0 +1,22 @@
+# 插件实现
+
+v1 按数据、模型和训练流程组织内置插件。配置文件通过实现名称选择插件，新增实现时使用对应的插件类注册。
+
+| 分类 | 内容 |
+|------|------|
+| [数据插件](data_plugins.md) | DataLoader 与 DataConverter |
+| [模型插件](model_plugins.md) | 初始化、PEFT、量化、Kernel 和 Sequence Parallel |
+| [训练器插件](trainer_plugins.md) | 分布式后端、批处理和优化器 |
+| [融合算子加速](kernel-acceleration/overview.md) | Kernel 选择与调用流程 |
+
+插件注册和参数解析的通用机制见[插件注册机制](../baseplugin_mechanism.md)。
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+data_plugins
+model_plugins
+trainer_plugins
+kernel-acceleration/overview
+```

docs/zh/developer-guide/plugins/kernel-acceleration/overview.md

@@ -0,0 +1,48 @@
+# 融合算子加速
+
+Kernel 系统在模型加载后应用融合算子加速。一个实现既可以替换单个算子，也可以组合多个融合操作或接入外部加速库。
+
+入口位于 `plugins/model_plugins/kernels/interface.py`。它负责名称选择与调用顺序，`base.py` 中的 BaseKernel 负责执行公共检查，各实现的 `_apply` 负责识别模型并进行具体替换。注册机制、检查流程和模型适配由这三层分别承担。
+
+## Kernel 应用流程
+
+```text
+ModelEngine
+  → apply_kernels(model, kernel_config)
+  → 解析 kernel_config.name
+  → auto 设备选择或 KernelPlugin(name)
+  → BaseKernel.apply()
+  → check_device()
+  → check_deps()
+  → _apply()
+```
+
+接口模块显式导入内置实现，使装饰器在调用前完成注册。`apply_kernels` 将名称按逗号拆分，逐个调用，并将返回模型传给下一个实现；每个实现收到同一份配置与 `require_logits` 等上下文。
+
+`auto` 是入口处的特殊分派：根据设备查询 `_AUTO_KERNELS`，再调用其中的已注册实现。它不是自动搜索最快实现的算法；当前映射只包含 NPU，其他设备不会因 `auto` 而执行替换。
+
+## BaseKernel 与具体实现如何协作
+
+注册表保存的是实现类。`KernelPlugin(name).apply(...)` 将方法调用转发到该类，继承的 `BaseKernel.apply` 再使用 `cls` 调用该实现的检查和替换方法。
+
+`check_device` 检查设备，`check_deps` 检查可选依赖，随后公共入口确认存在模型对象，最后调用 `_apply`。模型是否受支持、需要替换哪个模块，由具体 `_apply` 决定。BaseKernel 不统一检测所有模型结构。
+
+例如，CUDA Fused MoE 按模型架构和模块类名寻找目标并替换 forward；Liger 根据 model type 调用对应外部适配函数；FLA 通过算子注册表匹配模型属性。成功找到注册名称，只说明能进入实现，不能保证模型中存在可替换目标。
+
+## 组合与扩展边界
+
+组合时，后一个实现看到的是已经修改过的模型。入口不提供冲突检测、模型快照或失败回滚，也不会把各实现的专属配置拆成独立配置块。新增实现需要清楚界定自己修改哪些模块，并返回后续调用所需的模型对象。
+
+实现类继承 BaseKernel，提供 `check_device` 和 `_apply`，需要额外依赖时覆盖 `check_deps`；子类定义时会检查必需方法是否实现。名称注册后，还需要确保实现模块在使用前被导入。通用路由与注册规则见[插件注册机制](../../baseplugin_mechanism.md)。
+
+## 已注册实现
+
+- `liger_kernel`
+- `cuda_fused_moe`
+- `flash-linear-attention`
+- `npu_fused_moe`
+- `npu_fused_rmsnorm`
+- `npu_fused_rope`
+- `npu_fused_swiglu`
+
+用户配置见[融合算子加速](../../../feature-guide/kernel_acceleration.md)。

docs/zh/developer-guide/plugins/model_plugins.md

@@ -0,0 +1,47 @@
+# 模型插件
+
+模型插件提供模型加载和处理过程中的可替换操作。初始化、量化、PEFT 和 Kernel 由 ModelEngine 依次调用；Sequence Parallel 需要训练拓扑，因此由 BaseTrainer 在训练初始化阶段调用。
+
+## 每个插件接收和改变什么
+
+| 插件 | 接收 | 返回或修改 |
+|------|------|------------|
+| InitPlugin | 当前进程的设备与 rank 信息 | 返回用于创建模型的 `torch.device` |
+| QuantizationPlugin | 模型加载参数、量化配置与训练标记 | 返回补充量化选项后的加载参数 |
+| PeftPlugin | 已构造模型、PEFT 配置与训练标记 | 设置可训练参数、加载或合并 adapter，返回处理后的模型 |
+| KernelPlugin | PEFT 处理后的模型与 Kernel 配置 | 替换适配的计算路径，返回处理后的模型 |
+
+它们的接口不同，不能仅通过替换 `name` 在不同插件族之间互换。具体调用次序及原因见 [ModelEngine](../core/model_engine.md)。
+
+## InitPlugin
+
+注册 `init_on_default`、`init_on_meta`、`init_on_rank0`，返回模型创建使用的 `torch.device`。
+
+实现位于 `plugins/model_plugins/initialization.py`。这些函数不加载模型权重；ModelEngine 根据返回设备决定调用 `from_pretrained` 还是在 meta 上使用 `from_config`。Rank 0 加载与其他 rank 的权重同步需要后续分布式路径协作。
+
+## PeftPlugin
+
+注册 `lora` 与 `freeze`。两者分别通过 `LoraParams` 和 `FreezeParams` 严格解析配置。LoRA 还负责 adapter 加载、合并与导出。
+
+实现位于 `plugins/model_plugins/peft.py`。训练时，LoRA 创建或加载 adapter，Freeze 按层和模块选择可训练权重；后续优化器只收集 `requires_grad` 的参数。推理与合并导出也复用 LoRA 插件，因此同一配置入口的行为还取决于调用时的 `is_train`。
+
+## QuantizationPlugin
+
+注册 `auto` 与 `bnb`。插件修改 `from_pretrained` 的 init kwargs，不直接替换已经加载的权重。
+
+实现位于 `plugins/model_plugins/quantization.py`。调用发生在模型创建之前，使量化选项能参与权重加载；这也解释了它与加载完成后执行的 PEFT、Kernel 所处阶段不同。当前可配置字段见[模型参数](../../configuration/model.md#quant_config)。
+
+## KernelPlugin
+
+Kernel 在模型加载和 PEFT 处理后应用。调用流程见[融合算子加速](kernel-acceleration/overview.md)。
+
+## Sequence Parallel Plugins
+
+设置 `TrainingArguments.cp_size > 1` 后，BaseTrainer 使用 `cp_mode` 的值选择 `SequenceParallelModelPlugin`。因此，`cp_mode: ulysses` 会调用 `SequenceParallelModelPlugin("ulysses")` 修改模型 forward 所需的通信；训练循环再调用 `SequenceParallelLossPlugin("sequence_parallel_loss")` 处理 loss 聚合。用户配置见[分布式训练](../../feature-guide/distributed_training.md#ulysses-context-parallel)。
+
+这两个插件共同完成序列并行：模型侧处理 attention 的通信与切分，损失侧处理分布后的输入与监督计算。只替换 forward 而沿用不匹配的损失路径，会破坏这组协作关系。实现位于 `plugins/model_plugins/parallelization/`。
+
+## Chat Template 迁移
+
+旧 `RenderingPlugin` 和 `plugins/model_plugins/templates/` 已删除。Chat
+template 统一由 `core/rendering/` 调用 Hugging Face 模板。

docs/zh/developer-guide/plugins/trainer_plugins.md

@@ -0,0 +1,51 @@
+# 训练器插件
+
+训练器插件替换训练过程中的具体操作。BaseTrainer 持有模型、优化器和训练计数，BatchGenerator 持有读取进度与缓冲区；插件通过调用参数访问这些对象。替换实现时需要维持调用方依赖的输入、输出和状态约定。
+
+## DistributedPlugin
+
+当前注册 `fsdp2`、`fsdpturbo` 和 `deepspeed`。每个实现类提供统一的模型切分、保存和 checkpoint 方法组：
+
+- `shard_model`
+- `save_model`
+- `save_checkpoint`
+- `load_checkpoint`
+
+参数分别由 `FSDP2Params`、`FSDPTurboParams` 和 `DeepSpeedParams` 解析。FSDPTurbo 额外实现跨专家并行 Mesh 的梯度裁剪。公共 DeviceMesh 拓扑由 `TrainingArguments` 和 `DistributedInterface` 管理。
+
+注册和入口位于 `plugins/trainer_plugins/distributed/interface.py`，具体引擎位于同目录下的 `fsdp2.py`、`fsdpturbo.py` 和 `deepspeed.py`。路由层把配置转换为对应 Params，再委托后端执行；参数配置本身不负责创建进程组。
+
+FSDP2 / FSDPTurbo 的 `shard_model` 返回处理后的模型，BaseTrainer 再创建优化器。DeepSpeed 的该入口返回后端 engine，BaseTrainer 随后调用它的 `prepare`，共同准备模型、优化器和 scheduler。因此，公共入口背后的返回对象与初始化协议仍需结合 BaseTrainer 的后端分支理解。
+
+保存时，Trainer 和 checkpoint 协调器决定时机与通用训练状态，分布式插件负责其模型和优化器状态格式。扩展新后端需要同时提供分片、最终模型保存、checkpoint 保存与恢复；仅实现分片无法覆盖完整训练生命周期。
+
+## BatchingPlugin
+
+`normal` 是 BatchGenerator 默认路径。插件注册：
+
+- `padding_free`
+- `dynamic_batching`
+- `dynamic_padding_free`
+
+接口与实现位于 `plugins/trainer_plugins/batching.py`。实现类继承 BaseBatcher，提供四个操作：
+
+| 方法 | BatchGenerator 用它决定什么 |
+|------|-----------------------------|
+| `get_data_provider_batch_size` | 底层 DataLoader 每次读多少条样本 |
+| `compute_length` | 批次生成器报告的长度 |
+| `fill_buffer` | 何时继续读取样本、怎样填充缓冲区 |
+| `generate_batch` | 如何取出样本并组织一个更新步的 micro-batch 列表 |
+
+方法接收 `batch_info`、buffer 或读取函数，状态由调用方管理。`generate_batch` 返回 `None` 时，BatchGenerator 结束本次迭代。新策略需要同时考虑数据耗尽、剩余 buffer 和 checkpoint 恢复，不能只实现拼接张量。
+
+## OptimizerPlugin
+
+当前注册 `muon`。未指定插件时 BaseTrainer 使用默认优化器。Muon 将适合正交化更新的二维权重和其余 AdamW 权重分组。用户配置见[优化器](../../feature-guide/optimizer.md)。
+
+入口位于 `plugins/trainer_plugins/optimizers/optimizer.py`，接收处理后的模型与 `optim_config`，返回 optimizer 实例。当前 Muon 直接读取配置字段；顶层 `learning_rate` 在 TrainingArguments 初始化时写入配置的 `lr`。插件负责参数分组与优化器构造，反向传播和更新时机仍由 Trainer 或 DeepSpeed engine 控制。
+
+## LRSchedulerPlugin
+
+插件族存在，但当前没有注册可选的 scheduler 名称。
+
+接口位于 `plugins/trainer_plugins/lr_scheduler.py`。BaseTrainer 未收到配置时使用固定倍率的 LambdaLR；收到配置时按名称调用插件，传入 optimizer、训练总步数与配置，并保存返回的 scheduler。扩展实现应返回兼容训练循环和 checkpoint 状态保存的 scheduler 对象。