Sparrow 智能文档数据提取平台使用指南

Sparrow 是一款基于机器学习技术的文档数据提取工具，能够从各类文档、表单和图像中精准提取结构化数据。无论是发票、收据、银行对账单还是复杂表格，Sparrow 都能通过设备端部署的视觉大语言模型（Vision LLM）实现高效处理。本指南将帮助您从核心功能认知到实际操作应用，全面掌握 Sparrow 平台的使用方法。

一、核心功能解析

1.1 多模态文档处理系统

Sparrow 采用模块化架构设计，整合了光学字符识别（OCR）、大语言模型（LLM）和计算机视觉技术，形成完整的数据处理流水线。系统架构包含用户交互层、核心引擎层和基础设施层三个主要部分：

• 用户交互层：提供 Dashboard 可视化界面、API 接口和命令行（CLI）三种操作方式，满足不同场景需求
• 核心引擎层：包含文档处理、任务调度、数据分析和函数调用等核心功能模块
• 基础设施层：支持 vLLM、MLX、PyTorch 和 Ollama 等多种大语言模型运行环境

这种架构设计使 Sparrow 能够灵活应对从简单数据提取到复杂文档分析的各类任务，同时保持系统的可扩展性和稳定性。

1.2 智能代理系统

Sparrow 内置多种专业代理（Agents），针对不同业务场景优化数据提取策略：

• 医疗处方代理：专门处理医疗文档，能够识别药品名称、剂量、用药频率等专业信息
• 交易分析代理：针对金融文档优化，可提取交易对手、金额、日期等关键数据
• 通用文档代理：适用于大多数通用文档类型，提供平衡的提取精度和处理速度

各代理模块可通过配置文件灵活切换，您可以根据实际需求选择最适合的处理方案。

1.3 可视化操作与API支持

Sparrow 提供直观的用户界面和强大的 API 接口，满足不同技术背景用户的使用需求：

• Web界面：通过浏览器即可完成文件上传、参数配置和结果查看的全流程操作
• API接口：支持 RESTful 风格调用，方便集成到现有业务系统中
• 批处理能力：支持大量文档的批量处理，适合企业级应用场景

二、环境准备

2.1 系统要求与依赖安装

在开始使用 Sparrow 前，请确保您的系统满足以下要求：

• 操作系统：Linux（推荐 Ubuntu 20.04 或更高版本）
• 内存：至少 16GB（处理大型文档或批量任务建议 32GB 以上）
• 存储空间：至少 20GB 可用空间
• Python 版本：3.8 - 3.10

首先，克隆项目仓库到本地：

git clone https://gitcode.com/gh_mirrors/spa/sparrow
cd sparrow

Sparrow 采用模块化设计，不同功能模块有各自的依赖需求。您可以根据需要安装相应的依赖包：

# 基础依赖
pip install -r sparrow-ml/requirements_instructor.txt

# 如果需要使用llamaindex代理
pip install -r sparrow-ml/requirements_llamaindex.txt

# 如果需要使用haystack代理
pip install -r sparrow-ml/requirements_haystack.txt

🔍 注意：不同代理的依赖可能存在冲突，如果需要在同一环境中使用多种代理，建议使用虚拟环境隔离。例如：

# 创建并激活虚拟环境
python -m venv env_llamaindex
source env_llamaindex/bin/activate

# 在虚拟环境中安装特定代理依赖
pip install -r sparrow-ml/requirements_llamaindex.txt

2.2 模型配置与初始化

Sparrow 支持多种大语言模型后端，您需要根据硬件条件选择合适的模型配置：

1. 本地GPU部署：如果您的设备配备NVIDIA GPU且显存大于10GB，建议使用vLLM后端以获得最佳性能
2. 本地CPU部署：对于没有GPU的设备，可以使用Ollama后端运行较小的模型
3. Mac设备：推荐使用MLX后端，针对Apple Silicon进行了优化

📌 重点：首次运行前，需要初始化模型配置文件。复制示例配置并根据您的环境修改：

# 复制示例配置文件
cp sparrow-ml/config.properties.example sparrow-ml/config.properties

# 使用文本编辑器修改配置
nano sparrow-ml/config.properties

在配置文件中，您需要设置模型路径、硬件加速选项和缓存目录等关键参数。

三、操作指南

3.1 快速启动与基本操作

Sparrow 提供了便捷的启动脚本，让您可以快速开始使用系统功能。通过以下步骤，您可以在几分钟内完成第一次文档数据提取：

1. 启动服务：

# 启动Sparrow服务
cd sparrow-ml
./sparrow.sh start

2. 访问Web界面： 打开浏览器，访问 http://localhost:8000，您将看到Sparrow的主界面：

3. 上传文档并提取数据：
   • 点击"Choose File"按钮，选择要处理的文档（支持PDF、图片等格式）
   • 在查询框中输入提取指令，例如：[{"instrument_name":"str", "valuation":"0"}]
   • 点击"Process"按钮开始处理
   • 查看右侧结果区域的提取结果

