Site icon Ryadel

Harpyx: progetto open-source per RAG-based Document Intelligence

Ryan
Harpyx: Open-Source Platform for RAG-Based Document Intelligence

Negli ultimi mesi mi è capitato più volte di lavorare con aziende che volevano usare l’AI per qualcosa di più concreto della semplice generazione di testi da prompt: nello specifico, avevano la necessità di recuperare dati da una serie di archivi documentali in loro possesso, e produrre poi una serie di elaborazioni (o dati ulteriori) su quei dati recuperati.

La prima cosa che mi è venuta in mente, in questi casi, è stata suggerire l'utilizzo di strumenti come NotebookLM. Negli ultimi anni, anche grazie ai progressi dei modelli generativi e all’aumento delle finestre di contesto, questi strumenti hanno reso molto più accessibile un tipo di analisi documentale che fino a poco tempo fa avrebbe richiesto pipeline custom, indicizzazione dedicata e parecchio lavoro di integrazione. Per esigenze di quel tipo quegli strumenti solitamente funzionano bene, e consentono effettivamente di raggiungere l'obiettivo che ci si prefigge: sembra davvero di parlare con un assistente che si è letto tutte quelle informazioni ed è in grado di utilizzarle per generare contenuti nuovi.

Il problema nasce quando si ha a che fare con banche dati che, per usare un eufemismo, tendono ad essere molto eterogenee. In primo luogo per via dei formati, che contribuiscono non poco a complicare il quadro: PDF, fogli di calcolo, file di testo, email, presentazioni PowerPoint, documenti Word, esportazioni HTML e archivi compressi non sono sempre supportati da quel tipo di strumenti, e anche quando lo sono non producono risultati uniformi. In secondo luogo per via della diversa tipologia di contenuti: specifiche tecniche, documentazione di progetto, contratti, verbali di riunione, ticket, manuali, report, presentazioni e scansioni accumulate negli anni, inevitabilmente prodotti da persone diverse, in momenti diversi, e soprattutto con criteri e stili diversi.

Per non parlare delle problematiche legate agli aspetti di data retention, governance e security. Negli ambienti professionali, i documenti portano spesso con sé vincoli concreti: dati personali, materiale confidenziale, policy di conservazione, audit, governance, permessi, requisiti GDPR; tutti aspetti che non è possibile gestire in modo efficace con strumenti di terze parti.

Dopo essermi scontrato più volte con questi problemi, ho iniziato a immaginare uno strumento che mi consentisse di risolvere entrambe queste problematiche, ovvero che mi fornisse maggior controllo su ingestion, storage, indicizzazione, retrieval, provider, tenant, quote e ciclo di vita dei dati. Insomma, avevo bisogno di una piattaforma adeguata ai carichi di lavoro reali delle aziende, dove la document intelligence deve inevitabilmente adattarsi a data source spesso non ottimali, nonché fare i conti con sicurezza, compliance, infrastruttura e operatività quotidiana.

Da questa esigenza è nato Harpyx: un progetto open-source, rilasciato con licenza MIT, che consente di svolgere attività di document intelligence, RAG-based analysis e knowledge work assistito dall'AI. La piattaforma può essere utilizzata in modalità self-hosted oppure in un ambiente  SaaS (con piano gratuito), ed è pensata per team che devono lavorare con raccolte documentali grandi, eterogenee e talvolta sensibili, mantenendo il controllo su come i dati vengono archiviati, elaborati e collegati ai provider LLM.

In questo articolo di presentazione cercherò di fornire una panoramica generale di Harpyx, evidenziando il modo in cui è organizzata la piattaforma dal punto di vista funzionale e architetturale e come può aiutare team e organizzazioni a lavorare su grandi raccolte documentali senza rinunciare al controllo su dati, infrastruttura e provider. Per quanto riguarda il dettaglio dell’installazione, la configurazione dei singoli componenti e l'implementazione interna delle pipeline di ingestion, indicizzazione e retrieval, consiglio di consultare la wiki ufficiale del progetto, che offre un taglio più tecnico e operativo.

