# 训练参数

## 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)。