transformers

用途

Hugging Face Transformers 库提供对数千个预训练模型的访问，任务范围覆盖自然语言处理（NLP）、计算机视觉、音频和多模态领域。该技能用于加载模型、执行推理，并在自定义数据上进行微调。

安装

资料中说明该技能针对 transformers 5.12.0（当前 PyPI 发布版本；2026 年 6 月）测试。要求 Python 3.10+；torch extra 当前要求 PyTorch 2.4+。

基础安装命令：

uv pip install "transformers[torch]==5.12.0" huggingface_hub==1.19.0 datasets==5.0.0 evaluate==0.4.6 accelerate==1.14.0

视觉任务需追加：

uv pip install timm==1.0.27 pillow==12.2.0

音频任务需追加：

uv pip install librosa==0.11.0 soundfile==0.14.0

资料说明这些版本固定用于可复现的示例；探索性工作可在查看 Transformers 与 Hub 发布说明中的 API 变更后再放宽版本。检查版本：

import transformers
print(transformers.__version__)

认证

Hub 上许多模型是受限或私有的，加载前需先认证。

推荐使用 CLI 登录（令牌存储在 ~/.cache/huggingface/token）：

hf auth login

Python 方式：

from huggingface_hub import login
login()  # 交互式提示；不要在脚本中硬编码令牌

服务器 / CI：在环境中设置 HF_TOKEN（切勿将令牌提交到 git 或 shell 配置文件）：

export HF_TOKEN="..."  # 从密钥管理器读取令牌，而非源代码

令牌获取地址：https://huggingface.co/settings/tokens

安全提示：切勿将令牌粘贴到 notebook、仓库或共享配置中。优先使用 hf auth login，而不是在 .bashrc 或 .zshrc 中导出令牌。使用能满足需求的最小令牌范围：私有或受限模型下载用 read，仅上传用 write。若长期运行的环境不应在每次 Hub 请求时发送已存储令牌，可设置 HF_HUB_DISABLE_IMPLICIT_TOKEN=1，仅在需要认证处传入令牌。

Transformers v5

Transformers v5 仅支持 PyTorch（TensorFlow 和 JAX 后端已移除）。从 v4 升级请参阅 v5 迁移指南。新项目应将 transformers 5.x 与 huggingface_hub 1.x 搭配使用。

受限或自定义架构：在 Hub 上接受模型许可后，仅当模型卡要求你已审查过的自定义代码时，才使用 trust_remote_code=True 加载。

缓存位置：设置 HF_HOME 控制所有 Hugging Face 缓存，或仅用 HF_HUB_CACHE 控制 Hub 文件。仅在所需模型快照已缓存后，才使用 HF_HUB_OFFLINE=1。

快速开始

使用 Pipeline API 可快速推理，无需手动配置：

from transformers import pipeline

# 文本生成（因果语言模型优先使用 max_new_tokens）
generator = pipeline("text-generation", model="Qwen/Qwen2.5-1.5B")
result = generator("The future of AI is", max_new_tokens=50)

# 文本分类
classifier = pipeline("text-classification")
result = classifier("This movie was excellent!")

# 问答
qa = pipeline("question-answering")
result = qa(question="What is AI?", context="AI is artificial intelligence...")

核心能力

Pipelines 快速推理：用于跨多种任务的简单、优化推理。支持文本生成、分类、NER、问答、摘要、翻译、图像分类、目标检测、音频分类等。适用场景：快速原型、简单推理任务、无需自定义预处理。详见 references/pipelines.md。
模型加载与管理：加载预训练模型，可对配置、设备放置和精度进行细粒度控制。适用场景：自定义模型初始化、高级设备管理、模型检查。详见 references/models.md。
文本生成：使用 LLM 生成文本，支持多种解码策略（贪心、束搜索、采样）和控制参数（temperature、top-k、top-p）。适用场景：创意文本生成、代码生成、对话式 AI、文本补全。详见 references/generation.md。
训练与微调：使用 Trainer API 在自定义数据集上微调预训练模型，支持自动混合精度、分布式训练和日志记录。适用场景：任务特定模型适配、领域适配、提升模型性能。详见 references/training.md。
分词：将文本转换为 token 和 token ID 作为模型输入，支持填充、截断和特殊 token 处理。适用场景：自定义预处理流水线、理解模型输入、批处理。详见 references/tokenizers.md。

常见模式

模式 1：简单推理

pipe = pipeline("task-name", model="model-id")
output = pipe(input_data)

模式 2：自定义模型使用

from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("model-id")
model = AutoModelForCausalLM.from_pretrained("model-id", device_map="auto")

inputs = tokenizer("text", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

模式 3：微调

from transformers import Trainer, TrainingArguments

training_args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=3,
    per_device_train_batch_size=8,
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
)

trainer.train()

参考文档

Pipelines：references/pipelines.md — 所有支持的任务与优化
Models：references/models.md — 加载、保存与配置
Generation：references/generation.md — 文本生成策略与参数
Training：references/training.md — 使用 Trainer API 微调
Tokenizers：references/tokenizers.md — 分词与预处理

智能体操作流程

检查环境。确认 Python 环境与库版本（python -c "import pkg; print(pkg.version)"），并检查数据的形状、类型与缺失值。
明确输入。从数据或用户处确认格式、标识符与参数。任何会改变结果的取值都应询问而非猜测。
先运行小规模版本。先在样本或单个 fold 上运行，检查运行时间与内存。
使用上述说明与参考执行完整任务。
验证结果。使用留出数据、固定随机种子与合适的指标；检查泄漏；报告不确定性（置信区间、跨种子标准差）。
报告。说明运行了什么（版本、命令、参数）、检查了什么、还有什么不确定。

异常处理：

内存不足或执行极慢：下采样、使用分块或惰性计算，或减小模型规模，并告知用户所做的更改。
说明中的函数、标志或端点在当前安装版本中缺失：查阅已安装版本自身的文档（help()、--help、官方文档），适配并告知用户。切勿臆造 API。
必需的输入、标识符或参数不明确：询问用户，或在运行前明确说明假设。

完整性规则

切勿捏造结果、参数、标识符、引用或统计量。若某项无法运行或验证，应如实说明。
切勿报告本次会话中未计算的指标；展示产生每个数字的代码路径。
将此处版本相关的细节视为可能过时：对照已安装版本的官方文档进行确认。
在涉及花钱、占用共享 GPU 或云配额、触碰个人或患者数据、或不可撤销的操作前，先询问。

技能介绍

用途

安装

认证