Chonkie: la libreria Python ultraleggera per il chunking RAG

Cos'è Chonkie

Chonkie è una libreria open-source scritta in Python, rilasciata con licenza MIT, che si occupa di una sola fase della pipeline RAG (Retrieval-Augmented Generation): il chunking, cioè la suddivisione dei documenti in porzioni di testo pronte per essere trasformate in embedding e indicizzate in un database vettoriale. Il progetto è ospitato su GitHub con la simpatica mascotte di un ippopotamo pigmeo (in gergo internet, un animale "chonky" è grassoccio e adorabile), ed è nato dalla frustrazione dei suoi autori di fronte a due estremi: librerie di chunking troppo pesanti, che trascinano megabyte di dipendenze, oppure soluzioni così minimaliste da dover riscrivere tutto da zero ogni volta.

Il risultato è un pacchetto che segue la regola del "minimum install": la wheel di base pesa circa 505 KB, l'installazione completa resta intorno ai 50 MB, e le dipendenze più onerose si attivano solo se servono, tramite gli extras di pip (chonkie[semantic], chonkie[code], chonkie[all] e così via). Supporta 56 lingue, italiano compreso, e oltre a Python esiste un port ufficiale per TypeScript (@chonkiejs/core) pensato per chi sviluppa backend Node.js o Next.js.

Perché il chunking conta davvero

Chiunque abbia costruito un chatbot sui documenti aziendali sa che il punto debole raramente è il modello linguistico: è il modo in cui i testi vengono tagliati. Un chunk troppo lungo spreca token e diluisce il segnale; uno troppo corto spezza frasi e contesto, producendo embedding ambigui e risposte fuorvianti. Tagliare "a metà frase" un contratto o una norma tecnica significa restituire al LLM pezzi di testo privi di senso compiuto.

Il chunking è quindi una scelta progettuale, non un dettaglio di ingegneria. Determina quanti chunk finiscono nel database, quanto costa indicizzarli (ogni embedding ha un prezzo, in denaro o in GPU), quanto è precisa la ricerca vettoriale e quanto contesto utile arriva al modello. Eppure nella maggior parte dei tutorial il chunking si riduce a un split() ogni N caratteri: il modo peggiore di farlo, perché ignora completamente la struttura del testo.

Come funziona: undici strategie, un'unica API

La caratteristica principale di Chonkie è offrire una famiglia di chunker intercambiabili con la stessa interfaccia: si istanzia il chunker, lo si chiama come una funzione sul testo, e si ottiene una lista di oggetti Chunk con testo, conteggio token e metadati di posizione. Le strategie disponibili coprono praticamente ogni caso d'uso:

• TokenChunker: divide in chunk di dimensione fissa misurata in token reali (via tiktoken o tokenizer HuggingFace), non in caratteri approssimati. Essenziale per rispettare i limiti di contesto dei modelli.
• FastChunker: chunking byte-based accelerato SIMD, dichiarato oltre 100 GB/s: pensato per volumi enormi dove conta solo la velocità.
• SentenceChunker: spezza rispettando i confini di frase, così nessun chunk taglia un periodo a metà.
• RecursiveChunker: divide gerarchicamente (paragrafi, poi frasi, poi parole) fino a rientrare nella dimensione target, preservando il più possibile la struttura del documento. È la strategia di default consigliata per testi generici.
• SemanticChunker: calcola embedding delle frasi e taglia dove cambia il significato, producendo chunk semanticamente coerenti anche se di lunghezza variabile. Ispirato al lavoro divulgativo di Greg Kamradt.
• LateChunker: applica la tecnica del "late chunking": prima calcola gli embedding sull'intero testo, poi taglia, così ogni chunk conserva il contesto globale.
• NeuralChunker: usa un piccolo modello neurale per individuare i confini ottimali.
• SlumberChunker (detto anche AgenticChunker): affida a un LLM il compito di trovare i punti di taglio semanticamente sensati.
• CodeChunker: spezza il codice sorgente rispettandone la struttura sintattica (funzioni, classi, moduli), ideale per indicizzare repository.
• TableChunker: gestisce le tabelle in Markdown spezzandole per righe o per dimensione, senza mutilarne l'intestazione.

Un esempio minimo dà l'idea della semplicità:

from chonkie import RecursiveChunker

chunker = RecursiveChunker(chunk_size=512)
chunks = chunker("Il vostro testo lungo da indicizzare...")

for chunk in chunks:
    print(chunk.text, chunk.token_count)

