使用 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 入口点。
要求
- 集群中已安装 Alauda AI Workbench。
- 具有互联网访问权限(或内部 PyPI 镜像)的 workbench、至少一个 NVIDIA GPU,以及用于保存检查点的持久化存储。
- HuggingFace 模型名称或本地路径。
- JSONL 格式的训练数据(见下文)。
数据格式
每行表示一个对话:
角色: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 中,然后逐单元执行:
安装并配置:
在预构建的 traininghub0.1-cu126-amd64:v0.1.0 runtime 镜像中,请在全新的 venv
中安装 training-hub — pip install --user training-hub 会将 transformers
升级到与捆绑的 peft 不兼容的版本:
编辑参数单元格:
随附的模型预设涵盖 Qwen 2.5 7B、Llama 3.1 8B、Phi 4 Mini,以及通用 7B / 小型模型。
运行所有单元格。最后的训练单元格会调用:
每个 epoch 的检查点会保存到 ckpt_output_dir(由 checkpoint_at_epoch 控制)。
关键参数
通用参数(SFT 和 OSFT):
仅 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 位参数:
QLoRA 专用参数:
输出是一个 LoRA adapter,而不是完整的检查点。要进行服务部署,请使用 peft 加载基础模型和 adapter,或使用 merge_and_unload() 合并一次并导出独立模型。
通过 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 窗口中。
CPT 数据是原始文本,不是聊天轮次——document_column_name 下每行放置一个文档:
CPT 专用参数:
CPT 会更新所有权重并写入完整检查点。这可能导致通用能力灾难性遗忘——可以通过使用较低的学习率、混入一些通用领域文本,以及后续执行 SFT/OSFT 训练来缓解(将 model_path 指向 CPT 检查点)。如果首要考虑是避免遗忘,请优先使用 OSFT。
NPU:全参数持续预训练也可以通过 Huawei Ascend 的
MindSpeed-LLM 运行时(pretrain_gpt.py)运行。请参阅
在 Ascend NPU 上进行微调和预训练 以及
qwen25_pretrain_verify.ipynb 配方。
多节点
在每个节点上使用相同的 rdzv_id / rdzv_endpoint,并使用不同的 node_rank 运行 notebook(或脚本):
所有节点都必须能够在训练开始前访问 rdzv_endpoint。