Documind trasforma PDF disordinati e scansioni in JSON puliti

Chiunque abbia mai scritto un parser per estratti conto bancari o fatture conosce questo dolore. Si usa pdf-parse o l'OCR classico, lo si esegue su un documento reale, e si ottiene un caos di righe dove le colonne delle tabelle sono disallineate, le date si mescolano con i numeri di contratto, e i totali si staccano dai nomi delle voci.

Con l'avvento dei modelli linguistici multimodali, il parsing dei documenti è diventato notevolmente più semplice. Ma assemblare la conversione pagina-per-immagine, l'invio al modello, la validazione della struttura e l'assemblaggio finale del JSON richiede tipicamente centinaia di righe di codice boilerplate.

Recentemente mi sono imbattuto in Documind su GitHub, un progetto del team DocumindHQ. È una piccola libreria Node.js che gestisce tutto il lavoro sporco dell'estrazione di dati strutturati da documenti non strutturati.

Cosa può fare la libreria

Sotto il cofano, Documind combina utility di rendering delle pagine di sistema e modelli vision. Il progetto è nato dal popolare strumento Zerox ma si è evoluto in una piattaforma standalone per lavorare con schemi di dati.

La libreria risolve quattro compiti specifici:

1. Legge vari formati: PDF, DOCX, HTML, TXT, PNG e JPG.
2. Accetta il tuo schema dei campi e restituisce JSON prevedibile popolato con i dati del documento.
3. Funziona sia con l'API cloud OpenAI che con modelli locali tramite Llava o Llama 3.2 Vision.
4. Converte documenti complessi multipagina in Markdown pulito, preservando le strutture delle tabelle e degli elenchi.

Se non hai tempo di definire manualmente uno schema dei campi, Documind può generarne uno automaticamente basato sui contenuti del primo documento.

Avvio rapido e dipendenze di sistema

La libreria è scritta in JavaScript per Node.js versione 18 e successive. Poiché il rendering delle pagine PDF in immagini richiede strumenti di basso livello, devi installare Ghostscript e GraphicsMagick nel tuo sistema prima di installare il pacchetto npm.

Su macOS, questo si fa tramite Homebrew:

brew install ghostscript graphicsmagick

Su Ubuntu o Debian:

sudo apt-get update
sudo apt-get install -y ghostscript graphicsmagick

Dopo di che, installa il pacchetto stesso:

npm install documind

Per lavorare con OpenAI, crea un file .env nella root del progetto e passa la chiave:

OPENAI_API_KEY=your_openai_api_key

Come definire uno schema dati

L'idea centrale dietro Documind è che definisci la forma dell'oggetto di output attraverso un array di campi. Ogni campo ha un nome, un tipo (string, number, array, object, boolean, enum), e una descrizione testuale che serve come hint per la rete neurale.

Ecco un esempio di schema per il parsing di un estratto conto bancario con una tabella delle transazioni nidificata:

const schema = [
  {
    name: "accountNumber",
    type: "string",
    description: "The account number of the bank statement."
  },
  {
    name: "openingBalance",
    type: "number",
    description: "The opening balance of the account."
  },
  {
    name: "transactions",
    type: "array",
    description: "List of transactions in the account.",
    children: [
      {
        name: "date",
        type: "string",
        description: "Transaction date."
      },
      {
        name: "creditAmount",
        type: "number",
        description: "Credit Amount of the transaction."
      },
      {
        name: "debitAmount",
        type: "number",
        description: "Debit Amount of the transaction."
      },
      {
        name: "description",
        type: "string",
        description: "Transaction description."
      }
    ]
  },
  {
    name: "closingBalance",
    type: "number",
    description: "The closing balance of the account."
  }
];

Ora passa lo schema e l'URL del file alla funzione extract:

import { extract } from 'documind';

async function main() {
  const result = await extract({
    file: 'https://example.com/bank_statement.pdf',
    schema
  });

  console.log(JSON.stringify(result, null, 2));
}

main();

Il risultato è un oggetto pronto all'uso senza la necessità di parsare testo grezzo con regex:

{
  "success": true,
  "pages": 1,
  "data": {
    "accountNumber": "100002345",
    "openingBalance": 3200,
    "transactions": [
      {
        "date": "2021-05-12",
        "creditAmount": null,
        "debitAmount": 100,
        "description": "transfer to Tom"
      },
      {
        "date": "2021-05-12",
        "creditAmount": 50,
        "debitAmount": null,
        "description": "For lunch the other day"
      }
    ],
    "closingBalance": 2420
  },
  "fileName": "bank_statement.pdf"
}

Template pronti all'uso

Per documenti tipici come scontrini, fatture o estratti conto standard, non devi scrivere uno schema da zero. La libreria include template integrati.

Puoi controllare l'elenco dei preset disponibili in questo modo:

import { templates } from 'documind';

console.log(templates.list());

E invocare il parsing tramite template è ancora più semplice:

import { extract } from 'documind';

const result = await extract({
  file: 'https://example.com/bank_statement.pdf',
  template: 'bank_statement'
});

Modelli locali e sicurezza dei dati

I documenti spesso contengono dati personali, cartelle mediche o informazioni finanziarie riservate che non possono essere inviate ad API cloud esterne.

Gli sviluppatori di Documind hanno integrato il supporto per modelli vision locali. Puoi eseguire Llama 3.2 Vision o Llava sul tuo server GPU e indirizzare le richieste lì. Il processo di parsing rimane lo stesso, ma i dati non escono mai dalla tua rete privata.

Cosa tenere a mente

Prima di distribuire il progetto in produzione, ci sono un paio di sfumature da considerare:

• Licenza AGPL v3.0. Se prevedi di incorporare Documind direttamente in un backend commerciale chiuso, i requisiti stricti dell'AGPL potrebbero diventare un problema legale. In quel caso, ha più senso isolare l'elaborazione dei documenti in un microservizio separato.
• Binari di sistema. Ghostscript e GraphicsMagick complicano il deployment in ambienti serverless come AWS Lambda o Vercel Functions se non stai costruendo un'immagine Docker personalizzata.

A chi sarà utile

Documind è ottimo per i team che costruiscono pipeline di elaborazione dei documenti in entrata, automatizzano servizi fintech, o preparano database di documenti non strutturati per il caricamento in vector store (RAG).

Lo strumento elimina la necessità di scrivere parser fragili basati su regex e ti dà un risultato tipizzato in poche righe di codice. Se hai bisogno di automatizzare rapidamente l'inserimento manuale dei documenti, questo repository merita sicuramente un'occhiata.