BroadRouter

用视觉大模型把发票、收据和表单数据提取为 JSON

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于

把每一页渲染成图片,连同一条写明每个字段及其格式的提示词发给视觉模型,并要求只返回 JSON。然后在代码里校验:解析、检查 schema、核对明细行加起来等于总额,失败时带上错误信息重试一次。反复失败的交给人工处理。

A paper invoice headed "فاتورة" (invoice) with tabs labelled Vendor, Date and Total, and the text "Turn documents into useful data."
Illustrative example.

发票、收据和表单都有同一个问题:数据在图片里,而你需要它进数据库。基于模板的 OCR 每遇到一家新供应商的版式就会失效。视觉语言模型读取页面后直接返回字段。问题在于它可能错得很自信,所以功夫要下在它周围的流水线上。本文讲适用于任何语言的通用流水线。阿拉伯语文档的接入见用视觉模型读取阿拉伯语发票,什么时候传统 OCR 更合适见阿拉伯语 OCR 与视觉大模型。

流水线是什么样的?

  1. 预处理每一页:把 PDF 渲染成图片、纠正旋转、缩放尺寸。
  2. 提取:每份文档一个请求,提示词逐字段写明,只返回 JSON。
  3. 校验:解析、schema 检查、金额核对。
  4. 校验失败时,带上错误信息重试一次。
  5. 复核:仍然失败的交给人工,附上图片和草稿结果。
  6. 在标注样本上衡量字段准确率,每次更换模型或提示词时重新跑一遍。

怎样预处理文档图片?

用 PyMuPDF 把 PDF 渲染成图片,让最小的文字保持清晰,同时不多发一个不必要的像素:

# pip install pymupdf pillow
import base64, io
import pymupdf  # older code imports it as fitz
from PIL import Image

