Hugging Face Transformers Project

A comprehensive project for working with Hugging Face Transformers library, including sentiment analysis, zero-shot classification, speech recognition, tokenization, and model loading capabilities.

📋 Table of Contents

Prerequisites
Quick Start
Installation Methods
- Method 1: Local Development (Virtual Environment)
- Method 2: Docker (Recommended)
Project Structure
Usage
Features
Development
Troubleshooting

Prerequisites

System Requirements

Python: 3.11 or higher
Operating System: Linux (Ubuntu/Debian recommended), macOS, or Windows
Docker (optional, for containerized deployment): Docker 20.10+
Disk Space: At least 5GB free (for models and dependencies)

System Dependencies

For audio processing (speech recognition):

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y ffmpeg

# macOS
brew install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

Quick Start

Using Docker (Recommended)

# Build and run with auto-reload
docker-compose build
docker-compose up

# Or use the helper script
./scripts/run-dev.sh

Using Local Python

# Run installation script
./scripts/install.sh

# Or manually
python3 -m venv venv
source venv/bin/activate
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
python src/main.py

For detailed instructions, see INSTALL.md.

Installation Methods

Method 1: Local Development (Virtual Environment)

Step 1: Clone or Navigate to Project Directory

cd /path/to/transformers

Step 2: Create Virtual Environment

python3 -m venv venv

Step 3: Activate Virtual Environment

# Linux/macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

Step 4: Install Python Dependencies

# Upgrade pip
pip install --upgrade pip

# Install PyTorch (CPU version - smaller download)
pip install torch --index-url https://download.pytorch.org/whl/cpu

# Install other dependencies
pip install -r requirements.txt

Step 5: Verify Installation

python -c "from transformers import pipeline; print('✓ Transformers installed successfully!')"
python -c "import torch; print(f'✓ PyTorch version: {torch.__version__}')"

Step 6: Run the Application

python src/main.py

Method 2: Docker (Recommended)

Docker provides an isolated environment with all dependencies pre-configured.

Step 1: Install Docker

Ubuntu/Debian:

# Install Docker via snap (easiest)
sudo snap install docker

# Or install via apt
sudo apt-get update
sudo apt-get install -y docker.io docker-compose

macOS:

# Install Docker Desktop from https://www.docker.com/products/docker-desktop

Windows:

# Install Docker Desktop from https://www.docker.com/products/docker-desktop

Step 2: Configure Docker Permissions (Linux)

If using snap Docker:

# Enable removable-media access (if project is on external drive)
sudo snap connect docker:removable-media

# Fix socket permissions (if needed)
sudo chmod 666 /var/run/docker.sock

Or add user to docker group:

sudo groupadd docker
sudo usermod -aG docker $USER
# Log out and log back in for changes to take effect

Step 3: Navigate to Project Directory

cd /path/to/transformers

Step 4: Build Docker Image

docker-compose build

This will:

Download Python 3.11 base image
Install system dependencies (ffmpeg)
Install PyTorch (CPU version)
Install transformers and other Python packages
Set up the working environment

Expected output:

[+] Building ...
[+] Building X.Xs (Y/Y) FINISHED

Step 5: Run the Container

docker-compose up

To run in detached mode (background):

docker-compose up -d

To view logs:

docker-compose logs -f

Step 6: Stop the Container

docker-compose down

Project Structure

transformers/
├── src/                     # Source code
│   ├── __init__.py         # Package initialization
│   ├── main.py             # Main entry point
│   └── utils.py            # Utility functions for NLP tasks
├── scripts/                 # Helper scripts
│   ├── install.sh          # Automated installation
│   ├── run-dev.sh          # Development mode runner
│   └── run-prod.sh         # Production mode runner
├── data/                    # Data files
│   └── mlk.flac            # Sample audio file
├── models/                  # Cached Hugging Face models (gitignored)
├── test/                    # Test files
│   └── test_main.py        # Unit tests
├── Dockerfile               # Docker image configuration
├── docker-compose.yml       # Docker Compose (production)
├── docker-compose.dev.yml   # Docker Compose (development)
├── watch.py                # File watcher for auto-reload
├── requirements.txt         # Python dependencies
├── README.md                # Main documentation
├── INSTALL.md              # Installation guide
├── AUTO_RELOAD.md          # Auto-reload documentation
└── PROJECT_STRUCTURE.md    # Project structure details

For detailed structure information, see PROJECT_STRUCTURE.md.

Usage

Running Different Functions

Edit src/main.py to uncomment and use different functions:

import utils

# Sentiment Analysis
utils.sentiment_analysis([
    "I am feeling very happy",
    "I am feeling very sad"
])

# Zero-shot Classification
utils.zero_shot_classification("I am feeling very hopeless about my life")

# Speech Recognition (local file)
utils.speech_recognition("data/mlk.flac")

# Speech Recognition (from URL)
utils.speech_recognition("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")

# Fill-mask (find masking words)
utils.find_masking_words()

# Tokenization
utils.tokenize_text("I am feeling very hopeless")
utils.tokenize_text_batch(["I am feeling very hopeless", "I am feeling very hopeful"])

