Swift框架

Swift框架

规则：

• 命令行传入list使用空格隔开
• 命令行传入dict使用json

一般在 Linux shell 里推荐外层用单引号，里面用双引号

基本参数

tuner_type：决定哪种微调方式，默认为lora

参数值	常用程度	含义	实际建议
lora	最常用	LoRA 微调	默认推荐，适合大多数 SFT、分类、指令微调、领域适配
full	常用，但贵	全参数微调	数据量大、算力足、想最大幅度改模型时用
lora_llm	SWIFT 多模态场景常用	只对 LLM 部分做 LoRA	多模态模型常见，例如 VLM

adapters：用来指定 adapter 的路径列表，常用于推理或部署，默认为[]

--model    = 底座模型 / 完整模型
--adapters = LoRA 等增量权重

训练结束后，SWIFT 会在输出目录里保存 LoRA/adapter 增量权重，在推理时需要带上这个增量权重，因为 LoRA 微调后，并不是得到一个完整的新模型

模型参数

model：核心参数，指定 模型 id 或 本地模型路径

--model Qwen/Qwen2.5-7B-Instruct

指向一个完整模型目录，里面通常要有：

config.json    # 描述模型架构和关键超参数
tokenizer 文件  # 把文本变成 token id，不能混用
model.safetensors # 模型权重，模型太大会分片存储权重
generation_config.json # 默认生成参数

用户输入文本
    ↓
tokenizer 编码
    ↓
input_ids
    ↓
config.json 决定模型结构
    ↓
model.safetensors 加载权重
    ↓
模型 forward / generate
    ↓
generation_config.json 控制生成方式
    ↓
tokenizer 解码
    ↓
输出文本

不能把 LoRA 输出目录直接当成 --model，除非已经把 LoRA merge 回完整模型

task_type：决定任务类型

默认 causal_lm，也就是普通大语言模型生成任务

task_type	用途	常见程度
causal_lm	普通 SFT、聊天模型微调	最常见
seq_cls	分类任务	需要额外参数
embedding	向量模型训练	特定任务
reranker	重排序模型训练	特定任务
generative_reranker	生成式 reranker	特定任务

torch_dtype：控制模型权重的数据类型

参数	含义	建议
bfloat16	BF16 精度	A100/H100/4090 等新卡常用，推荐
float16	FP16 精度	老一些的 GPU 常用
float32	FP32 精度	显存占用大，训练大模型少用

类型	符号位	指数位 exponent	尾数位 mantissa	核心特点
float16 / FP16	1	5	10	精度比 BF16 高，但数值范围小
bfloat16 / BF16	1	8	7	数值范围接近 FP32，但精度比 FP16 低

举个例子讲一下指数位的计算：

对于FP16，指数位为5，那么一共能表示32个指数，E的取值为0~31，31留给 inf 和 NaN，可用30个

最小正规指数为-14，最大正规指数为15，表示范围就覆盖$2^{-14}\sim 2^{15}$

指数位控制数量级，尾数控制有效数字位数，默认为None，从config.json文件中读取

数据参数

dataset：训练数据来源

最常用

--dataset swift/self-cognition

https://www.modelscope.cn/datasets/swift/self-cognition

--model_name：替换掉数据集中的{{NAME}}通配符

--model_author：替换掉数据集中的{{AUTHOR}}通配符

多个数据集之间用空格隔开

val_dataset：如果已有单独的验证集，就直接输入，默认为[]

split_dataset_ratio：从训练集中切一部分当验证集

load_from_cache_file：是否读取数据缓存，默认是 False；实际运行时建议设为 True，debug 阶段设为 False

模板参数

template：对话模版类型，指定模型使用哪种对话模板，默认是 None，SWIFT 会根据模型自动选择对应模板

system：全局 system prompt

max_length：单条样本最大 token 长度

max_pixels：多模态图片最大像素数

生成参数

max_new_tokens：最多生成多少新 token，默认 None，不显式限制

temperature：控制随机性，可以设置 --temperature 0 来取消推理随机性

top_k：在概率最高的 k 个 token 里选，实际使用中，top_p 比 top_k 更常调

top_p：核采样，保留累计概率达到 p 的候选 token

stream：是否流式输出，默认是 None：交互式界面中为 True，数据集批量推理中为 False

训练参数

output_dir：训练结果位置，保存 checkpoint、日志、配置文件、训练参数等

gradient_accumulation_steps：梯度累加，用多个小 batch 累加梯度，再更新一次参数，该参数可以显著降低显存占用，但降低训练速度，默认None

learning_rate：官方默认值，全参数训练默认 1e-5，LoRA 等 tuner 训练默认 1e-4

训练方式	常用学习率
LoRA / QLoRA	1e-4、2e-4
全参数微调	1e-5、5e-6
小数据集精调	5e-5、1e-5

lr_scheduler_type：学习率调度器

默认是 cosine，常见选择包括 linear、constant、cosine_with_min_lr，普通训练不需要改

调度器	含义	适合
cosine	学习率余弦下降	默认推荐
constant	学习率不降	短训可试
cosine_with_min_lr	余弦下降但保留最低学习率	不想 lr 降到太低

num_train_epochs：训练几个 epoch，官方默认值是 3

save_strategy：可选no、steps、epoch，默认是 steps；save_steps 默认是 500

save_total_limit：最多保留几个 checkpoint，默认为None，但是建议设为2

lora_rank：决定 LoRA 增量矩阵的秩，越大可训练参数越多，表达能力越强，默认为8

lora_alpha：LoRA 增量的缩放强度
$$
\text{scaling} = \frac{\text{lora_alpha}}{\text{lora_rank}}
$$

lora_rank	lora_alpha	alpha / rank	直观含义
8	32	4	SWIFT 默认，更新强度较明显
16	32	2	参数更多，但缩放强度较小
16	64	4	保持和默认相同缩放比例
32	64	2	容量更大，更新相对温和
64	128	2	大容量 LoRA，常用于更复杂任务

推理参数

infer_backend：推理加速后端，默认是 transformers

场景	推荐
本地调试、最稳	transformers
高吞吐批量推理	vllm

企业部署一般就是vllm

简单小实验

自我认知微调

CUDA_VISIBLE_DEVICES=0 \
swift sft \
  --model Qwen/Qwen3-4B-Instruct-2507 \
  --tuner_type lora \
  --dataset 'swift/self-cognition#500' \
  --torch_dtype bfloat16 \
  --num_train_epochs 1 \
  --per_device_train_batch_size 1 \
  --per_device_eval_batch_size 1 \
  --learning_rate 1e-4 \
  --lora_rank 8 \
  --lora_alpha 32 \
  --target_modules all-linear \
  --gradient_accumulation_steps 16 \
  --eval_steps 50 \
  --save_steps 50 \
  --save_total_limit 2 \
  --warmup_ratio 0.05 \
  --logging_steps 5 \
  --max_length 2048 \
  --dataloader_num_workers 4 \
  --model_name '小思' \
  --model_author 'Fallinty' \
  --output_dir output

CUDA_VISIBLE_DEVICES=0 \
swift infer \
    --adapters output/v1-20260706-113104/checkpoint-32 \
    --stream true \
    --temperature 0 \
    --max_new_tokens 2048