huggingface-transformers

项目地址： https://github.com/huggingface/transformers

官方文档： https://huggingface.co/docs/transformers/

许可证： Apache-2.0 最新版本： v5.19.0（PyPI 与 GitHub Releases 双核实，截至 2026-10）

概述

Transformers 是 Hugging Face 开源的模型定义框架，为文本、视觉、音频与多模态模型提供统一的推理与训练接口。它把「配置、模型、预处理器」抽象为三类基类，并只用 pipeline 与 Trainer 两个 API 覆盖推理与微调两条主线。模型权重托管在 Hugging Face Hub，from_pretrained() 可按名称或路径自动下载并缓存。

• AutoClass：AutoModel / AutoTokenizer / AutoModelForCausalLM / AutoModelForSequenceClassification / AutoModelForSeq2SeqLM 等按任务自动推断架构
• pipeline()：任务级推理封装，一行完成预处理、前向与后处理
• Trainer：PyTorch 训练/评估循环，配合 TrainingArguments 配置超参
• 显存管理：device_map="auto"、dtype="auto"、BitsAndBytesConfig 量化
• 生态：datasets、evaluate、accelerate、huggingface_hub、safetensors 协同工作

Transformers 是库（进程内推理/训练），与 Ollama 这类独立推理服务定位不同，详见「最佳实践」。

---

环境准备

要求 Python >= 3.10（v5 起）。

# 核心：Transformers 与 PyTorch
pip install -U transformers torch

# 常用配套：数据集、评估指标、多设备调度
pip install -U datasets evaluate accelerate

可选 GPU 加速：

# NVIDIA CUDA（按显卡驱动选择 cu 版本，示例）
pip install torch --index-url https://download.pytorch.org/whl/cu124

量化推理（8bit/4bit）需额外安装：

pip install -U bitsandbytes

验证安装：

python -X utf8 -c "import torch, transformers; print(transformers.__version__, torch.__version__, torch.cuda.is_available())"

登录 Hub（拉取受限模型或推送模型时需要，Token 从账号设置生成）：

hf auth login

---

核心 API/命令

pipeline() 快速推理

pipeline(task, model=..., device=..., dtype=...) 返回任务流水线；不传 model 时使用该任务的默认模型。

from transformers import pipeline

# 文本分类（情感分析别名 sentiment-analysis）
clf = pipeline("text-classification", model="distilbert/distilbert-base-uncased-finetuned-sst-2-english")
clf("This restaurant is awesome")
# [{'label': 'POSITIVE', 'score': 0.9998...}]

# 文本生成
gen = pipeline("text-generation", model="openai-community/gpt2")
gen("the secret to baking a good cake is", max_new_tokens=40, return_full_text=False)

# 特征抽取（嵌入）
feat = pipeline("feature-extraction", model="BAAI/bge-large-zh-v1.5")
feat("地理信息系统")