Sparrow：一款开源的文档处理与指令调用工具，助力你的工作更高效

在日常工作中，处理各种文档——如发票、收据、银行对账单或复杂表格——往往让人头疼。Sparrow 是一款开源工具，专为解决这类问题而设计。它结合了机器学习（ML）、大型语言模型（LLM）和视觉大型语言模型（Vision LLM），不仅能提取文档中的数据，还能处理文本、验证信息甚至执行简单的决策任务。如果你需要一个既强大又灵活的助手来处理文档，Sparrow 值得一试。

这篇文章将带你全面了解 Sparrow 的功能、使用方法和安装步骤。无论你是技术爱好者还是企业用户，这里都有实用的内容帮你快速上手。

Sparrow UI：简单易用的交互界面

Sparrow 提供了一个交互式的 Web 界面，叫做 Sparrow UI。它的设计非常直观，即使你不熟悉代码也能轻松使用。你可以直接拖放文件上传，比如一张发票图片或一个 PDF，系统会立刻处理并展示结果。

怎么体验？

想试试看？直接访问 sparrow.katanaml.io。这个在线版本运行在 Mac Mini M4 Pro 上，性能稳定，随时可用。

Sparrow UI 的亮点

拖放上传：无需复杂操作，把文件拖进去就行。
实时结果：上传后马上看到处理后的数据。
JSON 查询：可以用 JSON 格式指定想提取的信息，简单又灵活。
结构化输出：结果以清晰的 JSON 格式呈现，方便后续使用。
标注查看：可以看到文档中每个数据的边界框，直观了解提取位置。

Sparrow 能做什么？

Sparrow 的功能非常丰富，既适合个人开发者，也能满足企业需求。以下是它的核心特点：

通用文档处理：无论是发票、收据还是银行对账单，它都能搞定。
灵活架构：你可以根据需要组合不同的处理管道，比如 Sparrow Parse 或 Agents。
多后端支持：支持 MLX（苹果芯片）、Ollama、PyTorch 等多种技术。
多格式兼容：支持 PNG、JPG 图片和多页 PDF。
自动验证：通过 JSON 模式确保提取的数据准确。
API 优先：提供 RESTful API，轻松集成到你的项目中。
指令调用：不仅提取数据，还能处理文本或执行简单计算。
可视化监控：内置仪表板，实时查看处理情况。
企业友好：支持速率限制和使用分析，还提供商业许可。

无论你是想从表格中提取数据，还是需要处理复杂的多页文档，Sparrow 都能提供帮助。

Sparrow 的架构：它是如何工作的？

Sparrow 的强大离不开它的模块化设计。以下是它的核心组件：

Sparrow ML LLM：主引擎，负责文档处理的核心逻辑。
Sparrow Parse：视觉 LLM 库，专门提取结构化数据。
Sparrow Agents：工作流管理，用于复杂任务。
Sparrow OCR：文本识别模块，预处理文档内容。
Sparrow UI：前面提到的 Web 界面。

这些组件协同工作，让 Sparrow 既高效又灵活。你可以根据需求选择合适的模块，比如只用 Parse 处理简单文档，或者用 Agents 管理多步骤任务。

快速上手：30 秒启动 Sparrow

想马上试试 Sparrow？跟着下面的步骤走，只需半分钟就能跑起来。

准备工作

Python 3.10.4+：建议用 pyenv 管理版本。
操作系统：macOS（推荐 MLX 后端）或 Linux/Windows。
硬件：如果用 GPU，确保内存足够支持 Vision LLM。

安装步骤

# 1. 安装 Python 3.10.4
pyenv install 3.10.4
pyenv global 3.10.4

# 2. 创建虚拟环境
python -m venv .env_sparrow_parse
source .env_sparrow_parse/bin/activate  # Linux/Mac
# Windows 用户运行：.env_sparrow_parse\Scripts\activate

# 3. 安装 Sparrow Parse
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"

运行后，你会得到这样的结果：