📌 重点：验证方法 - 提取完成后，检查结果JSON中的"valid"字段是否为"true"，表示提取成功。

3.2 命令行工具使用

对于需要自动化或批量处理的场景，Sparrow 提供了功能完善的命令行工具：

场景：批量处理发票文件，提取发票号码、日期和总金额

操作：

# 使用instructor代理处理invoice_1.jpg
./sparrow.sh ingest \
  --file-path sparrow-ml/llm/data/invoice_1.jpg \
  --agent instructor \
  --index-name invoice_data \
  --output-format json

预期结果： 命令执行完成后，将在当前目录生成一个JSON文件，包含提取的发票信息：

{
  "invoice_number": "61356291",
  "date_of_issue": "09/06/2012",
  "total_amount": 212.09,
  "valid": true
}

🔍 注意：命令行工具支持通配符批量处理多个文件，例如 --file-path "data/invoices/*.pdf"。

3.3 API接口调用

对于开发人员，Sparrow 提供了RESTful API接口，可以方便地集成到自定义应用中：

场景：通过API提取银行对账单中的交易数据

操作：

# 使用curl调用API
curl -X POST http://localhost:8000/api/v1/sparrow-llm/inference \
  -H "Content-Type: multipart/form-data" \
  -F "file=@sparrow-ml/llm/data/bank_statement.png" \
  -F "query=[{\"transaction_date\":\"str\", \"description\":\"str\", \"amount\":\"float\"}]" \
  -F "pipeline=sparrow-parse" \
  -F "options=mlx:mlx-community/Qwen2-5-VL-7B-Instruct-4bit"

预期结果： API将返回JSON格式的交易数据列表：

{
  "data": [
    {"transaction_date": "02/01", "description": "PGD EasyPay Debit", "amount": -203.24},
    {"transaction_date": "02/02", "description": "AB&B Online Payment", "amount": -71.23},
    // 更多交易记录...
  ],
  "valid": true
}

四、进阶配置

4.1 代理选择策略

Sparrow 提供多种代理，适用于不同场景，选择合适的代理可以显著提高提取 accuracy：

• instructor代理：

  • 适用场景：结构化数据提取，如表格、表单
  • 优势：提取精度高，支持复杂数据结构
  • 推荐模型：Qwen2-VL、Llava

• llamaindex代理：

  • 适用场景：长文档处理，多文档关联分析
  • 优势：支持文档索引和语义检索
  • 推荐模型：GPT-4V、Claude 3

• haystack代理：

  • 适用场景：大规模文档库检索与提取
  • 优势：处理速度快，支持分布式部署
  • 推荐模型：Mistral Large、Llama 3

📌 重点：对于财务文档（如发票、银行对账单），建议优先使用instructor代理；对于研究论文、技术文档等长文本，推荐使用llamaindex代理。

4.2 性能优化配置

根据您的硬件条件和任务需求，可以通过以下配置优化Sparrow的性能：

1. 模型选择：

   • 高性能GPU（>24GB显存）：使用Qwen2-5-VL-7B或更大模型
   • 中等GPU（8-12GB显存）：使用4-bit量化的Qwen2-5-VL-4B模型
   • CPU/低配置设备：使用Ollama运行llama3-vision:8B模型

2. 并行处理： 修改配置文件启用多线程处理：

   [processing]
   max_workers=4
   batch_size=2
   

3. 缓存配置： 启用模型缓存以加快重复任务处理速度：

   [cache]
   enabled=true
   cache_dir=./cache
   max_cache_size=10GB
   

🔍 注意：缓存会占用较多磁盘空间，定期清理不再需要的缓存可以释放存储空间。

4.3 自定义数据提取模板

对于特定格式的文档，您可以创建自定义提取模板以提高准确性：

1. 创建模板文件 custom_templates/invoice_template.json：

{
  "fields": [
    {"name": "invoice_number", "type": "str", "regex": "Invoice no: (\\d+)"},
    {"name": "date", "type": "date", "format": "DD/MM/YYYY"},
    {"name": "total_amount", "type": "float", "xpath": "//table[contains(@class, 'summary')]/tr[last()]/td[last()]"}
  ]
}

2. 使用自定义模板进行提取：

./sparrow.sh ingest \
  --file-path data/invoice.pdf \
  --agent instructor \
  --template custom_templates/invoice_template.json

通过自定义模板，您可以针对特定文档格式优化提取规则，显著提高复杂文档的处理 accuracy。

Sparrow 为文档数据提取提供了强大而灵活的解决方案，无论是个人用户还是企业级应用都能找到合适的使用方式。通过本指南的学习，您已经掌握了从环境搭建到高级配置的全部要点。随着使用深入，您可以进一步探索 Sparrow 的高级功能，如自定义模型训练、多模态数据融合等，以满足更复杂的业务需求。