企业官网建设流程全解析

新手入门 lift-oQ3.5：从零安装 mlx-vlm 运行环境的详细教程

【免费下载链接】lift-oQ3.5项目地址: https://ai.gitcode.com/hf_mirrors/mlx-community/lift-oQ3.5

想要在 Mac 上本地运行视觉大模型？lift-oQ3.5是一款能把 PDF、发票、截图等图片内容自动提取成结构化 JSON 的开源视觉语言模型，配合mlx-vlm运行环境，新手也能在 Apple 芯片上轻松跑起来。本教程将从零开始，带你完成环境安装、模型下载、命令行生成和 API 服务搭建的全部步骤。

lift-oQ3.5 是什么？90 秒看懂这个"文档提取神器" 🧾

lift-oQ3.5 是社区基于 9B 参数的qwen3_5视觉语言模型（VLM）做的 MLX 量化版本，它的核心能力只有一个：看懂图片里的文字，然后按你定义的规则输出 JSON。

简单说，你给它一张发票照片，它能返回这样的结构化数据：

{ "invoice_number": "INV-2026-001", "total": 1280.5, "line_items": [{"description": "键盘", "amount": 899.0}] }

适合处理发票识别、单据录入、合同抽取、表格解析等场景，无需联网、数据不出本机。

oQ3.5 版本为什么值得选？

从表格能看出，oQ3.5 用更小的体积换来了约3.5 倍的速度提升，16GB 内存的 MacBook 也能流畅运行，是入门本地部署的绝佳选择。如果你更在意精度，同一系列还有 oQ4 / oQ5 / oQ6 / oQ8 等版本可以按需挑选。

运行环境要求：需要什么电脑才能跑起来？💻

mlx-vlm 是苹果 MLX 框架的视觉语言模型推理工具，只支持Apple Silicon（M 系列芯片）的 Mac，包括 M1 / M2 / M3 / M4 / M5 全系。

另外建议提前安装好uv（Python 包管理工具），它能让安装过程快到飞起，下文所有命令都基于 uv 编写。

最快安装方法：一键安装 uv 与 mlx-vlm ⚡

第一步：安装 uv

打开终端（Terminal），执行：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后重启终端，输入uv --version能输出版本号即代表成功。

第二步：安装 mlx-vlm

mlx-vlm 是 lift-oQ3.5 的推理引擎，两种方式任选：

方式一（推荐，无需手动装包）：直接用 uvx 运行

uvx --from mlx-vlm mlx_vlm.generate --help

uvx 会自动创建临时环境并下载 mlx-vlm，省去手动管理依赖的麻烦。

方式二（需要频繁开发）：安装到当前环境

uv pip install mlx-vlm

装好后可以用python -c "import mlx_vlm"验证是否安装成功。这一步完成后，运行环境就绪 ✅

下载模型权重：4.9GB 文件清单与本地路径配置 📥

模型权重约 4.9GB，可以直接下载到本地文件夹。有两种方式：

方式一：用 huggingface-cli 下载

huggingface-cli download mlx-community/lift-oQ3.5 --local-dir ./lift-oQ3.5

方式二：直接克隆仓库（国内用户更推荐）

git clone https://gitcode.com/hf_mirrors/mlx-community/lift-oQ3.5

下载完成后，文件夹里应该包含这些关键文件：

💡 小提示：两个 safetensors 分片是模型的主体（约 5GB），下载时务必确认完整，缺一个都会加载失败。

mlx_vlm.generate 命令行生成方法：提取发票 JSON 实操 🚀

模型就绪后，用一条命令即可完成图片信息提取。我们先准备一张invoice.png（发票或单据截图），然后执行：

uvx --from mlx-vlm mlx_vlm.generate \ --model ./lift-oQ3.5 \ --image invoice.png \ --prompt "Extract the invoice as JSON." \ --max-tokens 800

参数说明：

• --model：模型路径（也可以是mlx-community/lift-oQ3.5让它自动下载）
• --image：要识别的图片路径
• --prompt：提取指令，推荐用英文描述任务
• --max-tokens：最大生成长度，发票等单据建议 800 左右

首次运行会先加载模型，之后终端会直接输出结构化的 JSON 结果，全程离线、毫秒级响应，109 t/s 的速度体验非常丝滑 🎉

OpenAI 兼容 API 服务：用 JSON Schema 锁定输出格式 🔧

如果不想每次都在命令行敲参数，可以启动一个 OpenAI 兼容的本地服务，让其他程序通过 HTTP 调用：

uvx --from mlx-vlm mlx_vlm.server \ --model ./lift-oQ3.5 \ --port 8080

服务启动后，mlx_vlm.server会在解码阶段通过 llguidance 强制校验 JSON Schema，保证输出一定是合法且符合类型的 JSON，彻底告别"模型输出格式不稳定"的烦恼。

然后用 Python 调用：

import base64, json from openai import OpenAI client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="local") img = base64.b64encode(open("invoice.png", "rb").read()).decode() schema = { "type": "object", "properties": { "invoice_number": {"type": "string"}, "total": {"type": "number"}, "line_items": {"type": "array", "items": {"type": "object", "properties": { "description": {"type": "string"}, "amount": {"type": "number"}}}}, }, "required": ["invoice_number", "total"], } resp = client.chat.completions.create( model="mlx-community/lift-oQ3.5", messages=[{"role": "user", "content": [ {"type": "text", "text": "Extract this invoice."}, {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img}"}}, ]}], response_format={"type": "json_schema", "json_schema": {"name": "invoice", "schema": schema}}, temperature=0.0, max_tokens=800, ) print(json.loads(resp.choices[0].message.content))

💡 注意：server 会把整个 HuggingFace 缓存都列出来，所以调用时要显式指定模型名，否则可能加载错模型。

新手常见问题与解决技巧 🛠️

1. 模型一直输出<|im_end|>停不下来？

这是经典的 eos 问题。原版模型只配置了一个结束符，而对话结尾实际用的是另一个 token。本仓库的generation_config.json已经修复，将eos_token_id设置为[248044, 248046]两个结束符。如果你自己重新转换模型，记得补上这一项：

{ "eos_token_id": [248044, 248046] }

2. 加载时报内存不足（OOM）？

oQ3.5 峰值内存约 6.5GB，建议至少 8GB 内存。如果仍然紧张，可以关闭其他大程序，或选择更小的 oQ3 版本（约 6.2GB 峰值）。

3. 识别复杂文档时精度下降？

量化位数越低速度越快，但遇到排版复杂的合同、扫描件时精度可能下降。如果对精度敏感，可以换用 oQ5 / oQ8 版本，或对提示词做更详细的字段描述。

4. 下载速度慢怎么办？

国内用户建议直接用git clone https://gitcode.com/hf_mirrors/mlx-community/lift-oQ3.5拉取仓库，速度更稳定。

总结：3 步跑通 lift-oQ3.5 ✅

至此，你已经拥有了一套完整的本地视觉信息提取能力：Apple 芯片 + mlx-vlm + lift-oQ3.5，可以离线把任何图片、PDF 单据转成规范的 JSON 数据。无论是个人记账、发票归档还是自动化办公，它都能成为你的得力助手。快去试试吧！🚀

【免费下载链接】lift-oQ3.5项目地址: https://ai.gitcode.com/hf_mirrors/mlx-community/lift-oQ3.5