{
  "data": [
    {"instrument_name": "UNITS BLACKROCK...", "valuation": 19049},
    {"instrument_name": "UNITS ISHARES...", "valuation": 83488}
  ],
  "valid": "true"
}

简单几步，你就从图片中提取出了结构化数据！

完整安装指南

如果 30 秒设置还不够，下面是更详细的安装步骤。

基础步骤

克隆代码库：

git clone https://github.com/katanaml/sparrow.git
cd sparrow

设置 Python 环境：
用 pyenv 安装 3.10.4，确保版本一致。
创建虚拟环境：
- .env_sparrow_parse：用于视觉 LLM 处理。
- .env_instructor：用于文本 LLM 处理。
- .env_ocr：可选，用于 OCR。
安装依赖：
根据你选择的管道，安装对应依赖文件中的内容。

平台注意事项

macOS：

brew install poppler  # 处理 PDF 必备

Ubuntu/Debian：

sudo apt-get install poppler-utils libpoppler-cpp-dev

苹果芯片：用 MLX 后端性能最佳。
NVIDIA GPU：支持 local_gpu 或 Ollama（开发中）。
纯 CPU：可以用小模型或云端后端。

验证安装

启动服务后，访问 http://localhost:8002/api/v1/sparrow-llm/docs，如果看到文档页面，说明安装成功。

实用示例：Sparrow 如何帮你处理文档

1. 银行对账单处理

假设你有一份银行对账单 PDF，想提取所有信息：

./sparrow.sh "*" \
  --pipeline "sparrow-parse" \
  --options mlx \
  --options mlx-community/Qwen2.5-VL-72B-Instruct-4bit \
  --file-path "data/bank_statement.pdf"

结果会包含账户信息、交易记录等，类似这样：

{
  "bank": "First Platypus Bank",
  "account_holder": "Mary G. Orta",
  "transactions": [
    {"date": "02/01", "description": "PGD EasyPay Debit", "withdrawal": "203.24"}
  ],
  "valid": "true"
}

2. 金融表格提取

从债券表格中提取数据：

./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"

输出会是这样的结构化数据：

{
  "data": [
    {"instrument_name": "UNITS BLACKROCK...", "valuation": 19049}
  ],
  "valid": "true"
}

3. 发票处理

处理发票时，可以用裁剪提高准确性：

./sparrow.sh "*" \
  --pipeline "sparrow-parse" \
  --options mlx \
  --options mlx-community/Qwen2.5-VL-72B-Instruct-4bit \
  --crop-size 60 \
  --file-path "data/invoice.pdf"

结果包括发票号、卖家信息等：

{
  "invoice_number": "61356291",
  "seller": {"name": "Chapman, Kim and Green"},
  "items": [
    {"description": "Wine Glasses", "quantity": 5, "net_price": 12.0}
  ]
}

4. 多页 PDF 处理

对于多页财务报告，可以逐页提取表格：

./sparrow.sh '{"table": [{"description": "str", "latest_amount": 0, "previous_amount": 0}]}' \
  --pipeline "sparrow-parse" \
  --file-path "data/financial_report.pdf"

输出会按页面组织数据：

[
  {
    "table": [
      {"description": "Revenues", "latest_amount": 12453, "previous_amount": 11445}
    ],
    "page": 1
  }
]

5. 文本指令处理

想做简单计算？试试这个：

./sparrow.sh "instruction: do arithmetic operation, payload: 2+2=" \
  --pipeline "sparrow-instructor" \
  --options mlx \
  --options mlx-community/Mistral-Small-3.1-24B-Instruct-2503-8bit

输出：

The result of 2 + 2 is: 4

命令行使用：更灵活的操作

Sparrow 的命令行界面（CLI）非常强大，基本语法是：

./sparrow.sh "<JSON_SCHEMA>" --pipeline "<PIPELINE>" [OPTIONS] --file-path "<FILE>"

常用参数