Non solo chunker: una pipeline completa di ingestion

Chonkie non si ferma al taglio. Attorno ai chunker ruota un ecosistema di componenti componibili che copre l'intera fase di ingestion. I Chefs preparano i dati grezzi: MarkdownChef interpreta Markdown con tabelle e blocchi di codice, TableChef estrae tabelle, TextChef normalizza file di testo semplice. I Refineries arricchiscono i chunk dopo il taglio: OverlapRefinery aggiunge sovrapposizione tra chunk adiacenti per non perdere informazioni ai confini, mentre EmbeddingsRefinery calcola e allega i vettori usando i principali provider di embedding, con rilevamento automatico delle dimensioni.

Infine le Handshakes scrivono direttamente nel database vettoriale scelto: pgvector (PostgreSQL), Qdrant, ChromaDB, Weaviate, Pinecone, MongoDB Atlas, Elasticsearch e Turbopuffer. In pratica, con poche righe si costruisce una pipeline che va dal documento grezzo al database popolato, senza orchestratori esterni. Il pacchetto include anche un server REST per esporre il chunking come microservizio, supporto async e batch per l'elaborazione parallela, un visualizzatore dei chunk a colori da terminale e l'integrazione con Hugging Face Hub per condividere configurazioni.

Prestazioni e ingombro

Secondo i benchmark pubblicati dal progetto, Chonkie è circa 33 volte più veloce dell'alternativa più lenta nel token chunking, quasi il doppio nel sentence chunking e fino a 2,5 volte più rapido nel semantic chunking, grazie all'uso di tokenizer veloci e di embedding statici Model2Vec di default. Su hardware comune dichiara di processare migliaia di documenti al secondo. Anche senza prendere per oro colato i numeri del produttore, l'ingombro ridotto è un fatto oggettivo: mezzo megabyte di wheel contro librerie concorrenti da 1 a 12 MB, e un'installazione che resta dieci volte più leggera anche con le componenti semantiche. Per chi gira su VPS di piccole dimensioni o in container serverless con limiti di spazio e cold start, è una differenza concreta.

A chi serve e quando sceglierlo

Chonkie è una buona scelta per chi sta costruendo un assistente sui documenti aziendali — manuali, contratti, pratiche, normative, knowledge base di supporto — e vuole controllare la fase di ingestion senza adottare un framework RAG monolitico. Il caso tipico per una PMI o un'agenzia: documenti Word o PDF convertiti in testo, chunking ricorsivo o semantico, embedding, e scrittura in pgvector accanto al database che già si usa. Chi indicizza codice sorgente per tool di assistenza allo sviluppo apprezzerà il CodeChunker; chi ha volumi enormi e budget GPU zero punterà sul FastChunker.

Ha senso preferire Chonkie a una soluzione fai-da-te quando serve più di una strategia di taglio, conteggi token affidabili o la sovrapposizione tra chunk. Ha meno senso se si usa già un framework RAG completo che include il proprio chunking, o se il bisogno è talmente semplice che un sentence splitter di venti righe basta e avanza. Va anche ricordato che il progetto offre una versione cloud gestita (Chonkie Cloud): la libreria open-source resta completa e local-first, ma alcuni chunker avanzati nel port TypeScript passano dall'API cloud.

Licenza, comunità e dove trovarlo

Il progetto è pubblicato su GitHub all'indirizzo github.com/chonkie-inc/chonkie con licenza MIT, quindi utilizzabile liberamente anche in prodotti commerciali. La documentazione ufficiale è su docs.chonkie.ai, con guide per installazione, singoli chunker, pipeline e integrazioni. L'installazione si riduce a pip install chonkie (o npm install @chonkiejs/core per TypeScript), e gli extras permettono di attivare solo le strategie necessarie. La comunità è in crescita, con migliaia di stelle GitHub, rilasci frequenti e perfino skill ufficiali per gli agenti di coding (Claude Code, Cursor, Gemini CLI) che conoscono l'API della libreria. Per chi sviluppa in .NET esiste anche un port community non ufficiale, Chonkie.Net.

In sintesi: Chonkie prende un problema noioso e sottovalutato — tagliare bene i testi — e lo risolve con una libreria piccola, veloce e modulare. Non sostituisce il database vettoriale, non genera embedding da sola (li orchestra), non è un motore RAG completo: è il pezzo di pipeline che sta tra il documento e l'indice, ed è proprio quel pezzo a decidere, molto più di quanto si pensi, se le risposte del vostro assistente saranno utili o spazzatura.