Che cos’è Harpyx

L’idea alla base di Harpyx è semplice: l’AI basata sui documenti diventa molto più utile quando riesce a gestire il perimetro, spesso disordinato, dei documenti reali.

In molte aziende, la conoscenza non si trova in un unico repository ordinato. È distribuita tra PDF, file Word, fogli Excel, presentazioni PowerPoint, note Markdown, export HTML, file JSON, messaggi email, archivi compressi e materiale scansionato. Una parte è aggiornata, una parte è obsoleta, una parte è duplicata; e una quantità sorprendente resta comunque preziosa, se riesci a recuperarla nel momento giusto.

Non volevo che Harpyx fosse limitato dall’assunzione che un progetto contenga un piccolo numero di fonti curate. Questa assunzione funziona per attività di ricerca leggere, ma cede rapidamente quando si pensa a reparti tecnici, team legali, workflow di compliance, knowledge base per il customer support, documentazione interna o progetti software di lunga durata.

Harpyx è costruito attorno a questo perimetro più ampio. Considera ingestion, estrazione, chunking, storage e retrieval come parti centrali del sistema, non come dettagli nascosti dietro un pulsante di upload.

Progettato per grandi raccolte documentali

Harpyx è organizzato attorno a workspace, progetti, ingestion in background, chunking dei documenti, indicizzazione vettoriale e retrieval. L’architettura è pensata per supportare raccolte che possono crescere nel tempo, invece di presupporre che gli utenti mantengano le proprie fonti piccole e perfettamente ordinate.

In termini pratici, la scala effettiva di un’installazione Harpyx dipende dall’infrastruttura sottostante: SQL Server per i dati relazionali, object storage compatibile con MinIO per i file, OpenSearch per i workload di ricerca, Redis e RabbitMQ per coordinamento ed elaborazione in background, oltre alla capacità dei worker assegnati a ingestion e indicizzazione.

Questo rende il sistema scalabile dal punto di vista del design applicativo. Invece di essere vincolato soltanto da una quota SaaS fissa, l’operatore può scalare i servizi che contano per l’installazione: storage, ricerca, code, worker e utilizzo dei modelli.

Questo rende Harpyx anche più onesto come piattaforma. La document intelligence su larga scala non è magia: è il risultato di decisioni sullo storage, strategie di indicizzazione, gestione delle code, costi dei modelli, qualità del chunking e monitoraggio operativo. Harpyx prova a rendere visibili queste componenti, in modo che sviluppatori e amministratori possano capirle e migliorarle.

Oltre i PDF

Una piattaforma seria di document intelligence non può fermarsi ai PDF. Il supporto ai PDF è importante, naturalmente, ma la maggior parte dei repository reali contiene molto di più. Harpyx è progettato per gestire un insieme ampio di formati aziendali e tecnici, tra cui:

  • documenti PDF, incluso materiale destinato a workflow orientati all’OCR;
  • file di testo semplice, Markdown e HTML;
  • documenti Word, Excel e PowerPoint;
  • formati OpenDocument;
  • file CSV, JSON, XML e YAML;
  • file email e record di comunicazione esportati;
  • archivi compressi contenenti più documenti;
  • formati immagine che possono essere elaborati tramite pipeline OCR quando necessario.

I documenti caricati vengono validati, archiviati, elaborati in modo asincrono, estratti in testo, suddivisi in chunk ricercabili e preparati per il retrieval. I file lunghi possono essere spezzati in unità semantiche più piccole, così che le risposte si basino sui passaggi più rilevanti invece che su un contesto sovradimensionato e poco focalizzato.

Questa parte conta più di quanto possa sembrare all’inizio. Nei progetti di document AI, la qualità della risposta finale dipende molto da tutto ciò che accade prima che il prompt raggiunga il modello. Un’estrazione scadente, un chunking debole o un retrieval impreciso produrranno risposte deboli anche con un ottimo LLM dietro le quinte.

RAG by Design