def pdf_pages_as_data_urls(path, long_edge=1800):
    urls = []
    for page in pymupdf.open(path):
        pix = page.get_pixmap(dpi=200)
        img = Image.open(io.BytesIO(pix.tobytes("png"))).convert("RGB")
        img.thumbnail((long_edge, long_edge))
        buf = io.BytesIO()
        img.save(buf, format="JPEG", quality=90)
        urls.append("data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode())
    return urls

在 BroadNet Inference 上,图片以 data: URL 的形式放进消息,并带上准确的 MIME 类型;按量付费时按输入 token 计费,图片越大用量越多。先用 usage 字段测一次每页的 token 数,再据此确定批量大小;做法见发送前计算 token,视觉大模型每张图片的费用则把 token 换算成每页费用。想在发送任何请求之前估算每页 token,把一张样例扫描件拖进图片 token 计算器即可。

提取提示词应该怎么写?

键、类型、格式和缺失值都要写得一丝不苟。如果你还需要一个 JSON Schema,用于校验或用于强制执行 schema 的供应商,免费的 JSON Schema 生成器可以根据一张样例发票生成:

PROMPT = """Extract this invoice. Reply with one JSON object only, no prose.
Keys:
- vendor_name: string, as printed
- vendor_tax_id: string or null
- invoice_number: string
- invoice_date: string, YYYY-MM-DD
- currency: ISO 4217 code, e.g. USD, EUR, SAR
- line_items: list of {description: string, quantity: number, unit_price: number, line_total: number}
- subtotal: number
- tax: number or null
- total: number
Rules: numbers without currency symbols or thousands separators. If a field is not on the page, use null. Never guess."""

“Never guess”(绝不猜测)加上明确的 null 最为关键。没有这条,模型会用看似合理的值填补空缺,这比留空更糟,因为它能通过简单的检查。

怎样获得结构化输出并加以校验?

结构化输出分两个层次。JSON 模式保证输出是合法的 JSON;受 schema 约束的输出还能保证结构。OpenAI 的指南说得很直白:两者都会生成合法的 JSON,但只有 Structured Outputs 能确保遵循 schema。各供应商、各模型对这两者的支持不一,所以无论 API 承诺了什么,都要在代码里校验:

import json, os
from decimal import Decimal
from pydantic import BaseModel, ValidationError, model_validator
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Line(BaseModel):
    description: str
    quantity: Decimal
    unit_price: Decimal
    line_total: Decimal

class Invoice(BaseModel):
    vendor_name: str
    vendor_tax_id: str | None = None
    invoice_number: str
    invoice_date: str
    currency: str
    line_items: list[Line]
    subtotal: Decimal
    tax: Decimal | None = None
    total: Decimal

    @model_validator(mode="after")
    def sums(self):
        tol = Decimal("0.02")
        if abs(sum(l.line_total for l in self.line_items) - self.subtotal) > tol:
            raise ValueError("line_totals do not sum to subtotal")
        if abs(self.subtotal + (self.tax or 0) - self.total) > tol:
            raise ValueError("subtotal + tax != total")
        return self

def extract(image_urls, model="broadnet/qwen3.8-27b"):
    content = [{"type": "text", "text": PROMPT}] + [
        {"type": "image_url", "image_url": {"url": u}} for u in image_urls]
    messages = [{"role": "user", "content": content}]
    for attempt in range(2):
        r = client.chat.completions.create(model=model, messages=messages, max_tokens=4000, temperature=0)
        raw = (r.choices[0].message.content or "").strip().removeprefix("```json").removesuffix("```")
        try:
            return Invoice.model_validate(json.loads(raw)), r.usage
        except (json.JSONDecodeError, ValidationError, ValueError) as e:
            messages += [{"role": "assistant", "content": raw},
                         {"role": "user", "content": f"That failed validation: {e}. Re-read the image and reply with corrected JSON only."}]
    return None, r.usage  # send to human review

金额请用 Decimal,不要用 float。max_tokens 要设得宽松:Qwen3.8 27B 回答前会先思考,思考计入上限;上限太小会返回空字符串。见思考模型为什么返回空回复。

哪些检查能发现最多的错误?

检查 能发现 成本
JSON 能解析 JSON 前后夹杂的文字、被截断 免费
schema 校验通过 缺少键、类型错误 免费
明细之和等于小计 读错数字、漏行 免费
小计 + 税额 = 总额 读错总额或税额 免费
日期能解析且不在未来 日月颠倒、OCR 噪声 免费
供应商税号与你的供应商名单一致 供应商错误、欺诈 一次查找
同一供应商的发票号是否重复 重复付款 一次查询

金额核对最划算:只要读错一个数字,加总几乎必然对不上。收据往往没有明细行,所以有什么就查什么,对收据接受较少的检查项。

上线前怎样衡量准确率?

手工标注 50 到 100 份真实文档,跑一遍流水线,按字段打分,而不是按文档。总额和日期的标准应该比描述字段更严。跟踪三个数字:字段准确率、无需重试即通过校验的文档比例,以及转入复核的比例。怎样设计这个复核环节,包括对已通过文档的随机抽查,见让人工复核成为文档 AI 流程的一部分。尝试其他模型时,用同一套样本跑;方法见切换前评估大模型。

BroadNet Inference 上有哪些合适的视觉模型?

模型 图片 上下文 说明
Qwen3.8 27B 支持 262,144 列出了工具调用、结构化输出和思考;BroadNet 做过阿拉伯语测试
Gemma 4 VL 26B 支持 32,768 BroadNet 价格最低的模型;可用免费额度和按小时密钥运行
DeepSeek V4.1 Flash 支持 1,048,576 不限量套餐包含图片

每 100 万 token 的价格见价格页;把实测的每页 token 数乘以月度量,填进大模型 API 费用计算器即可。

BroadNet Inference 适合什么场景

BroadNet Inference 通过标准的 OpenAI 消息格式,在三个对话模型上接受图片输入,并且在请求结束后不保留提示词、图片或回答。这对满是姓名、税号和银行信息的发票很重要(零数据保留)。它的文档为 Qwen3.8 27B 列出了结构化输出,但没有说明 schema 参数,所以请依靠上面的校验层,而不是依靠 API 来强制执行你的 schema。BroadNet 没有公布图片大小限制,也没有专门的文档 AI 产品,其文档描述的是图片输入而不是 PDF 上传,所以要先把页面渲染成图片。需要在固定预算下大批量处理时,不限量的 DeepSeek V4.1 Flash 套餐包含图片。

常见问题

视觉大模型能代替 OCR 识别发票吗?

对很多版式来说可以。视觉模型一步就能读图并把文字映射到字段,不需要为每家供应商做模板。但它有时仍会读错数字,所以要保留校验和复核队列。

怎样让视觉模型稳定输出 JSON?

在提示词里列出确切的键、类型和格式,要求只返回 JSON,并在代码里解析。如果模型支持受 schema 约束的输出,就用上。无论哪种方式,都要用 schema 库校验,并带上错误信息重试一次。

多页 PDF 发票怎么提取数据?

把每页渲染成图片;如果装得进模型的上下文,就把同一张发票的所有页面放在一个请求里发送,这样最后一页的总额能和第一页的明细对上。

发票图片分辨率设多少合适?

高到最小的数字也清晰即可,不要更高。图片越大,输入 token 越多。对 A4 页面来说,长边约 1,500 到 2,000 像素是一个合理的起点;请用你自己的文档测试。

怎样衡量提取的准确率?

手工标注 50 到 100 份真实文档,逐字段打分。总额和日期要与供应商名称这类自由文本字段分开统计,因为它们出错的代价不同。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity