ARahim3 / mlx-tune

Fine-tune LLMs, Vision, and Audio models on your Mac SFT, DPO, GRPO, Vision, TTS, and STT fine-tuning — natively on MLX. Unsloth-compatible API. Documentation · Quick Start · Training Methods · Examples · Status --- > [!NOTE] > **Name Change**: This project was originally called . Since it's not an official Unsloth project and to avoid any confusion, it has been renamed to . The vision remains the same — bringing the Unsloth experience to Mac users via MLX. If you were using , simply switch to and update your imports from to . > [!NOTE] > **Why I Built This (A Personal Note)** > > I rely on Unsloth for my daily fine-tuning on cloud GPUs—it's the gold standard for me. But recently, I started working on a MacBook M4 and hit a friction point: I wanted to prototype locally on my Mac, then scale up to the cloud without rewriting my entire training script. > > Since Unsloth relies on Triton (which Macs don't have, yet), I couldn't use it locally. I built to solve this specific "Context Switch" problem. It wraps Apple's native MLX framework in an Unsloth-compatible API. > > **The goal isn't to replace Unsloth or claim superior performance.** The goal is **code portability**: allowing you to write code once on your Mac, test it, and then push that *exact same script* to a CUDA cluster. It solves a workflow problem, not just a hardware one. > > This is an "unofficial" project built by a fan, for fans who happen to use Macs. It's helping me personally, and if it helps others like me, then I'll have my satisfaction. Why MLX-Tune? Bringing the Unsloth experience to Mac users via Apple's MLX framework. • 🚀 **Fine-tune LLMs, VLMs, TTS & STT** locally on your Mac (M1/M2/M3/M4/M5) • 💾 **Leverage unified memory** (up to 512GB on Mac Studio) • 🔄 **Unsloth-compatible API** - your existing training scripts just work! • 📦 **Export anywhere** - HuggingFace format, GGUF for Ollama/llama.cpp • 🎙️ **Audio fine-tuning** - Orpheus TTS (SNAC codec) + Whisper STT What This Is (and Isn't) **This is NOT** a replacement for Unsloth or an attempt to compete with it. Unsloth is incredible - it's the gold standard for efficient LLM fine-tuning on CUDA. **This IS** a bridge for Mac users who want to: • 🧪 **Prototype locally** - Experiment with fine-tuning before committing to cloud GPU costs • 📚 **Learn & iterate** - Develop your training pipeline with fast local feedback loops • 🔄 **Then scale up** - Move to cloud NVIDIA GPUs + original Unsloth for production training Project Status > 🚀 **v0.4.7** - Audio fine-tuning (TTS + STT), post-training workflow, track-based docs | Feature | Status | Notes | |---------|--------|-------| | SFT Training | ✅ Stable | Native MLX training | | Model Loading | ✅ Stable | Any HuggingFace model (quantized & non-quantized) | | Save/Export | ✅ Stable | HF format, GGUF (see limitations) | | DPO Training | ✅ Stable | **Full DPO loss** | | ORPO Training | ✅ Stable | **Full ORPO loss** | | GRPO Training | ✅ Stable | **Multi-generation + reward** | | KTO/SimPO | ✅ Stable | Proper loss implementations | | Chat Templates | ✅ Stable | 15 models (llama, gemma, qwen, phi, mistral) | | Response-Only Training | ✅ Stable | | | Multi-turn Merging | ✅ Stable | + | | Column Mapping | ✅ Stable | auto-rename | | Dataset Config | ✅ Stable | structured loading | | Vision Models | ✅ Stable | Full VLM fine-tuning via mlx-vlm | | **TTS Fine-Tuning** | ✅ **NEW** | **Orpheus-3B via SNAC audio codec** | | **STT Fine-Tuning** | ✅ **NEW** | **Whisper with encoder-decoder LoRA** | | ** ** | ✅ **NEW** | **HF → MLX conversion (LLM, TTS, STT)** | | ** ** | ✅ **NEW** | **Upload to HuggingFace Hub** | | PyPI Package | ✅ Available | | Installation Quick Start > [!NOTE] > **GGUF Export**: Works with non-quantized base models. If using a 4-bit model (like above), > see Known Limitations for workarounds. Chat Templates & Response-Only Training Vision Model Fine-Tuning (NEW!) Fine-tune vision-language models like Qwen3.5 on image+text tasks: See for the full workflow, or for text-only fine-tuning on Qwen3.5. TTS Fine-Tuning (NEW!) Fine-tune text-to-speech models like Orpheus-3B using the SNAC audio codec: See for the full workflow. STT Fine-Tuning (NEW!) Fine-tune Whisper speech-to-text models with encoder-decoder LoRA: See for the full workflow. Post-Training Workflow All model types (LLM, VLM, TTS, STT) support the full post-training workflow: Supported Training Methods | Method | Trainer | Implementation | Use Case | |--------|---------|----------------|----------| | **SFT** | | ✅ Native MLX | Instruction fine-tuning | | **DPO** | | ✅ Native MLX | Preference learning (proper log-prob loss) | | **ORPO** | | ✅ Native MLX | Combined SFT + odds ratio preference | | **GRPO** | | ✅ Native MLX | Reasoning with multi-generation (DeepSeek R1 style) | | **KTO** | | ✅ Native MLX | Kahneman-Tversky optimization | | **SimPO** | | ✅ Native MLX | Simple preference optimization | | **VLM SFT** | | ✅ Native MLX | Vision-Language model fine-tuning | | **TTS SFT** | | ✅ Native MLX | Text-to-Speech (Orpheus + SNAC codec) | | **STT SFT** | | ✅ Native MLX | Speech-to-Text (Whisper encoder-decoder) | Examples Check for working code: • Basic model loading and inference (01–07) • Complete SFT fine-tuning pipeline (08) • RL training methods — DPO, GRPO, ORPO (09) • Vision model fine-tuning — Qwen3.5 (10–11) • TTS fine-tuning — Orpheus-3B (12) • STT fine-tuning — Whisper (13) Requirements • **Hardware**: Apple Silicon Mac (M1/M2/M3/M4/M5) • **OS**: macOS 13.0+ • **Memory**: 8GB+ unified RAM (16GB+ recommended) • **Python**: 3.9+ Comparison with Unsloth | Feature | Unsloth (CUDA) | MLX-Tune | |---------|----------------|----------| | Platform | NVIDIA GPUs | Apple Silicon | | Backend | Triton Kernels | MLX Framework | | Memory | VRAM (limited) | Unified (up to 512GB) | | API | Original | 100% Compatible | | Best For | Production training | Local dev, large models | Known Limitations GGUF Export from Quant…