参数	类型	说明	示例
`query`	JSON/字符串	数据模式或指令	`'[{"field":"str"}]'`
`--pipeline`	字符串	选择处理管道	`sparrow-parse`
`--file-path`	路径	输入文件	`data/invoice.pdf`
`--options`	字符串	后端配置	`mlx,model-name`
`--crop-size`	整数	裁剪像素	`60`

高级用法

多页 PDF 分类：

./sparrow.sh "*" --page-type invoice --page-type table --pipeline "sparrow-parse" --file-path "multi_page.pdf"

表格裁剪提取：

./sparrow.sh '*' --options tables_only --crop-size 100 --file-path "scan.pdf"

API 使用：集成到你的项目

Sparrow 的 API 设计方便开发者使用。启动服务后，你可以通过 HTTP 请求调用功能。

启动服务

python api.py  # 默认端口 8002

提取文档数据

curl -X POST 'http://localhost:8002/api/v1/sparrow-llm/inference' \
  -F 'query=[{"field_name":"str", "amount":0}]' \
  -F 'pipeline=sparrow-parse' \
  -F 'file=@document.pdf'

处理文本指令

curl -X POST 'http://localhost:8002/api/v1/sparrow-llm/instruction-inference' \
  -d 'query=instruction: analyze data, payload: {...}' \
  -d 'pipeline=sparrow-instructor'

API 文档可以在 http://localhost:8002/api/v1/sparrow-llm/docs 查看。

Sparrow Agents：复杂任务的得力助手

对于需要多步骤处理的场景，Sparrow Agents 能帮你编排工作流。比如处理医疗处方：

curl -X POST 'http://localhost:8001/api/v1/sparrow-agents/execute/file' \
  -F 'agent_name=medical_prescriptions' \
  -F 'file=@prescription.pdf'

它支持实时监控和错误恢复，非常适合企业级应用。

仪表板：实时掌握运行情况

Sparrow 内置了一个仪表板，访问 sparrow.katanaml.io 就能看到。它能展示 API 调用情况、模型性能等数据，帮你优化使用。

管道对比：选择适合你的工具

Sparrow 有三种主要管道：

特性	Sparrow Parse	Sparrow Instructor	Sparrow Agents
输入	文档 + JSON 模式	文本指令	复杂工作流
输出	结构化 JSON	自由文本	多步骤结果
用例	数据提取	文本分析	企业流程
复杂度	简单	中等	高

Parse：适合快速提取结构化数据。
Instructor：处理文本任务的好帮手。
Agents：复杂流程的理想选择。

性能优化建议

硬件选择

苹果芯片：用 MLX 后端，内存利用率高。
NVIDIA GPU：需要 12GB+ 显存。
纯 CPU：建议用小模型，速度较慢。

内存管理

# 减少内存占用
--crop-size 100  # 裁剪大图
--options tables_only  # 只处理表格

模型选择

用例	推荐模型	内存	速度
发票	Mistral-Small-3.1-24B	35GB	快
复杂表格	Qwen2.5-VL-72B	50GB	慢
快速测试	Qwen2.5-VL-7B	20GB	最快

故障排除：遇到问题怎么办？

安装问题

Python 版本不对：

python --version  # 检查版本
pyenv install 3.10.4  # 修复

Poppler 缺失：

brew install poppler  # macOS
sudo apt-get install poppler-utils  # Ubuntu

运行问题

内存不足：用小模型或裁剪图像。
提取质量差：提高分辨率或用 --crop-size 60。

需要帮助？可以查看 GitHub Issues 或联系 abaranovskis@redsamuraiconsulting.com。

开源与商业许可

Sparrow 使用 GPL 3.0 许可证，免费开放给年收入低于 500 万美元的组织。企业用户可以联系作者获取商业许可。

结语

Sparrow 是一个强大且易用的工具，能帮你高效处理文档和文本任务。它的开源特性和灵活设计让它适合各种场景。无论你是想快速提取数据，还是构建复杂的处理流程，Sparrow 都能提供支持。赶快去 GitHub 给它点个星，开始你的体验吧！

Sparrow开源文档处理工具：机器学习驱动的PDF表格提取全攻略