Transformers 安装与部署

二、安装与部署

1. 先装后端框架。transformers 本身只是模型定义，真正的张量运算由 PyTorch（或 TensorFlow）提供。先按官方选择器装好 PyTorch，再装 transformers，避免依赖被反向改写。
2. 装核心三件套。transformers、datasets、accelerate 是最常见的组合；要用 LoRA 再加 peft，要做量化再加对应后端。
3. 配好缓存与镜像。模型默认下载到用户目录下的缓存目录，系统盘小的机器要改到数据盘；网络受限时配置镜像端点或走离线模式。这一步是内网环境能否跑起来的关键。
4. 验证加载。用一个公开的小模型跑通「分词 → 前向 → 生成」三步，确认权重下载与算力后端都正常。
5. 服务化（可选）。单机演示可以用 pipeline；上生产建议换成专门的推理引擎（吞吐差一个量级），或至少用 FastAPI 起一个只加载一次模型的常驻服务，不要在请求里加载模型。

# 1) 后端（示例，实际 CUDA 标签以官方选择器为准）
pip install torch --index-url https://download.pytorch.org/whl/<CUDA_TAG>

# 2) 生态
pip install transformers datasets accelerate
# 需要微调适配器 / 量化时
pip install peft bitsandbytes

# 3) 缓存与镜像（Linux 写法，写进 ~/.bashrc 或容器环境变量）
export HF_HOME=/data/hf-cache              # 权重与数据集缓存根目录
export HF_ENDPOINT=https://hf-mirror.com   # 网络受限时的镜像端点，按需设置

# 4) 验证
python - <<'PY'
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
name = "<一个公开的小模型>"
tok = AutoTokenizer.from_pretrained(name)
model = AutoModelForCausalLM.from_pretrained(
    name,
    torch_dtype=torch.bfloat16,
    device_map="auto",          # 多卡 / 显存不足时自动切分
)
ids = tok("人工智能的未来是", return_tensors="pt").to(model.device)
out = model.generate(**ids, max_new_tokens=32, do_sample=False)
print(tok.decode(out[0], skip_special_tokens=True))
PY

依赖与环境要求

• Python：跟随官方支持矩阵，过旧的 Python 无法安装新版依赖。
• PyTorch：版本要和 transformers 的兼容范围对齐，跨大版本容易在自定义 kernel 上报错。
• 显存：加载一个模型所需显存大致由「参数量 × 每参数字节数」决定，半精度约每参数 2 字节，再加激活值、KV cache 与量化开销。规划容量时务必留出余量，不要按理论值卡死。
• 磁盘：权重文件动辄数 GB，多模型实验很快吃掉几百 GB；建议缓存目录单独挂盘。
• 网络：首次下载需要外网；内网部署要提前把权重同步到本地并设置离线环境变量。

常见报错与排查