Transformers

环境与安装

要求 Python 3.10+ 与 PyTorch 2.6+。先建虚拟环境，别污染系统 Python：

bashpython -m venv .my-env
source .my-env/bin/activate
pip install "transformers[torch]"

用 uv 的话是 uv venv .my-env 加 uv pip install "transformers[torch]"。

想要 main 分支的最新改动（比如刚支持的新架构）就从源码装：

bashgit clone https://github.com/huggingface/transformers.git
cd transformers
pip install '.[torch]'

代价是不稳定，出问题直接去仓库开 issue。

pipeline 这一个 API 就够开始

pipeline 处理预处理并返回对应输出，换 task 和 model 就换模态，代码形状不变：

pythonfrom transformers import pipeline

pipe = pipeline(task="text-generation", model="Qwen/Qwen2.5-1.5B")
pipe("the secret to baking a really good cake is ")

语音识别：

pythonpipe = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
pipe("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")

图像分类：

pythonpipe = pipeline(task="image-classification", model="facebook/dinov2-small-imagenet1k-1-layer")
pipe("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")

第一次跑会下载权重并缓存，之后复用。磁盘不够会在这里卡住。

聊天：构造 chat 历史

和生成接口完全一样，只是输入变成对话列表：

pythonimport torch
from transformers import pipeline

chat = [
    {"role": "system", "content": "You are a sassy, wise-cracking robot."},
    {"role": "user", "content": "Hey, can you tell me any fun things to do in New York?"},
]
pipe = pipeline(task="text-generation", model="meta-llama/Meta-Llama-3-8B-Instruct",
                dtype=torch.bfloat16, device_map="auto")
response = pipe(chat, max_new_tokens=512)

不想写代码，命令行也行——前提是 transformers serve 已经在跑：

bashtransformers chat Qwen/Qwen2.5-0.5B-Instruct

官方说：这些情况别用它

这一节比功能列表更重要，原文两条：

1. 它不是神经网络的模块化积木盒。 模型文件故意不做额外抽象，为的是研究者能直接改单个模型，不用在抽象层里绕。
2. 训练 API 是围绕它自己的 PyTorch 模型优化的。 你要写通用机器学习循环，用 Accelerate。

补一条实践结论：Transformers 负责「定义和跑模型」，不负责「服务」。要并发、要吞吐、要生产级接口，把模型交给 vLLM 这类推理引擎，它们直接吃 Transformers 的模型定义。