Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Citazioni automatiche e migliori pratiche

Lezione 16 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Risposte documentate e affidabili
  2. Come funzionano le citazioni
  3. Visualizzare le citazioni nella tua applicazione
  4. Migliori pratiche per la produzione
  5. Checklist di deployment
  6. Punti chiave
  7. Metti alla prova le tue conoscenze

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

CampoDescrizione
typeSempre url_citation
urlURL della fonte
titleTitolo della pagina fonte
start_indexPosizione iniziale nel testo
end_indexPosizione 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.id per la tracciabilità
  • usage.total_tokens per il consumo
  • usage.cost_in_nano_usd per 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_search o x_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.