Citări automate și bune practici
Pe această pagină
Răspunsuri documentate și fiabile
Atunci când modelul utilizează căutarea pe web sau căutarea în X, API-ul Responses include automat citări în răspuns. Aceste citări le permit utilizatorilor dumneavoastră să verifice sursele și să construiască încredere în răspunsurile generate.
Cum funcționează citările
Citările apar în tabloul annotations al fiecărui element de conținut:
{
"output": [{
"type": "message",
"content": [{
"type": "output_text",
"text": "According to the latest data, the AI market...",
"annotations": [
{
"type": "url_citation",
"url": "https://example.com/article",
"title": "AI Market Analysis in 2026",
"start_index": 35,
"end_index": 68
}
]
}]
}]
}
Câmpurile citării
| Câmp | Descriere |
|---|---|
type | Întotdeauna url_citation |
url | URL-ul sursei |
title | Titlul paginii sursă |
start_index | Poziția de început în text |
end_index | Poziția de sfârșit în text |
Afișarea citărilor în aplicația dumneavoastră
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest advancements in AI?",
tools=[{"type": "web_search"}]
)
text = response.output[0].content[0].text
annotations = response.output[0].content[0].annotations
# Construirea textului cu note de subsol
footnotes = []
for i, ann in enumerate(annotations, 1):
footnotes.append(f"[{i}] {ann.title} — {ann.url}")
print(text)
print("\n--- Sources ---")
for fn in footnotes:
print(fn)
În HTML
def render_with_citations(text, annotations):
# Sortare după poziție (de la sfârșit la început pentru a evita deplasarea indicilor)
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
Bune practici pentru producție
1. Validați întotdeauna starea
response = client.responses.create(...)
if response.status != "completed":
handle_error(response)
return
2. Gestionați răspunsurile goale
if not response.output or not response.output[0].content:
return "The model did not generate a response."
text = response.output[0].content[0].text
3. Înregistrați metricile
Pentru fiecare cerere în producție, înregistrați:
response.idpentru trasabilitateusage.total_tokenspentru consumusage.cost_in_nano_usdpentru costuri- Timpul de răspuns la nivelul clientului
- Starea răspunsului
4. Asigurați-vă cheia API
- Stocați-o într-o variabilă de mediu, niciodată în cod
- Utilizați un manager de secrete în producție (Vault, AWS Secrets Manager)
- Rotați cheile în mod regulat
- Nu le expuneți niciodată la nivelul clientului (browser)
5. Gestionați conținutul generat
Răspunsurile modelului pot conține conținut inadecvat, în ciuda filtrelor. Implementați un strat de moderare dacă afișați răspunsurile public.
6. Planificați scalabilitatea
- Utilizați streaming pentru a reduce timpul de așteptare perceput
- Implementați un sistem de coadă pentru cererile intensive
- Faceți cache la răspunsurile frecvente
- Monitorizați cotele de limitare a ratei
Lista de verificare pentru implementare
- Timeout setat la 3600 de secunde
- Reîncercare cu backoff exponențial
- Limitarea ratei la nivelul clientului
- Înregistrarea metricilor (tokeni, costuri, latență)
- Gestionarea erorilor (401, 429, 500, timeout)
- Cheie API securizată
- Moderarea conținutului, dacă este necesar
- Monitorizarea costurilor și alerte
- Întrerupător de circuit (circuit breaker) pentru reziliență
Puncte cheie
- Citările sunt automate atunci când modelul utilizează
web_searchsaux_search - Acestea conțin URL-ul, titlul și poziția în text
- Validați întotdeauna starea și gestionați răspunsurile goale
- Asigurați-vă cheia API – niciodată în codul sursă sau la nivelul clientului
- Implementați înregistrarea jurnalului, reîncercarea, limitarea ratei și monitorizarea înainte de a trece în producție
Testați-vă cunoștințele
API-ul Responses în profunzime: verificarea finală.
1. Ce oferă API-ul Responses comparativ cu Chat Completions?
Răspuns: Formatul modern: persistența răspunsului la nivelul serverului (GET/DELETE, înlănțuire după ID), instrumente integrate și funcționalități recente – API-ul pe care xAI își concentrează evoluția.
2. Cum înlănțuiți o conversație?
Răspuns: Prin referințierea răspunsului anterior: contextul este păstrat la nivelul serverului – nu este nevoie să retrimiteți întregul istoric la fiecare interacțiune.
3. Ce este raționamentul criptat?
Răspuns: Raționamentul intern al modelului returnat sub formă criptată: reutilizabil în interacțiunile următoare fără a fi lizibil – procesul de gândire călătorește, confidențialitatea rămâne.
4. Ce permite combinarea instrumentelor de server și de client?
Răspuns: Combinarea instrumentelor integrate executate de xAI (căutare web etc.) și a funcțiilor dumneavoastră personalizate executate de codul dumneavoastră – fiecare instrument la locul potrivit, orchestrat în aceeași cerere.
5. Care sunt bunele practici pentru producție?
Răspuns: Gestionați timeout-ul și reîncercarea, urmăriți facturile (tokeni, instrumente) și valorificați citările automate pentru răspunsuri verificabile – robustețe și încredere împreună.
Persistență, instrumente, raționament criptat, citări: API-ul Responses este fundația modernă – aplicațiile dumneavoastră Grok sunt construite aici.