Sfruttare le citazioni nei risultati
In questa pagina
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.

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://)