AB
AiBoss
Tutorials

StableLM

Tutorials

用 Transformers 加载 StableLM 3B 4E1T 完成文本生成与 Flash Attention 2 加速

StableLM 3B 4E1T 是 Stability AI 发布的多轮预训练解码器语言模型,可在 Transformers 中直接加载做文本生成。本文从环境准备讲起,给出基础推理、Flash Attention 2 加速、StableLmConfig 关键参数与 Zephyr 指令微调版本的使用方式,并整理常见坑。

StableLM 3B 4E1T 是 Stability AI 提出的多轮预训练语言模型系列中的第一个成员,采用仅解码器(decoder-only)的 Transformer 架构,在约 1 万亿 token 的英文与代码数据上训练了四个 epoch。它本身是一个基座模型,适合做续写、补全、下游微调的起点;同一系列还提供了指令微调版本 StableLM Zephyr 3B,可直接用于对话类应用。本文要解决的问题很具体:如何在 Transformers 中把 StableLM 3B 4E1T 加载起来、跑通一次文本生成,并在支持的硬件上启用 Flash Attention 2 提速。如果你只是想在本地或单卡环境里验证这个模型能不能用、该怎么传参、配置项各管什么,这篇教程覆盖的就是这些内容。相关工具页可参考 StableLM。

适合的读者:已经熟悉 Python 与 PyTorch 基本用法、装过 Transformers、想快速把 StableLM 跑起来的人;以及需要了解 StableLmConfig 各字段含义、准备做微调或推理优化的人。本文不涉及训练细节与数据集构建。

准备工作

运行环境与依赖

StableLM 3B 4E1T 通过 Transformers 的 AutoModelForCausalLM 与 AutoTokenizer 加载,因此核心依赖只有 Transformers 与 PyTorch。建议使用较新的 Transformers 版本,因为该模型在 Transformers 中的支持是后续加入的,旧版本可能不认识 stablelm 这个模型类型。具体版本号请以官网当前信息为准。

pip install -U transformers torch

如果计划启用 Flash Attention 2,还需要额外安装 flash-attn,并且硬件必须兼容 Flash Attention 2。安装命令如下:

pip install -U flash-attn --no-build-isolation

注意 --no-build-isolation 这个参数:flash-attn 在安装时需要访问已安装的 PyTorch 来编译扩展,隔离构建环境会导致找不到 torch 而失败。

模型权重与显存

模型权重托管在 Hugging Face Hub 上,仓库名为 stabilityai/stablelm-3b-4e1t,指令微调版本为 StableLM Zephyr 3B。首次运行会自动下载权重,需要保证网络可达 Hub,或提前把权重缓存到本地。3B 参数量在默认精度下对显存有一定要求,代码中使用 device_map="auto" 让 accelerate 自动分配设备;如果显存不足,可以改用半精度加载(见下文 Flash Attention 2 部分,那里本来就要求半精度)。

账号与许可

下载公开权重通常不需要额外申请,但模型卡上会标注许可证与使用条款,商用前请自行核对。许可证类型与可用地区请以官网当前信息为准。

操作步骤

第一步:加载分词器与模型

StableLM 3B 4E1T 系列模型使用的分词器与 GPTNeoXTokenizerFast 相同,但不需要手动指定类名,直接用 AutoTokenizer 按仓库名加载即可,它会根据仓库中的配置选择正确的实现。

from transformers import AutoModelForCausalLM, AutoTokenizer, set_seed

set_seed(0)
tokenizer = AutoTokenizer.from_pretrained("stabilityai/stablelm-3b-4e1t")
model = AutoModelForCausalLM.from_pretrained(
    "stabilityai/stablelm-3b-4e1t",
    device_map="auto",
)

这里有两个细节值得说明。set_seed(0) 固定随机种子,保证采样结果可复现;device_map="auto" 让 accelerate 根据可用显存自动把各层放到合适的设备上,单卡时就是整模型放 GPU,多卡时会做切分。

第二步:构造输入并生成

