Chinese Invoice
& Data Extractor

1.1 What is XteVision Invoice Extractor?

XteVision Invoice Extractor is a standalone Node.js server for extracting structured data from Chinese invoice PDFs and saving the results to CSV files. This version runs independently — without ComfyUI — so it can be deployed on any machine with Node.js and, optionally, an Ollama vision model.

1.2 Key Capabilities

• PDF processing: Convert PDF invoices to images and extract text via OCR
• QR decoding: Read Chinese tax-authority QR codes for authoritative amounts and numbers
• LLM integration: Use an Ollama vision model (e.g. qwen2.5vl:latest) for intelligent field extraction
• CSV export: Write UTF-8 BOM CSV files with full Chinese character support and Excel compatibility
• Batch processing: Process an entire folder of invoices in one go
• Web UI: Drag-and-drop interface for single or batch processing

1.3 Target Users

• Primary: Finance and accounting teams that receive many Chinese invoices and need them digitized quickly and accurately
• Secondary: Developers integrating invoice extraction into a larger accounting or ERP workflow

2.1 High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    XteVision Invoice Extractor                    │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
│  │   PDF    │──▶│   QR     │──▶│  Ollama  │──▶│   CSV    │ │
│  │Processor │   │ Decoder  │   │Extractor │   │  Writer  │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘ │
│       │              │              │              │        │
│       ▼              ▼              ▼              ▼        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Invoice Data Merger                      │  │
│  │   (QR data = Ground Truth for amounts & numbers)      │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

2.2 Communication Flow

1. Frontend → Server: Upload a PDF or folder path via the Web UI or REST API
2. PDF Processor: Rasterize pages at 300 DPI and run OCR (Chinese + English)
3. QR Decoder: Detect and decode the tax QR code; parse amount, date, and invoice number
4. LLM Extractor: Send image + OCR text to the Ollama vision model for company name, tax rate, product type, and remarks
5. Data Merger: Combine QR (ground truth) and LLM data, then write the CSV

2.3 Deployment Model

The server is designed for self-hosted, standalone operation:

• Runs as a standalone Node.js server on your own hardware
• No ComfyUI, PyTorch, or GPU required — works on CPU
• The Ollama model may run locally or on a remote host (set OLLAMA_URL)
• All invoice data stays on your local server — no cloud dependency

• Node.js ≥ 18.0.0
• Ollama with a vision model installed (e.g. qwen2.5vl:latest)
• Tesseract OCR for text extraction (with Chinese language data)
• Poppler (optional, for better PDF rendering)

4.1 macOS

# Install Homebrew packages
brew install tesseract tesseract-lang poppler

# Install Chinese language data
brew install tesseract-lang

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

# Pull a vision model
ollama pull qwen2.5vl:latest

4.2 Ubuntu/Debian

# Install system packages
sudo apt-get update
sudo apt-get install -y tesseract-ocr tesseract-ocr-chi-sim poppler-utils

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

# Pull a vision model
ollama pull qwen2.5vl:latest

4.3 Windows

# Install via Chocolatey
choco install tesseract poppler

# Or download from:
# Tesseract: https://github.com/UB-Mannheim/tesseract/wiki
# Poppler: https://blog.alivate.com.au/poppler-windows/

# Install Ollama from https://ollama.com
ollama pull qwen2.5vl:latest

5.1 Install & Configure

# Navigate to the project directory
cd XteVision-standalone

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Edit .env to match your setup
# Especially OLLAMA_URL if Ollama is running on a different host

5.2 Start the Server

# Start the server
npm start

# Or with auto-reload for development
npm run dev

The server will start at http://localhost:3000.

Edit the .env file to match your deployment. The following keys are supported:

7.1 Endpoints Overview

7.2 Examples

Process a single invoice:

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

Process a folder of invoices:

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 Processing: Convert PDF pages to images (300 DPI default) and perform OCR (Chinese + English).
2. QR Code Decoding: Detect and decode the QR codes from invoice images, then parse the invoice number, amount, and date. QR data is treated as ground truth for amounts.
3. LLM Extraction: Send images and OCR text to the Ollama vision model to extract company name, tax rate, product type, and remarks.
4. Data Merging: QR data takes absolute priority for invoice number, total amount, and date. LLM data provides company name, tax rate, product content, and remarks. The untaxed amount and tax are recalculated from the QR total using the LLM tax rate.
5. CSV Generation: Write merged data to CSV with UTF-8 BOM for Excel compatibility, supporting append mode for batch processing.

8.1 CSV Output Columns

9.1 Ollama Connection Issues

# Check if Ollama is running
ollama list

# Check Ollama API
curl http://localhost:11434/api/tags

# If using remote Ollama, set OLLAMA_URL in .env
OLLAMA_URL=http://192.168.1.100:11434

9.2 OCR Not Working

# Check Tesseract installation
tesseract --version

# List available languages
tesseract --list-langs

# Install Chinese language if missing
# Ubuntu/Debian:
sudo apt-get install tesseract-ocr-chi-sim
# macOS:
brew install tesseract-lang

9.3 PDF Not Rendering Properly

# Ensure poppler is installed
# Ubuntu/Debian:
sudo apt-get install poppler-utils
# macOS:
brew install poppler