Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Sfruttare le citazioni nei risultati

Lezione 3 di 14 Aggiornata il 30 luglio 2026 Principiante
In questa pagina
  1. Risposte tracciabili con citazioni
  2. Citazioni globali: l’elenco completo delle fonti
  3. Citazioni inline: riferimenti nel testo
  4. Lo schema di annotazione strutturata
  5. Comportamento in streaming
  6. Costruire un’interfaccia con le fonti
  7. Citazioni delle collezioni
  8. Esercitazione pratica
  9. Punti chiave

Risposte tracciabili con citazioni

Quando un utente pone alla tua applicazione una domanda fattuale, desidera verificare le informazioni. Le citazioni dell’API Grok rispondono esattamente a questa esigenza: ogni fatto recuperato tramite ricerca web è accompagnato dalla sua fonte. Questo ti permette di costruire interfacce in cui ogni affermazione è cliccabile e verificabile.

Citazioni e fonti nelle risposte di Grok

L’API offre due meccanismi di citazione complementari: citazioni globali e citazioni inline. Comprendere il loro funzionamento ti consente di creare esperienze utente professionali e trasparenti.

Citazioni globali: l’elenco completo delle fonti

Le citazioni globali vengono restituite di default nell’attributo citations della risposta. Contengono un elenco di tutti gli URL consultati dal modello, anche quelli non direttamente citati nel testo della risposta.

response = client.responses.create(
    model="grok-4.5",
    input="What are the latest AI regulations in Europe?",
    tools=[{"type": "web_search"}]
)

# Access global citations
for citation in response.citations:
    print(f"Source: {citation.url}")

Non è necessaria alcuna configurazione aggiuntiva. Questo è il comportamento nativo dell’API.

Citazioni inline: riferimenti nel testo

Le citazioni inline inseriscono link Markdown direttamente nel testo della risposta, utilizzando il formato [[N]](url) dove N è un numero sequenziale che inizia da 1. Se la stessa fonte viene citata più volte, viene riutilizzato il numero originale.

Il comportamento predefinito dipende dall’SDK utilizzato:

  • API Risposte Dirette: citazioni inline abilitate di default
  • xAI SDK: citazioni inline disabilitate di default (opt-in)

Abilitare le citazioni inline con xAI SDK

response = client.responses.create(
    model="grok-4.5",
    input="Current status of the European AI Act",
    tools=[{"type": "web_search"}],
    include=["inline_citations"]
)

Disabilitare le citazioni inline sull’API Risposte

response = client.responses.create(
    model="grok-4.5",
    input="Current status of the European AI Act",
    tools=[{"type": "web_search"}],
    include=["no_inline_citations"]
)

Lo schema di annotazione strutturata

Ogni citazione inline genera un oggetto di annotazione con metadati precisi. Questa struttura consente un’elaborazione programmatica avanzata:

{
  "type": "url_citation",
  "url": "https://eur-lex.europa.eu/eli/reg/2024/1689",
  "start_index": 145,
  "end_index": 178,
  "title": "1"
}

I campi start_index e end_index seguono la convenzione di slicing di Python. Puoi utilizzarli per estrarre il testo citato esatto o creare un rendering HTML personalizzato:

text = response.output_text

for annotation in response.annotations:
    cited_text = text[annotation.start_index:annotation.end_index]
    print(f"Cited text: {cited_text}")
    print(f"Source: {annotation.url}")

Comportamento in streaming

Quando si utilizza lo streaming, le citazioni inline appaiono progressivamente nei chunk di testo. Tuttavia, le annotazioni complete sono disponibili solo nella risposta finale. Prevedi un’elaborazione in due fasi se la tua interfaccia visualizza le fonti in tempo reale.

Costruire un’interfaccia con le fonti

Ecco un esempio di trasformazione delle citazioni in HTML strutturato:

def format_response_with_sources(response):
    text = response.output_text
    sources = []

    # Collect unique sources
    seen_urls = set()
    for citation in response.citations:
        if citation.url not in seen_urls:
            sources.append(citation.url)
            seen_urls.add(citation.url)

    # Build the render
    html = f"<div class='response'>{text}</div>"
    html += "<div class='sources'><h4>Sources</h4><ul>"
    for i, url in enumerate(sources, 1):
        html += f"<li><a href='{url}'>[{i}] {url}</a></li>"
    html += "</ul></div>"

    return html

Citazioni delle collezioni

Se utilizzi lo strumento collections_search insieme a web_search, le citazioni provenienti dai tuoi documenti caricati utilizzano un formato URI specifico: collections://collection_id/files/file_id. Distingui queste citazioni da quelle web standard per adattare il rendering del front-end.

Esercitazione pratica

Crea un’applicazione che visualizzi i risultati della ricerca di Grok con un sistema di note a piè di pagina. Ogni fatto dovrebbe collegarsi alla sua fonte originale. Esegui test con domande su eventi attuali e verifica manualmente che i link siano validi e pertinenti.

Punti chiave

  • Le citazioni globali (elenco URL) vengono restituite di default, senza configurazione
  • Le citazioni inline (link nel testo) si abilitano tramite il parametro include
  • Il comportamento predefinito delle citazioni inline varia in base all’SDK
  • Ogni annotazione contiene l’URL, gli indici di posizione e il numero di citazione
  • In streaming, le annotazioni complete sono disponibili solo nella risposta finale
  • Le citazioni delle collezioni utilizzano un formato URI distinto (collections://)