Automatické citácie a osvedčené postupy
Na tejto strane
Zdrojované a spoľahlivé odpovede
Keď model využije vyhľadávanie na webe alebo v sieti X, API Responses automaticky zahrnie do odpovede citácie. Tieto citácie umožňujú tvojim používateľom overiť zdroje a budovať dôveru v generované odpovede.
Ako fungujú citácie
Citácie sa objavujú v poli annotations každej položky obsahu:
{
"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
}
]
}]
}]
}
Polia citácie
| Pole | Popis |
|---|---|
type | Vždy url_citation |
url | URL zdroja |
title | Názov zdrojovej stránky |
start_index | Počiatočná pozícia v texte |
end_index | Koncová pozícia v texte |
Zobrazenie citácií v tvojej aplikácii
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
# Vytvorenie textu s poznámkami pod čiarou
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)
V HTML
def render_with_citations(text, annotations):
# Triedenie podľa pozície (od konca k začiatku, aby sa neposunuli indexy)
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
Osvedčené postupy pre produkciu
1. Vždy overuj stav
response = client.responses.create(...)
if response.status != "completed":
handle_error(response)
return
2. Ošetruj prázdne odpovede
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. Loguj metriky
Pre každú produkčnú požiadavku loguj:
response.idpre sledovateľnosťusage.total_tokenspre spotrebuusage.cost_in_nano_usdpre náklady- Čas odozvy na strane klienta
- Stav odpovede
4. Zabezpeč svoj API kľúč
- Ukladaj ho ako premennú prostredia, nikdy nie priamo v kóde
- V produkcii používaj správcu tajomstiev (Vault, AWS Secrets Manager)
- Pravidelne rotuj svoje kľúče
- Nikdy ich nezverejňuj na strane klienta (v prehliadači)
5. Spravuj generovaný obsah
Odpovede modelu môžu napriek filtrom obsahovať nevhodný obsah. Ak odpovede zobrazuješ verejne, implementuj vrstvu moderovania.
6. Plánuj škálovateľnosť
- Používaj streamovanie na zníženie vnímaného čakania
- Pre náročné požiadavky implementuj systém frontov
- Ukladaj do cache časté odpovede
- Monitoruj svoje kvóty obmedzenia rýchlosti (rate limiting)
Kontrolný zoznam pred nasadením
- Časový limit nastavený na 3600 sekúnd
- Opakovanie s exponenciálnym oneskorením (exponential backoff)
- Obmedzenie rýchlosti na strane klienta
- Logovanie metrík (tokeny, náklady, latencia)
- Ošetrenie chýb (401, 429, 500, časový limit)
- Zabezpečený API kľúč
- Moderovanie obsahu v prípade potreby
- Monitorovanie nákladov a alerty
- Istič (circuit breaker) pre odolnosť
Kľúčové poznatky
- Citácie sú automatické, keď model použije
web_searchalebox_search - Obsahujú URL, názov a pozíciu v texte
- Vždy overuj stav a ošetruj prázdne odpovede
- Zabezpeč svoj API kľúč – nikdy nie v zdrojovom kóde ani na strane klienta
- Pred nasadením do produkcie implementuj logovanie, opakovanie, obmedzenie rýchlosti a monitorovanie
Otestuj si svoje vedomosti
API Responses do hĺbky: záverečná skúška.
1. Čo ponúka API Responses v porovnaní s Chat Completions?
Odpoveď: Moderný formát: trvalé ukladanie odpovedí na strane servera (GET/DELETE, reťazenie podľa ID), vstavané nástroje a najnovšie funkcie – API, na ktoré sa xAI sústredí pri ďalšom vývoji.
2. Ako zreťazíš konverzáciu?
Odpoveď: Odvolaním sa na predchádzajúcu odpoveď: kontext zostáva na strane servera – nie je potrebné pri každom kole odosielať celú históriu.
3. Čo je šifrované uvažovanie?
Odpoveď: Interné uvažovanie modelu vrátené v šifrovanej forme: opakovane použiteľné v nasledujúcich kolách bez toho, aby bolo čitateľné – proces myslenia putuje ďalej, dôvernosť zostáva zachovaná.
4. Čo umožňuje kombinácia serverových a klientskych nástrojov?
Odpoveď: Kombináciu vstavaných nástrojov spúšťaných xAI (vyhľadávanie na webe atď.) a tvojich vlastných funkcií spúšťaných tvojim kódom – každý nástroj na správnom mieste, orchestrovaný v rámci jednej požiadavky.
5. Aké sú osvedčené postupy pre produkciu?
Odpoveď: Ošetrenie časového limitu a opakovania, sledovanie fakturácie (tokeny, nástroje) a využitie automatických citácií pre overiteľné odpovede – robustnosť a dôvera pohromade.
Trvalosť, nástroje, šifrované uvažovanie, citácie: API Responses je moderným základom – tvoje aplikácie Grok sú postavené práve tu.