Automatické citace a osvědčené postupy
Na této stránce
Zdrojované a spolehlivé odpovědi
Když model využije vyhledávání na webu nebo na síti X, API Responses automaticky zahrne do odpovědi citace. Tyto citace umožňují tvým uživatelům ověřit zdroje a budují důvěru v generované odpovědi.
Jak fungují citace
Citace se objevují v poli annotations u každé 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
}
]
}]
}]
}
Pole citací
| Pole | Popis |
|---|---|
type | Vždy url_citation |
url | URL zdroje |
title | Název zdrojové stránky |
start_index | Počáteční pozice v textu |
end_index | Koncová pozice v textu |
Zobrazení citací ve tvé aplikaci
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
# Vytvoření textu s poznámkami pod čarou
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):
# Seřazení podle pozice (od konce ke začátku, aby se neposunuly 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
Osvědčené postupy pro produkci
1. Vždy ověř stav
response = client.responses.create(...)
if response.status != "completed":
handle_error(response)
return
2. Ošetři prázdné odpovědi
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
Pro každý produkční požadavek zaznamenej:
response.idpro sledovatelnostusage.total_tokenspro spotřebuusage.cost_in_nano_usdpro náklady- Doba odezvy na straně klienta
- Stav odpovědi
4. Zabezpeč svůj API klíč
- Ukládej jej jako proměnnou prostředí, nikdy přímo v kódu
- V produkci používej správce tajných údajů (Vault, AWS Secrets Manager)
- Pravidelně obměňuj své klíče
- Nikdy je nezveřejňuj na straně klienta (v prohlížeči)
5. Spravuj generovaný obsah
Odpovědi modelu mohou i přes filtry obsahovat nevhodný obsah. Pokud odpovědi zobrazuješ veřejně, implementuj vrstvu moderování.
6. Plánuj škálovatelnost
- Používej streamování pro snížení vnímané doby čekání
- Pro náročné požadavky implementuj systém front
- Mezi odpovědi ukládej do mezipaměti ty časté
- Sleduj své kvóty pro omezování rychlosti (rate limiting)
Kontrolní seznam pro nasazení
- Časový limit nastaven na 3600 sekund
- Opakování s exponenciálním backoffem
- Omezování rychlosti na straně klienta
- Logování metrik (tokeny, náklady, latence)
- Ošetření chyb (401, 429, 500, časový limit)
- Zabezpečený API klíč
- Moderování obsahu v případě potřeby
- Monitorování nákladů a alerty
- Jistič (circuit breaker) pro odolnost
Klíčové poznatky
- Citace jsou automatické, když model použije
web_searchnebox_search - Obsahují URL, název a pozici v textu
- Vždy ověř stav a ošetři prázdné odpovědi
- Zabezpeč svůj API klíč – nikdy ho nedávej do zdrojového kódu ani na stranu klienta
- Před nasazením do produkce implementuj logování, opakování, omezování rychlosti a monitorování
Ověř si své znalosti
API Responses do hloubky: závěrečná zkouška.
1. Co nabízí API Responses ve srovnání s Chat Completions?
Odpověď: Moderní formát: perzistence odpovědí na straně serveru (GET/DELETE, řetězení podle ID), vestavěné nástroje a nejnovější funkce – API, na které se xAI soustředí při dalším vývoji.
2. Jak řetězíš konverzaci?
Odpověď: Odkazem na předchozí odpověď: kontext zůstává na straně serveru – nemusíš při každém kroku znovu odesílat celou historii.
3. Co je šifrované uvažování?
Odpověď: Vnitřní uvažování modelu vrácené v zašifrované podobě: znovu použitelné v následujících krocích, aniž by bylo čitelné – myšlenkový proces putuje dál, důvěrnost zůstává zachována.
4. Co umožňuje kombinace serverových a klientských nástrojů?
Odpověď: Kombinaci vestavěných nástrojů spouštěných xAI (vyhledávání na webu atd.) a tvých vlastních funkcí spouštěných tvým kódem – každý nástroj na správném místě, orchestrované v rámci jednoho požadavku.
5. Jaké jsou osvědčené postupy pro produkci?
Odpověď: Ošetři časové limity a opakování, sleduj fakturaci (tokeny, nástroje) a využij automatické citace pro ověřitelné odpovědi – robustnost a důvěra pohromadě.
Perzistence, nástroje, šifrované uvažování, citace: API Responses je moderním základem – zde stavíš své aplikace s Grok.