Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Ricerca file: indicizzazione e interrogazione dei documenti

Lezione 7 di 20 Sviluppatore
In questa pagina
  1. Ricerca file: indicizzazione e interrogazione dei documenti
  2. Creare un archivio vettoriale
  3. Caricare e indicizzare i file
  4. Interrogare con la ricerca file
  5. Esaminare i risultati della ricerca
  6. Configurare la ricerca
  7. Gestire il ciclo di vita dell’archivio vettoriale
  8. Esempio completo: assistente per la documentazione
  9. Punti chiave

Ricerca file: indicizzazione e interrogazione dei documenti

La funzione File Search permette al modello di esplorare i tuoi documenti privati. Carichi i file in un archivio vettoriale (vector store) e il modello li interroga automaticamente ogni volta che necessita di informazioni specifiche. Questa è la base del RAG (Retrieval-Augmented Generation) integrato direttamente nelle API di OpenAI.

Creare un archivio vettoriale

L’archivio vettoriale è l’unità organizzativa per la ricerca file e la struttura che scegli qui ti accompagnerà a lungo. Un unico archivio per l’intera azienda è semplice da amministrare, ma mescola documenti con vocabolari non correlati, degradando la pertinenza dei risultati. Archivi separati per team o dominio richiedono una gestione leggermente più complessa, ma rendono ogni ricerca significativamente più precisa. In caso di dubbio, separali: unire in seguito è più facile che districare un pasticcio.

from openai import OpenAI

client = OpenAI()

# Create the vector store
vector_store = client.vector_stores.create(
    name="product-documentation"
)
print(f"Vector store created: {vector_store.id}")

Caricare e indicizzare i file

L’indicizzazione è asincrona ed è la fonte di errori più comune al primo tentativo: aggiungi i file, interroghi immediatamente e il modello risponde di non aver trovato nulla. Non perché la ricerca sia fallita, ma perché nulla è stato ancora indicizzato. Controlla sempre lo stato prima di interrogare, come mostrato nella sezione sul ciclo di vita.

Una nota sui formati: l’elenco è ampio, ma non tutti i file sono uguali. Un PDF generato da un elaboratore di testi viene estratto pulitamente; un PDF scansionato senza livello di testo non aggiunge nulla, poiché letteralmente non ci sono parole da indicizzare.

import os

# Upload a single file
with open("user-guide.pdf", "rb") as f:
    file_obj = client.files.create(file=f, purpose="assistants")

# Attach to the vector store
client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file_obj.id
)

# Batch upload
folder = "./documentation/"
for filename in os.listdir(folder):
    path = os.path.join(folder, filename)
    if os.path.isfile(path):
        with open(path, "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
        )
        print(f"Indexed: {filename}")

Interrogare con la ricerca file

La chiamata è volutamente diretta: dichiari lo strumento, poni la tua domanda e il modello decide se effettuare una ricerca. Tutto il lavoro di RAG — frammentazione, vettorializzazione, classificazione e iniezione nel contesto — avviene sul server. Questo fa risparmiare molto tempo all’avvio e la prossima lezione copre le impostazioni da conoscere quando i valori predefiniti non bastano.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the refund procedure for premium clients?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }]
)

print(response.output_text)

Il modello cerca automaticamente nei tuoi documenti e formula una risposta basata sul contenuto che trova.

Esaminare i risultati della ricerca

Le annotazioni sono ciò che distingue una risposta verificabile da una mera affermazione. Esponile ai tuoi utenti: in una base di conoscenza interna, la capacità di risalire al documento originale cambia completamente il livello di fiducia nel sistema e ti aiuta a individuare i casi in cui il modello ha sbagliato.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What SLAs are guaranteed in the contract?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }]
)

# Iterate through annotations
for item in response.output:
    if item.type == "message":
        for block in item.content:
            if hasattr(block, "annotations"):
                for ann in block.annotations:
                    if ann.type == "file_citation":
                        print(f"File: {ann.file_id}")
                        print(f"Position: {ann.start_index}-{ann.end_index}")

Configurare la ricerca

Numero di risultati

Aumentare il numero di passaggi non migliora meccanicamente la risposta. Oltre una decina, gli estratti poco pertinenti diluiscono quelli buoni e consumano contesto fatturato. Aumenta questo valore solo quando la risposta è visibilmente incompleta, non come principio generale.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="List all penalty clauses in the contract",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "max_num_results": 20  # Default: 5, max: 50
    }]
)

Filtraggio per metadati

I metadati sono la leva più sottovalutata per la precisione. Filtrare per anno, dipartimento o tipo di documento prima della ricerca vettoriale elimina il rumore a monte che la classificazione avrebbe altrimenti dovuto filtrare. Questo ti permette anche di rispondere «secondo la procedura attuale» invece di mescolare tre versioni successive dello stesso documento.

# Upload with metadata
with open("contract-2026.pdf", "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={
        "doc_type": "contract",
        "year": 2026,
        "client": "acme-corp"
    }
)

# Filtered search
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the due date?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "filters": {
            "type": "eq",
            "key": "doc_type",
            "value": "contract"
        }
    }]
)

Filtri composti

Combina più criteri utilizzando operatori logici:

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Summarize contractual obligations for 2026",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "filters": {
            "type": "and",
            "filters": [
                {"type": "eq", "key": "doc_type", "value": "contract"},
                {"type": "gte", "key": "year", "value": 2026}
            ]
        }
    }]
)

Gestire il ciclo di vita dell’archivio vettoriale

Monitorare l’indicizzazione

# Check vector store status
vs = client.vector_stores.retrieve(vector_store.id)
print(f"Status: {vs.status}")
print(f"Files: {vs.file_counts.completed} indexed, "
      f"{vs.file_counts.in_progress} in progress, "
      f"{vs.file_counts.failed} failed")

Rimuovere i file obsoleti

# List files in the vector store
files = client.vector_stores.files.list(vector_store.id)
for f in files.data:
    print(f"{f.id} - {f.status}")

# Detach a file
client.vector_stores.files.delete(
    vector_store_id=vector_store.id,
    file_id="file_abc123"
)

Esempio completo: assistente per la documentazione

def documentation_assistant(question: str, vs_id: str) -> dict:
    """Assistant that answers based on internal documentation."""
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions=(
            "You are a documentation assistant. Answer solely based on the "
            "provided documents. If the information is not in the documents, "
            "state that clearly. Cite your sources."
        ),
        input=question,
        tools=[{
            "type": "file_search",
            "vector_store_ids": [vs_id],
            "max_num_results": 10
        }]
    )

    return {
        "answer": response.output_text,
        "model": response.model,
        "tokens": response.usage.total_tokens
    }

Punti chiave

  • Crea un archivio vettoriale e carica i tuoi file per abilitare la ricerca file
  • Il modello decide autonomamente quando cercare nei documenti
  • max_num_results controlla la profondità della ricerca
  • Metadati e filtri abilitano ricerche mirate
  • Monitora lo stato dell’indicizzazione prima di interrogare