Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Batching e Chunking

Lezione 4 di 18 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. La sfida dei grandi volumi
  2. Batching: elaborazione in gruppi
  3. Chunking: suddivisione del testo
  4. Sovrapposizione (Overlap)
  5. Pipeline completa: Chunk + Batch + Embed
  6. Punti chiave

La sfida dei grandi volumi

Quando lavori con migliaia di documenti, non puoi codificare tutto in una singola chiamata API. Devi gestire il batching (elaborazione in gruppi) e il chunking (suddivisione del testo). Queste due tecniche sono essenziali per costruire sistemi di ricerca semantica su larga scala.

I due concetti sembrano simili, ma risolvono problemi opposti. Il chunking gestisce un singolo documento troppo grande per essere codificato efficacemente nella sua interezza; il batching gestisce troppi documenti per stare in una singola richiesta. Un manuale tecnico di trecento pagine rientra nella prima categoria, un’esportazione di ventimila ticket nella seconda, e un progetto reale coinvolge quasi sempre entrambi.

Batching: elaborazione in gruppi

L’API mistral-embed accetta un elenco di input, ma esistono limiti pratici (dimensione della richiesta, conteggio dei token). La soluzione consiste nel dividere il tuo corpus in batch e iterarli. La funzione sottostante fa esattamente questo, mostrando l’avanzamento: un dettaglio critico quando la codifica di un intero corpus richiede diversi minuti e devi sapere se il processo sta avanzando o è bloccato.

import numpy as np
from mistralai.client import Mistral

client = Mistral(api_key=api_key)

def get_embeddings_by_chunks(data, chunk_size=25):
    """Codifica un ampio elenco di testi in batch."""
    chunks = [data[x:x + chunk_size] for x in range(0, len(data), chunk_size)]
    embeddings = []

    for i, chunk in enumerate(chunks):
        print(f"Batch {i+1}/{len(chunks)} ({len(chunk)} testi)...")
        response = client.embeddings.create(
            model="mistral-embed",
            inputs=chunk,
        )
        embeddings.extend([d.embedding for d in response.data])

    return embeddings

# Esempio con 1000 documenti
documents = [f"Documento numero {i} con contenuto vario." for i in range(1000)]
all_embeddings = get_embeddings_by_chunks(documents, chunk_size=50)

print(f"Totale: {len(all_embeddings)} embedding di {len(all_embeddings[0])} dimensioni")

L’uso di extend invece di append garantisce che l’ordine dei vettori corrisponda esattamente all’ordine del testo di input. Questo ti permette di recuperare il documento originale da un semplice indice in seguito.

Ottimizzazione della dimensione del batch

La dimensione ottimale del batch dipende dalla lunghezza media dei tuoi testi: cinquanta titoli di articoli e cinquanta rapporti completi non pesano lo stesso in termini di token. Invece di scegliere una costante a caso, stimarla direttamente dal corpus.

def optimal_batch_size(documents, max_tokens_per_batch=16000):
    """Stima la dimensione ottimale del batch."""
    # Stima approssimativa: 1 token ~ 4 caratteri in inglese
    avg_chars = sum(len(d) for d in documents) / len(documents)
    avg_tokens = avg_chars / 4

    batch_size = max(1, int(max_tokens_per_batch / avg_tokens))
    return min(batch_size, 100)  # Limite a 100

# Regola in base al tuo corpus
batch_size = optimal_batch_size(documents)
print(f"Dimensione del batch consigliata: {batch_size}")

Il limite a 100 non è estetico: oltre tale soglia, un singolo batch fallito causa una significativa perdita di lavoro e la memoria consumata dalla risposta diventa sostanziale.

Chunking: suddivisione del testo

I testi lunghi devono essere suddivisi in chunk prima della codifica. Esistono diverse strategie, ognuna con i suoi vantaggi, e la scelta impatta direttamente sulla qualità della risposta: un chunk che inizia nel mezzo di una frase produce un vettore sfocato, portando a risultati di ricerca imprecisi.

Suddivisione basata sui caratteri (Semplice)

Il metodo più diretto taglia ogni N caratteri, indipendentemente dal contenuto. Il suo merito è la prevedibilità e la velocità, rendendolo accettabile per un prototipo o per testi senza una struttura chiara.

def chunk_by_chars(text, chunk_size=2048, overlap=200):
    """Divide il testo in chunk con sovrapposizione."""
    chunks = []
    start = 0
    while start < len(text):
        end = start + chunk_size
        chunk = text[start:end]
        chunks.append(chunk)
        start = end - overlap  # Sovrapposizione per il contesto
    return chunks

long_text = "Un documento molto lungo..." * 500
chunks = chunk_by_chars(long_text, chunk_size=2048, overlap=200)
print(f"{len(chunks)} chunk creati")

Suddivisione basata sui paragrafi (Consigliata)

