Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Recupero: Suddivisione in chunk e classificazione

Lezione 8 di 20 Sviluppatore
In questa pagina
  1. Recupero: Suddivisione in chunk e classificazione
  2. La pipeline di recupero
  3. Configurazione della strategia di chunking
  4. Soglia di rilevanza e classificazione
  5. Ottimizzazione della qualità del recupero
  6. Misurazione della qualità del recupero
  7. Strategie avanzate
  8. Punti chiave

Recupero: Suddivisione in chunk e classificazione

La ricerca nei file si basa su una pipeline di recupero completa: i tuoi documenti vengono suddivisi in chunk, vettorizzati, indicizzati e quindi classificati per rilevanza quando arriva una query. Comprendere questa pipeline ti permette di ottimizzare la qualità delle risposte.

La pipeline di recupero

Quando carichi un file in un vector store, OpenAI esegue automaticamente:

  1. Parsing: Estrae il testo grezzo dal formato sorgente
  2. Chunking: Divide il testo in segmenti di dimensione controllata
  3. Embedding: Vettorizza ogni chunk
  4. Indicizzazione: Memorizza i vettori nell’indice vettoriale

Al momento della query:

  1. Query Embedding: La domanda viene vettorizzata
  2. Ricerca vettoriale: Identifica i chunk più vicini
  3. Classificazione (Ranking): Riordina i risultati per rilevanza
  4. Iniezione: Inietta i chunk migliori nel contesto del modello

Configurazione della strategia di chunking

Il chunking è l’impostazione che guida tutto il resto e il compromesso è semplice. I chunk brevi producono risultati di ricerca precisi ma forniscono estratti privi di contesto: trovi la frase giusta ma perdi il riferimento a cosa si riferisce. I chunk lunghi preservano il contesto ma seppelliscono le informazioni rilevanti in testo irrilevante, indebolendo il punteggio di similarità.

Non esiste un valore universale: l’impostazione corretta dipende dalla struttura del tuo documento, esattamente come riassunto nella tabella seguente.

from openai import OpenAI

client = OpenAI()

# Default strategy: auto
vector_store = client.vector_stores.create(
    name="legal-base",
    chunking_strategy={"type": "auto"}
)

# Custom strategy: smaller chunks for higher precision
vector_store = client.vector_stores.create(
    name="support-faq",
    chunking_strategy={
        "type": "static",
        "static": {
            "max_chunk_size_tokens": 400,
            "chunk_overlap_tokens": 100
        }
    }
)

Scelta della dimensione corretta del chunk

Tipo di contenutomax_chunk_sizeoverlapPerché
FAQ, Q&A200-40050Risposte brevi e autonome
Documentazione tecnica600-800200Paragrafi con contesto
Contratti, testi legali800-1200300Clausole lunghe e interconnesse
Codice sorgente400-600100Funzioni e classi

Impatto dell’overlap

L’overlap risolve un problema specifico: le informazioni che si trovano al confine tra due chunk verrebbero altrimenti tagliate a metà, il che significherebbe che nessuna delle due metà corrisponderebbe alla query. Sovrapponendo i chunk, garantisci che ogni frase appaia intatta in almeno un segmento. Il costo è la ridondanza: un overlap di 300 token su chunk da 800 token memorizza quasi il 40% di testo duplicato.

# Original text (simplified)
# "Clause 5.1 states the supplier must deliver within 30 days.
#  In case of delay, penalties of 1% per day apply.
#  Clause 5.2 specifies penalties are capped at 15%."

# Without overlap: Clause 5.1 and penalties might end up in different chunks
# With overlap: the link between clause and penalties is preserved

Soglia di rilevanza e classificazione

La classificazione determina quali chunk vengono mantenuti. Puoi configurare un filtro:

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the return policy?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "max_num_results": 10,
        "ranking_options": {
            "ranker": "auto",
            "score_threshold": 0.5
        }
    }]
)

Il score_threshold filtra i risultati al di sotto di una soglia di rilevanza. Un valore di 0,0 restituisce tutto, mentre 1,0 sarebbe troppo restrittivo. In pratica, un valore tra 0,3 e 0,6 produce buoni risultati.

Ottimizzazione della qualità del recupero

Preparazione dei documenti

Questa è la leva più economica di tutta questa lezione e l’unica che non costa nulla in termini di impostazioni: un documento ben strutturato si indicizza bene. Usa titoli espliciti, una frase introduttiva per ogni sezione ed evita tabelle convertite in un ammasso di testo. Al contrario, nessuna impostazione di chunking salverà un PDF la cui estrazione produce colonne ingarbugliate.

