使用 Training Hub 对 LLM 进行微调

training_hub 是一个 Python 库,它将多个 LLM 后训练算法——监督微调(SFT)、正交子空间微调(OSFT)、LoRA / QLoRA,以及持续预训练(CPT)——封装在单一函数调用(sft(...)、osft(...)、lora_sft(...))之下,以统一方式处理单 GPU、多 GPU 和多节点训练。

  • 自动内存管理 — max_tokens_per_gpu 用于限制 GPU 内存,并自动计算 micro-batch 大小和梯度累积,以满足你的目标 effective_batch_size。
  • OSFT 实现了 Nayak et al., 2025 (arXiv:2504 .07097) —— 将权重更新限制在正交子空间中,可在无需回放数据的情况下避免灾难性遗忘。
  • QLoRA 以 4-bit 方式加载冻结的基础模型,并仅训练 LoRA adapter,使大模型能够适配单个小型 GPU 切片(Dettmers et al., 2023, arXiv:2305 .14314)。
  • 持续预训练(CPT) 在原始文本语料上执行 next-token prediction,在进行指令微调之前注入领域知识。
  • 内置 checkpoint、实验跟踪以及 Liger kernel 支持。
Design context

training_hub 是 RHOAI / Open Data Hub 用于通过单一 API 暴露后训练 算法的上游库,而 Alauda AI 在 Kubeflow Trainer v2 (TrainJob / ClusterTrainingRuntime)上运行相同代码。算法(此库) 与分布式运行时(Kubeflow Trainer)之间的划分遵循 Open Data Hub 架构决策记录 (参见 distributed-workload 和 workbenches 组件文档)——因此,无论你是在 workbench notebook 中运行,还是作为集群 TrainJob 运行,这里的示例都能 无缝映射到相同的 sft / osft / lora_sft 入口点。

方面SFTOSFTQLoRACPT
使用场景初始指令微调已微调模型的持续领域适配内存高效适配注入领域知识
数据Chat JSONLChat JSONLChat JSONL原始文本
可训练权重全部(bf16)正交子空间LoRA adapter(基础模型为 4-bit)全部(bf16)
关键参数标准超参数unfreeze_rank_ratio(0.0–1.0)load_in_4bit + lora_ris_pretraining + block_size
入口点sft(...)osft(...)lora_sft(...)sft(..., is_pretraining=True)
后端instructlab-trainingmini-trainerunsloth / peft + bitsandbytesinstructlab-training

要求

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

数据格式

每一行都是一个会话:

{"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。Mask 规则:

  • SFT(默认) — 只有 assistant 内容会参与 loss。为某个样本添加 "unmask": true 可将所有非 system 内容纳入训练。
  • OSFT — 由 unmask_messages 控制(默认 False)。

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

运行示例 notebook

下载到你的 workbench 中并逐个 cell 执行:

Notebook算法下载
SFT comprehensive tutorialSFTsft-comprehensive-tutorial.ipynb
OSFT comprehensive tutorialOSFTosft-comprehensive-tutorial.ipynb
QLoRA comprehensive tutorialQLoRAqlora-comprehensive-tutorial.ipynb
CPT comprehensive tutorialCPTcpt-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 runtime image 上,请在一个全新的 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

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

运行所有 cell。最终的训练 cell 会调用:

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 的 checkpoint 会保存到 ckpt_output_dir 中(由 checkpoint_at_epoch 控制)。

关键参数

通用(SFT 和 OSFT):

参数必需说明
model_path是HF 名称或本地路径
data_path是JSONL 训练数据
ckpt_output_dir是checkpoint 目录
effective_batch_size是全局有效 batch 大小
max_tokens_per_gpu是每个 GPU 的令牌预算;自动计算 micro-batch 大小
max_seq_len是最大序列长度
learning_rate是优化器学习率
num_epochs否默认 1
lr_scheduler, warmup_steps否学习率调度
use_liger否Liger kernels(OSFT 默认 True)
seed否默认 42
data_output_dir否已处理数据缓存;RAM-disk 使用 "/dev/shm"
use_processed_dataset否如果数据已包含 input_ids / labels,则跳过分词
checkpoint_at_epoch, save_final_checkpoint否默认 True
nproc_per_node, nnodes, node_rank否分布式拓扑
rdzv_id, rdzv_endpoint否多节点 rendezvous

仅 OSFT:

参数必需说明
unfreeze_rank_ratio是每个权重矩阵中可更新部分的比例(0.0–1.0)。越低,保留越多。
unmask_messages否如果为 True,则在所有非 system 内容上训练
target_patterns否用于将 OSFT 限制到特定层的子字符串模式

QLoRA(4-bit LoRA)

QLoRA 将基础模型以 4-bit NormalFloat(NF4) 精度冻结,并仅在其上训练小型 LoRA adapter 矩阵。原本需要约 ~60 GiB 才能完成全量 SFT 的 7B 模型,现在可以放到单个 16–24 GiB GPU(或 HAMI vGPU 切片)上运行。只要你受到 GPU 内存限制,就应优先使用它;代价是会有轻微的量化质量损失以及略慢的 step 速度。

training_hub 通过 lora_sft(...) 暴露 QLoRA —— 即 LoRA 加上 bitsandbytes 的 4-bit 配置项:

from training_hub import lora_sft

result = lora_sft(
    model_path="Qwen/Qwen2.5-7B-Instruct",   # HF name or local path
    data_path="/path/to/training_data.jsonl", # same chat JSONL as SFT
    ckpt_output_dir="/path/to/checkpoints/qlora_run",
    # LoRA adapter
    lora_r=16, lora_alpha=32, lora_dropout=0.05,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],  # or "all-linear"
    # 4-bit quantization — this is what makes it QLoRA
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype="bfloat16",
    bnb_4bit_use_double_quant=True,
    # core training (LoRA tolerates higher LRs than full SFT)
    num_epochs=3, effective_batch_size=16, learning_rate=2e-4, max_seq_len=4096,
    nproc_per_node=1,
)

