企业官网建设流程全解析

自定义 JSON Schema 进阶：用 lift-oQ3 提取任意复杂文档结构

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

把 PDF、发票、合同等复杂文档一键变成干净、可用的 JSON 数据，是当下很多团队的核心需求。lift-oQ3正是为这一场景而生的视觉语言模型：它是 mlx-community 对 datalab-to/lift 的 MLX 量化版本，专攻「文档 → JSON Schema 约束下的结构化输出」。这篇文章从自定义 JSON Schema 出发，带你掌握用 lift-oQ3 提取任意复杂文档结构的进阶技巧——从嵌套字段、表格明细到条件分支，一步步把模型的输出装进你想要的格式里。

为什么文档提取离不开 JSON Schema 约束？

让大模型"自由发挥"地读文档，结果往往是字段缺失、类型混乱、格式漂移，无法直接入库。而JSON Schema 约束能在解码阶段就锁定输出的结构和类型：

• ✅ 输出 100% 合法 JSON，不会出现截断或乱码
• ✅ 字段名、嵌套层级、必填项全部可控
• ✅ 数字就是数字、数组就是数组，下游程序零清洗

lift-oQ3 的服务端通过 llguidance 在解码时实时强制约束，相当于给模型戴上了一副"格式眼镜"——这正是它被称为结构化提取模型的原因。

lift-oQ3 是什么？Apple Silicon 上的结构化提取模型

lift-oQ3 基于 9B 参数的 qwen3_5 视觉语言架构，能同时理解图片和文字，把文档版面"看"成结构化数据。作为 oQ3 变体，它采用数据驱动的逐层混合精度量化（约 3.5 bits/weight，模型仅 4.6 GB），在 Apple Silicon 上表现相当亮眼：

（数据来自 M5 Max 单图发票提取实测，仅作参考。）内存占用低、速度快，意味着普通 Mac 也能本地跑文档提取，数据不出本机，隐私更安心。

快速上手：如何用 lift-oQ3 启动 JSON Schema 提取服务

先把仓库克隆到本地（模型权重就在仓库内）：

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

再通过 mlx-vlm 启动 OpenAI 兼容的服务：

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

之后用任意 OpenAI SDK 调用，关键在response_format里传入我们自定义的 JSON Schema：

from openai import OpenAI client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="local") resp = client.chat.completions.create( model="lift-oQ3", # 以服务端启动时的模型名为准 messages=[{"role": "user", "content": [ {"type": "text", "text": "提取这张发票的信息。"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}, ]}], response_format={"type": "json_schema", "json_schema": {"name": "invoice", "schema": {...你的 Schema...}}}, temperature=0.0, max_tokens=800, )

接下来是重点：这个schema怎么写，才能覆盖任意复杂文档？

自定义 JSON Schema 进阶技巧一：用嵌套对象提取层级结构

真实文档很少是"平铺"的：发票有购买方、销售方，合同有甲方、乙方，体检报告有多个检查小节。用嵌套 object 可以把层级结构原样映射出来：

{ "type": "object", "properties": { "invoice_number": {"type": "string"}, "issue_date": {"type": "string"}, "total": {"type": "number"}, "payer": { "type": "object", "properties": { "name": {"type": "string"}, "tax_id": {"type": "string"} }, "required": ["name", "tax_id"] } }, "required": ["invoice_number", "total"] }

要点：外层字段声明类型，内层对象再定义自己的properties和required。层级越深，模型越容易把同类信息归拢到一起，输出也更接近人工整理的效果。

自定义 JSON Schema 进阶技巧二：用数组提取表格与明细行

发票明细、订单条目、化验单项目……凡是"一行一条"的数据，都该用array。这是表格识别最核心的一招：

"line_items": { "type": "array", "items": { "type": "object", "properties": { "description": {"type": "string"}, "quantity": {"type": "integer"}, "unit_price": {"type": "number"}, "amount": {"type": "number"} }, "required": ["description", "amount"] } }

给每条明细单独约束字段类型，模型就能稳定地把多行表格拆成数组元素——行数多少不重要，结构始终统一，入库、对账都非常方便。

自定义 JSON Schema 进阶技巧三：用枚举与条件字段规范化输出

文档类型千变万化，但业务上往往只有几种取值。用enum强制收敛，输出立刻变得"好查询"：

"doc_type": {"type": "string", "enum": ["invoice", "receipt", "contract"]}, "currency": {"type": "string", "enum": ["CNY", "USD", "EUR"]}

更进阶的玩法是oneOf：同一张单据，付款方式是"转账"就要带银行账号，是"现金"就不用——用条件分支让 Schema 精确匹配真实业务：

"payment": { "oneOf": [ {"properties": {"method": {"const": "bank_transfer"}, "account": {"type": "string"}}, "required": ["method", "account"]}, {"properties": {"method": {"const": "cash"}}, "required": ["method"]} ] }

enum管取值、const管分支、required管必填，三者组合起来，再复杂的文档也能约束得明明白白。

复杂文档提取实战：一套 Schema 搞定合同与报告

把上面的技巧组合起来：合同提取可以把「双方主体」做成嵌套对象、「条款列表」做成数组、「合同类型」用枚举、「付款条件」用 oneOf 分支。一份几十行的自定义 JSON Schema，就能覆盖整份合同的骨架，模型按图索骥逐项填值，返回的 JSON 直接可以进数据库。

如果文档很长，建议按页切图、逐页提取后再合并，配合高分辨率预处理（preprocessor_config.json支持超长边图像输入），复杂版式中的小字也能看得清。

复杂文档提取的避坑指南与注意事项

• eos 修复别丢：本仓库的generation_config.json已把eos_token_id设为[248044, 248046]，修复了服务端不停输出<|im_end|>的问题；若自行从上游重新转换，务必补上这一项。
• 低比特的取舍：上游 9B 原版在 225 份文档基准上字段级准确率约 90.2%；oQ3 精度只有约 3.5 bits，遇到版式刁钻的难样本可能掉点，正式场景建议先用 oQ4/oQ5 对比验证。
• max_tokens 给足：文档信息量大，默认 800 不够时就调大到 1500~2000，避免输出被截断。
• temperature 归零：提取是确定性任务，保持temperature=0，结果才可复现。
• 对话模板：chat_template.jinja支持图文混合输入，多图、图文对照都能处理，注意别把图片塞进 system 消息即可。

结语

从嵌套对象到数组表格，从枚举取值到条件分支，自定义 JSON Schema 就是解锁 lift-oQ3 全部能力的钥匙。只要 Schema 设计得足够贴合业务，再复杂的文档结构也能被稳定地"装"成 JSON。现在就克隆仓库、跑起服务，用一份属于自己的 Schema 试试手吧！🚀

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