把提示文本编码成 PyTorch 张量,移动到模型所在设备,然后调用 generate。注意 model_inputs 必须 .to(model.device),否则在模型被切分到多设备时会报设备不一致的错误。

model_inputs = tokenizer(
    "The weather is always wonderful in",
    return_tensors="pt",
).to(model.device)

generated_ids = model.generate(
    **model_inputs,
    max_length=32,
    do_sample=True,
)

responses = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)
print(responses)

关键参数说明:

  • max_length=32:生成序列的总长度上限(含输入 token),不是新增 token 数。想要更长输出就调大这个值,但不要超过模型的最大位置编码长度。
  • do_sample=True:开启采样而非贪心解码。开启后输出有随机性,配合 set_seed 才能复现。
  • skip_special_tokens=True:解码时跳过特殊 token,避免输出里混入控制符号。

输出是一个字符串列表,长度等于批大小。示例提示下模型会续写出关于某个旅行目的地的段落,这是基座模型的正常行为——它只做续写,不保证回答你的问题。

第三步:启用 Flash Attention 2

在硬件兼容的前提下,把注意力实现切换为 Flash Attention 2 可以降低显存占用并提升吞吐。做法是在 from_pretrained 中传入 attn_implementation="flash_attention_2",同时必须以半精度加载模型,例如 torch.bfloat16。这一点是硬性要求,用全精度加载再开 Flash Attention 2 会报错。

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, set_seed

set_seed(0)
tokenizer = AutoTokenizer.from_pretrained("stabilityai/stablelm-3b-4e1t")
model = AutoModelForCausalLM.from_pretrained(
    "stabilityai/stablelm-3b-4e1t",
    attn_implementation="flash_attention_2",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

model_inputs = tokenizer(
    "The weather is always wonderful in",
    return_tensors="pt",
).to(model.device)

generated_ids = model.generate(**model_inputs, max_length=32, do_sample=True)
responses = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)
print(responses)

如果运行时报出与 flash-attn 相关的导入或兼容性错误,先确认三件事:flash-attn 是否安装成功、GPU 架构是否在 Flash Attention 2 的支持范围内、模型是否确实以半精度加载。三者缺一都会失败。

第四步:改用指令微调版本做对话

基座模型不擅长遵循指令。如果目标是聊天式交互,应加载 StableLM Zephyr 3B 这个指令微调版本,加载方式与上面一致,只把仓库名换成对应的指令微调权重。对话场景下还需要按该模型要求的对话模板组织输入,模板格式请以模型卡当前说明为准,不要自行拼接。

一个完整示例

下面是一个从加载到输出的完整脚本,包含半精度与 Flash Attention 2 开关,方便在不同硬件上切换。

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, set_seed

MODEL_ID = "stabilityai/stablelm-3b-4e1t"
USE_FLASH_ATTN = True  # 硬件不支持时改为 False

set_seed(0)

tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)

load_kwargs = {"device_map": "auto"}
if USE_FLASH_ATTN:
    load_kwargs["attn_implementation"] = "flash_attention_2"
    load_kwargs["torch_dtype"] = torch.bfloat16

model = AutoModelForCausalLM.from_pretrained(MODEL_ID, **load_kwargs)

prompt = "The weather is always wonderful in"
model_inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

generated_ids = model.generate(
    **model_inputs,
    max_length=32,
    do_sample=True,
)

responses = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)
for i, text in enumerate(responses):
    print(f"[{i}] {text}")

把这段脚本保存为 run_stablelm.py 后直接执行即可。第一次运行会下载权重,耗时取决于网络;之后会命中本地缓存。若显存吃紧,先把 USE_FLASH_ATTN 设为 True 走半精度路径;若硬件不支持 Flash Attention 2,则设为 False,并考虑手动加上 torch_dtype=torch.bfloat16 以降低显存占用。

StableLmConfig 关键参数

理解配置字段有助于判断模型行为边界,也方便在微调或改结构时知道哪些值可以动。以下是 StableLmConfig 中与使用最相关的字段及其默认值。

