Automaattiset viitteet ja parhaat käytännöt
Tällä sivulla
Lähteistetyt ja luotettavat vastaukset
Kun malli käyttää verkkohakua tai X-hakua, Responses API sisällyttää vastaukseen automaattisesti viitteet. Nämä viitteet antavat käyttäjillesi mahdollisuuden tarkistaa lähteet ja lisäävät luottamusta generoituihin vastauksiin.
Miten viitteet toimivat
Viitteet näkyvät kunkin sisältöalkion annotations-taulukossa:
{
"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
}
]
}]
}]
}
Viitteen kentät
| Kenttä | Kuvaus |
|---|---|
type | Aina url_citation |
url | Lähteen URL-osoite |
title | Lähteen sivun otsikko |
start_index | Aloituspaikka tekstissä |
end_index | Lopetuspaikka tekstissä |
Viitteiden näyttäminen sovelluksessasi
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
# Rakenna teksti alaviitteineen
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)
HTML-muodossa
def render_with_citations(text, annotations):
# Järjestä sijainnin mukaan (lopusta alkuun indeksien siirtymisen välttämiseksi)
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
Tuotannon parhaat käytännöt
1. Vahvista tila aina
response = client.responses.create(...)
if response.status != "completed":
handle_error(response)
return
2. Käsittele tyhjät vastaukset
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. Lokita mittareita
Kirjaa jokaisesta tuotantopyynnöstä:
response.idjäljitettävyyden vuoksiusage.total_tokenskulutuksen seuraamiseksiusage.cost_in_nano_usdkustannusten laskemiseksi- Asiakaspään vasteaika
- Vastauksen tila
4. Suojaa API-avaimesi
- Tallenna se ympäristömuuttujaan, älä koskaan koodiin
- Käytä salaisuuksien hallintajärjestelmää tuotannossa (Vault, AWS Secrets Manager)
- Kierrä avaimiasi säännöllisesti
- Älä koskaan paljasta niitä asiakaspäässä (selain)
5. Hallitse generoitua sisältöä
Mallin vastaukset voivat sisältää sopimatonta sisältöä suodattimista huolimatta. Toteuta moderointikerros, jos näytät vastauksia julkisesti.
6. Suunnittele skaalautuvuus
- Käytä suoratoistoa vähentääksesi koettua odotusaikaa
- Toteuta jonotusjärjestelmä raskaille pyynnöille
- Välimuistita usein toistuvia vastauksia
- Valvo nopeusrajoituskiintiöitäsi
Käyttöönoton tarkistuslista
- Aikakatkaisu asetettu 3600 sekuntiin
- Yritykset eksponentiaalisella takaisinvedolla
- Asiakaspään nopeusrajoitus
- Mittareiden lokitus (tokenit, kustannukset, viive)
- Virheenkäsittely (401, 429, 500, aikakatkaisu)
- Turvallinen API-avain
- Sisällön moderointi tarvittaessa
- Kustannusten seuranta ja hälytykset
- Katkaisija vikasietoisuuden varmistamiseksi
Keskeiset asiat
- Viitteet ovat automaattisia, kun malli käyttää
web_search- taix_search-toimintoja - Ne sisältävät URL-osoitteen, otsikon ja sijainnin tekstissä
- Vahvista tila aina ja käsittele tyhjät vastaukset
- Suojaa API-avaimesi – älä koskaan lähdekoodissa tai asiakaspäässä
- Toteuta lokitus, yritykset, nopeusrajoitus ja valvonta ennen tuotantoon siirtymistä
Testaa tietämyksesi
Responses API syvällisesti: lopullinen tarkistus.
1. Mitä Responses API tarjoaa verrattuna Chat Completionsiin?
Vastaus: Modernin muodon: palvelinpuolen vastauksen pysyvyys (GET/DELETE, ketjutus ID:n perusteella), sisäänrakennetut työkalut ja uusimmat ominaisuudet – API, johon xAI keskittää kehityksensä.
2. Miten ketjutat keskustelun?
Vastaus: Viittaamalla edelliseen vastaukseen: konteksti säilyy palvelinpuolella – koko historiaa ei tarvitse lähettää uudelleen joka kierroksella.
3. Mikä on salattu päättely?
Vastaus: Mallin sisäinen päättely palautetaan salatussa muodossa: uudelleenkäytettävissä seuraavilla kierroksilla ilman lukukelpoisuutta – ajatusprosessi kulkee mukana, luottamuksellisuus säilyy.
4. Mitä palvelin- ja asiakastyökalujen yhdistäminen mahdollistaa?
Vastaus: Yhdistää xAI:n suorittamat sisäänrakennetut työkalut (verkkohaku jne.) ja koodisi suorittamat mukautetut funktiot – jokainen työkalu oikeassa paikassa, orkestroituna samassa pyynnössä.
5. Mitkä ovat tuotannon parhaat käytännöt?
Vastaus: Käsittele aikakatkaisut ja yritykset, seuraa laskutusta (tokenit, työkalut) ja hyödynnä automaattisia viitteitä varmennettaviin vastauksiin – robustius ja luottamus yhdessä.
Pysyvyys, työkalut, salattu päättely, viitteet: Responses API on moderni perusta – Grok-sovelluksesi rakennetaan tähän.