NOTES · 期刊

5.1K Star！Sparrow：把发票PDF变成干净JSON，本地运行零云依赖

发布于 2026/08/27 11:50 · 更新于 2026/08/27 11:50

5.1K Star！Sparrow：把发票PDF变成干净JSON，本地运行零云依赖

↑阅读之前记得关注+星标⭐️，😄，每天才能第一时间接收到更新

大家好，我是杰克王，AI 算法 6 年老兵。

公司财务每个月收到几十张 PDF 发票，格式不统一，供应商一家一个样。有人手动录系统，有人做 Excel，有人找外包。这个问题几乎每家中小企业都有。

或者你是开发者，接了个文档解析需求——客户的采购单、银行流水、财报表格，想用 AI 提取结构化数据。调云 API？贵，而且数据出境有风险。自己搭模型？依赖一堆，不同硬件配置又是不同的坑。

这个问题，Sparrow 想正面解决。

先看效果。把一张银行账单扔进去，出来是这样的结构化 JSON（完整字段，开箱可用）：

{
  "bank": "First Platypus Bank",
  "account_holder": "Mary G. Orta",
  "account_number": "1234567890123",
  "statement_date": "3/1/2022",
  "period_covered": "2/1/2022 - 3/1/2022",
  "account_summary": {
    "balance_on_march_1": "$25,032.23",
    "total_money_in": "$10,234.23",
    "total_money_out": "$10,532.51"
  },
  "transactions": [
    {"date": "02/01", "description": "PGD EasyPay Debit", "withdrawal": "203.24"},
    {"date": "02/05", "description": "Payroll Direct Dep Giants", "deposit": "2,534.65"},
    {"date": "02/07", "description": "Check No. 234", "withdrawal": "1,400.00"}
  ],
  "valid": "true"
}

字段名你来定，Sparrow 按你的 JSON schema 提取，自动验证格式是否符合 schema。valid: true 意味着结果可以直接接入后端或数据管道，不需要二次清洗。

Sparrow 是由 Andrey Volk（SignalWire 平台工程师）在 2022 年创建的 API-first 企业文档智能平台。四年持续维护，截至 2026-06-11 累计 5160 Stars，518 Forks，当天还有更新提交。项目以 GPL v3 许可证开源，商业授权也在提供。

Sparrow 的核心设计理念：全程本地，无外部依赖。不调 OpenAI、不上传到云端，LLM 跑在你自己的机器上，数据留在内网。

架构：三条流水线

Sparrow 的可插拔架构把不同任务拆成三条独立流水线，互不干扰。

三条 Pipeline 的定位：

Pipeline	输入	输出	底层技术
Sparrow Parse	文档图片/PDF + JSON schema	验证过的结构化 JSON	Vision LLM
Sparrow Instructor	文本指令	自由格式文本	Text LLM（Gemma、Mistral、Qwen）
Sparrow Agents	多步骤工作流定义	复杂流程结果	多 Agent 编排 + Prefect

什么时候用哪条？

Sparrow Parse 是主力——拿来提取发票金额、表格数据、表单字段，告诉它你要什么字段、什么格式，它给你结构化结果。Sparrow Instructor 做文字处理：对已提取的文本做摘要、分析、问答、决策判断。Sparrow Agents 处理更复杂的企业场景：先分类文档类型，再提取字段，最后写入数据库，全套流程可视化监控。

三条 Pipeline 可以混搭，Prefect 负责编排和监控，失败重试、错误处理都有内置支持。

拿来就能用的 UI

Sparrow 带了一个网页 UI，不写代码也能试。上传文档、填 JSON schema、点运行，实时看结果。适合先验证精度再决定是否接 API。

UI 功能：拖拽上传（PNG/JPG/多页 PDF）、JSON 查询 schema、结构化输出展示、内置 Dashboard 看 API 调用统计和模型性能对比。

在线版：https://sparrow.katanaml.io（跑在作者自己的\[1\] Mac Mini M4 Pro 64GB 上，非 demo 环境）

四套后端，按硬件选

Sparrow 同一套 API，多个推理后端，不同机器对应不同方案：

