Blaizzy/mlx-vlm

[](https://github.com/Blaizzy/mlx-vlm/actions/workflows/python-publish.yml) # MLX-VLM MLX-VLM 是一个软件包，用于在 Mac 上使用 MLX 对视觉语言模型 和全能模型 (支持音频和视频的 VLM) 进行推理和微调。 ## 目录 - [安装](#installation) - [用法](#usage) - [命令行界面 (CLI)](#command-line-interface-cli) - [使用 Gradio 的聊天界面](#chat-ui-with-gradio) - [Python 脚本](#python-script) - [激活量化 (CUDA)](#activation-quantization-cuda) - [多图像聊天支持](#multi-image-chat-support) - [支持的模型](#supported-models) - [使用示例](#usage-examples) - [特定模型文档](#model-specific-documentation) - [微调](#fine-tuning) ## 特定模型文档 部分模型提供了包含 prompt 格式、示例和最佳实践的详细文档： | 模型 | 文档 | |-------|---------------| | DeepSeek-OCR | [文档](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/deepseekocr/README.md) | | DeepSeek-OCR-2 | [文档](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/deepseekocr_2/README.md) | | DOTS-OCR | [文档](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/dots_ocr/README.md) | | GLM-OCR | [文档](https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/glm_ocr/README.md) | ## 安装 最简单的入门方法是使用 pip 安装 `mlx-vlm` 包： ``` pip install -U mlx-vlm ``` 某些模型（例如 Qwen2-VL）需要来自 `torch` 扩展的额外依赖项： ``` pip install -U mlx-vlm[torch] ``` 这将安装 `torch`、`torchvision` 以及某些模型处理器所需的其他依赖项。 ## 用法 ### 命令行界面 (CLI) 使用 CLI 从模型生成输出： ``` # 文本生成 mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "Hello, how are you?" # 图像生成 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 # 音频生成 (新) mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit --max-tokens 100 --prompt "Describe what you hear" --audio /path/to/audio.wav # 多模态生成 (图像 + 音频) 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 ``` ### 使用 Gradio 的聊天界面 使用 Gradio 启动聊天界面： ``` mlx_vlm.chat_ui --model mlx-community/Qwen2-VL-2B-Instruct-4bit ``` ### Python 脚本 以下是如何在 Python 脚本中使用 MLX-VLM 的示例： ``` 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 # 加载模型 model_path = "mlx-community/Qwen2-VL-2B-Instruct-4bit" model, processor = load(model_path) config = load_config(model_path) # 准备输入 image = ["http://images.cocodataset.org/val2017/000000039769.jpg"] # image = [Image.open("...")] 也可以与 PIL.Image.Image 对象一起使用 prompt = "Describe this image." # 应用 chat template formatted_prompt = apply_chat_template( processor, config, prompt, num_images=len(image) ) # 生成输出 output = generate(model, processor, formatted_prompt, image, verbose=False) print(output) ``` #### 音频示例 ``` 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/gemma-3n-E2B-it-4bit" model, processor = load(model_path) config = model.config # 准备音频输入 audio = ["/path/to/audio1.wav", "/path/to/audio2.mp3"] prompt = "Describe what you hear in these audio files." # 应用带音频的 chat template formatted_prompt = apply_chat_template( processor, config, prompt, num_audios=len(audio) ) # 生成带音频的输出 output = generate(model, processor, formatted_prompt, audio=audio, verbose=False) print(output) ``` #### 多模态示例 (图像 + 音频) ``` 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/gemma-3n-E2B-it-4bit" model, processor = load(model_path) config = model.config # 准备输入 image = ["/path/to/image.jpg"] audio = ["/path/to/audio.wav"] prompt = "" # 应用 chat template formatted_prompt = apply_chat_template( processor, config, prompt, num_images=len(image), num_audios=len(audio) ) # 生成输出 output = generate(model, processor, formatted_prompt, image, audio=audio, verbose=False) print(output) ``` ### 服务器 (FastAPI) 启动服务器： ``` mlx_vlm.server --port 8080 # 启用 trust remote code (部分模型需要) mlx_vlm.server --trust-remote-code ``` #### 服务器选项 - `--host`：主机地址 (默认值：`0.0.0.0`) - `--port`：端口号 (默认值：`8080`) - `--trust-remote-code`：从 Hugging Face Hub 加载模型时信任远程代码 您也可以通过环境变量设置信任远程代码： ``` MLX_TRUST_REMOTE_CODE=true mlx_vlm.server ``` 服务器为不同的用例提供多个端点，并支持带有缓存（一次一个模型）的动态模型加载/卸载。 #### 可用端点 - `/models` 和 `/v1/models` - 列出本地可用的模型 - `/chat/completions` 和 `/v1/chat/completions` - 兼容 OpenAI 的聊天式交互端点，支持图像、音频和文本 - `/responses` 和 `/v1/responses` - 兼容 OpenAI 的响应端点 - `/health` - 检查服务器状态 - `/unload` - 从内存中卸载当前模型 #### 使用示例 ##### 列出可用模型 ``` curl "http://localhost:8080/models" ``` ##### 文本输入 ``` 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 }' ``` ##### 图像输入 ``` 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 }' ``` ##### 音频支持 (新增) ``` 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 }' ``` ##### 多模态 (图像 + 音频) ``` 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 }' ``` ##### 响应端点 ``` 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 }' ``` #### 请求参数 - `model`：模型标识符 (必填) - `messages`：用于 chat/OpenAI 端点的聊天消息 - `max_tokens`：生成的最大 token 数 - `temperature`：采样温度 - `top_p`：Top-p 采样参数 - `stream`：启用流式响应 ## 激活量化 (CUDA) 在 NVIDIA GPU 上使用 MLX CUDA 运行时，使用 `mxfp8` 或 `nvfp4` 模式量化的模型需要激活量化才能正常工作。这将把 `QuantizedLinear` 层转换为 `QQLinear` 层，从而对权重和激活进行量化。 ### 命令行 使用 `-qa` 或 `--quantize-activations` 标志： ``` mlx_vlm.generate --model /path/to/mxfp8-model --prompt "Describe this image" --image /path/to/image.jpg -qa ``` ### Python API 将 `quantize_activations=True` 传递给 `load` 函数： ``` from mlx_vlm import load, generate # 加载并启用 activation quantization model, processor = load( "path/to/mxfp8-quantized-model", quantize_activations=True ) # 照常生成 output = generate(model, processor, "Describe this image", image=["image.jpg"]) ``` ### 支持的量化模式 - `mxfp8` - 8 位 MX 浮点 - `nvfp4` - 4 位 NVIDIA 浮点 ## 多图像聊天支持 MLX-VLM 支持使用特定模型同时分析多张图像。此功能支持在单个对话中对多张图像进行更复杂的视觉推理任务和综合分析。 ### 使用示例 #### 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) ``` #### 命令行 ``` 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 ``` ## 视频理解 MLX-VLM 还支持使用特定模型进行视频分析，例如字幕生成、摘要等。 ### 支持的模型 以下模型支持视频聊天： 1. Qwen2-VL 2. Qwen2.5-VL 3. Idefics3 4. LLaVA 更多模型即将推出。 ### 使用示例 #### 命令行 ``` 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 ``` 这些示例演示了如何使用 MLX-VLM 处理多张图像以执行更复杂的视觉推理任务。 # 微调 MLX-VLM 支持使用 LoRA 和 QLoRA 微调模型。 ## LoRA & QLoRA 要了解更多关于 LoRA 的信息，请参阅 [LoRA.md](./mlx_vlm/LORA.MD) 文件。

标签：Apex, DeepSeek, DLL 劫持, Gradio, IaC 扫描, MacOS, MLX, OCR, Python, Qwen2-VL, VLM, 人工智能, 光学字符识别, 凭据扫描, 多模态模型, 大语言模型, 开源库, 搜索引擎爬虫, 无后门, 本地部署, 机器学习, 模型微调, 模型推理, 深度学习, 熵值分析, 用户模式Hook绕过, 苹果芯片, 视觉语言模型, 计算机视觉, 逆向工具, 量化