使用 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 支持。
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 入口点。
要求
- 集群中已安装 Alauda AI Workbench。
- 一个带有互联网访问权限(或内部 PyPI 镜像)、至少一张 NVIDIA GPU,以及用于 checkpoint 的持久化存储的 workbench。
- HuggingFace 模型名称或本地路径。
- JSONL 格式的训练数据(见下文)。
数据格式
每一行都是一个会话:
角色: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 执行:
安装并配置:
在预构建的 traininghub0.1-cu126-amd64:v0.1.0 runtime image 上,请在一个全新的 venv 中安装 training-hub —— pip install --user training-hub 会将 transformers
升级到与内置 peft 不兼容的版本:
编辑参数单元格:
内置的 model preset 覆盖 Qwen 2.5 7B、Llama 3.1 8B、Phi 4 Mini,以及通用的 7B / 小型模型。
运行所有 cell。最终的训练 cell 会调用:
每个 epoch 的 checkpoint 会保存到 ckpt_output_dir 中(由 checkpoint_at_epoch 控制)。
关键参数
通用(SFT 和 OSFT):
仅 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 配置项:
QLoRA 专用参数:
输出的是一个 LoRA adapter,而不是完整 checkpoint。用于服务时,可通过 peft 加载基础模型 + adapter,或者使用 merge_and_unload() 一次性合并并导出独立模型。
通过 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 窗口中。
CPT 数据是原始文本,不是 chat 对话轮次——在 document_column_name 下每行一个文档:
CPT 专用参数:
CPT 会更新所有权重并写出完整 checkpoint。它可能导致通用能力的灾难性遗忘——可通过降低学习率、混入部分通用领域文本,以及在之后再执行一轮 SFT/OSFT(将 model_path 指向 CPT checkpoint)来缓解。如果你主要担心遗忘问题,建议优先选择 OSFT。
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:
训练开始前,所有节点都需要能够访问 rdzv_endpoint。