Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Automaattiset viitteet ja parhaat käytännöt

Oppitunti 16 / 16 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Lähteistetyt ja luotettavat vastaukset
  2. Miten viitteet toimivat
  3. Viitteiden näyttäminen sovelluksessasi
  4. Tuotannon parhaat käytännöt
  5. Käyttöönoton tarkistuslista
  6. Keskeiset asiat
  7. Testaa tietämyksesi

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
typeAina url_citation
urlLähteen URL-osoite
titleLähteen sivun otsikko
start_indexAloituspaikka tekstissä
end_indexLopetuspaikka 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.id jäljitettävyyden vuoksi
  • usage.total_tokens kulutuksen seuraamiseksi
  • usage.cost_in_nano_usd kustannusten 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- tai x_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.