Harpyx usa la retrieval-augmented generation come principio progettuale centrale.

Quando un utente fa una domanda, Harpyx non inoltra semplicemente il prompt a un modello: cerca nei documenti del progetto selezionato, recupera i chunk più rilevanti e invia quel contesto al modello chat configurato. La risposta è quindi ancorata al materiale caricato, invece di basarsi soltanto sulla conoscenza generale del modello.

La pipeline RAG è progettata per supportare l’intero flusso:

  • upload dei documenti e ingestion in background;
  • estrazione del testo da diversi formati file;
  • strategie di chunking adatte a documenti lunghi ed eterogenei;
  • generazione degli embedding, per rendere il contenuto estratto ricercabile tramite similarità semantica;
  • retrieval vettoriale e keyword-based, con supporto sia per la ricerca semantica sia per corrispondenze esatte o basate su termini;
  • chat a livello di progetto sulle raccolte documentali selezionate;
  • selezione del contesto con consapevolezza delle fonti, così che gli utenti possano capire da dove arriva una risposta.

Il mio obiettivo con Harpyx è mantenere questa pipeline comprensibile: i sistemi RAG possono diventare opachi molto rapidamente, soprattutto quando vengono confezionati come una feature invece che progettati come infrastruttura. Harpyx segue la strada opposta: ingestion, indicizzazione e retrieval sono parti esplicite dell’applicazione, perché sono proprio quelle che gli sviluppatori di solito devono regolare quando arriva il primo dataset reale.

Supporto flessibile ai provider LLM

Harpyx non è legato a un singolo provider AI: la piattaforma segue un modello bring-your-own-key e può essere configurata per lavorare con provider e capacità di modello differenti, inclusi chat, embedding e workflow orientati all’OCR. Oltre ai provider cloud, Harpyx può essere integrato anche con modelli locali o self-hosted, quando l’organizzazione preferisce mantenere l’elaborazione AI all’interno della propria infrastruttura o ridurre la dipendenza da servizi esterni. Questo consente ai team di scegliere la configurazione più adatta ai propri requisiti di privacy, profilo di costo, aspettative di latenza e vincoli di compliance.

Per le organizzazioni con esigenze operative più rigide, i modelli hosted possono anche essere configurati centralmente dagli amministratori. È una distinzione utile nella pratica: un piccolo team può desiderare la massima flessibilità, mentre un’azienda può preferire un elenco controllato di provider e modelli approvati.

Questa è una delle aree in cui il self-hosting fa davvero la differenza. Il provider AI è solo una parte del sistema; storage dei documenti, metadati, accesso utenti, policy di retention e auditability contano altrettanto quando la piattaforma viene usata con materiale sensibile o business-critical.

Self-hosted e controllata dall’operatore

Uno dei motivi principali per cui Harpyx esiste è il controllo. Con un’installazione self-hosted, l’operatore decide dove risiedono i dati, come vengono salvati, quali utenti possono accedervi, quali provider LLM sono disponibili e se utilizzare modelli cloud, modelli locali o endpoint self-hosted. Questo significa poter scegliere non solo dove archiviare i documenti, ma anche dove avviene l’elaborazione AI: presso un provider esterno, all’interno della propria infrastruttura, oppure attraverso una combinazione dei due approcci.

Queste capacità sono di primaria importanza per team che lavorano con documenti legali, procedure interne, record dei clienti, repository tecnici o dati regolamentati, dove privacy, data residency, auditability e controllo operativo non possono essere trattati come aspetti secondari.

Più nello specifico, Harpyx è progettato affinché gli operatori possano controllare:

  • dove vengono archiviati i documenti e il contenuto estratto;
  • quali componenti infrastrutturali vengono usati per storage, ricerca ed elaborazione in background;
  • quali provider e modelli LLM sono abilitati;
  • come sono organizzati utenti, tenant, workspace e progetti;
  • come vengono gestiti retention dei documenti, encryption, backup e disaster recovery;
  • come vengono gestiti log, observability e audit trail.

