使用 Training Hub 对 LLM 进行微调

training_hub 是一个 Python 库,通过单个函数调用(sft(...)、osft(...))封装了监督式微调(Supervised Fine-Tuning, SFT)和正交子空间微调(Orthogonal Subspace Fine-Tuning, OSFT),可统一处理单 GPU、多 GPU 和多节点训练。

  • 自动内存管理 — max_tokens_per_gpu 限制 GPU 内存占用,并自动计算 micro-batch size 和 gradient accumulation,以达到目标 effective_batch_size。
  • OSFT 实现了 Nayak et al., 2025 (arXiv:2504 .07097)——将权重更新限制在正交子空间中,可在无需回放数据的情况下防止灾难性遗忘。
  • 内置检查点保存、实验跟踪以及 Liger kernel 支持。
AspectSFTOSFT
Use case初始指令微调已微调模型的持续领域适配
Forgetting mitigation混合/回放数据算法式(正交子空间)
Key parameter标准超参数unfreeze_rank_ratio (0.0–1.0)
Backendinstructlab-trainingmini-trainer

Requirements

  • 你的集群中已安装 Alauda AI Workbench。
  • 一个具备互联网访问(或内部 PyPI 镜像)、至少一块 NVIDIA GPU,以及用于保存检查点的持久化存储的 workbench。
  • HuggingFace 模型名称或本地路径。
  • JSONL 格式的训练数据(见下文)。

Data format

每一行都是一段对话:

{"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is machine learning?"}, {"role": "assistant", "content": "Machine learning is a subset of AI..."}]}

角色:system、user、assistant、pretraining。掩码:

  • SFT(默认)——仅 assistant 内容参与 loss 计算。向样本中添加 "unmask": true 即可包含所有非 system 内容。
  • OSFT——由 unmask_messages 控制(默认 False)。

如果数据已包含 input_ids / labels,可通过 use_processed_dataset=True 支持预分词数据集。

运行示例 notebook

下载到你的 workbench 中并逐个单元格执行:

NotebookAlgorithmDownload
SFT comprehensive tutorialSFTsft-comprehensive-tutorial.ipynb
OSFT comprehensive tutorialOSFTosft-comprehensive-tutorial.ipynb

安装并配置:

pip install training-hub
# `training-hub` pulls a stray `attr` package that shadows `attrs.attr` and
# breaks `aiohttp`; uninstall it.
pip uninstall -y attr
NOTE

在预构建的 traininghub0.1-cu126-amd64:v0.1.0 运行时镜像上,请在全新的 venv 中安装 training-hub —— pip install --user training-hub 会将 transformers 升级到与内置 peft 不兼容的版本:

python -m venv /workspace/venv
source /workspace/venv/bin/activate
pip install training-hub
pip uninstall -y attr

编辑参数单元格:

model_path = "Qwen/Qwen2.5-7B-Instruct"        # HF name or local path
data_path       = "/path/to/your/training_data.jsonl"
ckpt_output_dir = "/path/to/checkpoints/my_experiment"
selected_distributed = "single_node_8gpu"      # or single_gpu_dev, multi_node_master, ...
# OSFT only:
unfreeze_rank_ratio = 0.25                      # 0.1–0.3 conservative, 0.3–0.5 balanced

内置模型预设覆盖 Qwen 2.5 7B、Llama 3.1 8B、Phi 4 Mini,以及通用 7B / 小型模型。

运行所有单元格。最后的训练单元格调用:

from training_hub import sft, osft

result = sft(model_path=model_path, data_path=data_path, ckpt_output_dir=ckpt_output_dir,
             effective_batch_size=128, max_tokens_per_gpu=20000, max_seq_len=16384,
             learning_rate=1e-5, num_epochs=3, nproc_per_node=8)

result = osft(model_path=model_path, data_path=data_path, ckpt_output_dir=ckpt_output_dir,
              unfreeze_rank_ratio=0.25,
              effective_batch_size=128, max_tokens_per_gpu=10000, max_seq_len=8192,
              learning_rate=5e-6, num_epochs=1, nproc_per_node=8)

每个 epoch 结束后,检查点会保存到 ckpt_output_dir 中(由 checkpoint_at_epoch 控制)。

Key parameters

通用(SFT 和 OSFT):

ParameterRequiredDescription
model_pathYesHF 名称或本地路径
data_pathYesJSONL 训练数据
ckpt_output_dirYes检查点目录
effective_batch_sizeYes全局有效批大小
max_tokens_per_gpuYes每个 GPU 的 token 预算;自动计算 micro-batch size
max_seq_lenYes最大序列长度
learning_rateYes优化器 LR
num_epochsNo默认 1
lr_scheduler, warmup_stepsNoLR 调度
use_ligerNoLiger kernels(OSFT 默认 True)
seedNo默认 42
data_output_dirNo处理后数据缓存;"/dev/shm" 用作 RAM-disk
use_processed_datasetNo如果数据已包含 input_ids / labels,则跳过分词
checkpoint_at_epoch, save_final_checkpointNo默认 True
nproc_per_node, nnodes, node_rankNo分布式拓扑
rdzv_id, rdzv_endpointNo多节点 rendezvous

仅 OSFT:

ParameterRequiredDescription
unfreeze_rank_ratioYes每个权重矩阵中可更新的比例(0.0–1.0)。值越低,保留越多。
unmask_messagesNo如果为 True,则在所有非 system 内容上训练
target_patternsNo用于将 OSFT 限定到特定层的子字符串模式

Multi-node

在每个节点上使用相同的 rdzv_id / rdzv_endpoint,并设置不同的 node_rank 运行 notebook(或脚本):

nproc_per_node = 8
nnodes         = 2
rdzv_id        = 42
rdzv_endpoint  = "10.0.0.1:29500"
node_rank      = 0   # 1 on the worker

训练开始前,所有节点都需要能够访问 rdzv_endpoint。