Skip to content

01-getting-started.md

Latest commit

 

History

History
475 lines (349 loc) · 14.8 KB

01-getting-started.md

File metadata and controls

475 lines (349 loc) · 14.8 KB
layout default
title Chapter 1: Getting Started with HuggingFace Transformers
parent HuggingFace Transformers Tutorial
nav_order 1

Chapter 1: Getting Started with HuggingFace Transformers

Welcome to the world of state-of-the-art AI with HuggingFace Transformers! If you've ever wanted to add powerful AI capabilities to your applications without building models from scratch, you're in the right place. HuggingFace Transformers makes cutting-edge AI accessible through thousands of pre-trained models.

What Makes Transformers Special?

Transformers revolutionizes AI development by:

  • 100,000+ Pre-trained Models - Ready-to-use AI for any task
  • Simple APIs - Just a few lines of code to add AI capabilities
  • Open-Source Ecosystem - Community-driven innovation and collaboration
  • Multi-Modal Support - Text, vision, audio, and multimodal models
  • Production-Ready - Optimized for performance and scalability

Installing Transformers

Basic Installation

# Install Transformers and PyTorch
pip install transformers torch

# Or install with TensorFlow support
pip install transformers tensorflow

# For GPU acceleration (if you have CUDA)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Optional: Install additional libraries
pip install datasets accelerate

Development Setup

# Clone Transformers for development
git clone https://github.com/huggingface/transformers.git
cd transformers

# Install in development mode
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

Your First AI Model

Let's run your first AI model with just a few lines of code:

Step 1: Basic Setup

from transformers import pipeline

# Create a sentiment analysis pipeline
sentiment_analyzer = pipeline("sentiment-analysis")

print("🤖 AI Model loaded successfully!")

Step 2: Analyze Text Sentiment

# Analyze sentiment of text
result = sentiment_analyzer("I love using HuggingFace Transformers!")

print("Input: I love using HuggingFace Transformers!")
print(f"Sentiment: {result[0]['label']}")
print(".3f")

Step 3: Try Different Tasks

# Text classification
classifier = pipeline("text-classification", model="cardiffnlp/twitter-roberta-base-sentiment-latest")
result = classifier("The movie was absolutely amazing!")
print(f"Twitter Sentiment: {result[0]['label']} ({result[0]['score']:.3f})")

# Named Entity Recognition
ner = pipeline("ner", model="dbmdz/bert-large-cased-finetuned-conll03-english")
entities = ner("Barack Obama was the 44th President of the United States.")
for entity in entities:
    print(f"{entity['word']}: {entity['entity']} ({entity['score']:.3f})")

# Question Answering
qa = pipeline("question-answering")
context = "HuggingFace Transformers is a library for natural language processing."
question = "What is HuggingFace Transformers?"
answer = qa(question=question, context=context)
print(f"Question: {question}")
print(f"Answer: {answer['answer']} (confidence: {answer['score']:.3f})")

Understanding Pipeline Architecture

What are Pipelines?

Pipelines are the simplest way to use Transformers models:

Input Text → Preprocessing → Model → Postprocessing → Output

Available Pipelines

# Text Processing
sentiment = pipeline("sentiment-analysis")
classification = pipeline("text-classification")
summarization = pipeline("summarization")
translation = pipeline("translation")

# Token-level Tasks
ner = pipeline("ner")                    # Named Entity Recognition
pos = pipeline("pos")                    # Part-of-Speech Tagging
fill_mask = pipeline("fill-mask")        # Masked Language Modeling

# Generation Tasks
text_gen = pipeline("text-generation")
qa = pipeline("question-answering")
conversational = pipeline("conversational")

# Vision Tasks
image_classification = pipeline("image-classification")
object_detection = pipeline("object-detection")
image_segmentation = pipeline("image-segmentation")

# Audio Tasks
speech_recognition = pipeline("automatic-speech-recognition")
audio_classification = pipeline("audio-classification")

Working with Models Directly

Loading Models and Tokenizers

from transformers import AutoTokenizer, AutoModelForSequenceClassification

# Load a pre-trained model and tokenizer
model_name = "distilbert-base-uncased-finetuned-sst-2-english"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)

print(f"Model: {model_name}")
print(f"Tokenizer vocab size: {tokenizer.vocab_size}")

Manual Inference

import torch

# Prepare input
text = "This movie is fantastic!"
inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True)