La suddivisione basata sui paragrafi rispetta l’unità di significato intesa dall’autore. Nella documentazione di prodotto, ogni paragrafo copre generalmente un punto specifico; mantenerlo intatto produce un chunk in grado di rispondere a una domanda autonomamente. La funzione accumula i paragrafi finché non viene superata la dimensione massima, quindi chiude il chunk corrente.

def chunk_by_paragraphs(text, max_chunk_size=2048):
    """Divide rispettando i confini dei paragrafi."""
    paragraphs = text.split("\n\n")
    chunks = []
    current_chunk = ""

    for para in paragraphs:
        if len(current_chunk) + len(para) + 2 > max_chunk_size:
            if current_chunk:
                chunks.append(current_chunk.strip())
            current_chunk = para
        else:
            current_chunk += "\n\n" + para if current_chunk else para

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

    return chunks

Suddivisione basata sulle frasi

Quando il testo manca di paragrafi utilizzabili—una trascrizione di chiamata, un log di esecuzione—la frase diventa la più piccola unità di significato disponibile. La suddivisione segue quindi la stessa logica di accumulo, basandosi sulla punteggiatura di fine frase.

import re

def chunk_by_sentences(text, max_chunk_size=1500):
    """Divide rispettando i confini delle frasi."""
    # Divide sulla punteggiatura di fine frase
    sentence_pattern = r'(?<=[.!?])\s+'
    sentences = re.split(sentence_pattern, text)
    chunks = []
    current_chunk = ""

    for sentence in sentences:
        if len(current_chunk) + len(sentence) + 1 > max_chunk_size:
            if current_chunk:
                chunks.append(current_chunk.strip())
            current_chunk = sentence
        else:
            current_chunk += " " + sentence if current_chunk else sentence

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

    return chunks

Sovrapposizione (Overlap)

La sovrapposizione tra i chunk evita di tagliare un’idea a metà. Aggiungendo una sovrapposizione dal 10% al 20% della dimensione del chunk, preservi il contesto tra i pezzi adiacenti. Immagina una procedura in cui il passaggio 4 termina al carattere 2040 e la conseguenza è spiegata immediatamente dopo: senza sovrapposizione, nessun chunk contiene entrambe le metà del ragionamento e la ricerca non recupererà mai la risposta completa.

I valori seguenti servono come punti di partenza collaudati in base al tipo di contenuto:

# Parametri consigliati per tipo di contenuto
PARAMS = {
    "articles":     {"chunk_size": 1500, "overlap": 200},
    "documentation": {"chunk_size": 1000, "overlap": 150},
    "conversations": {"chunk_size": 500,  "overlap": 50},
    "code":          {"chunk_size": 2000, "overlap": 300},
}

Le conversazioni scendono a 500 caratteri perché un turno di parola è breve e un chunk più grande mescolerebbe più argomenti; il codice sale a 2000 con una generosa sovrapposizione perché una funzione perde significato se la sua firma è separata dal suo corpo.

Pipeline completa: Chunk + Batch + Embed

Ecco come combinare chunking e batching in una pipeline di produzione. L’elemento che non devi trascurare è chunk_metadata: senza di esso, ottieni vettori orfani incapaci di indicare da quale documento provengono e non sarai mai in grado di citare le tue fonti nella risposta finale.

def pipeline_embed(documents, chunk_size=1500, overlap=200, batch_size=50):
    """Pipeline completa: chunk, batch, embed."""
    # 1. Suddividi tutti i documenti in chunk
    all_chunks = []
    chunk_metadata = []  # Traccia il documento sorgente

    for doc_idx, doc in enumerate(documents):
        chunks = chunk_by_paragraphs(doc, max_chunk_size=chunk_size)
        for chunk_idx, chunk in enumerate(chunks):
            all_chunks.append(chunk)
            chunk_metadata.append({
                "doc_index": doc_idx,
                "chunk_index": chunk_idx,
            })

    print(f"{len(documents)} documenti -> {len(all_chunks)} chunk")

    # 2. Codifica in batch
    embeddings = get_embeddings_by_chunks(all_chunks, chunk_size=batch_size)

    # 3. Restituisci risultati strutturati
    return {
        "chunks": all_chunks,
        "embeddings": np.array(embeddings),
        "metadata": chunk_metadata,
    }

# Utilizzo
result = pipeline_embed(documents)
print(f"Embedding: {result['embeddings'].shape}")

Esegui questa pipeline su una dozzina dei tuoi documenti reali e ispeziona all_chunks a occhio prima di codificare qualsiasi cosa su larga scala. Una cattiva suddivisione è immediatamente visibile leggendo, mentre non appare mai nella forma della matrice.

Punti chiave

  • Il batching ti permette di codificare migliaia di documenti senza superare i limiti API
  • Il chunking suddivide i testi lunghi per una migliore granularità semantica
  • Una sovrapposizione del 10–20% tra i chunk preserva il contesto
  • La suddivisione per paragrafi o frasi è preferibile a quella per caratteri
  • Mantieni i metadati (documento sorgente, posizione) per ogni chunk