Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Configurare e controllare i risultati web

Lezione 6 di 20 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Configurare e controllare i risultati web
  2. Il parametro search_context_size
  3. Guidare le query di ricerca tramite il prompt
  4. Estrarre e strutturare le citazioni
  5. Pattern: ricerca con convalida incrociata
  6. Gestire l’assenza di risultati
  7. Ricerca web con streaming
  8. Filtrare domini ed elencare le fonti
  9. Punti chiave

Lezione aggiornata il 2 novembre 2026 sulla base della documentazione OpenAI: lo strumento Code Interpreter richiede un parametro container (aggiunto a tutti gli esempi), le parti di testo in input sono di tipo input_text e la ricerca web utilizza lo strumento web_search (web_search_preview è ora uno strumento legacy senza filtri di dominio). I file generati vengono recuperati utilizzando le funzioni fichiers_generes e telecharger della Lezione 10. Fonti: Code Interpreter · Ricerca web.

Configurare e controllare i risultati web

Abilitare la ricerca web richiede una sola riga; ottenere risposte affidabili ne richiede tre, che questa lezione dettaglia. La prima decide quanto contenuto web viene iniettato nel contesto, influenzando direttamente la tua fattura. La seconda orienta le query che il modello formula da solo—perché le scrive lui, non tu. La terza riguarda le citazioni; senza di esse, una risposta sourced è solo un’affermazione categorica.

Il parametro search_context_size

Il parametro search_context_size controlla quanto contenuto web viene iniettato nel contesto del modello. Non cambia né il numero di ricerche né la loro qualità: determina quanto testo, una volta trovate le pagine, entra effettivamente nel prompt. Si tratta di un compromesso tra esaustività e costo, che dovresti regolare in base al tipo di compito, non impostare una volta per tutte.

from openai import OpenAI

client = OpenAI()

# Contesto minimo: risposte veloci e concise
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is France's GDP in 2025?",
    tools=[{
        "type": "web_search",
        "search_context_size": "low"
    }]
)

# Contesto medio: buon compromesso (default)
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Summarize AI market trends in Europe",
    tools=[{
        "type": "web_search",
        "search_context_size": "medium"
    }]
)

# Contesto ampio: analisi approfondita
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Compare AI strategies in France, Germany, and the Netherlands",
    tools=[{
        "type": "web_search",
        "search_context_size": "high"
    }]
)

Impatto su costi e latenza

La regola è semplice: aumenta il livello di un gradino solo quando la risposta ottenuta ti ha concretamente deluso. Una data, una cifra o una conferma fattuale non richiedono nulla più di low; usare high per questo equivale a pagare per un intero dossier per leggere una sola riga.

DimensioneToken di contestoLatenzaCostoUtilizzo
lowMinimoVeloceBassoFatti semplici, cifre
mediumModeratoStandardMedioRiassunti, confronti
highMassimoLentaAltoAnalisi approfondite

Guidare le query di ricerca tramite il prompt

Ecco il punto che molti scoprono troppo tardi: il modello formula le proprie query di ricerca. Tu scrivi «quali sono le recenti modifiche normative?» e lui le traduce in parole chiave che non vedrai mai. La qualità del risultato dipende quindi da una riformulazione su cui hai solo un controllo indiretto: il prompt di sistema. Nomina le fonti autorevoli nel tuo settore e il periodo che ti interessa: è ciò che sposta davvero l’ago della bilancia.

response = client.responses.create(
    model="gpt-5.6-terra",
    instructions=(
        "You are a market analyst specializing in European technology. "
        "When you perform web searches, prioritize institutional sources "
        "(European Commission, INSEE, Eurostat) and specialized media "
        "(Les Echos, La Tribune, TechCrunch). "
        "Ignore personal blogs and forums."
    ),
    input="What is the state of AI startup funding in France?",
    tools=[{
        "type": "web_search",
        "search_context_size": "high"
    }]
)

Estrarre e strutturare le citazioni

Le citazioni arrivano come annotazioni allegate alla risposta, non nel testo stesso. Questa separazione è una buona notizia: ti permette di visualizzare le fonti come preferisci, verificarle o rifiutare una risposta che ne sia priva. In qualsiasi applicazione dove la risposta ha un peso—legale, medico, finanziario—trattare le annotazioni mancanti come un errore è più sicuro che fidarsi del testo.