参数默认值含义
vocab_size50304词表大小,决定 input_ids 可表示的 token 数量
hidden_size2560隐藏表示维度
intermediate_size6912MLP 层维度
num_hidden_layers32解码器层数
num_attention_heads32每层注意力头数
num_key_value_heads32KV 头数;等于头数时为 MHA,为 1 时为 MQA,其余为 GQA
hidden_actsilu解码器非线性激活函数
max_position_embeddings4096模型可用的最大序列长度
layer_norm_eps1e-05LayerNorm 的 epsilon
initializer_range0.02权重初始化截断正态分布的标准差
use_cacheTrue是否返回最后一层的 key/value 注意力缓存
tie_word_embeddingsFalse是否共享输入输出词嵌入
use_qkv_biasFalse是否给 query/key/value 加偏置
qk_layernormFalse是否在注意力中对 query/key 做归一化
use_parallel_residualFalse是否使用并行残差结构
hidden_dropout0.0隐藏层 dropout 比例
attention_dropout0.0注意力 dropout 比例
bos_token_id0序列起始 token id
eos_token_id0序列结束 token id
pad_token_idNone填充 token id,批处理时需要关注

关于 num_key_value_heads:当它等于 num_attention_heads 时使用多头注意力(MHA);等于 1 时使用多查询注意力(MQA);介于两者之间则使用分组查询注意力(GQA)。把多头检查点转换为 GQA 检查点时,每个组的 key/value 头由该组内所有原始头做均值池化得到。不指定该字段时默认取 num_attention_heads 的值。

关于 rope_parameters:这是一个字典,用于配置 RoPE 嵌入参数,必须包含 rope_theta,可选地包含用于缩放的参数——当你希望模型在超过 max_position_embeddings 的更长序列上工作时会用到缩放配置。

关于 use_cache:它只在 config.is_decoder=True 或模型本身是仅解码器生成模型时才有意义。生成任务中保持默认的 True 能显著减少重复计算。

架构上的几个特点

StableLM 3B 4E1T 的架构与 LLaMA 相似,但有三处明确差异,理解这些差异有助于排查加载与推理中的异常:

  • RoPE 只作用于 25% 的头部嵌入维度,而不是全部维度。
  • 使用 LayerNorm,而不是 RMSNorm。
  • QKV 偏置项是可选的,由 use_qkv_bias 控制,默认关闭。

此外,模型使用 SwiGLU 激活(对应 hidden_act="silu")。这些结构差异意味着不能把 LLaMA 的权重直接套进来,也不能假设两者的配置字段一一对应。

注意事项

  • Flash Attention 2 必须配半精度。 用 attn_implementation="flash_attention_2" 时若未指定 torch_dtype 为 torch.bfloat16 之类的半精度类型,会直接报错。这是最常见的失败原因。
  • 硬件兼容性先确认。 Flash Attention 2 对 GPU 架构有要求,不兼容的卡上安装或运行都会失败。不确定时先用默认注意力实现跑通,再尝试开启。
  • max_length 是总长度。 它包含输入 token,不是新增 token 数。提示较长时,留给生成的空间会被压缩,甚至可能不产生任何新 token。
  • 基座模型不做问答。 StableLM 3B 4E1T 是基座模型,输出是续写而非对指令的响应。需要对话行为请换用 StableLM Zephyr 3B,并按模型卡给出的对话模板组织输入。
  • 输入张量要放到模型设备上。 使用 device_map="auto" 时模型可能分布在多个设备,model_inputs 忘记 .to(model.device) 会触发设备不匹配错误。
  • 批处理注意 pad_token_id。 该字段默认为 None,做批量推理时需要显式设置填充 token,否则解码与生成可能出问题。
  • 可复现性依赖种子。 do_sample=True 时输出随机,只有配合 set_seed 才能复现同一结果;贪心解码则不需要。
  • 许可证、可用地区与版本信息会变化。 模型许可证、权重可用性、Transformers 支持版本等均以官网当前信息为准,本文不保证长期有效。