Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Chunking: suddividere i documenti in modo intelligente

Lezione 12 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Obiettivi
  2. Perché suddividere i documenti?
  3. Strategia 1: Chunking a dimensione fissa
  4. Strategia 2: Chunking basato su separatori
  5. Strategia 3: Chunking per sezioni Markdown
  6. Strategia 4: Chunking semantico
  7. Arricchire i chunk con il contesto
  8. Quale dimensione di chunk scegliere?
  9. Punti chiave

Obiettivi

  • Capire perché il chunking è cruciale per la qualità del RAG
  • Padroneggiare diverse strategie di suddivisione
  • Scegliere la dimensione e la sovrapposizione dei chunk corretti

Perché suddividere i documenti?

I modelli di embedding hanno un limite di token: 8.191 per OpenAI. Questo limite è il primo motivo per suddividere i documenti, ma non è il più importante. Anche un documento ben al di sotto del soffitto produce risultati scarsi se codificato come un unico blocco, perché il vettore risultante fa una media di tutto il contenuto e perde i dettagli. Prendi un manuale HR di 40 pagine che copre politiche sulle ferie, lavoro da remoto, rimborsi spese e assicurazione sanitaria: il suo singolo embedding non assomiglia davvero a nessuno di questi quattro argomenti e una ricerca su “quanti giorni di ferie” lo classificherà sotto un documento molto più breve ma molto più mirato.

Il chunking risolve questo problema spezzando il documento in pezzi coerenti, ognuno dei quali cattura un’idea o un paragrafo specifico. Questo è il passaggio in cui una pipeline RAG guadagna o perde più qualità, ancora prima di scegliere un modello di embedding.

Strategia 1: Chunking a dimensione fissa

Il metodo più semplice conta le parole e taglia a intervalli regolari. Ignora completamente la struttura del testo, rendendolo brutale, ma richiede tre righe di codice e funge da baseline essenziale: qualsiasi strategia più sofisticata deve dimostrare di performare meglio di questa.

def chunker_fixed_size(
    text: str,
    size: int = 500,
    overlap: int = 100
) -> list[str]:
    """Splits text into fixed-size chunks with overlap."""
    words = text.split()
    chunks = []

    for i in range(0, len(words), size - overlap):
        chunk = " ".join(words[i:i + size])
        if chunk.strip():
            chunks.append(chunk)

    return chunks

long_text = "A very long document... " * 500
chunks = chunker_fixed_size(long_text, size=300, overlap=50)
print(f"{len(chunks)} chunks generated")

Il parametro overlap merita attenzione. Senza sovrapposizione, un taglio finirà inevitabilmente nel mezzo di una spiegazione: la frase “il periodo di preavviso è di tre mesi” finisce in un chunk e “tranne durante il periodo di prova” nel successivo. Nessuno dei due risponde correttamente alla domanda e il secondo è persino fuorviante. Sovrapponendo i chunk del 10–20% della loro dimensione, garantisci che ogni idea esista intatta almeno una volta da qualche parte nell’indice. Questo è un buon punto di partenza; regolalo in seguito in base alla densità del tuo documento.

Strategia 2: Chunking basato su separatori

Invece di tagliare parola per parola, puoi rispettare i confini naturali del testo. L’idea è provare prima il separatore più forte — il doppio ritorno a capo che separa due paragrafi — per poi scendere a separatori progressivamente più deboli finché il pezzo risultante supera la dimensione massima. Un post di blog verrà quindi diviso paragrafo per paragrafo e solo un paragrafo mostruoso verrà frammentato per frasi.

import re

def chunker_separators(
    text: str,
    separators: list[str] = ["\n\n", "\n", ". ", " "],
    max_size: int = 1000
) -> list[str]:
    """Splits text while respecting natural separators."""
    chunks = []
    current_chunk = ""

    # Split by the strongest separator first
    segments = [text]
    for sep in separators:
        new_segments = []
        for segment in segments:
            parts = segment.split(sep)
            for part in parts:
                if len(part.split()) > max_size:
                    new_segments.append(part)
                else:
                    if (current_chunk and
                        len((current_chunk + sep + part).split()) > max_size):
                        chunks.append(current_chunk.strip())
                        current_chunk = part
                    else:
                        current_chunk = (
                            current_chunk + sep + part
                            if current_chunk else part
                        )
        segments = new_segments

    if current_chunk.strip():
        chunks.append(current_chunk.strip())

    return chunks

Strategia 3: Chunking per sezioni Markdown

Quando il tuo corpus è costituito da documentazione strutturata, le intestazioni fanno già il lavoro per te: l’autore ha già delimitato le unità di significato. Dividere ai livelli di intestazione # e ## produce chunk che corrispondono esattamente alle sezioni e la funzione sottostante mantiene l’intestazione insieme al testo, che useremo subito dopo per l’arricchimento.

