{
  "bank": "第一鸭嘴兽银行",
  "address": "纽约市国王街1234号，邮编12123",
  "account_holder": "玛丽·G·奥尔塔",
  "account_number": "1234567890123",
  "statement_date": "2022年3月1日",
  "period_covered": "2022年2月1日至2022年3月1日",
  "account_summary": {
    "balance_on_march_1": "$25,032.23",
    "total_money_in": "$10,234.23",
    "total_money_out": "$10,532.51"
  },
  "transactions": [
    {
      "date": "2月1日",
      "description": "PGD EasyPay 借记",
      "withdrawal": "203.24",
      "deposit": "",
      "balance": "22,098.23"
    },
    {
      "date": "2月2日",
      "description": "AB&B 在线支付*****",
      "withdrawal": "71.23",
      "deposit": "",
      "balance": "22,027.00"
    },
    {
      "date": "2月4日",
      "description": "支票 No. 2345",
      "withdrawal": "",
      "deposit": "450.00",
      "balance": "22,477.00"
    },
    {
      "date": "2月5日",
      "description": "巨人队23422342号工资直接存款",
      "withdrawal": "",
      "deposit": "2,534.65",
      "balance": "25,011.65"
    },
    {
      "date": "2月6日",
      "description": "TJP 签名式 POS 借记",
      "withdrawal": "84.50",
      "deposit": "",
，bal…

# 处理多页PDF，每页输出结构化数据
./sparrow.sh '{"table": [{"description": "str", "latest_amount": 0, "previous_amount": 0}]}' \
  --pipeline "sparrow-parse" \
  --options mlx \
  --options mlx-community/Qwen2.5-VL-72B-Instruct-4bit \
  --file-path "data/financial_report.pdf" \
  --debug-dir "debug/"

[
    {
        "table": [
            {
                "description": "收入",
                "latest_amount": 12453,
                "previous_amount": 11445
            },
            {
                "description": "运营费用",
                "latest_amount": 9157,
                "previous_amount": 8822
            }
        ],
        "valid": "true",
        "page": 1
    },
    {
        "table": [
            {
                "description": "收入", 
                "latest_amount": 12453,
                "previous_amount": 11445
            },
            {
                "description": "运营费用",
                "latest_amount": 9157,
                "previous_amount": 8822
            }
        ],
        "valid": "true",
        "page": 2
    }
]

💬 文本指令处理

# 基于指令的处理
./sparrow.sh "instruction: do arithmetic operation, payload: 2+2=" \
  --pipeline "sparrow-instructor" \
  --options mlx \
  --options lmstudio-community/Mistral-Small-3.2-24B-Instruct-2506-8bit

# 带文档输入的指令处理
./sparrow.sh "check if business entity Chapman, Kim and Green is invoice issuing party" 
  --pipeline "sparrow-parse" 
  --instruction 
  --options mlx --options lmstudio-community/Mistral-Small-3.2-24B-Instruct-2506-8bit 
  --file-path "invoice_1.jpg"

JSON 输出：

2 + 2 的结果是：

4

📈 股票数据函数调用

# 函数调用示例
./sparrow.sh assistant --pipeline "stocks" --query "Oracle"

JSON 输出：

{
  "company": "Oracle Corporation",
  "ticker": "ORCL"
}

附加输出：

甲骨文公司的股价为 186.3699951171875 美元。

💻 CLI 使用

基本语法

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

命令行参数

管道选项

Sparrow Parse（视觉 LLM）

# MLX 后端（Apple Silicon）
./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"

# Hugging Face Cloud GPU
--options huggingface --options your-space/model-name

# 其他标志
--options tables_only        # 仅提取表格
--options validation_off     # 禁用模式验证
--options apply_annotation   # 包括边界框
--page-type financial_table  # 分类页面类型

Sparrow Instructor（文本 LLM）

# 基于指令的处理
./sparrow.sh "instruction: do arithmetic operation, payload: 2+2=" \
  --pipeline "sparrow-instructor" \
  --options mlx \
  --options lmstudio-community/Mistral-Small-3.2-24B-Instruct-2506-8bit

高级示例

# 多页 PDF 并进行页面分类
./sparrow.sh "*" \
  --page-type invoice \
  --page-type table \
  --pipeline "sparrow-parse" \
  --options mlx \
  --options mlx-community/Qwen2.5-VL-72B-Instruct-4bit \
  --file-path "multi_page.pdf"

# 处理缺失字段并用空值代替
./sparrow.sh '[{"required_field":"str", "optional_field":"str or null"}]' \
  --pipeline "sparrow-parse" \
  --options mlx \
  --options mlx-community/Qwen2.5-VL-72B-Instruct-4bit \
  --file-path "document.png"

# 带裁剪的表格提取
./sparrow.sh '*' \
  --pipeline "sparrow-parse" \
  --options mlx \
  --options mlx-community/Qwen2.5-VL-72B-Instruct-4bit \
  --options tables_only \
  --crop-size 100 \
  --file-path "scan.pdf"

# 执行指令
./sparrow.sh "check if business entity Chapman, Kim and Green is invoice issuing party" 
  --pipeline "sparrow-parse" 
  --instruction 
  --options mlx --options lmstudio-community/Mistral-Small-3.2-24B-Instruct-2506-8bit 
  --file-path "invoice_1.jpg"

# 字段验证
./sparrow.sh "tax_id,shipment_code,total_gross_worth" 
  --pipeline "sparrow-parse" 
  --validation 
  --options mlx --options lmstudio-community/Mistral-Small-3.2-24B-Instruct-2506-8bit 
  --file-path "invoice_1.jpg"

{
  "tax_id": true,
  "shipment_code": false,
  "total_gross_worth": true
}

🌐 API 使用

启动服务器

# 默认端口 (8002)
python api.py

# 自定义端口
python api.py --port 8001

# 多实例
python api.py --port 8002 &  # Sparrow Parse
python api.py --port 8003 &  # Instructor

API 端点

文档提取 (/inference)

curl -X POST 'http://localhost:8002/api/v1/sparrow-llm/inference' \
  -H 'Content-Type: multipart/form-data' \
  -F 'query=[{"field_name":"str", "amount":0}]' \
  -F 'pipeline=sparrow-parse' \
  -F 'options=mlx,mlx-community/Qwen2.5-VL-72B-Instruct-4bit' \
  -F 'file=@document.pdf'

文本指令 (/instruction-inference)

curl -X POST 'http://localhost:8002/api/v1/sparrow-llm/instruction-inference' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'query=instruction: analyze data, payload: {...}' \
  -d 'pipeline=sparrow-instructor' \
  -d 'options=mlx,mlx-community/Qwen2.5-VL-72B-Instruct-4bit'

API 文档

访问 http://localhost:8002/api/v1/sparrow-llm/docs 查看交互式 Swagger 文档。

🤖 麻雀代理

借助 Prefect 提供的可视化监控功能，编排复杂的文档处理工作流。

功能

• 多步骤工作流：串联分类、提取和验证流程
• 可视化监控：实时跟踪管道状态
• 错误处理：强大的失败恢复机制
• 可扩展性：针对特定用例的自定义代理

使用方法

# 启动代理服务器
cd sparrow-ml/agents
python api.py --port 8001

# 处理医疗处方
curl -X POST 'http://localhost:8001/api/v1/sparrow-agents/execute/file' \
  -F 'agent_name=medical_prescriptions' \
  -F 'extraction_params={"sparrow_key":"123456"}' \
  -F 'file=@prescription.pdf'

📊 仪表板

内置分析与监控仪表板，访问地址为 sparrow.katanaml.io。这是 Sparrow UI 的一部分，需要本地安装 Oracle Database 23ai Free 版本。

功能

• 使用情况分析：跟踪 API 调用、成功率及性能指标
• 地理分布：按国家查看使用情况
• 模型性能：对比不同模型的表现
• 实时监控：展示实时处理统计信息

🔧 工作流对比

如何选择使用

Sparrow Parse：适用于从文档中提取结构化数据
Sparrow Instructor：适用于文本分析、摘要生成及问答任务
Sparrow Agents：适用于复杂的多步骤文档处理工作流

⚡ 性能优化建议

硬件优化

Apple Silicon (MLX)

• ✅ 统一内存带来最佳性能
• ✅ 支持模型：Mistral-Small-3.2-24B、Qwen2.5-VL-72B
• ⚠️ 需 macOS 系统且配备 Apple Silicon 芯片

NVIDIA GPU

• ✅ 推荐使用 vLLM 或 Ollama 后端
• ✅ 建议使用 Nvidia DGX Spark（显存 12GB 以上）或 AMD GPU
• ⚠️ 需配置 CUDA 环境

仅 CPU

• ⚠️ 性能显著较低
• ✅ 宜选用较小规模模型（参数量不超过 7B）
• ✅ 可考虑使用 Hugging Face 云端后端

内存管理

# 降低内存占用
--crop-size 100        # 裁剪大尺寸图片
--options tables_only  # 仅处理表格

# 处理大型 PDF
--debug-dir ./temp     # 监控处理过程
# 必要时手动拆分大 PDF

模型选择

🔍 故障排除

常见问题

# 检查 Python 版本
python --version  # 应为 3.12.10+

# 使用 pyenv 修复
pyenv install 3.12.10
pyenv global 3.12.10

# 若 MLX 安装失败
pip install --upgrade pip
pip install mlx-vlm --no-cache-dir

# 若 pip install 报错 AttributeError: 'NoneType' object has no attribute 'get'
# 存在安全风险——绕过了 SSL 验证。请在了解风险的情况下谨慎操作
pip install mlx-vlm --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org

# macOS
brew install poppler

# Ubuntu/Debian  
sudo apt-get install poppler-utils

# 验证安装
pdftoppm -h

# 清除模型缓存
rm -rf ~/.cache/huggingface/
rm -rf ~/.mlx/

# 重新下载模型
python -c "from mlx_vlm import load; load('model-name')"

# 检查服务是否运行
curl http://localhost:8002/health

# 查看日志
python api.py --debug

# 手动测试 PDF
pdftoppm -png input.pdf output

# 检查页数
python -c "
import pypdf
with open('file.pdf', 'rb') as f:
    reader = pypdf.PdfReader(f)
    print(f'Pages: {len(reader.pages)}')
"

获取帮助

1. 📖 查阅文档：仔细阅读本 README 和各组件文档
2. 🐛 搜索问题：访问 GitHub Issues
3. 💬 提交新问题：提供日志、系统信息及最小复现示例
4. 📧 商业支持：联系 abaranovskis@redsamuraiconsulting.com

⭐ 星标历史

📜 许可证

开源：采用 GPL 3.0 许可证。对开源项目及年收入低于 500 万美元的组织免费。

商业版：提供双重许可，适用于专有用途、企业级功能及专属支持。

联系方式：如需商业许可或咨询，请联系 abaranovskis@redsamuraiconsulting.com。

👥 作者

• Katana ML - AI/ML 咨询与解决方案提供商
• Andrej Baranovskij - 主要开发者

⭐ 如果 Sparrow 对您的项目有帮助，请在 GitHub 上为我们点亮星标！
github.com/katanaml/sparrow