mlx-vlm

环境要求

• Apple Silicon 芯片的 Mac（项目基于 Apple MLX 框架，README 明确说明用于 Mac）
• 已安装 Python 与 pip，可执行 pip install 命令
• 使用 zsh 等会展开方括号的 shell 时，安装带 extras 的包需要加引号
• 首次调用模型需要联网从 Hugging Face 下载权重，需预留磁盘空间

安装与启动步骤

1. 1安装 mlx-vlm

   README 给出的最简安装方式，用 pip 安装并升级到最新版本。

   pip install -U mlx-vlm

   复制

2. 2装 Gradio 界面

   可选。Gradio 聊天界面的依赖不在基础安装中，需要单独安装这个 extra。

   pip install -U 'mlx-vlm[ui]'

   复制

3. 3启动本地服务

   README 正文提供了 Server (FastAPI) 章节，但本次节选未给出启动命令，请以仓库该章节为准，服务默认端口 8080。

4. 4查询模型列表

   服务起来后调用 /models 查看当前可发现的模型。

   curl "http://localhost:8080/models"

   复制

5. 5发送文本对话

   向 /chat/completions 发 POST 请求做纯文本推理，model 换成你本地可用的模型仓库。

   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}'

   复制

6. 6发送图片请求

   把 image_url 换成本地图片路径，即可让视觉语言模型分析图片。

   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 "http://localhost:8080/models" 能返回模型列表，且向 /chat/completions 发请求能收到模型回复，即表示部署成功。

常见问题

注意事项

• 必须在 Apple Silicon Mac 上使用，依赖 Apple MLX 框架。
• Gradio 聊天界面需要额外安装 [ui] extra，且 zsh 下必须加引号。
• 服务默认端口为 8080，示例接口地址均基于 localhost:8080。
• 本次 README 节选未包含 FastAPI 服务的启动命令，请以仓库对应章节为准，不要自行猜测参数。