新手入门 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 版本为什么值得选对比项lift-oQ3.5本仓库原版 bf16量化方式oQ 逐层混合精度全量 bf16平均位数≈4.0 bpw16 bpw模型体积4.9 GB18 GB峰值内存约 6.5 GB约 19.9 GB生成速度参考约 109 t/s约 31 t/s从表格能看出oQ3.5 用更小的体积换来了约3.5 倍的速度提升16GB 内存的 MacBook 也能流畅运行是入门本地部署的绝佳选择。如果你更在意精度同一系列还有 oQ4 / oQ5 / oQ6 / oQ8 等版本可以按需挑选。运行环境要求需要什么电脑才能跑起来mlx-vlm 是苹果 MLX 框架的视觉语言模型推理工具只支持Apple SiliconM 系列芯片的 Mac包括 M1 / M2 / M3 / M4 / M5 全系。项目最低建议推荐配置芯片Apple SiliconM 系列M 系列 16GB 内存系统macOS 13macOS 14磁盘空间8GB 可用20GB 以上Python3.93.11另外建议提前安装好uvPython 包管理工具它能让安装过程快到飞起下文所有命令都基于 uv 编写。最快安装方法一键安装 uv 与 mlx-vlm ⚡第一步安装 uv打开终端Terminal执行curl -LsSf https://astral.sh/uv/install.sh | sh安装完成后重启终端输入uv --version能输出版本号即代表成功。第二步安装 mlx-vlmmlx-vlm 是 lift-oQ3.5 的推理引擎两种方式任选方式一推荐无需手动装包直接用 uvx 运行uvx --from mlx-vlm mlx_vlm.generate --helpuvx 会自动创建临时环境并下载 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下载完成后文件夹里应该包含这些关键文件文件作用config.json模型结构与量化配置含逐层混合精度位数generation_config.json生成参数含修复后的 eos_token_idtokenizer.json分词器model-00001-of-00002.safetensors权重分片 1model-00002-of-00002.safetensors权重分片 2model.safetensors.index.json权重索引chat_template.jinja对话模板 小提示两个 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_urlhttp://127.0.0.1:8080/v1, api_keylocal) 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( modelmlx-community/lift-oQ3.5, messages[{role: user, content: [ {type: text, text: Extract this invoice.}, {type: image_url, image_url: {url: fdata:image/png;base64,{img}}}, ]}], response_format{type: json_schema, json_schema: {name: invoice, schema: schema}}, temperature0.0, max_tokens800, ) 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. 加载时报内存不足OOMoQ3.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 ✅步骤操作耗时1安装 uv mlx-vlm约 5 分钟2下载模型权重4.9GB视网速而定3命令行生成或启动 API 服务约 2 分钟至此你已经拥有了一套完整的本地视觉信息提取能力Apple 芯片 mlx-vlm lift-oQ3.5可以离线把任何图片、PDF 单据转成规范的 JSON 数据。无论是个人记账、发票归档还是自动化办公它都能成为你的得力助手。快去试试吧【免费下载链接】lift-oQ3.5项目地址: https://ai.gitcode.com/hf_mirrors/mlx-community/lift-oQ3.5创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
