Samodejne navedbe in najboljše prakse
Na tej strani
Viri in zanesljivi odgovori
Ko model uporabi spletno iskanje ali iskanje po X, API za odgovore samodejno vključi navedbe v odgovor. Te navedbe tvojim uporabnikom omogočajo preverjanje virov in gradijo zaupanje v ustvarjene odgovore.
Kako delujejo navedbe
Navedbe se pojavijo v polju annotations vsakega elementa vsebine:
{
"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
}
]
}]
}]
}
Polja navedb
| Polje | Opis |
|---|---|
type | Vedno url_citation |
url | URL vira |
title | Naslov izvorne strani |
start_index | Začetni položaj v besedilu |
end_index | Končni položaj v besedilu |
Prikaz navedb v tvoji aplikaciji
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
# Izgradnja besedila z opombami
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-ju
def render_with_citations(text, annotations):
# Razvrsti po položaju (od konca proti začetku, da se indeksi ne premaknejo)
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
Najboljše prakse za proizvodnjo
1. Vedno preveri stanje
response = client.responses.create(...)
if response.status != "completed":
handle_error(response)
return
2. Obravnavaj prazne odgovore
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. Beleži metrike
Za vsak zahtevek v proizvodnji beleži:
response.idza sledljivostusage.total_tokensza porabousage.cost_in_nano_usdza stroške- Odzivni čas na strani odjemalca
- Stanje odgovora
4. Zavaruj svoj API ključ
- Shrani ga v spremenljivko okolja, nikoli ne v kodo
- V proizvodnji uporabi upravitelja skrivnosti (Vault, AWS Secrets Manager)
- Ključe redno menjaj
- Nikoli jih ne izpostavljaj na strani odjemalca (brskalnik)
5. Upravljaj ustvarjeno vsebino
Odgovori modela lahko kljub filtrom vsebujejo neustrezno vsebino. Če odgovore prikazuješ javno, uvedi plast za moderiranje.
6. Načrtuj razširljivost
- Uporabi pretakanje (streaming) za zmanjšanje zaznanega čakalnega časa
- Za zahtevne zahtevke uvedi sistem čakalne vrste
- Predpomni pogoste odgovore
- Spremljaj svoje kvote omejevanja hitrosti
Kontrolni seznam za uvedbo
- Časovna omejitev nastavljena na 3600 sekund
- Ponovni poskus z eksponentnim zamikom
- Omejevanje hitrosti na strani odjemalca
- Beleženje metrik (žetoni, stroški, latenca)
- Obravnava napak (401, 429, 500, časovna omejitev)
- Varen API ključ
- Moderiranje vsebine, če je potrebno
- Nadzor stroškov in opozorila
- Odklopnik (circuit breaker) za odpornost
Ključne ugotovitve
- Navedbe so samodejne, ko model uporabi
web_searchalix_search - Vsebujejo URL, naslov in položaj v besedilu
- Vedno preveri stanje in obravnavaj prazne odgovore
- Zavaruj svoj API ključ – nikoli ne v izvorni kodi ali na strani odjemalca
- Pred prehodom v proizvodnjo uvedi beleženje, ponovne poskuse, omejevanje hitrosti in nadzor
Preveri svoje znanje
API za odgovore do potankosti: končni preizkus.
1. Kaj ponuja API za odgovore v primerjavi z Chat Completions?
Odgovor: Sodoben format: trajno shranjevanje odgovorov na strežniku (GET/DELETE, veriženje po ID-ju), vgrajena orodja in najnovejše funkcije – API, na katerega se xAI osredotoča pri razvoju.
2. Kako verišiš pogovor?
Odgovor: Z navezavo na prejšnji odgovor: kontekst ostane na strežniku – ni treba vsakič znova pošiljati celotne zgodovine.
3. Kaj je šifrirano sklepanje?
Odgovor: Notranje sklepanje modela, vrnjeno v šifrirani obliki: uporabno v naslednjih korakih, ne da bi bilo berljivo – proces razmišljanja potuje, zaupnost ostaja.
4. Kaj omogoča mešanje strežniških in odjemalčevih orodij?
Odgovor: Združitev vgrajenih orodij, ki jih izvaja xAI (spletno iskanje itd.), in tvojih prilagojenih funkcij, ki jih izvaja tvoja koda – vsako orodje na pravem mestu, usklajeno v istem zahtevku.
5. Katere so najboljše prakse za proizvodnjo?
Odgovor: Obravnava časovnih omejitev in ponovnih poskusov, sledenje obračunu (žetoni, orodja) in izkoriščanje samodejnih navedb za preverljive odgovore – robustnost in zaupanje skupaj.
Trajnost, orodja, šifrirano sklepanje, navedbe: API za odgovore je sodobna temeljna plast – tukaj gradiš svoje aplikacije Grok.