> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuneplane.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 用 ms-swift 训练

> 把 ModelScope 的工具箱接进平台：扁平的参数面、只做全参微调，以及一个 GRPO trainer 覆盖整个家族。

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp new my-swift --method ms-swift/sft
tp submit my-swift --profile h200:8 \
  --model Qwen/Qwen3.5-9B --train-data data/train.jsonl
```

目录版本为 `4.5.3`，两个后端。Hugging Face Trainer 后端八个方法：`sft`，以及 `swift rlhf` 背后的
`dpo` / `kto` / `cpo` / `orpo` / `rm` / `grpo` / `gkd`。Megatron 后端另有三个：`megatron-sft`、
`megatron-grpo`、`megatron-gkd`。配置是扁平的命令行参数 —— 只有一层，没有点号路径 —— 适配器把训练
入口放在 `torchrun` 下启动。

<Warning>
  ms-swift 没有发布同时带 vLLM、Ray 和 DeepSpeed 的 GPU 镜像，而且它自己声明的依赖是*区间*而不是
  固定版本。管理员需要用 `deploy/docker/Dockerfile.msswift` 构建一张并设置
  `TUNEPLANE_IMAGE_MS_SWIFT`，或者登记 `ms-swift-4.5.3` 这个 runtime id，之后才能提交作业。

  它不能和 TRL 共用镜像：ms-swift 要求 `trl<1.0`，而 TRL runtime 是 `trl==1.10.0`。
</Warning>

## 参数绑到哪些字段

| 平台参数                | ms-swift 参数     |
| ------------------- | --------------- |
| `--model`           | `--model`       |
| `--train-data`      | `--dataset`     |
| `--validation-data` | `--val_dataset` |

和 verl、TRL 不同，这里验证集文件是可选的。改设 `split_dataset_ratio`，ms-swift 会从训练集里切一份
出来；显式传了 `--validation-data` 就用显式的那份，比例参数被忽略。

训练数据是本地的 `jsonl` / `json` / `csv` / `parquet` 文件，经 `datasets` 读取，所以扩展名决定用哪个
loader。列名遵循 ms-swift 自己的 schema（`messages`，或 `query`/`response`）—— 平台不做重映射。

## LoRA 是一个参数，不是另一个方法

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp submit my-swift --profile h200:8 \
  --model Qwen/Qwen3.5-9B --train-data data/train.jsonl \
  -s tuner_type=lora -s lora_rank=16 -s lora_alpha=32
```

八个方法都认 `tuner_type`：`full` 训练全部参数，`lora` 只训练适配器。学习率跟着它走 —— LoRA 大约要
全参的 10\~100 倍，ms-swift 自己的默认值分别是 `1e-5` 和 `1e-4`。

其余一切不变，导出也一样。平台读的是这一趟**实际写出来**的东西：全参 checkpoint 直接登记，适配器
目录用 `swift export --merge_lora` 合回底座模型。没有 `-lora` 方法要挑，也没有格式会选错。

## 实验配置是逃生口

实验里的 `config.yaml` 承载这个方法没有暴露成参数的 ms-swift 标志，扁平书写：

```yaml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
truncation_strategy: delete
target_modules: [q_proj, k_proj, v_proj, o_proj]
```

如果某个标志本身*就是*这个方法的参数，或者是平台自己设定的（`model`、`dataset`、`val_dataset`、
`output_dir`、`logging_dir`、`add_version`、`report_to`），会被拒绝而不是被忽略 —— 请去设那个参数，
这样控制台显示的才是真正生效的值。

## 一个 GRPO trainer，多个已发表方法

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp submit my-swift --profile h200:8 \
  --model Qwen/Qwen3.5-9B --train-data data/prompts.jsonl \
  -s reward_funcs=accuracy \
  -s num_generations=8 \
  -s importance_sampling_level=sequence
```

`importance_sampling_level=sequence` 就是 GSPO。`epsilon_high` 设得比 `epsilon` 大就是 DAPO 的
clip-higher。`advantage_estimator` 能切到 RLOO 和 REINFORCE++。`scale_rewards=none` 是 Dr. GRPO 的
无偏形式。这些都不需要换一个方法。

偏好这一族也一样：`ms-swift/cpo` 设 `loss_type=simpo` 就是 SimPO，而 CPO 和 ORPO 都完全不加载参考
模型 —— 同样模型规模下显存大约是 DPO 的一半。

rollout 引擎 vLLM 跑在训练卡上（`vllm_mode=colocate`），所以 `vllm_gpu_memory_utilization` 要和训练
状态共享同一张卡的显存，OOM 时先动它 —— 在动 batch size 之前。

## Megatron 后端

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp new my-mcore --method ms-swift/megatron-sft
tp submit my-mcore --profile h200:8 \
  --model Qwen/Qwen3-30B-A3B --train-data data/train.jsonl \
  -s expert_model_parallel_size=8 -s tensor_model_parallel_size=2
```

用张量/流水线/上下文/专家并行代替 ZeRO 切分 —— 这正是大规模 MoE 能训得起来的原因。它是单独一张镜像
（`Dockerfile.msswift-megatron`）和单独一个设置（`TUNEPLANE_IMAGE_MS_SWIFT_MEGATRON`），因为
Megatron-core 与 TransformerEngine 不在另一张里。模型在 Hugging Face 后端放得下就用那个：模型覆盖
一样，栈更简单。

`megatron-grpo` 和 `megatron-gkd` 走 ms-swift 自己的 Ray 流水线，这是 ms-swift 唯一用到 Ray 的地方。
placement 由平台编译 —— 每个 worker 组拿几张卡、横跨几台机器、哪些组共卡 —— 来自 profile 与角色到
资源池的映射。`config.yaml` 里不需要也不允许写卡的事，写了会被拒绝。把 `rollout`（或 `teacher`）角色
映射到独立资源池就能给它独立的卡；映射到同一个池，这些组会被声明为共卡。

Megatron-core 自己的参数（`save_interval`、`eval_interval`、`log_interval`）放在实验的 `config.yaml`
里，而不是作为超参 —— 它们属于上游 Megatron 的参数面，不是 ms-swift 的，目录不会装作拥有它们。

## 确认成功

`tp job logs` 会先打出数据预处理，然后是第一个优化步。Charts 页开始出现 `train/loss` 和
`train/token_accuracy`（GRPO 则是 `train/reward` 和 `train/reward_zero_std_frac`）。盯住最后这个：
一组回复全部得分相同，优势就是 0，也就没有梯度，而 loss 曲线看上去照样在动。

ms-swift 的运行不上报验证样本 —— 它在 trainer 见到数据之前就完成了编码，共用的样本观察器拿不到文本。
指标序列不受影响。

## 下一步

[方法目录](/zh-Hans/guides/methods) ·
[自定义镜像](/zh-Hans/guides/custom-images)讲部署方怎么发布一个 ·
[流水线](/zh-Hans/guides/pipelines)