| Dibi8

lang: zh slug: huggingface-transformers-guide title: ‘Hugging Face Transformers: The Complete Developer’’s Guide (2025)’ description: ‘Master Hugging Face Transformers in 2025. Learn pipeline API, model fine-tuning, tokenization, optimization, and deployment with practical code examples.’ tags: [“guide”, “open-source”, “reference”, “tutorial”] date: 2026-05-18 00:00:00+08:00 lastmod: 2026-05-18 00:00:00+08:00 tech_stack: [] application_domain: Llm Frameworks source_version: ’' licensing_model: Open Source license_type: MIT file_size: ’' file_md5: ’' download_url: ’' backup_url: ’' github_repo: ’' last_maintained: ‘2026-05-18’ draft: false aliases:

/posts/huggingface-transformers-guide/ faqs:
- q: ‘How do I fix CUDA out of memory errors when training Hugging Face models?’ a: ‘Reduce the batch size (down to 1 if needed), enable gradient accumulation to simulate larger batches, and turn on gradient checkpointing with model.gradient_checkpointing_enable(). You can also apply LoRA or quantization, and clear unused memory with torch.cuda.empty_cache().’
- q: ‘What is the difference between the Hugging Face Hub and the Transformers library?’ a: ‘The Transformers library is the Python code you install with pip install transformers, providing model implementations, training utilities, and inference APIs. The Hugging Face Hub is the web platform at huggingface.co that hosts models, datasets, and spaces, which you download from using the Transformers library.’
- q: ‘Which Hugging Face model architecture should I use for my task?’ a: ‘Use encoder-only models like BERT, RoBERTa, or DistilBERT for classification, NER, and similarity. Use decoder-only models like GPT, LLaMA, or Mistral for text generation and completion. Use encoder-decoder models like T5, BART, or PEGASUS for translation and summarization.’
- q: ‘How does LoRA make fine-tuning large models cheaper?’ a: ‘LoRA (Low-Rank Adaptation) freezes the base model and trains only small adapter matrices, reducing trainable parameters by about 99% while retaining 95%+ of full fine-tuning quality. This lets you fine-tune models as large as 70B on consumer GPUs, available through the PEFT library.’
- q: ‘Can I use Hugging Face models commercially?’ a: ‘Most models on the Hub carry permissive licenses such as Apache 2.0 or MIT that allow commercial use, and the Transformers library itself is free under Apache 2.0. However, some models, particularly those derived from Meta’’s LLaMA family, have restrictive licenses, so always verify the license field on the model card before deploying commercially.’ {</* resource-info */>}If you work with natural language processing or large language models in 2025, you use Hugging Face Transformers. The library has become the standard infrastructure for the entire NLP field — powering everything from research prototypes at Stanford and MIT to production systems at Google and Microsoft. Over 500,000 pretrained models sit on the Hugging Face Hub, downloaded collectively more than 100 million times per month.This guide takes you from the basics of the Transformers library to production deployment. Whether you are fine-tuning BERT for sentiment analysis or serving GPT-style models at scale, you will find concrete code examples, performance benchmarks, and troubleshooting advice based on real production experience.
  
  Source: HuggingFace documentation-images## What is Hugging Face Transformers?Hugging Face Transformers is an open-source Python library that provides pre-trained transformer models and tools for natural language processing, computer vision, audio processing, and multimodal tasks. Originally focused on NLP, the library now supports tasks across virtually every modality of machine learning.The library’s core value proposition is simple: download a state-of-the-art model in one line of code and use it for your task in five. This accessibility democratized transformer models — what once required a PhD and months of engineering now takes minutes.### The Hugging Face Ecosystem: Hub, Datasets, AccelerateTransformers does not stand alone. It is part of a broader ecosystem of tools:| Tool | Purpose | Why It Matters | |— featureImage: /images/articles/hugging-face-transformers-완벽-가이드-2025-개발.png —|———|—————-| | Transformers | Pre-trained models and training APIs | Core model library | | Hub | Model and dataset hosting | 500,000+ models available instantly | | Datasets | Standardized dataset library | 20,000+ datasets ready for training | | Accelerate | Simplified distributed training | Run on multi-GPU or TPU without code changes | | PEFT | Parameter-efficient fine-tuning | Fine-tune 70B models on consumer GPUs | | TRL | Reinforcement learning from human feedback | Train models with RLHF |This integrated toolchain means you can go from idea to fine-tuned model without leaving the Hugging Face ecosystem.### Why It is the Most Popular NLP LibrarySeveral factors drove Transformers to dominance. The library abstracts every major transformer architecture — BERT, GPT, T5, LLaMA, Mistral — behind a unified API. It supports PyTorch, TensorFlow, and JAX, so you are not locked into a single framework. The Hugging Face Hub creates a social network for models, where researchers publish and the community votes on the best checkpoints.Crucially, the library handles the messy details: tokenization alignment, attention mask construction, padding strategies, and model-specific quirks. You focus on your task; Transformers handles the infrastructure.## Key Features and Capabilities### 500,000+ Pretrained ModelsThe Hugging Face Hub hosts models for virtually every NLP task and many beyond. The catalog includes foundation models like BERT, GPT-2, T5, and LLaMA; fine-tuned variants for specific languages and domains; and experimental architectures from recent papers. You can search by task, language, library, and license.### Support for 200+ LanguagesWhile early transformer models focused on English, the Hub now contains strong models for Arabic, Chinese, Hindi, Japanese, and hundreds of other languages. Multilingual models like XLM-RoBERTa and mBERT handle 100 languages in a single checkpoint.### PyTorch, TensorFlow, and JAX CompatibilityTransformers supports all three major deep learning frameworks. Most new models ship with PyTorch implementations first, but TensorFlow and JAX support follows quickly. You can even export models to ONNX for inference in other runtimes.## Installation and Environment SetupGetting started requires minimal setup. You need Python 3.8+ and a basic understanding of deep learning concepts.### Installing Transformers and Dependencies``` bas h pip install transformers pip install torch # or tensorflow, or flax