In molti scenari di document AI, questo livello di controllo è ciò che distingue un prototipo utile da qualcosa che può essere valutato seriamente all’interno di un’organizzazione.

Open source, licenza MIT

Harpyx è completamente open source e rilasciato con licenza MIT. Questa scelta è intenzionale: volevo che sviluppatori e organizzazioni potessero ispezionare il codice, distribuire la piattaforma in autonomia, adattarla ai propri workflow, integrarla con sistemi interni e contribuire miglioramenti al progetto.

Le piattaforme di document intelligence non dovrebbero essere misteriose rispetto a come i documenti vengono archiviati, elaborati, indicizzati e recuperati. Quando un sistema viene usato per ragionare su materiale importante, la trasparenza conta: gli sviluppatori devono capire la pipeline, i team di sicurezza devono valutare l’architettura e gli operatori devono sapere cosa succede quando qualcosa non funziona.

La licenza MIT rende il progetto semplice da adottare, anche in contesti professionali ed enterprise dove l’incertezza sulla licenza può fermare uno strumento utile prima ancora che arrivi a una valutazione tecnica.

A chi si rivolge Harpyx

Harpyx è adatto a team interessati all’AI basata sui documenti, ma che hanno bisogno di più controllo rispetto a quanto offerto da un workflow SaaS chiuso.

I casi d’uso tipici includono:

  • knowledge base AI costruite sopra grandi repository documentali;
  • team tecnici che devono interrogare specifiche, manuali, ticket, release note e documenti architetturali;
  • workflow legali, di compliance e di ricerca in cui il grounding sulle fonti e la localizzazione dei dati sono importanti;
  • sviluppatori che costruiscono applicazioni RAG custom sopra infrastrutture esistenti;
  • organizzazioni che vogliono analizzare grandi raccolte documentali senza inviare tutto a una piattaforma opaca;
  • community open-source alla ricerca di una base trasparente per document search e analisi assistita dall’AI.

Harpyx è particolarmente utile quando il set documentale è troppo grande, troppo vario, troppo sensibile o troppo importante dal punto di vista operativo per un workflow notebook leggero.

Stato attuale

Harpyx è ancora un progetto giovane, e questo è uno dei motivi per cui ho voluto rilasciarlo presto come open source.

C’è molto lavoro da fare: migliorare la qualità dell’ingestion, affinare le strategie di chunking, espandere il supporto ai provider, rafforzare le funzionalità amministrative, rifinire l’esperienza utente e testare la piattaforma su dataset reali sempre più complessi. Allo stesso tempo, la direzione è già chiara: document intelligence self-hosted, architettura RAG-first, ampio supporto ai formati file e controllo da parte dell’operatore.

Rilasciare Harpyx ora significa rendere visibile questa direzione e invitare feedback da persone che hanno problemi simili. Mi interessano in particolare i casi d’uso che mettono sotto stress il sistema in modi che le demo curate di solito evitano: grandi archivi, formati misti, file imperfetti, progetti di lunga durata, confini rigidi sui dati e team che hanno bisogno di capire perché una risposta è stata prodotta.

Conclusioni

Gli strumenti AI in stile notebook hanno mostrato quanto possa essere utile interagire con i documenti usando il linguaggio naturale. Harpyx porta questa idea in una direzione più aperta e controllabile dall’operatore, con un’architettura pensata per raccolte più grandi, supporto più ampio ai formati e reali esigenze di deployment.

Per me, il progetto è nato da un’esigenza semplice: volevo una piattaforma di document intelligence che potessi eseguire, ispezionare, estendere e adattare senza rinunciare al controllo sui documenti stessi. Harpyx è il mio tentativo di costruire quella piattaforma in modo aperto.

Se lavori con grandi raccolte documentali, stai sperimentando con RAG o cerchi un’alternativa self-hosted agli strumenti chiusi di document AI, Harpyx merita di essere seguito, provato e, spero, migliorato insieme.

Riferimenti

Print Friendly & PDF Download
Exit mobile version