Python 调用 lift-oQ3.5：OpenAI SDK 完整代码示例与常见坑位避雷

Python 调用 lift-oQ3.5OpenAI SDK 完整代码示例与常见坑位避雷【免费下载链接】lift-oQ3.5项目地址: https://ai.gitcode.com/hf_mirrors/mlx-community/lift-oQ3.5lift-oQ3.5 是一个专为「文档结构化提取」设计的视觉语言模型本文手把手教你如何用 Python 通过 OpenAI SDK 调用 lift-oQ3.5从启动本地服务到拿到规范 JSON 全流程跑通并把新手最容易踩的 6 个坑一次讲清楚。lift-oQ3.5 是什么为什么值得在本地跑lift-oQ3.5 是 datalab-to/lift9B 参数、qwen3_5 架构的视觉语言模型的 MLX 社区量化版本核心能力只有一个把图片 / PDF 变成符合 JSON Schema 的结构化 JSON。和通用大模型不同它在解码阶段就由 llguidance 强制约束输出结构返回结果类型正确、结构合法非常适合发票识别、合同信息抽取、表单结构化这类场景。这一版 oQ3.5 采用逐层混合精度量化约 4.0 bits/权重模型压到4.9GB、峰值内存约6.5GB实测生成速度约109 token/sApple Silicon 上。仓库里的config.json记录了完整的逐层量化配置preprocessor_config.json则展示了它对高分辨率图片的原生支持最长边可达 16777216扫描件也能直接喂。关键参数数值参数量9Bqwen3_5 架构量化方式oQ 逐层混合精度 ≈4.0 bits模型大小4.9 GB峰值内存≈6.5 GB生成速度≈109 token/s支持输入图片 / PDF / 视频帧开始前的环境准备3 步搭好运行环境第 1 步确认设备lift-oQ3.5 是 MLX 格式模型需要Apple SiliconM 系列芯片的 Mac才能本地运行。没有 Mac 也没关系下面的代码思路完全适用于任何 OpenAI 兼容服务。第 2 步安装依赖与获取模型只需要mlx-vlm负责加载与推理和openaiPython SDK两个东西用 uv 最省事。模型文件也可以直接从本仓库获取git clone https://gitcode.com/hf_mirrors/mlx-community/lift-oQ3.5第 3 步启动 OpenAI 兼容服务一条命令启动本地推理服务uvx --from mlx-vlm mlx_vlm.server --model mlx-community/lift-oQ3.5 --port 8080启动成功后本机 8080 端口就多了一个路径为/v1的 OpenAI 兼容接口任何 OpenAI SDK 都能直连。想先快速验证模型效果也可以用命令行生成模式uvx --from mlx-vlm mlx_vlm.generate --model mlx-community/lift-oQ3.5 --image invoice.png --prompt Extract the invoice as JSON. --max-tokens 800。Python 调用 lift-oQ3.5 完整代码示例三步拿到结构化 JSON核心就三步图片转 Base64 → 定义 JSON Schema → 发起对话请求完整代码如下import base64, json from openai import OpenAI # 1. 连接本地服务api_key 随便填本地不校验 client OpenAI(base_urlhttp://127.0.0.1:8080/v1, api_keylocal) # 2. 图片转 Base64 img base64.b64encode(open(invoice.png, rb).read()).decode() # 3. 定义你想要的输出结构JSON Schema 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], } # 4. 发起请求 resp client.chat.completions.create( modelmlx-community/lift-oQ3.5, # 必须显式指定见坑位 1 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, ) # 5. 直接解析成字典供下游业务使用 print(json.loads(resp.choices[0].message.content))跑通后invoice_number、total、line_items就会严格按照 schema 抽取出来可以直接入库或对接下游流程。常见坑位避雷新手最容易踩的 6 个坑 ⚠️坑位 1model 参数必须显式指定模型名mlx_vlm.server会把整个 HuggingFace 缓存目录都暴露给客户端model传错或漏传就会加载到错误的文件或直接失败。README.md 里特别强调要写全mlx-community/lift-oQ3.5。坑位 2输出刷|im_end|停不下来最诡异模型一直吐|im_end|刷屏、永不结束这是 eos_token 配置不全导致的。本仓库的generation_config.json已经修复eos_token_id同时包含248044和248046对话结束符|im_end|而上游只配置了前者。如果你自行重新转换模型务必重新应用这个修复否则服务端读取配置后永远无法停止生成。坑位 3图片必须用 data URL 传 Base64OpenAI SDK 的image_url字段需要data:image/png;base64,xxx这种带前缀的格式漏掉前缀会导致图片解析失败。传图格式严格按示例来一张图一个 data URL。坑位 4temperature 记得设为 0抽取任务追求确定性temperature0.0能让输出更稳定同时给足max_tokens示例用 800长文档被截断会导致 JSON 不完整甚至解析报错。坑位 5JSON Schema 别漏 required 字段schema 里定义字段只是「允许出现」required才能保证字段一定返回。发票号码、金额这类核心字段务必写进required否则下游程序可能收到缺字段的 JSON。坑位 6低比特量化在复杂文档上会掉精度oQ3.5 只有约 4.0 bits/权重简单发票没问题但复杂、对抗性文档的字段抽取精度可能下降。追求精度建议换同系列更高档位见下节追求速度再选低比特。性能参考量化档位怎么选同一系列还有多个档位按内存和精度需求挑选数据来自官方 README.mdM5 Max 单图发票抽取参考值版本≈bpw模型大小峰值内存生成速度lift-bf161618 GB19.9 GB31 t/slift-oQ8≈8.69.7 GB12.3 GB58 t/slift-oQ6≈67.7 GB9.4 GB73 t/slift-oQ5≈56.7 GB8.4 GB83 t/slift-oQ4≈4.65.6 GB7.2 GB100 t/slift-oQ3.5≈4.04.9 GB6.5 GB109 t/slift-oQ3≈3.54.6 GB6.2 GB119 t/s总结用 Python OpenAI SDK 调用 lift-oQ3.5 其实就四步启动 server、转 Base64、写 schema、发请求。只要记住模型名显式指定、图片带 data URL 前缀、temperature 设 0、schema 写 required配合本仓库已修复的generation_config.json就能稳定拿到结构化 JSON。想深入研究的读者可以翻阅仓库里的README.md、chat_template.jinja、preprocessor_config.json和tokenizer_config.json理解它的对话模板与图像预处理细节。【免费下载链接】lift-oQ3.5项目地址: https://ai.gitcode.com/hf_mirrors/mlx-community/lift-oQ3.5创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考