Hugging Face 详细教程：从调用模型到微调与部署

Mr Panda·约 7 分钟阅读

2026年10月7日10月7日

文章目录

如果你想把大模型真正用起来，Hugging Face 几乎是最值得掌握的平台之一。它不只是“模型下载站”，而是一整套围绕模型、数据集、训练、评测、分享与部署的开发生态。

这篇教程从零开始，带你完成一条完整路径：安装环境 → 调用预训练模型 → 处理数据集 → 微调模型 → 上传 Hub → 用 Spaces 部署应用。

一、Hugging Face 到底是什么？

Hugging Face 主要由几类核心能力组成：

• Hub：托管模型、数据集和 Demo。

• Transformers：加载、推理和训练 Transformer 模型。

• Datasets：统一下载、处理和缓存数据集。

• Tokenizers：高性能文本分词器。

• Accelerate：简化 CPU、单卡、多卡和混合精度训练。

• PEFT：用 LoRA 等参数高效方法微调大模型。

• Spaces：把模型快速部署成可交互应用。

一个实用的理解方式是：Hub 负责资源管理，库负责工程能力，Spaces 负责展示和部署。

二、安装环境

建议使用 Python 3.10 或更高版本，并创建独立虚拟环境：

python -m venv .venv
source .venv/bin/activate

Windows PowerShell：

.venv\Scripts\Activate.ps1

安装基础依赖：

pip install -U transformers datasets tokenizers accelerate evaluate huggingface_hub safetensors

如果使用 PyTorch，请根据 CUDA 版本从 PyTorch 官网安装匹配版本。检查环境：

import torch
print(torch.__version__)
print(torch.cuda.is_available())

如果 CUDA 返回 False，不代表代码不能运行，只是会使用 CPU，速度通常会慢很多。

三、登录 Hugging Face Hub

在 huggingface.co/settings/tokens 创建一个具有合适权限的 Access Token，然后登录：

from huggingface_hub import login
login()

命令行也可以使用：

hf auth login

不要把 Token 写进代码、提交到 Git，或放进公开日志。生产环境应使用环境变量或密钥管理服务。

四、用 Pipeline 快速完成推理

Pipeline 是最适合入门的高级 API。它会自动处理 tokenizer、模型加载、输入预处理和输出解码。

from transformers import pipeline
classifier = pipeline("sentiment-analysis")
print(classifier("Hugging Face makes model development much easier."))

文本生成：

generator = pipeline("text-generation", model="distilgpt2")
result = generator("Machine learning is", max_new_tokens=50)
print(result[0]["generated_text"])

常见任务包括：sentiment-analysis、text-classification、text-generation、question-answering、summarization、translation、automatic-speech-recognition、image-classification 和 object-detection。

第一次运行时模型会自动下载并缓存到本地。线上部署时，建议提前下载并固定模型版本，避免启动时临时下载。

五、理解 Tokenizer

模型不能直接理解字符串，必须先把文本转换成 token，再转换成 input IDs。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased")
inputs = tokenizer(
    "Hugging Face is useful.",
    return_tensors="pt",
    padding=True,
    truncation=True,
    max_length=128,
)
print(inputs)

批量输入：

texts = ["first sentence", "a much longer second sentence"]
batch = tokenizer(texts, padding=True, truncation=True, return_tensors="pt")

padding 让同一批次长度一致，truncation 防止超长输入，max_length 控制最大长度。训练时要特别注意 tokenizer 的 padding_side、pad_token 和模型最大上下文长度。

六、直接加载模型

分类模型示例：

from transformers import AutoModelForSequenceClassification

model = AutoModelForSequenceClassification.from_pretrained(
    "distilbert-base-uncased-finetuned-sst-2-english"
)
outputs = model(**inputs)
print(outputs.logits)

生成式模型则使用 AutoModelForCausalLM：

from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("distilgpt2")

设备映射：

model = AutoModelForCausalLM.from_pretrained(
    "your-model-name",
    device_map="auto",
    torch_dtype="auto",
)

显存不足时，可以考虑更小模型、量化、CPU offload、减少 batch size 或使用 PEFT。

七、使用 Datasets 处理数据

from datasets import load_dataset

dataset = load_dataset("imdb")
print(dataset)
print(dataset["train"][0])

批量分词：

def tokenize_function(examples):
    return tokenizer(
        examples["text"],
        truncation=True,
        max_length=256,
    )

tokenized = dataset.map(tokenize_function, batched=True)

常用操作：

• map：批量转换或增加字段。

• filter：筛选样本。

• train_test_split：切分训练集和验证集。

• remove_columns：删除原始字段。

• set_format：设置 PyTorch、NumPy 等输出格式。

数据处理的关键不是“全部塞进模型”，而是明确标签、去重、清洗异常样本、控制长度，并保留一份可复现的数据版本。

八、使用 Trainer 微调模型

from transformers import (
    AutoTokenizer,
    AutoModelForSequenceClassification,
    TrainingArguments,
    Trainer,
)

model_name = "distilbert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)

def tokenize(batch):
    return tokenizer(batch["text"], truncation=True, padding="max_length", max_length=256)

tokenized = dataset.map(tokenize, batched=True)

args = TrainingArguments(
    output_dir="./results",
    eval_strategy="epoch",
    save_strategy="epoch",
    learning_rate=2e-5,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=16,
    num_train_epochs=2,
    weight_decay=0.01,
    load_best_model_at_end=True,
    report_to="none",
)

trainer = Trainer(
    model=model,
    args=args,
    train_dataset=tokenized["train"],
    eval_dataset=tokenized["test"],
    tokenizer=tokenizer,
)
trainer.train()
trainer.evaluate()

实际项目中，学习率、batch size、训练轮数、最大长度和评测指标都需要根据数据规模调整。不要只看训练 loss，还要观察验证集指标和真实样例。

九、用 LoRA / PEFT 高效微调大模型

全参数微调需要更新模型的全部参数，显存和存储成本很高。LoRA 只训练少量低秩适配器参数，通常更适合个人开发者和中小团队。

pip install -U peft

from peft import LoraConfig, TaskType, get_peft_model

config = LoraConfig(
    task_type=TaskType.SEQ_CLS,
    r=8,
    lora_alpha=16,
    lora_dropout=0.05,
    target_modules=["q_lin", "v_lin"],
)
model = get_peft_model(model, config)
model.print_trainable_parameters()

不同架构的 target_modules 不同，不能机械照抄。使用前应查看模型结构，确认注意力层命名。对因果语言模型，TaskType 通常使用 CAUSAL_LM；对分类任务则使用 SEQ_CLS。

十、上传模型到 Hub

训练完成后：

trainer.push_to_hub()

或者手动上传：

model.push_to_hub("your-username/my-model")
tokenizer.push_to_hub("your-username/my-model")

建议同时上传 README.md，写清楚模型用途、训练数据、限制、评测结果、许可证和使用示例。一个可复现的模型仓库，通常比“只有权重文件”的仓库更有价值。

十一、用 Spaces 部署 Demo

Spaces 支持 Gradio、Streamlit 等方式。最小 Gradio 示例：

import gradio as gr
from transformers import pipeline

pipe = pipeline("sentiment-analysis")

def predict(text):
    return pipe(text)

gré = gr.Interface(
    fn=predict,
    inputs=gr.Textbox(label="输入文本"),
    outputs=gr.JSON(label="结果"),
    title="情感分析 Demo",
)
gré.launch()

把 app.py、requirements.txt 和必要配置上传到 Space，Hub 会自动构建并运行。部署前要注意启动时间、内存、并发、模型缓存和隐私问题。