def extract_sources(response) -> list[dict]:
    """Extract all URL citations from a Web Search response."""
    sources = []
    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 == "url_citation":
                            sources.append({
                                "url": ann.url,
                                "title": ann.title,
                                "excerpt_start": ann.start_index,
                                "excerpt_end": ann.end_index
                            })
    return sources

# Usage
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What are the new GDPR rules for AI in 2026?",
    tools=[{"type": "web_search"}]
)

sources = extract_sources(response)
for s in sources:
    print(f"  {s['title']}: {s['url']}")

Pattern: ricerca con convalida incrociata

Una singola fonte rimane una singola fonte, anche se trovata da un modello. Per le informazioni che guidano una decisione, chiedi esplicitamente una conferma da più fonti indipendenti e fai sì che il modello segnali le discrepanze invece di arbitrare silenziosamente: un disaccordo tra due fonti è esso stesso un’informazione, spesso più utile della media delle due.

def validated_search(question: str, min_sources: int = 3) -> dict:
    """Web search requiring multiple sources."""
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions=(
            f"To answer this question, you must find at least "
            f"{min_sources} independent sources that confirm the information. "
            "If sources contradict each other, flag the discrepancies. "
            "Cite each source explicitly."
        ),
        input=question,
        tools=[{
            "type": "web_search",
            "search_context_size": "high"
        }]
    )

    sources = extract_sources(response)
    return {
        "answer": response.output_text,
        "sources": sources,
        "reliability": "high" if len(sources) >= min_sources else "verify"
    }

Gestire l’assenza di risultati

C’è un caso che si dimentica di gestire: la ricerca non restituisce nulla. Il rischio non è la mancanza di una risposta, ma il fatto che, in assenza di risultati, il modello risponda basandosi sulla sua conoscenza interna senza segnalarlo, fornendoti informazioni plausibili ma obsolete. Chiedigli di dirlo esplicitamente e prevedi una riformulazione.

def search_with_fallback(question: str) -> dict:
    """Web search with failure detection and reformulation."""
    # First attempt
    response = client.responses.create(
        model="gpt-5.6-terra",
        input=question,
        tools=[{"type": "web_search"}]
    )

    sources = extract_sources(response)

    if len(sources) == 0:
        # Automatic reformulation
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=f"Rephrase this question for a more effective web search, "
                  f"then search: {question}",
            tools=[{"type": "web_search", "search_context_size": "high"}]
        )
        sources = extract_sources(response)

    return {
        "answer": response.output_text,
        "sources": sources
    }

Ricerca web con streaming

Una ricerca web richiede alcuni secondi, a volte di più se il modello concatena diverse query. Con lo streaming, l’utente vede la risposta costruirsi invece di fissare un indicatore di caricamento—e per questo tipo di latenza, la differenza di percezione è enorme a costo implementativo quasi nullo.

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="What are this week's tech news headlines?",
    tools=[{"type": "web_search"}],
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        # Extract sources at the end
        sources = extract_sources(event.response)
        print(f"\n\n--- {len(sources)} sources consulted ---")

Filtrare domini ed elencare le fonti

Lo strumento web_search accetta un parametro filters che limita la ricerca a un elenco di domini consentiti (fino a 100) o ne esclude un elenco (sempre fino a 100). Scrivi i domini senza http:// o https://. Il filtraggio esiste solo con web_search nell’API Responses: lo strumento legacy web_search_preview lo ignora.

response = client.responses.create(
    model="gpt-5.6-terra",
    tools=[{
        "type": "web_search",
        "filters": {"allowed_domains": ["service-public.fr", "legifrance.gouv.fr"]},
    }],
    include=["web_search_call.action.sources"],
    input="What are the price display requirements for retail stores in France?",
)
print(response.output_text)

L’opzione include=["web_search_call.action.sources"] restituisce l’elenco completo degli URL consultati, spesso più lungo dell’elenco delle citazioni. Le citazioni stesse arrivano come annotazioni url_citation (URL, titolo, posizione nel testo): la documentazione di OpenAI chiede di visualizzarle in modo visibile e cliccabile nella tua interfaccia.

Punti chiave

  • search_context_size controlla il volume di dati web iniettati
  • filters limita o esclude domini (max 100); include elenca tutte le fonti consultate
  • Il prompt di sistema orienta il modello verso le fonti giuste
  • Estrai le annotazioni url_citation per tracciare le fonti
  • Implementa la convalida incrociata per le informazioni critiche
  • Gestisci i risultati mancanti con una riformulazione automatica