微调 SDK 教程
1. 功能概览
潞晨云微调 SDK 旨在为开发者提供灵活、高效的大模型微调体验。该 SDK 基于 Thinking Machines Lab 开源的 Tinker 项目（Apache License 2.0）进行开发。我们感谢开源社区的贡献，并在此基础上针对潞晨云的云基础设施进行了深度定制。通过将繁重的计算负载卸载至云端高性能集群（HPC），微调 SDK 在保障本地开发灵活性的同时，实现了高效的微调流程。
核心优势：
- 本地逻辑，云端执行：您可以在本地编写训练循环、调试数据处理逻辑，而梯度计算与参数更新则在远程服务器上高效完成。
- 细粒度控制：支持 forward、backward 和 optim_step 等原子级操作，让您像编写 PyTorch 原生代码一样控制训练流程。
- 开箱即用：内置对主流模型（如 Qwen 系列）和 LoRA 微调技术的完整支持。
注：我们目前主要支持的是大模型的 Supervised Fine-Tuning，会在后续的开发中陆续支持强化学习（RL）对应的 function，如 sample 等。
2. 准备工作
在开始之前，请确保您已完成环境配置及鉴权设置，具体操作请参考以下步骤：
2.1 获取 API 密钥
为了建立与高性能计算集群的安全连接，您需要获取专属的 API Key：
- 登录潞晨云控制台。
- 点击右上角头像进入 账户信息 页面。
- 选择 API 密钥 选项卡，点击 创建 API 密钥 生成密钥。
- 注意：请妥善保管 API Key ，切勿在公开代码库中泄露。
2.2 安装 SDK
您需要安装基础 SDK 及配套工具。目前支持通过源码或 pip 安装：
# 克隆仓库并安装
git clone https://github.com/hpcaitech/HPC-AI-SDK
# Local install
pip install -e .
3. Quick Start：构建您的第一个微调任务
本教程将演示如何在潞晨云上使用微调 SDK，基于 LoRA 技术对 Qwen3-8B 模型进行监督微调（SFT）。
步骤 1：初始化客户端
首先，配置连接端点并初始化服务客户端。
请注意：Base URL 可公开，是连接潞晨云机器的 URL；API KEY 不可公开，每个用户有单独的 API KEY，用于校验。
import time
import hpcai
from hpcai import types
import wandb
from pathlib import Path
import datasets
from datasets import concatenate_datasets
from hpcai.cookbook import renderers
from hpcai.cookbook.data import conversation_to_datum
from hpcai import checkpoint_utils
BASE_URL = "cloud.luchentech.com/finetunesdk" # 连接潞晨云机器的 URL
API_KEY = "Your_API_Key_Here"# 实例化服务客户端
service_client = hpcai.ServiceClient(base_url=BASE_URL, api_key=API_KEY)
步骤 2：创建训练实例
定义模型参数并创建远程训练实例。潞晨云 SDK 支持通过简单的配置开启 LoRA 微调。
MODEL_NAME = 'Qwen/Qwen3-8B'
LORA_RANK = 32# 创建 LoRA 训练客户端，这一步会在云端初始化模型资源
training_client = service_client.create_lora_training_client(
base_model=MODEL_NAME,
rank=LORA_RANK,
)
print(f"Training session started with Model ID: {training_client.model_id}")
步骤 3：数据准备与处理
利用 SDK 提供的 Tokenizer 处理数据集。本例使用 "Knights and Knaves" 数据集。
import datasets
from datasets import concatenate_datasets
from hpcai.cookbook import renderers
from hpcai.cookbook.data import conversation_to_datum
# 获取与远程模型匹配的 Tokenizer
tokenizer = training_client.get_tokenizer()
# 加载并预处理数据
dataset = datasets.load_dataset("K-and-K/knights-and-knaves", "train")
dataset = concatenate_datasets([dataset[k] for k in dataset.keys()]).shuffle(seed=42)
# 格式化数据结构
dataset = dataset.map(
lambda example: {"messages": [
{"role": "user", "content": example["quiz"]},
{"role": "assistant", "content": example["solution_text"]},
]}
)
步骤 4：执行训练循环
这是 SDK 最具特色的部分。通过 forward_backward 和 optim_step 驱动云端训练, 您可以完全掌控训练的每一步（前向传播、反向传播、优化器更新）。
import time
import wandb
from hpcai import checkpoint_utils
# 超参数配置
BATCH_SIZE = 32
LEARNING_RATE = 1e-4
MAX_LENGTH = 1024
TRAIN_STEPS = 30
SAVE_EVERY = 30
LOG_PATH = "./tmp/tinker-examples/sl-loop"# 初始化 WandB 监控（可选）
wandb.init(project='qwen-3-8B-sft-demo')
target_steps = min(len(dataset) // BATCH_SIZE, TRAIN_STEPS)
renderer = renderers.get_renderer("role_colon", tokenizer)
print("Starting training loop...")
for step in range(target_steps):
start_time = time.time()
# 1. 检查点保存逻辑if step > 0 and step % SAVE_EVERY == 0:
paths = await checkpoint_utils.save_checkpoint_async(
training_client, name=f"step_{step}", log_path=LOG_PATH,
loop_state={"step": step}, kind="both"
)
print(f"Checkpoint saved: {paths}")
# 2. 准备批次数据
batch_start = step * BATCH_SIZE
batch_rows = dataset.select(range(batch_start, batch_start + BATCH_SIZE))
batch = [
conversation_to_datum(
row["messages"], renderer, MAX_LENGTH,
renderers.TrainOnWhat.ALL_ASSISTANT_MESSAGES
) for row in batch_rows
]
# 3. 远程执行前向与反向传播 (Forward + Backward)
fwd_bwd = training_client.forward_backward(batch, loss_fn="cross_entropy")
# 4. 学习率调度与优化器步进 (Optim Step)
lr = LEARNING_RATE * (1.0 - step / target_steps)
optim = training_client.optim_step(types.AdamParams(learning_rate=lr))
# 5. 获取结果与指标
result = fwd_bwd.result()
loss = result.metrics.get("loss:mean", 0.0)
# 打印进度
elapsed = time.time() - start_time
print(f"Step {step + 1}/{target_steps} | Loss: {loss:.4f} | LR: {lr:.2e} | Time: {elapsed:.2f}s")
wandb.log({'train_loss': loss}, step=step+1)
步骤 5：资源释放
训练完成后，请释放云端 GPU 资源。
# 释放模型资源
training_client.unload_model().result()
print("Model unloaded successfully.")