后端	硬件要求	特点	推荐场景
MLX	Apple Silicon Mac	统一内存，性能最优	M1～M4 Mac 本地开发/生产
vLLM	NVIDIA GPU（推荐 96GB VRAM）	生产级推理，全精度模型	Linux 服务器部署
Ollama	通用（CPU/GPU 均可）	安装最简单	Linux/Windows 快速起步
Mistral OCR	云服务	企业级 OCR 精度	高精度文档 + 无本地 GPU
Hugging Face	云 GPU	无本地硬件要求	测试环境/无 GPU 备选

不同文档类型对应不同的推荐模型：

场景	推荐模型	后端
发票/表单（欧洲格式）	Mistral Small 3.2 24B	vLLM / MLX
发票/表单（美国格式）	Gemma 4 31B Dense	MLX
大型复杂表格	dots.ocr	vLLM
快速测试	Qwen3.6 27B Dense	MLX
低内存设备	Qwen3.6 35B MoE / Gemma 4 26B MoE	MLX

对大型复杂表格，Sparrow 有专门的处理路径：dots.ocr 先把表格内容转成 HTML 中间格式，再用 Sparrow Templates 映射到 JSON schema，精度比直接 Vision LLM 更稳。适合财务报表、多列发票这类场景。

快速上手

环境要求：Python 3.12.10+，macOS（MLX）或 Linux/Windows（其他后端）

# 1. 安装 pyenv + Python 3.12.10
pyenv install 3.12.10
pyenv global 3.12.10

# 2. 创建虚拟环境
python -m venv .env_sparrow_parse
source .env_sparrow_parse/bin/activate

# 3. 克隆 + 安装依赖
git clone https://github.com/katanaml/sparrow.git
cd sparrow/sparrow-ml/llm
pip install -r requirements_sparrow_parse.txt

# 4. macOS 需要安装 poppler（PDF 处理）
brew install poppler

# 5. 启动 API 服务
python api.py

第一次提取债券表格数据：

./sparrow.sh '[{"instrument_name":"str", "valuation":0}]' \
  --pipeline "sparrow-parse" \
  --options mlx \
  --options mlx-community/Qwen2.5-VL-72B-Instruct-4bit \
  --file-path "data/bonds_table.png"

Sparrow 还支持多页 PDF（--file-path xxx.pdf），以及图片裁剪（针对表单的某一区域做提取，减少干扰）。需要提高精度？用 hints 文件给模型加提示，比如告诉它"注意区分供应商税号和收货方税号"，或者"日期统一格式化为 YYYY-MM-DD"：

./sparrow.sh '[{"instrument_name":"str", "valuation":"int"}]' \
  --pipeline "sparrow-parse" --debug --options mlx \
  --options mlx-community/gemma-4-31b-it-8bit \
  --file-path "data/bonds_table.png" \
  --hints-file-path "data/llm_hints_eu.json"

安装坑实录（来自 GitHub Issues，截至 2026-06-11）

社区里反馈最多的坑，你可以提前避开：

坑 1：pip 安装直接报错（8 条评论，高频）

Error running pip install -r requirements.txt

多数是 Python 版本问题。Sparrow 明确要求 3.12.10，偏一个小版本可能就报 AttributeError。用 pyenv 锁版本，比系统 Python 或 conda 省事。

坑 2：运行时 ModelConfig 报错（8 条评论）

TypeError: 'ModelConfig' object is not subscriptable

依赖包版本不兼容的经典错误。先 pip install --upgrade pip，再 pip install --no-cache-dir 重装。

坑 3：非 Mac 用户根本跑不起来（7 条评论，最坑）

Unable to use sparrow parse without MLX

这是用户最集中的反馈。README 里 MLX 部分讲得比较显眼，很多 Linux/Windows 用户以为 MLX 是必须的。实际上不是——在 requirements_sparrow_parse.txt 里把 sparrow-parse[mlx] 改成 sparrow-parse（去掉 [mlx] 部分），就会跳过 MLX 相关库，然后用 Ollama 后端即可。

建议：本地部署前先用 https://sparrow.katanaml.io\[2\] 在线版测试。把你的实际文档丢上去，看提取精度是否满足需求，再决定要不要折腾本地部署。