# Make prediction
with torch.no_grad():
    outputs = model(**inputs)
    predictions = torch.softmax(outputs.logits, dim=1)

# Get results
predicted_class = torch.argmax(predictions, dim=1).item()
confidence = predictions[0][predicted_class].item()

labels = ["NEGATIVE", "POSITIVE"]
print(f"Text: {text}")
print(f"Sentiment: {labels[predicted_class]} ({confidence:.3f})")

Real-World Applications

Sentiment Analysis Service

from transformers import pipeline
from flask import Flask, request, jsonify

app = Flask(__name__)
sentiment_analyzer = pipeline("sentiment-analysis", model="cardiffnlp/twitter-roberta-base-sentiment-latest")

@app.route('/analyze', methods=['POST'])
def analyze_sentiment():
    data = request.get_json()
    text = data.get('text', '')

    if not text:
        return jsonify({'error': 'No text provided'}), 400

    result = sentiment_analyzer(text)[0]

    return jsonify({
        'text': text,
        'sentiment': result['label'],
        'confidence': round(result['score'], 3)
    })

if __name__ == '__main__':
    app.run(debug=True)

Content Summarization Tool

from transformers import pipeline

class ContentSummarizer:
    def __init__(self):
        self.summarizer = pipeline(
            "summarization",
            model="facebook/bart-large-cnn",
            max_length=150,
            min_length=50
        )

    def summarize_text(self, text, max_length=150):
        """Summarize long text into key points"""
        if len(text.split()) < 100:
            return "Text is too short to summarize effectively."

        summary = self.summarizer(text, max_length=max_length, min_length=50)[0]['summary_text']
        return summary

    def summarize_batch(self, texts):
        """Summarize multiple texts"""
        summaries = []
        for text in texts:
            summary = self.summarize_text(text)
            summaries.append(summary)
        return summaries

# Usage
summarizer = ContentSummarizer()

text = """
HuggingFace Transformers is an open-source library that provides thousands of pre-trained models
for various natural language processing tasks. It supports tasks like text classification,
question answering, text generation, and more. The library is built on top of PyTorch and
TensorFlow, making it easy to integrate into existing machine learning workflows.
"""

summary = summarizer.summarize_text(text)
print("Summary:", summary)

Multilingual Translation Service

from transformers import pipeline

class MultilingualTranslator:
    def __init__(self):
        # Load multiple translation models
        self.translators = {
            'en-fr': pipeline("translation_en_to_fr", model="Helsinki-NLP/opus-mt-en-fr"),
            'fr-en': pipeline("translation_fr_to_en", model="Helsinki-NLP/opus-mt-fr-en"),
            'en-es': pipeline("translation_en_to_es", model="Helsinki-NLP/opus-mt-en-es"),
            'es-en': pipeline("translation_es_to_en", model="Helsinki-NLP/opus-mt-es-en"),
        }

    def translate(self, text, source_lang="en", target_lang="fr"):
        """Translate text between languages"""
        model_key = f"{source_lang}-{target_lang}"

        if model_key not in self.translators:
            return f"Translation from {source_lang} to {target_lang} not supported."

        translator = self.translators[model_key]
        result = translator(text)[0]['translation_text']

        return result

    def detect_language(self, text):
        """Simple language detection (you could use a dedicated model)"""
        # This is a simplified example - in practice, use a proper language detection model
        indicators = {
            'es': ['el', 'la', 'los', 'las', 'es', 'son'],
            'fr': ['le', 'la', 'les', 'et', 'est', 'sont'],
        }

        for lang, words in indicators.items():
            if any(word in text.lower().split() for word in words):
                return lang

        return 'en'  # Default to English

# Usage
translator = MultilingualTranslator()

text = "Hello, how are you today?"
translated = translator.translate(text, "en", "fr")
print(f"English: {text}")
print(f"French: {translated}")

Configuration and Optimization

Basic Configuration

from transformers import pipeline

# Configure pipeline with custom settings
sentiment_analyzer = pipeline(
    "sentiment-analysis",
    model="nlptown/bert-base-multilingual-uncased-sentiment",
    tokenizer="nlptown/bert-base-multilingual-uncased-sentiment",
    device=0,  # Use GPU if available
    batch_size=8,
    return_all_scores=True
)

