base on MLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX. [](https://github.com/Blaizzy/mlx-vlm/actions/workflows/python-publish.yml) # MLX-VLM MLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) and Omni Models (VLMs with audio and video support) on your Mac using MLX. ## Table of Contents - [Installation](#installation) - [Usage](#usage) - [Command Line Interface (CLI)](#command-line-interface-cli) - [Thinking Budget](#thinking-budget) - [Chat UI with Gradio](#chat-ui-with-gradio) - [Python Script](#python-script) - [Activation Quantization (CUDA)](#activation-quantization-cuda) - [Multi-Image Chat Support](#multi-image-chat-support) - [Supported Models](#supported-models) - [Usage Examples](#usage-examples) - [Model-Specific Documentation](#model-specific-documentation) - [Fine-tuning](#fine-tuning) ## Model-Specific Documentation Some models have detailed documentation with prompt formats, examples, and best practices: | Model | Documentation | |-------|---------------| | DeepSeek-OCR | [Docs](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/deepseekocr/README.md) | | DeepSeek-OCR-2 | [Docs](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/deepseekocr_2/README.md) | | DOTS-OCR | [Docs](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/dots_ocr/README.md) | | GLM-OCR | [Docs](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/glm_ocr/README.md) | | Phi-4 Reasoning Vision | [Docs](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/phi4_siglip/README.md) | | MiniCPM-o | [Docs](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/minicpmo/README.md) | | Phi-4 Multimodal | [Docs](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/phi4mm/README.md) | | Moondream3 | [Docs](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/moondream3/README.md) | ## Installation The easiest way to get started is to install the `mlx-vlm` package using pip: ```sh pip install -U mlx-vlm ``` Some models (e.g., Qwen2-VL) require additional dependencies from the `torch` extra: ```sh pip install -U mlx-vlm[torch] ``` This installs `torch`, `torchvision`, and other dependencies needed by certain model processors. ## Usage ### Command Line Interface (CLI) Generate output from a model using the CLI: ```sh # Text generation mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "Hello, how are you?" # Image generation mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --temperature 0.0 --image http://images.cocodataset.org/val2017/000000039769.jpg # Audio generation (New) mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit --max-tokens 100 --prompt "Describe what you hear" --audio /path/to/audio.wav # Multi-modal generation (Image + Audio) mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit --max-tokens 100 --prompt "Describe what you see and hear" --image /path/to/image.jpg --audio /path/to/audio.wav ``` #### Thinking Budget For thinking models (e.g., Qwen3.5), you can limit the number of tokens spent in the thinking block: ```sh mlx_vlm.generate --model mlx-community/Qwen3.5-2B-4bit \ --thinking-budget 50 \ --thinking-start-token "<think>" \ --thinking-end-token "</think>" \ --enable-thinking \ --prompt "Solve 2+2" ``` | Flag | Description | |------|-------------| | `--enable-thinking` | Activate thinking mode in the chat template | | `--thinking-budget` | Max tokens allowed inside the thinking block | | `--thinking-start-token` | Token that opens a thinking block (default: `<think>`) | | `--thinking-end-token` | Token that closes a thinking block (default: `</think>`) | When the budget is exceeded, the model is forced to emit `\n</think>` and transition to the answer. If `--enable-thinking` is passed but the model's chat template does not support it, the budget is applied only if the model generates the start token on its own. ### Chat UI with Gradio Launch a chat interface using Gradio: ```sh mlx_vlm.chat_ui --model mlx-community/Qwen2-VL-2B-Instruct-4bit ``` ### Python Script Here's an example of how to use MLX-VLM in a Python script: ```python import mlx.core as mx from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template from mlx_vlm.utils import load_config # Load the model model_path = "mlx-community/Qwen2-VL-2B-Instruct-4bit" model, processor = load(model_path) config = load_config(model_path) # Prepare input image = ["http://images.cocodataset.org/val2017/000000039769.jpg"] # image = [Image.open("...")] can also be used with PIL.Image.Image objects prompt = "Describe this image." # Apply chat template formatted_prompt = apply_chat_template( processor, config, prompt, num_images=len(image) ) # Generate output output = generate(model, processor, formatted_prompt, image, verbose=False) print(output) ``` #### Audio Example ```python from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template from mlx_vlm.utils import load_config # Load model with audio support model_path = "mlx-community/gemma-3n-E2B-it-4bit" model, processor = load(model_path) config = model.config # Prepare audio input audio = ["/path/to/audio1.wav", "/path/to/audio2.mp3"] prompt = "Describe what you hear in these audio files." # Apply chat template with audio formatted_prompt = apply_chat_template( processor, config, prompt, num_audios=len(audio) ) # Generate output with audio output = generate(model, processor, formatted_prompt, audio=audio, verbose=False) print(output) ``` #### Multi-Modal Example (Image + Audio) ```python from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template from mlx_vlm.utils import load_config # Load multi-modal model model_path = "mlx-community/gemma-3n-E2B-it-4bit" model, processor = load(model_path) config = model.config # Prepare inputs image = ["/path/to/image.jpg"] audio = ["/path/to/audio.wav"] prompt = "" # Apply chat template formatted_prompt = apply_chat_template( processor, config, prompt, num_images=len(image), num_audios=len(audio) ) # Generate output output = generate(model, processor, formatted_prompt, image, audio=audio, verbose=False) print(output) ``` ### Server (FastAPI) Start the server: ```sh mlx_vlm.server --port 8080 # Preload a model at startup (Hugging Face repo or local path) mlx_vlm.server --model <hf_repo_or_local_path> # Preload a model with adapter mlx_vlm.server --model <hf_repo_or_local_path> --adapter-path <adapter_path> # With trust remote code enabled (required for some models) mlx_vlm.server --trust-remote-code ``` #### Server Options - `--model`: Preload a model at server startup, accepts a Hugging Face repo ID or local path (optional, loads lazily on first request if omitted) - `--adapter-path`: Path for adapter weights to use with the preloaded model - `--host`: Host address (default: `0.0.0.0`) - `--port`: Port number (default: `8080`) - `--trust-remote-code`: Trust remote code when loading models from Hugging Face Hub You can also set trust remote code via environment variable: ```sh MLX_TRUST_REMOTE_CODE=true mlx_vlm.server ``` The server provides multiple endpoints for different use cases and supports dynamic model loading/unloading with caching (one model at a time). #### Available Endpoints - `/models` and `/v1/models` - List models available locally - `/chat/completions` and `/v1/chat/completions` - OpenAI-compatible chat-style interaction endpoint with support for images, audio, and text - `/responses` and `/v1/responses` - OpenAI-compatible responses endpoint - `/health` - Check server status - `/unload` - Unload current model from memory #### Usage Examples ##### List available models ```sh curl "http://localhost:8080/models" ``` ##### Text Input ```sh curl -X POST "http://localhost:8080/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "mlx-community/Qwen2-VL-2B-Instruct-4bit", "messages": [ { "role": "user", "content": "Hello, how are you" } ], "stream": true, "max_tokens": 100 }' ``` ##### Image Input ```sh curl -X POST "http://localhost:8080/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "mlx-community/Qwen2.5-VL-32B-Instruct-8bit", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": [ { "type": "text", "text": "This is today's chart for energy demand in California. Can you provide an analysis of the chart and comment on the implications for renewable energy in California?" }, { "type": "input_image", "image_url": "/path/to/repo/examples/images/renewables_california.png" } ] } ], "stream": true, "max_tokens": 1000 }' ``` ##### Audio Support (New) ```sh curl -X POST "http://localhost:8080/generate" \ -H "Content-Type: application/json" \ -d '{ "model": "mlx-community/gemma-3n-E2B-it-4bit", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe what you hear in these audio files" }, { "type": "input_audio", "input_audio": "/path/to/audio1.wav" }, { "type": "input_audio", "input_audio": "https://example.com/audio2.mp3" } ] } ], "stream": true, "max_tokens": 500 }' ``` ##### Multi-Modal (Image + Audio) ```sh curl -X POST "http://localhost:8080/generate" \ -H "Content-Type: application/json" \ -d '{ "model": "mlx-community/gemma-3n-E2B-it-4bit", "messages": [ { "role": "user", "content": [ {"type": "input_image", "image_url": "/path/to/image.jpg"}, {"type": "input_audio", "input_audio": "/path/to/audio.wav"} ] } ], "max_tokens": 100 }' ``` ##### Responses Endpoint ```sh curl -X POST "http://localhost:8080/responses" \ -H "Content-Type: application/json" \ -d '{ "model": "mlx-community/Qwen2-VL-2B-Instruct-4bit", "messages": [ { "role": "user", "content": [ {"type": "input_text", "text": "What is in this image?"}, {"type": "input_image", "image_url": "/path/to/image.jpg"} ] } ], "max_tokens": 100 }' ``` #### Request Parameters - `model`: Model identifier (required) - `messages`: Chat messages for chat/OpenAI endpoints - `max_tokens`: Maximum tokens to generate - `temperature`: Sampling temperature - `top_p`: Top-p sampling parameter - `top_k`: Top-k sampling cutoff - `min_p`: Min-p sampling threshold - `repetition_penalty`: Penalty applied to repeated tokens - `stream`: Enable streaming responses ## Activation Quantization (CUDA) When running on NVIDIA GPUs with MLX CUDA, models quantized with `mxfp8` or `nvfp4` modes require activation quantization to work properly. This converts `QuantizedLinear` layers to `QQLinear` layers which quantize both weights and activations. ### Command Line Use the `-qa` or `--quantize-activations` flag: ```sh mlx_vlm.generate --model /path/to/mxfp8-model --prompt "Describe this image" --image /path/to/image.jpg -qa ``` ### Python API Pass `quantize_activations=True` to the `load` function: ```python from mlx_vlm import load, generate # Load with activation quantization enabled model, processor = load( "path/to/mxfp8-quantized-model", quantize_activations=True ) # Generate as usual output = generate(model, processor, "Describe this image", image=["image.jpg"]) ``` ### Supported Quantization Modes - `mxfp8` - 8-bit MX floating point - `nvfp4` - 4-bit NVIDIA floating point > **Note**: This feature is required for mxfp/nvfp quantized models on CUDA. On Apple Silicon (Metal), these models work without the flag. ## Multi-Image Chat Support MLX-VLM supports analyzing multiple images simultaneously with select models. This feature enables more complex visual reasoning tasks and comprehensive analysis across multiple images in a single conversation. ### Usage Examples #### Python Script ```python from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template from mlx_vlm.utils import load_config model_path = "mlx-community/Qwen2-VL-2B-Instruct-4bit" model, processor = load(model_path) config = model.config images = ["path/to/image1.jpg", "path/to/image2.jpg"] prompt = "Compare these two images." formatted_prompt = apply_chat_template( processor, config, prompt, num_images=len(images) ) output = generate(model, processor, formatted_prompt, images, verbose=False) print(output) ``` #### Command Line ```sh mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "Compare these images" --image path/to/image1.jpg path/to/image2.jpg ``` ## Video Understanding MLX-VLM also supports video analysis such as captioning, summarization, and more, with select models. ### Supported Models The following models support video chat: 1. Qwen2-VL 2. Qwen2.5-VL 3. Idefics3 4. LLaVA With more coming soon. ### Usage Examples #### Command Line ```sh mlx_vlm.video_generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "Describe this video" --video path/to/video.mp4 --max-pixels 224 224 --fps 1.0 ``` These examples demonstrate how to use multiple images with MLX-VLM for more complex visual reasoning tasks. # Fine-tuning MLX-VLM supports fine-tuning models with LoRA and QLoRA. ## LoRA & QLoRA To learn more about LoRA, please refer to the [LoRA.md](./mlx_vlm/LORA.MD) file. ", Assign "at most 3 tags" to the expected json: {"id":"12887","tags":[]} "only from the tags list I provide: []" returns me the "expected json"