o
r
the full ecosystem experience:```
bas
h
pip install transformers datasets accelerate peft trl
```### Se```
bas
h
pip install transformers datasets accelerate peft trl
```ain
i
n
g
and large-scale inference. Install the CUDA-compatible PyTorch version:```
bas
h
pip install torch --index-url https://download.pytorch.org/whl/cu121
```Ver
i
f
y
GPU availability:```
pytho
n
import torch
```b
a
s
h
pip install torch --index-url https://download.pytorch.org/whl/cu121
```e
_name(0))  # Your GPU model
```### Using Google Colab for Free GPU AccessIf you lack local GPU r```
pytho
n
import torch
print(torch.cuda.is_available())  # Should print True
print(torch.cuda.get_device_name(0))  # Your GPU model
``` > Change runtime type > GPU) and install the libraries in the first cell. For larger models, Colab Pro ($9.99/month) offers more memory and faster GPUs.## The Pipeline API: The Easiest Way to StartThe pipeline API is Transformers' highest-level interface. It handles tokenization, model inference, and output parsing in a single function call. Here is how to perform common NLP tasks:### Text Classification```
pytho
n
from transformers import pipelineclassifier = pipeline("sentiment-analysis")
result = classifier("This movie was absolutely fantastic!")
# [{'label': 'POSITIVE', 'score': 0.9998}]
```### Named Entity Recognition (NER)```
pytho
n
ner = pipeline("ner", aggregation_strategy="simple")
result = ner("Apple Inc. was founded```
pytho
n
from transformers import pipeline

classifier = pipeline("sentiment-analysis")
result = classifier("This movie was absolutely fantastic!")
# [{'label': 'POSITIVE', 'score': 0.9998}]
```s
the capital of France?",
    context="Paris is the capital and largest city of France."
)
# {'answer': 'Paris', 'score': 0.99}
```### Text Generation```
pytho
n
generator = pipeline("text-generation", model="gpt2")
result ```
pytho
n
ner = pipeline("ner", aggregation_strategy="simple")
result = ner("Apple Inc. was founded by Steve Jobs in California.")
# [{'entity_group': 'ORG', 'word': 'Apple Inc.'}, ...]
```summariz
e
r
(long_article_text, max_length=130, min_length=30)
```### Translation```
pytho
n
translator = pipeline("translation_en_to_de", model="t5-base")
result = translator("Hello, how are you?")
```T
h
e
```pyt
h
o
n
qa = pipeline("question-answering")
result = qa(
    question="What is the capital of France?",
    context="Paris is the capital and largest city of France."
)
# {'answer': 'Paris', 'score': 0.99}
```uct
i
o
n
applications, use the Auto classes directly. This gives you control over batching, device placement, and output processing.### Loading Models and Tokenizers```
pytho
n
from transformers import AutoModel, AutoTokenizer
```pyt
h
o
n
generator = pipeline("text-generation", model="gpt2")
result = generator("The future of AI is", max_length=30, num_return_sequences=1)
```Mod
e
l
` family automatically selects the correct architecture based on the model name. For specific tasks, use specialized classes:```
pytho
n
from transformers im```
pytho
n
summarizer = pipeline("summarization", model="facebook/bart-large-cnn")
result = summarizer(long_article_text, max_length=130, min_length=30)
```s
(sentiment, NER)
cls_model = AutoModelForSequenceClassification.from_pretrained("distilbert-base-uncased")# Text generation (GPT-style)
gen_model = AutoModelForCau```
pytho
n
translator = pipeline("translation_en_to_de", model="t5-base")
result = translator("Hello, how are you?")
```ain
e
d
("t5-small")
```### Model Classes: Encoder, Decoder, Encoder-DecoderUnderstanding transformer architecture types helps you choose the right model:| Architecture | Examples | Best For |
|-------------|----------|----------|
| **Encoder-only** | BERT, RoBERTa, DistilBERT | Classification, NER, similarity |
| **Decoder-only** | GPT, LLaMA, Mistral | Text generation, completion |
| **Encoder-Decoder** | T5, BART, PEGASUS | Translation, summarization |### Understanding Model Configur```
pytho
n
from transformers import AutoModel, AutoTokenizer

model_name = "bert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)
```con
f
i
g
= AutoConfig.from_pretrained("bert-base-uncased")
print(config.num_hidden_layers)  # 12
print(config.hidden_size)  # 768
```### Saving and Loading Models Locally```
pytho
n
# Save
model.save_pretrained("./my_model")
tokenizer.save_pretrained("./my_model")# Load from local path
model = AutoModel.from_pretrained("./my_mod```
pytho
n
from transformers import AutoModelForSequenceClassification
from transformers import AutoModelForCausalLM
from transformers import AutoModelForSeq2SeqLM

# Classification tasks (sentiment, NER)
cls_model = AutoModelForSequenceClassification.from_pretrained("distilbert-base-uncased")

# Text generation (GPT-style)
gen_model = AutoModelForCausalLM.from_pretrained("gpt2")

# Translation, summarization (T5, BART)
seq2seq_model = AutoModelForSeq2SeqLM.from_pretrained("t5-small")
```dPie
c
e
, BPE, and SentencePiece AlgorithmsDifferent tokenizers use different algorithms:| Algorithm | Used By | Approach |
|-----------|---------|----------|
| **WordPiece** | BERT, DistilBERT | Greedy subword merging |
| **BPE** | GPT, RoBERTa | Merges most frequent pairs |
| **SentencePiece** | T5, LLaMA | Language-agnostic character-level |
| **Unigram** | Albert, XLNet | Probabilistic subword pruning |### Working with the Tokenizer API```
pytho
n
text = "Hello, Transformers!"
tokens = tokenizer.tokenize(text)
# ['hello', ',', 'transform', '##ers', '!']ids = tokenizer.encode(text)
# [101, 7592, 117, 19082, 1168, 106, 102]# Full encoding with attention mask
encoded = tokenizer(text, padding=True, truncation=True, max_length=512, return_tensors="pt")
# encoded['input_ids'], encoded['attention_mask']
```### Handling Special Tokens and PaddingTokenizers add special tokens automatically: `[CLS]` (classification start), `[SEP]` (separator), `[PAD]` (padding). The attention mask tells the model which tokens are real versus padding. Always pass the attention mask to avoid incorrect re```
pytho
n
from transformers import AutoConfig

config = AutoConfig.from_pretrained("bert-base-uncased")
print(config.num_hidden_layers)  # 12
print(config.hidden_size)  # 768
```t
l
y
.### Preparing Your DatasetThe Datasets library simplifies data preparation:```
pytho
n
from datasets import load_datasetdataset = load_dataset("imdb")
# dataset['train'], dataset['test'] with 'text' an```
pytho
n
# Save
model.save_pretrained("./my_model")
tokenizer.save_pretrained("./my_model")

# Load from local path
model = AutoModel.from_pretrained("./my_model")
```ti
o
n
, batched=True)
```### Using the Trainer APIThe Trainer class handles training loops, evaluation, checkpointing, and logging:```
pytho
n
from transformers import Trainer, TrainingArgumentstraining_args = TrainingArguments(
    output_dir="./results",
    learning_rate=2e-5,
    per_device_train_batch_size=16,
    num_train_epochs=3,
    weight_decay=0.01,
    evaluation_strategy="epoch",
    save_strategy="epoch",
    load_best_model_at_end=True,
)trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=tokenized["train"],
    eval_dataset=tokenized["test"],
)trainer.train()
```### Custom Training Loops with PyTorchFor full control, write your own training loop:```
pytho
n
from torch.optim import AdamW
from torch.utils.data import DataLoaderoptimizer = AdamW(model.parameters(), lr=5e-5)
train_loader = DataLoader(tokenized["train"], batch_size=8, shuffle=True)model.train()
for epoch in range(3):
    for batch in train_loader:
        optimizer.zero_grad()
        outputs = model(**batch)
        loss = outputs.loss
        loss.backward```
pytho
n
text = "Hello, Transformers!"
tokens = tokenizer.tokenize(text)
# ['hello', ',', 'transform', '##ers', '!']

ids = tokenizer.encode(text)
# [101, 7592, 117, 19082, 1168, 106, 102]

# Full encoding with attention mask
encoded = tokenizer(text, padding=True, truncation=True, max_length=512, return_tensors="pt")
# encoded['input_ids'], encoded['attention_mask']
```pyt
h
o
n
from transformers import AutoModelForCausalLM, DataCollatorForLanguageModelingmodel = AutoModelForCausalLM.from_pretrained("gpt2")
data_collator = DataCollatorForLanguageModeling(tokenizer, mlm=False)
# Use with Trainer for causal language modeling
```### Using LoRA for Efficient Fine-TuningFull fine-tuning updates billions of parameters, requiring massive GPU memory. LoRA (Low-Rank Adaptation) freezes the base model and trains small adapter matrices, reducing trainable parameters by 99% while maintaining 95%+ of full fine-tuning quality:```
pytho
n
from peft import LoraConfig, get_peft_modellora_config = LoraConfig(
    r=16,  # rank
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM"
)model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# trainable params: 9M || all params: 7B || train```
pytho
n
from datasets import load_dataset

dataset = load_dataset("imdb")
# dataset['train'], dataset['test'] with 'text' and 'label' columns

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

tokenized = dataset.map(tokenize_function, batched=True)
```t
=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16
)model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b",
    quantization_config=bnb_config
)
```### Model DistillationDistillation trains a smaller "student" model to mimic a larger "teacher." DistilBERT, for example, retains 97% of BERT's performance at 60% of the size and 40% faster inference.### ONNX Export a```
pytho
n
from transformers import Trainer, TrainingArguments

training_args = TrainingArguments(
    output_dir="./results",
    learning_rate=2e-5,
    per_device_train_batch_size=16,
    num_train_epochs=3,
    weight_decay=0.01,
    evaluation_strategy="epoch",
    save_strategy="epoch",
    load_best_model_at_end=True,
)

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

trainer.train()
``` Deploying with Hugging Face Inference APIFor zero-infrastructure deployment, use the [Hugging Face Inference API](https://huggingface.co/docs/api-inference):```
pytho
n
import requestsAPI_URL = "https://api-inference.huggingface.co/models/bert-base-uncased"
headers = {"Authorization": f"Bearer {token}"}def query(payload):
    response = requests.post(API_URL, headers=headers, json=payload)
    return response.json()result = query({"inputs": "The answer to life is [MASK]."})
```### Local Deployment with TransformersFor production, serve models with T```
pytho
n
from torch.optim import AdamW
from torch.utils.data import DataLoader

optimizer = AdamW(model.parameters(), lr=5e-5)
train_loader = DataLoader(tokenized["train"], batch_size=8, shuffle=True)

model.train()
for epoch in range(3):
    for batch in train_loader:
        optimizer.zero_grad()
        outputs = model(**batch)
        loss = outputs.loss
        loss.backward()
        optimizer.step()
```--------|------|
| **BERT-base-uncased** | Encoder | Classification, NER | 110M |
| **RoBERTa-large** | Encoder | Classification benchmarks | 355M |
| **GPT-2** | Decoder | Text generation, prototyping | 124M-1.5B |
| **T5-base** | Encoder-Decoder | Translation, summarization | 220M |
| **BART-large** | Encoder-Decoder | Summarization, generation | 400M |
| **XLM-RoBERTa** | Encoder | Multilingual tasks | 270M |
| **LLaMA-3-8B** | Decoder | General purpose, local deployment | 8B ```
pytho
n
from transformers import AutoModelForSequenceClassification

model = AutoModelForSequenceClassification.from_pretrained(
    "bert-base-uncased",
    num_labels=2
)
# Then train with Trainer or custom loop
```l
a
t
e
larger batches
- Enable gradient checkpointing: `model.gradient_checkpointing_enable()`
- Use LoRA or full quantization
- Clear CUDA cache: `torch.cuda.empty_cache()`### Model Compatibility IssuesAlways check the model card on Hugging Face Hub. ```
pytho
n
from transformers import AutoModelForCausalLM, DataCollatorForLanguageModeling

model = AutoModelForCausalLM.from_pretrained("gpt2")
data_collator = DataCollatorForLanguageModeling(tokenizer, mlm=False)
# Use with Trainer for causal language modeling
```ont
e
x
t
lengths. BERT handles 512 tokens; GPT-2 handles 1,024; modern LLaMA models handle up to 128,000. For long documents:- Use models with longer contexts (RoBERTa: 512, Longformer: 4096)
- Apply sliding window approaches
- Split documents and aggregate predictions## Frequently Asked Questions### Is Hugging Face Transformers free to use?Yes, the Transformers library is completely free and open-source under the Apache 2.0 license. You can use it commercially without restrictions. Individual models may have their own licenses — always check```
pytho
n
from peft import LoraConfig, get_peft_model

lora_config = LoraConfig(
    r=16,  # rank
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM"
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# trainable params: 9M || all params: 7B || trainable%: 0.13
```plementatio
n
s
, training utilities, and inference APIs. The Hugging Face Hub is a web platform (huggingface.co) that hosts models, datasets, and spaces. You download models from the Hub using the Transformers library — they work together but are separate things.### Can I use Hugging Face models commercially?Most models on the Hub carry permissive licenses (Apache 2.0, MIT) that allow commercial use. However, some models — particularly those derived from LLaMA — have restrictive licenses. Always verify the license field on the model card be```
pytho
n
from transformers import BitsAndBytesConfig
import torch

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

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b",
    quantization_config=bnb_config
)
```gl
i
s
h
classification, `distilbert-base-uncased` is a reliable default. For generation, `Mistral-7B-Instruct` offers excellent quality at a manageable size. Check the model card's benchmark scores and community downloads — popular models with high ratings are usually safe choices.### Does Hugging Face support fine-tuning on custom datasets?Absolutely. The Datasets library makes it easy to load custom data from CSV, JSON, Parquet, or text files. Combine it with the Trainer API or PyTorch training loops to fine-tune any model on your data. PEFT methods like LoRA make fine-tuning feasible even on c```
pytho
n
from transformers import AutoModelForSequenceClassification
import torch

model = AutoModelForSequenceClassification.from_pretrained("distilbert-base-uncased")
torch.onnx.export(
    model,
    (torch.zeros(1, 128, dtype=torch.long),),  # dummy input
    "model.onnx",
    input_names=["input_ids"],
    output_names=["logits"],
    dynamic_axes={"input_ids": {0: "batch", 1: "sequence"}}
)
```n
applications. Fine-tune with the Trainer API when you have labeled data. Optimize with quantization and ONNX when you need speed. The library scales with your needs from prototype to production.For continued learning, follow the [official documentation](https://huggingface.co/docs/transformers), explore the [Hugging Face Hub](https://huggingface.co/models), and join the community forums. The field moves fast, and the Hub is where new breakthroughs appear first.---## Recommended InfrastructureTo run any of the tools above reliably 24/7, infrastruct```
pytho
n
import requests

API_URL = "https://api-inference.huggingface.co/models/bert-base-uncased"
headers = {"Authorization": f"Bearer {token}"}

def query(payload):
    response = requests.post(API_URL, headers=headers, json=payload)
    return response.json()

result = query({"inputs": "The answer to life is [MASK]."})
```i
o
n
-proven.*Affiliate links — no extra cost to you, helps keep dibi8.com running.*<!--auto-references-->
## References & Sources- [Hugging Face Transformers](https://github.com/huggingface/transformers)
- [Hugging Face Datasets](https://github.com/huggingface/datasets)
- [Hugging Face Accelerate](https://github.com/huggingface/accelerate)
- [PEFT](https://github.com/huggingface/peft)
- [TRL](https://github.com/huggingface/trl)
- [Text Generation Inference (T```
pytho
n
from fastapi import FastAPI
from transformers import pipeline

app = FastAPI()
pipe = pipeline("text-classification", model="distilbert-base-uncased")

@app.post("/classify")
def classify(text: str):
    return pipe(text)[0]
```x
/onnx)
- [bitsandbytes](https://github.com/bitsandbytes-foundation/bitsandbytes)
- [FastAPI](https://github.com/fastapi/fastapi)

🔗 相关资源推荐

💬 留言讨论