中国发票
& 数据提取器

1.1 什么是 XteVision 发票提取器？

XteVision 发票提取器是一个 独立的 Node.js 服务器，用于从 中国发票 PDF 中提取结构化数据，并将结果保存为 CSV 文件。该版本可独立运行——无需 ComfyUI，因此可在任何装有 Node.js 的机器上部署，并可选地配备 Ollama 视觉模型。

1.2 核心能力

• PDF 处理：将发票 PDF 转化为图像，并通过 OCR 提取文本
• 二维码识别：读取中国税务二维码，获取权威的金额与编号
• LLM 集成：使用 Ollama 视觉模型（如 qwen2.5vl:latest）进行智能字段提取
• CSV 导出：输出支持中文、兼容 Excel 的 UTF-8 BOM CSV 文件
• 批量处理：一次性处理整个文件夹中的发票
• Web 界面：支持拖拽的单张或批量处理界面

1.3 目标用户

• 主要用户：需要快速、准确地将大量中国发票数字化的财务与会计团队
• 次要用户：将发票提取集成到更大规模记账或 ERP 工作流中的开发者

2.1 高层架构

┌─────────────────────────────────────────────────────────────┐
│                    XteVision 发票提取器                          │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
│  │   PDF    │──▶│  二维码    │──▶│  Ollama  │──▶│   CSV    │ │
│  │处理器    │   │  解码器    │   │  提取器   │   │  写入器   │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘ │
│       │              │              │              │        │
│       ▼              ▼              ▼              ▼        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              发票数据合并器                        │  │
│  │   (二维码数据 = 金额与编号的标准真值)              │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

2.2 通信流程

1. 前端 → 服务器：通过 Web 界面或 REST API 上传 PDF 或文件夹路径
2. PDF 处理器：以 300 DPI 光栅化页面并执行 OCR（中文 + 英文）
3. 二维码解码器：检测和解码税务二维码，解析金额、日期和发票号
4. LLM 提取器：将图像和 OCR 文本发送给 Ollama 视觉模型，提取公司名称、税率、产品类型和备注
5. 数据合并器：合并二维码（标准真值）与 LLM 数据，然后写入 CSV

2.3 部署模式

该服务器专为 自托管、独立运行而设计：

• 作为独立的 Node.js 服务器运行于你自己的硬件上
• 无需 ComfyUI、PyTorch 或 GPU——可在 CPU 上运行
• Ollama 模型可本地运行，也可运行于远程主机（设置 OLLAMA_URL）
• 所有发票数据保留在你的本地服务器上——无云端依赖

• Node.js ≥ 18.0.0
• Ollama 并安装视觉模型（如 qwen2.5vl:latest）
• Tesseract OCR 用于文本提取（含中文语言数据）
• Poppler（可选，用于更好的 PDF 渲染）

4.1 macOS

# 安装 Homebrew 包
brew install tesseract tesseract-lang poppler

# 安装中文语言数据
brew install tesseract-lang

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取视觉模型
ollama pull qwen2.5vl:latest

4.2 Ubuntu/Debian

# 安装系统包
sudo apt-get update
sudo apt-get install -y tesseract-ocr tesseract-ocr-chi-sim poppler-utils

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取视觉模型
ollama pull qwen2.5vl:latest

4.3 Windows

# 通过 Chocolatey 安装
choco install tesseract poppler

# 或从以下地址下载：
# Tesseract: https://github.com/UB-Mannheim/tesseract/wiki
# Poppler: https://blog.alivate.com.au/poppler-windows/

# 从 https://ollama.com 安装 Ollama
ollama pull qwen2.5vl:latest

5.1 安装与配置

# 进入项目目录
cd XteVision-standalone

# 安装依赖
npm install

# 复制环境配置
cp .env.example .env

# 根据你的环境编辑 .env
# 特别是当 Ollama 运行于其他主机时，需设置 OLLAMA_URL

5.2 启动服务器

# 启动服务器
npm start

# 或在开发模式下自动重载
npm run dev

服务器将启动于 http://localhost:3000。

编辑 .env 文件以匹配你的部署。支持以下键：

7.1 接口概览

7.2 示例

处理单张发票：

curl -X POST http://localhost:3000/api/process \
  -F "invoice=@/path/to/invoice.pdf" \
  -F "model=qwen2.5vl:latest" \
  -F "filenamePrefix=invoice_data"

处理文件夹中的发票：

curl -X POST http://localhost:3000/api/process-folder \
  -H "Content-Type: application/json" \
  -d '{
    "folderPath": "/path/to/invoices",
    "model": "qwen2.5vl:latest",
    "filenamePrefix": "batch_invoices"
  }'

1. PDF 处理：将 PDF 页面转化为图像（默认 300 DPI）并执行 OCR（中文 + 英文）。
2. 二维码识别：检测和解码发票图像中的二维码，解析发票号、金额和日期。二维码数据被视为标准真值。
3. LLM 提取：将图像和 OCR 文本发送给 Ollama 视觉模型，提取公司名称、税率、产品类型和备注。
4. 数据合并：二维码数据在发票号、总金额和日期上具有绝对优先级。LLM 数据提供公司名称、税率、产品内容和备注。未税金额和税额根据 QR 总额结合 LLM 税率重新计算。
5. CSV 生成：将合并数据写入 UTF-8 BOM CSV 以兼容 Excel，并支持批处理模式下的追加写入。

8.1 CSV 输出字段

9.1 Ollama 连接问题

# 检查 Ollama 是否正在运行
ollama list

# 检查 Ollama API
curl http://localhost:11434/api/tags

# 若使用远程 Ollama，请在 .env 中设置 OLLAMA_URL
OLLAMA_URL=http://192.168.1.100:11434

9.2 OCR 无法工作

# 检查 Tesseract 安装
tesseract --version

# 列出可用语言
tesseract --list-langs

# 若缺少中文语言数据：
# Ubuntu/Debian:
sudo apt-get install tesseract-ocr-chi-sim
# macOS:
brew install tesseract-lang

9.3 PDF 渲染异常

# 确保已安装 poppler
# Ubuntu/Debian:
sudo apt-get install poppler-utils
# macOS:
brew install poppler