Citazioni automatiche e migliori pratiche
In questa pagina
Risposte documentate e affidabili
Quando il modello utilizza la ricerca web o la ricerca su X, le API Responses includono automaticamente le citazioni nella risposta. Queste citazioni permettono ai tuoi utenti di verificare le fonti e di costruire fiducia nelle risposte generate.
Come funzionano le citazioni
Le citazioni appaiono nell’array annotations di ogni elemento di contenuto:
{
"output": [{
"type": "message",
"content": [{
"type": "output_text",
"text": "Secondo gli ultimi dati, il mercato dell'IA...",
"annotations": [
{
"type": "url_citation",
"url": "https://example.com/article",
"title": "Analisi del mercato dell'IA nel 2026",
"start_index": 35,
"end_index": 68
}
]
}]
}]
}
Campi delle citazioni
| Campo | Descrizione |
|---|---|
type | Sempre url_citation |
url | URL della fonte |
title | Titolo della pagina fonte |
start_index | Posizione iniziale nel testo |
end_index | Posizione finale nel testo |
Visualizzare le citazioni nella tua applicazione
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Quali sono gli ultimi progressi nell'IA?",
tools=[{"type": "web_search"}]
)
text = response.output[0].content[0].text
annotations = response.output[0].content[0].annotations
# Costruisci il testo con le note a piè di pagina
footnotes = []
for i, ann in enumerate(annotations, 1):
footnotes.append(f"[{i}] {ann.title} — {ann.url}")
print(text)
print("\n--- Fonti ---")
for fn in footnotes:
print(fn)
In HTML
def render_with_citations(text, annotations):
# Ordina per posizione (dalla fine all'inizio per evitare lo spostamento degli indici)
sorted_anns = sorted(annotations, key=lambda a: a.start_index, reverse=True)
html = text
for i, ann in enumerate(sorted_anns):
ref_num = len(sorted_anns) - i
link = f'<a href="{ann.url}" title="{ann.title}" target="_blank">[{ref_num}]</a>'
html = html[:ann.end_index] + link + html[ann.end_index:]
return html
Migliori pratiche per la produzione
1. Convalida sempre lo stato
response = client.responses.create(...)
if response.status != "completed":
handle_error(response)
return
2. Gestisci le risposte vuote
if not response.output or not response.output[0].content:
return "Il modello non ha generato una risposta."
text = response.output[0].content[0].text
3. Registra le metriche
Per ogni richiesta in produzione, registra:
response.idper la tracciabilitàusage.total_tokensper il consumousage.cost_in_nano_usdper i costi- Tempo di risposta lato client
- Stato della risposta
4. Proteggi la tua chiave API
- Memorizzala in una variabile d’ambiente, mai nel codice
- Usa un gestore di segreti in produzione (Vault, AWS Secrets Manager)
- Ruota le tue chiavi regolarmente
- Non esporle mai lato client (browser)
5. Gestisci i contenuti generati
Le risposte del modello possono contenere contenuti inappropriati nonostante i filtri. Implementa un livello di moderazione se mostri le risposte pubblicamente.
6. Pianifica la scalabilità
- Usa lo streaming per ridurre il tempo di attesa percepito
- Implementa un sistema di coda per le richieste pesanti
- Metti in cache le risposte frequenti
- Monitora le tue quote di limitazione della frequenza (rate limiting)
Checklist di deployment
- Timeout impostato a 3600 secondi
- Retry con backoff esponenziale
- Limitazione della frequenza lato client
- Registrazione delle metriche (token, costi, latenza)
- Gestione degli errori (401, 429, 500, timeout)
- Chiave API sicura
- Moderazione dei contenuti se necessaria
- Monitoraggio dei costi e avvisi
- Circuit breaker per la resilienza
Punti chiave
- Le citazioni sono automatiche quando il modello usa
web_searchox_search - Contengono URL, titolo e posizione nel testo
- Convalida sempre lo stato e gestisci le risposte vuote
- Proteggi la tua chiave API: mai nel codice sorgente o lato client
- Implementa registrazione, retry, limitazione della frequenza e monitoraggio prima di andare in produzione
Metti alla prova le tue conoscenze
Le API Responses nel dettaglio: il controllo finale.
1. Cosa offrono le API Responses rispetto alle Chat Completions?
Risposta: Il formato moderno: persistenza delle risposte lato server (GET/DELETE, concatenamento per ID), strumenti integrati e funzionalità recenti: l’API su cui xAI concentra l’evoluzione.
2. Come si concatena una conversazione?
Risposta: Facendo riferimento alla risposta precedente: il contesto viene mantenuto lato server, senza bisogno di reinviare l’intera cronologia a ogni turno.
3. Cos'è il ragionamento crittografato?
Risposta: Il ragionamento interno del modello restituito in forma crittografata: riutilizzabile nei turni successivi senza essere leggibile: il processo di pensiero viaggia, la riservatezza rimane.
4. Cosa permette la combinazione di strumenti server e client?
Risposta: Combinare strumenti integrati eseguiti da xAI (ricerca web, ecc.) e le tue funzioni personalizzate eseguite dal tuo codice: ogni strumento al posto giusto, orchestrato nella stessa richiesta.
5. Quali sono le migliori pratiche per la produzione?
Risposta: Gestisci timeout e retry, traccia la fatturazione (token, strumenti) e sfrutta le citazioni automatiche per risposte verificabili: robustezza e fiducia insieme.
Persistenza, strumenti, ragionamento crittografato, citazioni: le API Responses sono la fondazione moderna: le tue applicazioni Grok sono costruite qui.