QLoRA 专用参数:

参数必需说明
load_in_4bit是(QLoRA 必需)以 4-bit 加载冻结的基础模型。不使用该项时,lora_sft 就是普通的(16-bit)LoRA。
bnb_4bit_quant_type否"nf4"(推荐)或 "fp4"
bnb_4bit_compute_dtype否反量化计算 dtype,例如 "bfloat16"
bnb_4bit_use_double_quant否对量化常数进行嵌套量化(进一步节省内存)
lora_r, lora_alpha, lora_dropout是LoRA adapter 的 rank / scaling / dropout
target_modules否要适配的模块(attention projection,或 "all-linear")
load_in_8bit否8-bit 基础模型(LoRA-8bit,不是 QLoRA)

输出的是一个 LoRA adapter,而不是完整 checkpoint。用于服务时,可通过 peft 加载基础模型 + adapter,或者使用 merge_and_unload() 一次性合并并导出独立模型。

NOTE

通过 bitsandbytes 实现的 4-bit QLoRA 需要具备 sm_75 或更新计算能力的 NVIDIA GPU (Turing / Ampere / Hopper)。traininghub0.1-cu126-amd64 runtime 已经内置 trl、peft 和 bitsandbytes。默认的 lora_sft 后端是 unsloth;如果需要完全 控制,也可以在同一 runtime image 上直接使用 peft + bitsandbytes。

NPU: bitsandbytes 4-bit 不支持华为昇腾。请在 llamafactory0.9-cann8.5-arm64 runtime 上使用 LoRA(不带 4-bit)(finetuning_type: lora)作为参数高效路径—— 参见 Fine-tune and Pretrain on Ascend NPU。

持续预训练(CPT)

持续预训练(CPT)保留原始的 next-token prediction 目标,但将其运行在你领域内的 原始文本语料上(医学、法律、代码、新语言等)。它注入的是知识和词汇——不同于 SFT/OSFT,后者通过 chat 数据教授行为。一个常见的流水线是 CPT → SFT → alignment。

training_hub 通过相同的 sft(...) 入口点并设置 is_pretraining=True 来运行 CPT: loss 会覆盖所有令牌(没有仅 assistant 的 masking),并且文档会被打包到固定大小的 block_size 窗口中。

from training_hub import sft

result = sft(
    model_path="Qwen/Qwen2.5-7B",             # a BASE checkpoint
    data_path="/path/to/corpus.jsonl",         # raw text, one document per line
    ckpt_output_dir="/path/to/checkpoints/cpt_run",
    # continued pre-training
    is_pretraining=True,
    block_size=4096,                           # packed context-window length
    document_column_name="text",               # JSONL field holding the raw text
    # core training — keep the LR low to limit forgetting
    num_epochs=1, effective_batch_size=128, learning_rate=5e-6,
    max_seq_len=4096, max_tokens_per_gpu=20000,
    nproc_per_node=8,
)

CPT 数据是原始文本,不是 chat 对话轮次——在 document_column_name 下每行一个文档:

{"text": "A paragraph or document of raw domain text ..."}
{"text": "Another document ..."}

CPT 专用参数:

参数必需说明
is_pretraining是切换到原始文本预训练(不进行 chat masking)
block_size否打包后的上下文窗口长度(例如 1024–4096)
document_column_name否保存原始文本的 JSONL 字段(默认 "text")

CPT 会更新所有权重并写出完整 checkpoint。它可能导致通用能力的灾难性遗忘——可通过降低学习率、混入部分通用领域文本,以及在之后再执行一轮 SFT/OSFT(将 model_path 指向 CPT checkpoint)来缓解。如果你主要担心遗忘问题,建议优先选择 OSFT。

NOTE

NPU: 全参数持续预训练也可通过 MindSpeed-LLM runtime(pretrain_gpt.py)在华为昇腾上运行。参见 Fine-tune and Pretrain on Ascend NPU 以及 qwen25_pretrain_verify.ipynb 示例。

多节点

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

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。