# Analyze with detailed output
results = sentiment_analyzer("This product is amazing!")
for result in results[0]:
    print(".3f")

Environment Configuration

# .env file
TRANSFORMERS_CACHE_DIR=./cache
HF_HOME=./huggingface
CUDA_VISIBLE_DEVICES=0
PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512

# Optional: HuggingFace Hub settings
HF_TOKEN=your-huggingface-token
HF_HUB_ENABLE_HF_TRANSFER=1

Performance Optimization

import torch
from transformers import pipeline

# Enable GPU acceleration
device = 0 if torch.cuda.is_available() else -1

# Optimized pipeline
sentiment_analyzer = pipeline(
    "sentiment-analysis",
    model="distilbert-base-uncased-finetuned-sst-2-english",
    device=device,
    batch_size=16,
    use_fast=True,  # Use fast tokenizers
    torch_dtype=torch.float16 if device != -1 else torch.float32  # Use half precision on GPU
)

# Process multiple texts efficiently
texts = ["Great product!", "Terrible service.", "Okay experience."]
results = sentiment_analyzer(texts)

for text, result in zip(texts, results):
    print(f"{text} → {result['label']} ({result['score']:.3f})")

Model Hub Integration

Browsing Models

from huggingface_hub import HfApi

# Connect to HuggingFace Hub
api = HfApi()

# Search for models
models = api.list_models(
    filter="text-classification",
    sort="downloads",
    direction=-1,  # Descending
    limit=10
)

print("Top Text Classification Models:")
for model in models:
    print(f"- {model.id} ({model.downloads} downloads)")

Downloading Custom Models

from transformers import AutoModelForSequenceClassification, AutoTokenizer

# Load a specific model from the hub
model_name = "microsoft/DialoGPT-medium"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)

print(f"Loaded model: {model_name}")
print(f"Model parameters: {sum(p.numel() for p in model.parameters()):,}")

What We've Accomplished

Congratulations! 🎉 You've successfully:

  1. Installed HuggingFace Transformers and set up your development environment
  2. Run your first AI models with just a few lines of code
  3. Explored different AI tasks including sentiment analysis, NER, and Q&A
  4. Built real-world applications like translation and summarization services
  5. Optimized performance with GPU acceleration and batch processing
  6. Integrated with the Model Hub for accessing thousands of models
  7. Configured Transformers for different use cases and requirements

Next Steps

Now that you understand the basics, let's explore specific NLP tasks in detail. In Chapter 2: Text Classification & Analysis, we'll dive into building sophisticated text analysis systems with various classification approaches.

Practice what you've learned:

  1. Create a sentiment analysis tool for social media posts
  2. Build a question-answering system for your documentation
  3. Implement a text summarization service for long articles
  4. Experiment with different models and compare their performance

What kind of AI application would you build first with Transformers? 🤖

What Problem Does This Solve?

Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for pipeline, text, model so behavior stays predictable as complexity grows.

In practical terms, this chapter helps you avoid three common failures:

  • coupling core logic too tightly to one implementation path
  • missing the handoff boundaries between setup, execution, and validation
  • shipping changes without clear rollback or observability strategy

After working through this chapter, you should be able to reason about Chapter 1: Getting Started with HuggingFace Transformers as an operating subsystem inside HuggingFace Transformers Tutorial: Building State-of-the-Art AI Models, with explicit contracts for inputs, state transitions, and outputs.

Use the implementation notes around print, result, sentiment as your checklist when adapting these patterns to your own repository.

How it Works Under the Hood

Under the hood, Chapter 1: Getting Started with HuggingFace Transformers usually follows a repeatable control path:

  1. Context bootstrap: initialize runtime config and prerequisites for pipeline.
  2. Input normalization: shape incoming data so text receives stable contracts.
  3. Core execution: run the main logic branch and propagate intermediate state through model.
  4. Policy and safety checks: enforce limits, auth scopes, and failure boundaries.
  5. Output composition: return canonical result payloads for downstream consumers.
  6. Operational telemetry: emit logs/metrics needed for debugging and performance tuning.

When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.

Source Walkthrough

Use the following upstream sources to verify implementation details while reading this chapter:

  • View Repo Why it matters: authoritative reference on View Repo (github.com).

Suggested trace strategy:

  • search upstream code for pipeline and text to map concrete implementation paths
  • compare docs claims against actual runtime/config code before reusing patterns in production

Chapter Connections