transformers

Hugging Face Transformers

补充说明

Transformers 是 Hugging Face 的模型库，统一加载和运行文本、视觉、音频和多模态模型。提供 pipeline 高层接口、AutoModel 底层接口和命令行工具。

AI 环境排障常需要确认模型类、tokenizer、dtype、device map 和注意力实现是否正确。

常用示例

安装：

pip install transformers torch

快速推理：

from transformers import pipeline

pipe = pipeline("text-generation", model="Qwen/Qwen2.5-0.5B-Instruct")
print(pipe("你好", max_new_tokens=64))

加载模型和 tokenizer：

from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Instruct")
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-7B-Instruct",
    torch_dtype="bfloat16",
    device_map="auto",
)

命令行查看模型信息：

transformers-cli env
huggingface-cli scan-cache

保存和加载本地模型：

model.save_pretrained("./local-model")
tokenizer.save_pretrained("./local-model")

易错点与排错

• trust_remote_code=True 被滥用，加载不可信模型有代码执行风险。
• 模型权重是 safetensors，但本地缺少 tokenizer 或 config，加载失败。
• device_map="auto" 把模型分散到多卡，推理变慢或 OOM。
• dtype 使用 fp16 导致数值溢出，优先 bf16（硬件支持时）。
• Transformers 版本与模型架构不兼容，报 Unrecognized model。
• 离线环境没有设置 HF_HUB_OFFLINE=1，启动时卡在联网检查。
• tokenizer 的 padding side 与生成任务不匹配，输出异常。
• 多进程同时下载同一模型，缓存目录锁冲突。