Recupero: Suddivisione in chunk e classificazione
In questa pagina
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:
- Parsing: Estrae il testo grezzo dal formato sorgente
- Chunking: Divide il testo in segmenti di dimensione controllata
- Embedding: Vettorizza ogni chunk
- Indicizzazione: Memorizza i vettori nell’indice vettoriale
Al momento della query:
- Query Embedding: La domanda viene vettorizzata
- Ricerca vettoriale: Identifica i chunk più vicini
- Classificazione (Ranking): Riordina i risultati per rilevanza
- 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 contenuto | max_chunk_size | overlap | Perché |
|---|---|---|---|
| FAQ, Q&A | 200-400 | 50 | Risposte brevi e autonome |
| Documentazione tecnica | 600-800 | 200 | Paragrafi con contesto |
| Contratti, testi legali | 800-1200 | 300 | Clausole lunghe e interconnesse |
| Codice sorgente | 400-600 | 100 | Funzioni 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
staticcon dimensione e overlap personalizzati migliora la precisione - Chunk piccoli per le FAQ, chunk grandi per i documenti legali
score_thresholdfiltra i risultati irrilevanti- Pulisci e struttura i tuoi documenti prima dell’indicizzazione
- Valuta la qualità del recupero con un set di test