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

Ymmärrä vastausmuoto

Oppitunti 4 / 16 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Vastauksen anatomia
  2. Täydellinen rakenne
  3. Tärkeimmät kentät
  4. Ymmärrä usage-objekti
  5. Palvelinpuolen työkalujen käyttö
  6. Tekstin erottaminen Pythonilla
  7. Keskeiset asiat

Vastauksen anatomia

Kun lähetät pyynnön osoitteeseen POST /v1/responses, xAI-palvelin palauttaa jäsennellyn JSON-objektin. Jokaisen tässä objektissa olevan kentän ymmärtäminen on välttämätöntä, jotta voit hyödyntää tuloksia oikein sovelluksessasi.

Täydellinen rakenne

Tässä on tyypillinen vastaus:

{
  "id": "resp-abc123def456",
  "object": "response",
  "created_at": 1712000000,
  "status": "completed",
  "model": "grok-4.20-0309-reasoning",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Le machine learning est une branche de l'IA...",
          "annotations": []
        }
      ],
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 45,
    "output_tokens": 180,
    "total_tokens": 225,
    "output_tokens_details": {
      "reasoning_tokens": 120
    },
    "cost_in_nano_usd": 500000
  }
}

Tärkeimmät kentät

id

Vastauksen yksilöllinen tunniste muodossa resp-xxx. Käytät sitä seuraaviin tarkoituksiin:

  • Keskustelujen ketjuttamiseen parametrilla previous_response_id
  • Tallennetun vastauksen noutamiseen komennolla GET /v1/responses/{id}
  • Vastauksen poistamiseen komennolla DELETE /v1/responses/{id}

status

Vastauksen tila:

TilaMerkitys
completedVastaus luotu onnistuneesti
failedVirhe luonnin aikana
incompleteVastaus keskeytetty (tokinirajoitus, sisältösuodatin)
in_progressLuonti käynnissä (streaming)

Tarkista aina tila ennen vastauksen sisällön käyttämistä koodissasi.

output

Taulukko, joka sisältää vastauselementit. Jokaisella elementillä on type:

  • message: Mallin tuottama tekstivastaus
  • function_call: Mallin pyytämä työkalukutsu

Tekstisisältö sijaitsee osoitteessa output[0].content[0].text. Annotaatiot (lähdeviitteet, linkit) löytyvät saman objektin annotations-taulukosta.

usage

Käyttötiedot, jotka on eritelty alla.

Ymmärrä usage-objekti

usage-objekti on ratkaisevan tärkeä kustannusten seurannassa:

{
  "input_tokens": 45,
  "output_tokens": 180,
  "total_tokens": 225,
  "output_tokens_details": {
    "reasoning_tokens": 120
  },
  "cost_in_nano_usd": 500000
}

Syöte- ja tulostetokit

  • input_tokens: Kehotteesi (prompt) tokien määrä (sekä historia, jos ketjutat keskusteluja)
  • output_tokens: Luotujen tokien kokonaismäärä, päättely mukaan lukien
  • total_tokens: Molempien summa

Päättelytokit

output_tokens_details.reasoning_tokens kertoo, kuinka monta tokia malli käytti sisäiseen päättelyynsä. Näistä tokeista veloitetaan, mutta niitä ei näy tekstivastauksessa.

Yllä olevassa esimerkissä 180 tulostetokista 120 on varattu päättelyyn ja vain 60 muodostaa näkyvän vastauksen. Tämä on tyypillinen suhde päättelymalleille.

Kustannus nano-USD-muodossa

cost_in_nano_usd ilmoittaa pyynnön tarkan hinnan. Muunnos on yksinkertainen:

Kustannus USD = cost_in_nano_usd / 1 000 000 000

Esimerkissämme: 500000 / 1 000 000 000 = 0,0005 USD (0,0005 dollaria).

Palvelinpuolen työkalujen käyttö

Kun malli käyttää sisäänrakennettuja työkaluja, usage-objekti sisältää myös seuraavat tiedot:

{
  "server_side_tool_usage_details": {
    "web_search_calls": 2,
    "code_interpreter_calls": 0,
    "x_search_calls": 1,
    "document_search_calls": 0,
    "file_search_calls": 0,
    "mcp_calls": 0
  }
}

Tämän avulla näet tarkasti, mitä työkaluja on kutsuttu ja kuinka monta kertaa.

Tekstin erottaminen Pythonilla

Tässä on vahva malli tekstisisällön erottamiseen:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Explique les listes en Python."
)

# Tarkista tila
if response.status == "completed":
    text = response.output[0].content[0].text
    print(text)
else:
    print(f"Error: status {response.status}")

# Näytä käyttö
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")

Keskeiset asiat

  • Jokaisella vastauksella on yksilöllinen id, jota voi käyttää ketjutukseen tai noutoon
  • Tarkista aina status ennen sisällön käyttämistä
  • Teksti sijaitsee osoitteessa output[0].content[0].text
  • reasoning_tokens veloitetaan, mutta niitä ei näy vastauksessa
  • cost_in_nano_usd jaettuna miljardilla antaa kustannuksen dollareina