使用 Training Hub 微调 LLM

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

  • 自动内存管理 — max_tokens_per_gpu 限制 GPU 内存,并自动计算微批次大小和梯度累积步数,以达到目标 effective_batch_size。
  • OSFT 实现了 Nayak 等人,2025(arXiv:2504 .07097) — 将权重更新限制在正交子空间中,无需重放数据即可防止灾难性遗忘。
  • QLoRA 以 4-bit 加载冻结的基础模型,并仅训练 LoRA 适配器,使大型模型能够在单个小型 GPU 分片上运行(Dettmers 等人,2023,arXiv:2305 .14314)。
  • 持续预训练(CPT) 在原始文本语料库上执行下一个 token 预测,以便在指令微调之前注入领域知识。
  • 内置检查点、实验跟踪和 Liger kernel 支持。
设计背景

training_hub 是 RHOAI / Open Data Hub 用于通过单个 API 暴露后训练算法的上游库,Alauda AI Platform 则在 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 适配器(基础模型为 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 镜像)的 workbench、至少一个 NVIDIA GPU,以及用于保存检查点的持久化存储。
  • 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。掩码:

要从 PDF 或 Office 文件生成此 JSONL,请在 Workbench 中使用 Docling 进行转换,并使用 SDG Hub 生成合成问答 — 参见使用 Docling 和 SDG Hub 准备微调数据。

  • SFT(默认) — 只有 assistant 内容会参与损失计算。在样本中添加 "unmask": true,即可包含所有非系统内容。
  • OSFT — 由 unmask_messages 控制(默认为 False)。

通过 use_processed_dataset=True 支持包含 input_ids / labels 的预分词数据集。

运行示例 notebook

下载到 workbench 中,然后逐单元执行:

Notebook算法下载
SFT 综合教程SFTsft-comprehensive-tutorial.ipynb
OSFT 综合教程OSFTosft-comprehensive-tutorial.ipynb
QLoRA 综合教程QLoRAqlora-comprehensive-tutorial.ipynb
CPT 综合教程CPTcpt-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 镜像中,请在全新的 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 控制)。

关键参数

通用参数(SFT 和 OSFT):

参数必填描述
model_path是HF 名称或本地路径
data_path是JSONL 训练数据
ckpt_output_dir是检查点目录
effective_batch_size是全局有效批次大小
max_tokens_per_gpu是每个 GPU 的令牌预算;自动计算微批次大小
max_seq_len是最大序列长度
learning_rate是优化器学习率
num_epochs否默认值为 1
lr_scheduler、warmup_steps否学习率调度
use_liger否Liger kernels(OSFT 的默认值为 True)
seed否默认值为 42
data_output_dir否已处理数据缓存;使用内存磁盘时设置为 "/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,则对所有非系统内容进行训练
target_patterns否用于将 OSFT 限制到特定层的子字符串模式

QLoRA(4 位 LoRA)

QLoRA 将基础模型冻结在 4 位 NormalFloat (NF4) 精度下,只在其上训练小型 LoRA adapter 矩阵。一个完整 SFT 需要约 60 GiB 的 7B 模型,现在可以放入单张 16–24 GiB GPU(或 HAMI 虚拟 GPU切片)中。只要 GPU 内存成为瓶颈,就可以使用 QLoRA;代价是量化会造成轻微的质量差距,且训练步骤会略慢。

training_hub 通过 lora_sft(...) 提供 QLoRA——LoRA 加上 bitsandbytes 的 4 位参数:

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 位精度加载冻结的基础模型。不设置时,lora_sft 为普通(16 位)LoRA。
bnb_4bit_quant_type否"nf4"(推荐)或 "fp4"
bnb_4bit_compute_dtype否反量化计算数据类型,例如 "bfloat16"
bnb_4bit_use_double_quant否对量化常量进行嵌套量化(可进一步节省内存)
lora_r、lora_alpha、lora_dropout是LoRA adapter 的秩 / 缩放 / dropout
target_modules否要适配的模块(注意力投影,或 "all-linear")
load_in_8bit否8 位基础模型(LoRA-8bit,而非 QLoRA)

输出是一个 LoRA adapter,而不是完整的检查点。要进行服务部署,请使用 peft 加载基础模型和 adapter,或使用 merge_and_unload() 合并一次并导出独立模型。

NOTE

通过 bitsandbytes 使用 4 位 QLoRA 需要计算能力为 sm_75 或更高(Turing / Ampere / Hopper)的 NVIDIA GPU。traininghub0.1-cu126-amd64 运行时已内置 trl、peft 和 bitsandbytes。默认的 lora_sft 后端为 unsloth;如需完全掌控,也可以在同一运行时镜像上直接驱动 peft + bitsandbytes。

NPU:华为 Ascend 不支持 bitsandbytes 4 位量化。请在 llamafactory0.9-cann8.5-arm64 运行时(finetuning_type: lora)上使用 LoRA(不使用 4 位量化)作为参数高效训练方案,参见 在 Ascend NPU 上进行微调和预训练。

持续预训练(CPT)

持续预训练(CPT)保留原有的下一个令牌预测目标,但会在来自你所在领域的原始文本语料库(医疗、法律、代码、新语言等)上运行。它注入的是知识和词汇——不同于 SFT/OSFT,后者通过聊天数据教授行为。常见的流程是 CPT → SFT → 对齐。

training_hub 通过相同的 sft(...) 入口并配合 is_pretraining=True 运行 CPT: 损失涵盖所有令牌(不进行仅 assistant 掩码),文档会被打包到固定大小的 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 数据是原始文本,不是聊天轮次——document_column_name 下每行放置一个文档:

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

CPT 专用参数:

参数必填描述
is_pretraining是切换到原始文本预训练(不进行聊天掩码)
block_size否打包的上下文窗口长度(例如 1024–4096)
document_column_name否保存原始文本的 JSONL 字段(默认为 "text")

CPT 会更新所有权重并写入完整检查点。这可能导致通用能力灾难性遗忘——可以通过使用较低的学习率、混入一些通用领域文本,以及后续执行 SFT/OSFT 训练来缓解(将 model_path 指向 CPT 检查点)。如果首要考虑是避免遗忘,请优先使用 OSFT。

NOTE

NPU:全参数持续预训练也可以通过 Huawei Ascend 的 MindSpeed-LLM 运行时(pretrain_gpt.py)运行。请参阅 在 Ascend NPU 上进行微调和预训练 以及 qwen25_pretrain_verify.ipynb 配方。

多节点

在每个节点上使用相同的 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。