# Bad: Scanned PDF with approximate OCR
# -> Incoherent chunks, poor-quality embeddings

# Good: Structured document with headings and sections
# -> Chunks aligned with logical sections

# Pattern: Pre-process before upload
def prepare_document(raw_text: str) -> str:
    """Cleans and structures text before indexing."""
    # Remove repetitive headers/footers
    lines = raw_text.split("\n")
    lines = [l for l in lines if not is_header_footer(l)]

    # Normalize spaces
    text = "\n".join(lines)
    text = re.sub(r"\n{3,}", "\n\n", text)

    return text

Arricchimento con metadati

I metadati consentono il pre-filtraggio prima della ricerca vettoriale, migliorando la precisione:

# Upload with rich metadata
documents = [
    {"file": "hr-policy-2026.pdf", "department": "hr", "type": "policy", "year": 2026},
    {"file": "supplier-contract-a.pdf", "department": "procurement", "type": "contract", "year": 2026},
    {"file": "it-security-guide.pdf", "department": "it", "type": "guide", "year": 2025},
]

for doc in documents:
    with open(doc["file"], "rb") as f:
        file_obj = client.files.create(file=f, purpose="assistants")

    client.vector_stores.files.create(
        vector_store_id=vector_store.id,
        file_id=file_obj.id,
        attributes={
            "department": doc["department"],
            "document_type": doc["type"],
            "year": doc["year"]
        }
    )

Misurazione della qualità del recupero

Senza misurazione, qualsiasi impostazione di chunking è solo intuizione. Un insieme di venti domande di cui conosci la risposta attesa e il documento contenitore è sufficiente per oggettivare il processo: cambia un parametro, riesegui il set di test e confronta. È poco lavoro rispetto alle ore passate a discutere sulla dimensione dei chunk senza dati.

def evaluate_retrieval(test_questions: list[dict], vs_id: str) -> dict:
    """Evaluates retrieval quality on a test set.

    Each element in test_questions contains:
    - question: the question to ask
    - expected_answer: keywords or phrases expected in the response
    """
    results = {"total": 0, "relevant": 0, "irrelevant": 0}

    for test in test_questions:
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=test["question"],
            tools=[{
                "type": "file_search",
                "vector_store_ids": [vs_id],
                "max_num_results": 5
            }]
        )

        answer = response.output_text.lower()
        found_keywords = sum(
            1 for word in test["expected_answer"]
            if word.lower() in answer
        )

        results["total"] += 1
        if found_keywords >= len(test["expected_answer"]) * 0.5:
            results["relevant"] += 1
        else:
            results["irrelevant"] += 1

    results["relevance_rate"] = results["relevant"] / results["total"]
    return results

Strategie avanzate

Multi-Vector-Store

Interroga più basi documentali in parallelo:

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Compare our HR policy with legal obligations",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [
            vs_internal_policies,
            vs_legal_texts
        ],
        "max_num_results": 15
    }]
)

Query decomposte

Una domanda contenente più richieste produce un vettore medio che non assomiglia a nessuna di esse, portando a scarsi risultati di ricerca per tutte. Scomporla in sotto-domande separate produce risultati significativamente migliori: è lo stesso principio della ricerca web, una query precisa batte una esaustiva.

def decomposed_search(complex_question: str, vs_id: str) -> str:
    """Decomposes a complex question into sub-searches."""
    # Step 1: Decompose the question
    decomposition = client.responses.create(
        model="gpt-5.6-terra",
        input=f"Decompose this question into 2-3 simple sub-questions: {complex_question}",
    )

    # Step 2: Search for each sub-question
    sub_results = []
    for sub_q in decomposition.output_text.split("\n"):
        if sub_q.strip():
            r = client.responses.create(
                model="gpt-5.6-terra",
                input=sub_q.strip(),
                tools=[{"type": "file_search", "vector_store_ids": [vs_id]}]
            )
            sub_results.append(r.output_text)

    # Step 3: Synthesize
    synthesis = client.responses.create(
        model="gpt-5.6-terra",
        input=f"Original question: {complex_question}\n\n"
              f"Intermediate results:\n" + "\n---\n".join(sub_results) +
              "\n\nSynthesize a complete and coherent answer."
    )
    return synthesis.output_text

Punti chiave

  • Il chunking static con dimensione e overlap personalizzati migliora la precisione
  • Chunk piccoli per le FAQ, chunk grandi per i documenti legali
  • score_threshold filtra i risultati irrilevanti
  • Pulisci e struttura i tuoi documenti prima dell’indicizzazione
  • Valuta la qualità del recupero con un set di test