Hugging Face 模型使用全指南：从下载到部署

Hugging Face 已经成为 AI 模型生态的「GitHub」。从 BERT、GPT 到 Llama、Stable Diffusion，绝大多数开源模型都会在这里发布。对工程师来说，关键不是模型多，而是怎么快速下载、加载、推理、部署。

这篇文章聚焦 transformers 库和 huggingface_hub 的实战用法：Pipeline 快速上手、AutoModel 自定义、离线运行、量化推理，以及如何避免被 GFW 卡下载。

一、环境准备与镜像设置

国内访问 Hugging Face 需要镜像。推荐两种方案：

使用 HF-Mirror：https://hf-mirror.com
使用 ModelScope 转接：很多国产镜像会同步 HF 模型

# 设置环境变量使用镜像
export HF_ENDPOINT=https://hf-mirror.com

# 安装依赖
pip install transformers torch huggingface_hub

也可以把模型下载到本地，之后完全离线使用。后文会讲。

二、Pipeline：最快上手方式

如果你只想跑一个任务，pipeline 是最省心的封装。它自动帮你处理 tokenizer、model、后处理。

from transformers import pipeline

# 情感分析
classifier = pipeline(
    "sentiment-analysis",
    model="distilbert/distilbert-base-uncased-finetuned-sst-2-english",
    device=0  # 使用 GPU，CPU 用 -1
)
print(classifier("I love this blog!"))

# 文本生成
generator = pipeline(
    "text-generation",
    model="Qwen/Qwen2.5-0.5B-Instruct",
    torch_dtype="auto"
)
print(generator("请用一句话介绍 Hugging Face：", max_new_tokens=50))

Pipeline 适合快速验证，但灵活性不足。生产环境通常会用 AutoModel + AutoTokenizer 自己拼流程。

三、AutoModel：手动控制推理流程

以 Qwen2.5 为例，展示完整的手动推理流程：

from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_id = "Qwen/Qwen2.5-0.5B-Instruct"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
    device_map="auto"
)

messages = [
    {"role": "system", "content": "你是一位有帮助的助手。"},
    {"role": "user", "content": "解释什么是 Transformer？"}
]

text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(text, return_tensors="pt").to(model.device)

outputs = model.generate(
    **inputs,
    max_new_tokens=256,
    do_sample=True,
    temperature=0.7,
    top_p=0.9
)
response = tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(response)

关键点：

device_map="auto"：自动把模型层分配到多 GPU / CPU；
torch.float16：半精度推理，省显存；
apply_chat_template：按模型要求拼接对话模板，很多模型必须用这个，否则效果差。

四、模型下载与离线使用

使用 huggingface-cli 或 Python API 把模型下载到指定目录：

# 命令行下载
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download Qwen/Qwen2.5-0.5B-Instruct \
  --local-dir ./models/Qwen2.5-0.5B-Instruct \
  --local-dir-use-symlinks False

# Python 下载
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id="Qwen/Qwen2.5-0.5B-Instruct",
    local_dir="./models/Qwen2.5-0.5B-Instruct",
    local_dir_use_symlinks=False
)

之后加载时直接传本地路径即可：

tokenizer = AutoTokenizer.from_pretrained("./models/Qwen2.5-0.5B-Instruct")
model = AutoModelForCausalLM.from_pretrained("./models/Qwen2.5-0.5B-Instruct")

五、量化：让小显存也能跑大模型

7B 模型 FP16 大约需要 14GB 显存，INT4 量化后可以降到 4GB 左右。常用方案：

5.1 bitsandbytes 4bit 量化

from transformers import BitsAndBytesConfig

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
)

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-chat-hf",
    quantization_config=bnb_config,
    device_map="auto"
)

5.2 GGUF 格式（llama.cpp 生态）

如果显存非常小，或者想跑在 CPU 上，可以下载 GGUF 格式模型，用 llama-cpp-python 推理：

from llama_cpp import Llama

llm = Llama(model_path="./models/qwen2.5-0.5b-instruct-q4_k_m.gguf", n_ctx=4096)
output = llm("请解释 Transformer：", max_tokens=200)
print(output["choices"][0]["text"])

六、模型部署：从脚本到 API

简单部署可以用 transformers + FastAPI：

from fastapi import FastAPI
from pydantic import BaseModel
from transformers import pipeline

app = FastAPI()
generator = pipeline("text-generation", model="Qwen/Qwen2.5-0.5B-Instruct")

class Request(BaseModel):
    prompt: str
    max_new_tokens: int = 128

@app.post("/generate")
def generate(req: Request):
    result = generator(req.prompt, max_new_tokens=req.max_new_tokens)
    return {"text": result[0]["generated_text"]}

生产级高并发部署推荐：

vLLM：PagedAttention 实现高吞吐推理；
TGI (Text Generation Inference)：Hugging Face 官方推理服务；
llama.cpp server：CPU / 低显存场景，单文件部署。

七、常用技巧与踩坑

Token 长度：超过模型上下文窗口会报错，调用前用 tokenizer.model_max_length 检查并截断；
Trust Remote Code：部分国产模型需要 trust_remote_code=True；
磁盘缓存：默认缓存目录是 ~/.cache/huggingface，可通过 HF_HOME 修改；
下载中断：大模型用 huggingface-cli 下载更稳，支持断点续传；
模型许可：商用前务必查看模型 License（Llama、Qwen、GLM 各有不同限制）。

小结

Hugging Face 降低了使用开源模型的门槛：pipeline 快速验证，AutoModel 灵活控制，BitsAndBytes 和 GGUF 让小设备也能跑大模型。真正上线时，还要解决量化、批处理、并发、缓存、许可等问题。

建议先在本地用镜像把模型下好，跑通后再考虑 vLLM / TGI 部署。模型越大，越要注重推理效率和成本控制。

← 返回首页