def chunker_markdown(text: str, max_level: int = 2) -> list[dict]:
    """Splits a Markdown document by sections."""
    chunks = []
    current_section = {"title": "", "content": "", "level": 0}

    for line in text.split("\n"):
        # Detect headings
        match = re.match(r"^(#{1,6})\s+(.+)$", line)
        if match:
            level = len(match.group(1))
            title = match.group(2)

            if level <= max_level and current_section["content"].strip():
                chunks.append({
                    "title": current_section["title"],
                    "text": current_section["content"].strip(),
                    "level": current_section["level"]
                })

            if level <= max_level:
                current_section = {
                    "title": title,
                    "content": "",
                    "level": level
                }
            else:
                current_section["content"] += line + "\n"
        else:
            current_section["content"] += line + "\n"

    if current_section["content"].strip():
        chunks.append({
            "title": current_section["title"],
            "text": current_section["content"].strip(),
            "level": current_section["level"]
        })

    return chunks

Strategia 4: Chunking semantico

Per testi senza struttura esplicita — un riassunto di riunione, una trascrizione di chiamata — né la dimensione né i separatori sanno dove cambia l’argomento. Gli embedding sì. Codifichi ogni frase, confronti ogni frase con la precedente e tagli dove la similarità crolla: è esattamente lì che l’interlocutore è passato dal budget al recruiting. Nota che text-embedding-3-small è sufficiente qui dato che non cerchi una precisione assoluta ma una rottura relativa.

from openai import OpenAI
import numpy as np

client = OpenAI()

def chunker_semantic(
    text: str,
    similarity_threshold: float = 0.75,
    min_sentence_length: int = 20
) -> list[str]:
    """Groups sentences by semantic similarity."""
    # Split into sentences
    sentences = re.split(r"(?<=[.!?])\s+", text)
    sentences = [s for s in sentences if len(s) > min_sentence_length]

    if len(sentences) <= 1:
        return [text]

    # Embeddings for each sentence
    resp = client.embeddings.create(
        input=sentences,
        model="text-embedding-3-small"  # small is sufficient here
    )
    embs = np.array([d.embedding for d in sorted(resp.data, key=lambda x: x.index)])

    # Find break points
    chunks = []
    chunk_sentences = [sentences[0]]

    for i in range(1, len(sentences)):
        sim = float(np.dot(embs[i], embs[i - 1]))
        if sim < similarity_threshold:
            # Semantic break detected
            chunks.append(" ".join(chunk_sentences))
            chunk_sentences = [sentences[i]]
        else:
            chunk_sentences.append(sentences[i])

    if chunk_sentences:
        chunks.append(" ".join(chunk_sentences))

    return chunks

Arricchire i chunk con il contesto

Un chunk isolato perde spesso l’informazione che lo rendeva interpretabile. “La durata è di tre anni” non significa nulla se il lettore — o il modello di embedding — non sa che proviene dal capitolo sulla garanzia del produttore. Aggiungere a ogni chunk il titolo del documento e il titolo della sezione ripristina questo contesto direttamente nel vettore stesso e una ricerca su “durata garanzia” troverà quindi il passaggio.

def enrich_chunk(chunk: str, doc_title: str, section: str = "") -> str:
    """Adds context to the chunk for better embedding."""
    prefix = f"Document: {doc_title}"
    if section:
        prefix += f" | Section: {section}"
    return f"{prefix}\n\n{chunk}"

Quale dimensione di chunk scegliere?

La scelta comporta un compromesso tra precisione e contesto: un chunk breve mira in modo fine ma è mutilato, mentre un chunk lungo capisce tutto ma diluisce il segnale.

Dimensione (token)VantaggiSvantaggi
100–200Molto preciso, buona granularitàPerde il contesto
300–500Buon compromessoStandard
500–1000Contesto riccoMeno preciso, costoso
1000+Contesto massimoDiluisce le informazioni

Non esiste un valore universale: la dimensione ideale dipende dai tuoi documenti e dalle tue query. L’unico metodo affidabile è indicizzare lo stesso corpus con due o tre dimensioni, quindi misurare usando le metriche della lezione 10 su un insieme di domande reali. Una knowledge base di supporto fatta di risposte brevi tollera 200 token; un corpus legale ne richiederà 800.

Punti chiave

  • Il chunking è il passaggio più impattante nella pipeline RAG
  • Usa la dimensione fissa come baseline, i separatori per rispettare la struttura
  • Il chunking semantico rileva automaticamente i cambi di argomento
  • Sovrapposizione e arricchimento contestuale migliorano la qualità
  • Testa diverse dimensioni e misura con le metriche di ricerca