# Load Model
model = utils.load_model("distilbert-base-uncased-finetuned-sst-2-english")
model, tokenizer = utils.load_model_and_tokenizer()

Features

1. Sentiment Analysis

Analyze the sentiment (positive/negative) of text using pre-trained models.

2. Zero-Shot Classification

Classify text into custom categories without training.

3. Speech Recognition

Transcribe audio files to text using Whisper models.

4. Fill-Mask

Predict masked words in sentences using BERT models.

5. Tokenization

Tokenize text for model input using AutoTokenizer.

6. Model Loading

Load pre-trained models and tokenizers using AutoModel and AutoTokenizer.

Development

Auto-Reload in Docker

The project includes automatic reload functionality when running in Docker. Any changes to Python files in src/ will automatically restart the application.

# Development mode with auto-reload (default)
docker-compose up

# Or use helper script
./scripts/run-dev.sh

# Production mode (no auto-reload)
./scripts/run-prod.sh

For more details, see AUTO_RELOAD.md.

Running Tests

# Activate virtual environment
source venv/bin/activate

# Run tests
python -m pytest test/

Code Style

The project follows PEP 8 style guidelines. Consider using:

black for code formatting
flake8 for linting
mypy for type checking

Troubleshooting

Issue: Import "transformers" could not be resolved

Solution:

# Make sure virtual environment is activated
source venv/bin/activate

# Install dependencies
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt

Issue: FileNotFoundError for audio files

Solution:

Ensure the file path is correct relative to project root
For URLs, the function will download automatically
Check file permissions

Issue: Docker permission denied

Solution:

# Fix Docker socket permissions
sudo chmod 666 /var/run/docker.sock

# Or use sudo
sudo docker-compose up

Issue: ffmpeg not found (for speech recognition)

Solution:

# Ubuntu/Debian
sudo apt-get install ffmpeg

# macOS
brew install ffmpeg

Issue: Docker build fails - image not found

Solution:

Check internet connection
Verify Docker is running: docker ps
Try pulling base image manually: docker pull python:3.11-slim

Issue: Out of memory errors

Solution:

Reduce shm_size in docker-compose.yml (currently 16gb)
Use smaller models
Process data in batches

Issue: Models download slowly

Solution:

Models are cached in ./models directory
First download may take time
Subsequent runs use cached models

GPU Support (Optional)

NVIDIA GPU (CUDA)

Install NVIDIA Docker support:

# Ubuntu
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

Update Dockerfile:

# Replace CPU PyTorch with CUDA version
RUN pip3 install --no-cache-dir torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Update docker-compose.yml:

runtime: nvidia
environment:
  - NVIDIA_VISIBLE_DEVICES=all

AMD GPU (ROCm)

Install ROCm drivers on host system
Update Dockerfile to use ROCm PyTorch
Uncomment AMD GPU section in docker-compose.yml

Environment Variables

TRANSFORMERS_CACHE: Directory for caching models (default: /models in Docker)
HF_HOME: Hugging Face home directory (default: /models in Docker)

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

License

This project uses the Hugging Face Transformers library, which is licensed under Apache 2.0.

Resources

Support

For issues and questions:

Check the Troubleshooting section
Review Hugging Face Transformers documentation
Open an issue on the project repository

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
data		data
scripts		scripts
src		src
test		test
.gitignore		.gitignore
.gitignoreecho		.gitignoreecho
AUTO_RELOAD.md		AUTO_RELOAD.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
INSTALL.md		INSTALL.md
PROJECT_STRUCTURE.md		PROJECT_STRUCTURE.md
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt
watch.py		watch.py

Folders and files

Latest commit

History

Repository files navigation

Hugging Face Transformers Project

📋 Table of Contents

Prerequisites

System Requirements

System Dependencies

Quick Start

Using Docker (Recommended)

Using Local Python

Installation Methods

Method 1: Local Development (Virtual Environment)

Step 1: Clone or Navigate to Project Directory

Step 2: Create Virtual Environment

Step 3: Activate Virtual Environment

Step 4: Install Python Dependencies

Step 5: Verify Installation

Step 6: Run the Application

Method 2: Docker (Recommended)

Step 1: Install Docker

Step 2: Configure Docker Permissions (Linux)

Step 3: Navigate to Project Directory

Step 4: Build Docker Image

Step 5: Run the Container

Step 6: Stop the Container

Project Structure

Usage

Running Different Functions

Features

1. Sentiment Analysis

2. Zero-Shot Classification

3. Speech Recognition

4. Fill-Mask

5. Tokenization

6. Model Loading

Development

Auto-Reload in Docker

Running Tests

Code Style

Troubleshooting

Issue: Import "transformers" could not be resolved

Issue: FileNotFoundError for audio files

Issue: Docker permission denied

Issue: ffmpeg not found (for speech recognition)

Issue: Docker build fails - image not found

Issue: Out of memory errors

Issue: Models download slowly

GPU Support (Optional)

NVIDIA GPU (CUDA)

AMD GPU (ROCm)

Environment Variables

Contributing

License

Resources

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages