ModelForge 🔧⚡

Fine-tune LLMs on your laptop's GPU—no code, no PhD, no hassle.

ModelForge v3 is a complete architectural overhaul bringing 2x faster training, modular providers, advanced strategies, and production-ready code quality.

✨ What's New in v3

• 🚀 2x Faster Training with Unsloth provider
• 🧩 Multiple Providers: HuggingFace, Unsloth (more coming!)
• 🎯 Advanced Strategies: SFT, QLoRA, RLHF, DPO
• 📊 Built-in Evaluation with task-specific metrics
• 🖥️ Interactive CLI Wizard (modelforge cli) for headless/SSH environments
• 📦 Optional Quantization — bitsandbytes moved to [quantization] extra

See What's New in v3 →

🚀 Features

• GPU-Powered Fine-Tuning: Optimized for NVIDIA GPUs (even 4GB VRAM) and Apple Silicon (MPS)
• One-Click Workflow: Upload data → Configure → Train → Test
• Hardware-Aware: Auto-detects GPU (CUDA or MPS) and recommends optimal settings
• No-Code UI: Beautiful React interface, or use the CLI wizard for headless environments
• Multiple Providers: HuggingFace (standard, works on CUDA + MPS) or Unsloth (2x faster, CUDA only)
• Advanced Strategies: SFT, QLoRA, RLHF, DPO support
• Automatic Evaluation: Built-in metrics for all tasks

📖 Supported Tasks

• Text Generation: Chatbots, instruction following, code generation, creative writing
• Summarization: Document condensing, article summarization, meeting notes
• Question Answering: RAG systems, document search, FAQ bots

🎯 Quick Start

Prerequisites

• Python 3.11.x (Python 3.12 not yet supported)
• GPU with 4GB+ VRAM:
  • NVIDIA GPU (6GB+ recommended) for CUDA-accelerated training with Unsloth support
  • OR Apple Silicon (M1/M2/M3/M4/M5) for MPS-accelerated training (HuggingFace provider only, experimental)
• CUDA (for NVIDIA GPUs) - Installation Guide
• HuggingFace Account with access token (Get one here)
• Linux, Windows, or macOS operating system

Apple Silicon Users: ModelForge now has experimental support for Apple Silicon Macs with MPS (Metal Performance Shaders). See macOS MPS Installation Guide for setup instructions and limitations (HuggingFace provider only, no quantization support).

Windows Users: See Windows Installation Guide for platform-specific instructions, especially for Unsloth support.

Installation

# Install ModelForge
pip install modelforge-finetuning

# Optional extras
pip install modelforge-finetuning[cli]           # CLI wizard
pip install modelforge-finetuning[quantization]   # 4-bit/8-bit quantization

# Install PyTorch with CUDA support
# Visit https://pytorch.org/get-started/locally/ for your CUDA version
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

Set HuggingFace Token

Linux:

export HUGGINGFACE_TOKEN=your_token_here

Windows PowerShell:

$env:HUGGINGFACE_TOKEN="your_token_here"

Or use .env file:

echo "HUGGINGFACE_TOKEN=your_token_here" > .env

Run ModelForge

modelforge          # Launch web UI
modelforge cli      # Launch CLI wizard (headless/SSH)

Open your browser to http://localhost:8000 and start training!

Full Quick Start Guide →

📚 Documentation

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• What's New in v3 - Major features and improvements

Installation

• Windows Installation - Complete Windows setup (including WSL and Docker)
• Linux Installation - Linux setup guide
• macOS (Apple Silicon) Installation - Setup for M1/M2/M3/M4/M5 Macs with MPS support
• Post-Installation - Initial configuration

Configuration & Usage

• Configuration Guide - All configuration options
• Dataset Formats - Preparing your training data
• Training Tasks - Understanding different tasks
• Hardware Profiles - Optimizing for your GPU

Providers

• Provider Overview - Understanding providers
• HuggingFace Provider - Standard HuggingFace models
• Unsloth Provider - 2x faster training

Training Strategies

• Strategy Overview - Understanding strategies
• SFT Strategy - Standard supervised fine-tuning
• QLoRA Strategy - Memory-efficient training
• RLHF Strategy - Reinforcement learning
• DPO Strategy - Direct preference optimization

API Reference

• REST API - Complete API documentation
• Training Config Schema - Configuration options

Troubleshooting

• Common Issues - Frequently encountered problems
• Windows Issues - Windows-specific troubleshooting
• FAQ - Frequently asked questions

Contributing

• Contributing Guide - How to contribute
• Architecture - Understanding the codebase
• Model Configurations - Adding model recommendations

📖 Full Documentation Index →

🔧 Platform Support

Platform	HuggingFace Provider	Unsloth Provider	Notes
Linux (Native)	✅ Full support	✅ Full support	Recommended for best performance
Windows (Native)	✅ Full support	❌ Not supported	Use WSL or Docker for Unsloth
WSL 2	✅ Full support	✅ Full support	Recommended for Windows users
Docker	✅ Full support	✅ Full support	With NVIDIA runtime
macOS (Apple MPS)	✅ Experimental	❌ Not supported	Requires PyTorch MPS; no bitsandbytes / Unsloth; smaller models recommended

Platform-Specific Installation Guides →

⚠️ Important Notes

Windows Users

Unsloth provider is NOT supported on native Windows. For 2x faster training with Unsloth:

1. Option 1: WSL (Recommended) - WSL Installation Guide
2. Option 2: Docker - Docker Installation Guide

The HuggingFace provider works perfectly on native Windows.

Unsloth Constraints

When using Unsloth provider, you MUST specify a fixed max_sequence_length:

{
  "provider": "unsloth",
  "max_seq_length": 2048  // ✅ Required - cannot be -1
}

Auto-inference (max_seq_length: -1) is NOT supported with Unsloth.

Learn more about Unsloth →

📂 Dataset Format

ModelForge uses JSONL format. Each task has specific fields:

Text Generation:

{"input": "What is AI?", "output": "AI stands for Artificial Intelligence..."}
{"input": "Explain ML", "output": "Machine Learning is a subset of AI..."}

Summarization:

{"input": "Long article text...", "output": "Short summary."}

Question Answering:

{"context": "Document text...", "question": "What is X?", "answer": "X is..."}

Complete Dataset Format Guide →

🤝 Contributing

We welcome contributions! ModelForge's modular architecture makes it easy to:

• Add new providers - Just 2 files needed
• Add new strategies - Just 2 files needed
• Add model recommendations - Simple JSON configs
• Improve documentation
• Fix bugs and add features

Contributing Guide →

Adding Model Recommendations

ModelForge uses modular configuration files for model recommendations. See the Model Configuration Guide for instructions on adding new recommended models.

🛠 Tech Stack

• Backend: Python, FastAPI, SQLAlchemy
• Frontend: React.js
• ML: PyTorch, Transformers, PEFT, TRL
• Training: LoRA, QLoRA, bitsandbytes (optional)
• Providers: HuggingFace Hub, Unsloth

Results on NVIDIA RTX 3090. Your results may vary.

📜 License

BSD License - see LICENSE file for details.

🙏 Acknowledgments

• HuggingFace for Transformers and model hub
• Unsloth AI for optimized training kernels
• The open-source ML community

📧 Support

• Documentation: https://github.com/forgeopus/modelforge/tree/main/docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• PyPI: modelforge-finetuning

---

ModelForge v3 - Making LLM fine-tuning accessible to everyone 🚀

Get Started → | Documentation → | GitHub →