feat(paddleocr): add PaddleOCR OCR service (Docker images, server, tests, docs) and CI workflows

2026-01-16 13:23:01 +00:00
parent 67c38eeb67
commit bec379e9ca
10 changed files with 624 additions and 71 deletions
--- a/test/test.invoices.ts
+++ b/test/test.invoices.ts
@@ -22,16 +22,11 @@ interface IInvoice {
 * Extract OCR text from an image using PaddleOCR
 */
 async function extractOcrText(imageBase64: string): Promise<string> {
-  const formData = new FormData();
-  const imageBuffer = Buffer.from(imageBase64, 'base64');
-  const blob = new Blob([imageBuffer], { type: 'image/png' });
-  formData.append('img', blob, 'image.png');
-  formData.append('outtype', 'json');
-
  try {
    const response = await fetch(`${PADDLEOCR_URL}/ocr`, {
      method: 'POST',
-      body: formData,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ image: imageBase64 }),
    });

    if (!response.ok) return '';
@@ -180,29 +175,64 @@ function hashInvoice(invoice: IInvoice): string {

 /**
 * Extract with majority voting - run until 2 passes match
+ * Optimization: Run Pass 1, OCR, and Pass 2 (after OCR) in parallel
 */
 async function extractWithConsensus(images: string[], invoiceName: string, maxPasses: number = 5): Promise<IInvoice> {
  const results: Array<{ invoice: IInvoice; hash: string }> = [];
  const hashCounts: Map<string, number> = new Map();

-  // Extract OCR text from first page
-  const ocrText = await extractOcrText(images[0]);
-  if (ocrText) {
-    console.log(`  [OCR] Extracted ${ocrText.split('\n').length} text lines`);
+  const addResult = (invoice: IInvoice, passLabel: string): number => {
+    const hash = hashInvoice(invoice);
+    results.push({ invoice, hash });
+    hashCounts.set(hash, (hashCounts.get(hash) || 0) + 1);
+    console.log(`  [${passLabel}] ${invoice.invoice_number} | ${invoice.invoice_date} | ${invoice.total_amount} ${invoice.currency}`);
+    return hashCounts.get(hash)!;
+  };
+
+  // OPTIMIZATION: Run Pass 1 (no OCR) in parallel with OCR -> Pass 2 (with OCR)
+  let ocrText = '';
+  const pass1Promise = extractOnce(images, 1, '').catch((err) => ({ error: err }));
+
+  // OCR then immediately Pass 2
+  const ocrThenPass2Promise = (async () => {
+    ocrText = await extractOcrText(images[0]);
+    if (ocrText) {
+      console.log(`  [OCR] Extracted ${ocrText.split('\n').length} text lines`);
+    }
+    return extractOnce(images, 2, ocrText).catch((err) => ({ error: err }));
+  })();
+
+  // Wait for both to complete
+  const [pass1Result, pass2Result] = await Promise.all([pass1Promise, ocrThenPass2Promise]);
+
+  // Process Pass 1 result
+  if ('error' in pass1Result) {
+    console.log(`  [Pass 1] Error: ${(pass1Result as {error: unknown}).error}`);
+  } else {
+    const count = addResult(pass1Result as IInvoice, 'Pass 1');
+    if (count >= 2) {
+      console.log(`  [Consensus] Reached after parallel passes`);
+      return pass1Result as IInvoice;
+    }
  }

-  for (let pass = 1; pass <= maxPasses; pass++) {
+  // Process Pass 2 result
+  if ('error' in pass2Result) {
+    console.log(`  [Pass 2+OCR] Error: ${(pass2Result as {error: unknown}).error}`);
+  } else {
+    const count = addResult(pass2Result as IInvoice, 'Pass 2+OCR');
+    if (count >= 2) {
+      console.log(`  [Consensus] Reached after parallel passes`);
+      return pass2Result as IInvoice;
+    }
+  }
+
+  // Continue with passes 3+ using OCR text if no consensus yet
+  for (let pass = 3; pass <= maxPasses; pass++) {
    try {
      const invoice = await extractOnce(images, pass, ocrText);
-      const hash = hashInvoice(invoice);
+      const count = addResult(invoice, `Pass ${pass}+OCR`);

-      results.push({ invoice, hash });
-      hashCounts.set(hash, (hashCounts.get(hash) || 0) + 1);
-
-      console.log(`  [Pass ${pass}] ${invoice.invoice_number} | ${invoice.invoice_date} | ${invoice.total_amount} ${invoice.currency}`);
-
-      // Check if we have consensus (2+ matching)
-      const count = hashCounts.get(hash)!;
      if (count >= 2) {
        console.log(`  [Consensus] Reached after ${pass} passes`);
        return invoice;
@@ -267,6 +297,7 @@ function compareInvoice(

 /**
 * Find all test cases (PDF + JSON pairs) in .nogit/invoices/
+ * Priority invoices (like vodafone) run first for quick feedback
 */
 function findTestCases(): Array<{ name: string; pdfPath: string; jsonPath: string }> {
  const testDir = path.join(process.cwd(), '.nogit/invoices');
@@ -290,6 +321,22 @@ function findTestCases(): Array<{ name: string; pdfPath: string; jsonPath: strin
    }
  }

+  // Sort with priority invoices first, then alphabetically
+  const priorityPrefixes = ['vodafone'];
+  testCases.sort((a, b) => {
+    const aPriority = priorityPrefixes.findIndex((p) => a.name.startsWith(p));
+    const bPriority = priorityPrefixes.findIndex((p) => b.name.startsWith(p));
+
+    // Both have priority - sort by priority order
+    if (aPriority >= 0 && bPriority >= 0) return aPriority - bPriority;
+    // Only a has priority - a comes first
+    if (aPriority >= 0) return -1;
+    // Only b has priority - b comes first
+    if (bPriority >= 0) return 1;
+    // Neither has priority - alphabetical
+    return a.name.localeCompare(b.name);
+  });
+
  return testCases;
 }

--- a/test/test.paddleocr.ts
+++ b/test/test.paddleocr.ts
@@ -0,0 +1,258 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import * as os from 'os';
+
+const PADDLEOCR_URL = 'http://localhost:5000';
+
+interface IOCRResult {
+  text: string;
+  confidence: number;
+  box: number[][];
+}
+
+interface IOCRResponse {
+  success: boolean;
+  results: IOCRResult[];
+  error?: string;
+}
+
+interface IHealthResponse {
+  status: string;
+  model: string;
+  language: string;
+  gpu_enabled: boolean;
+}
+
+/**
+ * Convert PDF first page to PNG using ImageMagick
+ */
+function convertPdfToImage(pdfPath: string): string {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pdf-convert-'));
+  const outputPath = path.join(tempDir, 'page.png');
+
+  try {
+    execSync(
+      `convert -density 200 -quality 90 "${pdfPath}[0]" -background white -alpha remove "${outputPath}"`,
+      { stdio: 'pipe' }
+    );
+
+    const imageData = fs.readFileSync(outputPath);
+    return imageData.toString('base64');
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Create a simple test image with text using ImageMagick
+ */
+function createTestImage(text: string): string {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-image-'));
+  const outputPath = path.join(tempDir, 'test.png');
+
+  try {
+    execSync(
+      `convert -size 400x100 xc:white -font DejaVu-Sans -pointsize 24 -fill black -gravity center -annotate 0 "${text}" "${outputPath}"`,
+      { stdio: 'pipe' }
+    );
+
+    const imageData = fs.readFileSync(outputPath);
+    return imageData.toString('base64');
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+// Health check test
+tap.test('should respond to health check', async () => {
+  const response = await fetch(`${PADDLEOCR_URL}/health`);
+  expect(response.ok).toBeTrue();
+
+  const data: IHealthResponse = await response.json();
+  expect(data.status).toEqual('healthy');
+  expect(data.model).toEqual('PP-OCRv4');
+  expect(data.language).toBeTypeofString();
+  expect(data.gpu_enabled).toBeTypeofBoolean();
+
+  console.log(`PaddleOCR Status: ${data.status}`);
+  console.log(`  Model: ${data.model}`);
+  console.log(`  Language: ${data.language}`);
+  console.log(`  GPU Enabled: ${data.gpu_enabled}`);
+});
+
+// Base64 OCR test
+tap.test('should perform OCR on base64 image', async () => {
+  // Create a test image with known text
+  const testText = 'Hello World 12345';
+  console.log(`Creating test image with text: "${testText}"`);
+
+  const imageBase64 = createTestImage(testText);
+
+  const response = await fetch(`${PADDLEOCR_URL}/ocr`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ image: imageBase64 }),
+  });
+
+  expect(response.ok).toBeTrue();
+
+  const data: IOCRResponse = await response.json();
+  expect(data.success).toBeTrue();
+  expect(data.results).toBeArray();
+
+  const extractedText = data.results.map((r) => r.text).join(' ');
+  console.log(`Extracted text: "${extractedText}"`);
+
+  // Check that we got some text back
+  expect(data.results.length).toBeGreaterThan(0);
+
+  // Check that at least some of the expected text was found
+  const normalizedExtracted = extractedText.toLowerCase().replace(/\s+/g, '');
+  const normalizedExpected = testText.toLowerCase().replace(/\s+/g, '');
+  const hasPartialMatch =
+    normalizedExtracted.includes('hello') ||
+    normalizedExtracted.includes('world') ||
+    normalizedExtracted.includes('12345');
+
+  expect(hasPartialMatch).toBeTrue();
+});
+
+// File upload OCR test
+tap.test('should perform OCR via file upload', async () => {
+  const testText = 'Invoice Number 98765';
+  console.log(`Creating test image with text: "${testText}"`);
+
+  const imageBase64 = createTestImage(testText);
+  const imageBuffer = Buffer.from(imageBase64, 'base64');
+
+  const formData = new FormData();
+  const blob = new Blob([imageBuffer], { type: 'image/png' });
+  formData.append('img', blob, 'test.png');
+
+  const response = await fetch(`${PADDLEOCR_URL}/ocr/upload`, {
+    method: 'POST',
+    body: formData,
+  });
+
+  expect(response.ok).toBeTrue();
+
+  const data: IOCRResponse = await response.json();
+  expect(data.success).toBeTrue();
+  expect(data.results).toBeArray();
+
+  const extractedText = data.results.map((r) => r.text).join(' ');
+  console.log(`Extracted text: "${extractedText}"`);
+
+  // Check that we got some text back
+  expect(data.results.length).toBeGreaterThan(0);
+});
+
+// OCR result structure test
+tap.test('should return proper OCR result structure', async () => {
+  const testText = 'Test 123';
+  const imageBase64 = createTestImage(testText);
+
+  const response = await fetch(`${PADDLEOCR_URL}/ocr`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ image: imageBase64 }),
+  });
+
+  const data: IOCRResponse = await response.json();
+
+  if (data.results.length > 0) {
+    const result = data.results[0];
+
+    // Check result has required fields
+    expect(result.text).toBeTypeofString();
+    expect(result.confidence).toBeTypeofNumber();
+    expect(result.box).toBeArray();
+
+    // Check bounding box structure (4 points, each with x,y)
+    expect(result.box.length).toEqual(4);
+    for (const point of result.box) {
+      expect(point.length).toEqual(2);
+      expect(point[0]).toBeTypeofNumber();
+      expect(point[1]).toBeTypeofNumber();
+    }
+
+    // Confidence should be between 0 and 1
+    expect(result.confidence).toBeGreaterThan(0);
+    expect(result.confidence).toBeLessThanOrEqual(1);
+
+    console.log(`Result structure valid:`);
+    console.log(`  Text: "${result.text}"`);
+    console.log(`  Confidence: ${(result.confidence * 100).toFixed(1)}%`);
+    console.log(`  Box: ${JSON.stringify(result.box)}`);
+  }
+});
+
+// Test with actual invoice if available
+const invoiceDir = path.join(process.cwd(), '.nogit/invoices');
+if (fs.existsSync(invoiceDir)) {
+  const pdfFiles = fs.readdirSync(invoiceDir).filter((f) => f.endsWith('.pdf'));
+
+  if (pdfFiles.length > 0) {
+    const testPdf = pdfFiles[0];
+    tap.test(`should extract text from invoice: ${testPdf}`, async () => {
+      const pdfPath = path.join(invoiceDir, testPdf);
+      console.log(`Converting ${testPdf} to image...`);
+
+      const imageBase64 = convertPdfToImage(pdfPath);
+      console.log(`Image size: ${(imageBase64.length / 1024).toFixed(1)} KB`);
+
+      const startTime = Date.now();
+
+      const response = await fetch(`${PADDLEOCR_URL}/ocr`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ image: imageBase64 }),
+      });
+
+      const endTime = Date.now();
+      const elapsedMs = endTime - startTime;
+
+      expect(response.ok).toBeTrue();
+
+      const data: IOCRResponse = await response.json();
+      expect(data.success).toBeTrue();
+
+      console.log(`OCR completed in ${(elapsedMs / 1000).toFixed(2)}s`);
+      console.log(`Found ${data.results.length} text regions`);
+
+      // Print first 10 results
+      const preview = data.results.slice(0, 10);
+      console.log(`\nFirst ${preview.length} results:`);
+      for (const result of preview) {
+        console.log(`  [${(result.confidence * 100).toFixed(0)}%] ${result.text}`);
+      }
+
+      if (data.results.length > 10) {
+        console.log(`  ... and ${data.results.length - 10} more`);
+      }
+
+      // Should find text in an invoice
+      expect(data.results.length).toBeGreaterThan(5);
+    });
+  }
+}
+
+// Error handling test
+tap.test('should handle invalid base64 gracefully', async () => {
+  const response = await fetch(`${PADDLEOCR_URL}/ocr`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ image: 'not-valid-base64!!!' }),
+  });
+
+  const data: IOCRResponse = await response.json();
+
+  // Should return success: false with error message
+  expect(data.success).toBeFalse();
+  expect(data.error).toBeTypeofString();
+  console.log(`Error handling works: ${data.error}`);
+});
+
+export default tap.start();