Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Vastuse vormingu mõistmine

Õppetund 4 / 16 Värskendatud 30. juuli 2026 Arendajatele
Sellel lehel
  1. Vastuse anatoomia
  2. Täielik struktuur
  3. Peamised väljad
  4. Kasutusobjekti mõistmine
  5. Serveripoolne tööriistade kasutamine
  6. Teksti eraldamine Pythonis
  7. Peamised punktid

Vastuse anatoomia

Kui saadad päringu aadressile POST /v1/responses, tagastab xAI server struktureeritud JSON-objekti. Iga välja mõistmine selles objektis on hädavajalik, et saaksid tulemusi oma rakenduses õigesti kasutada.

Täielik struktuur

Siin on tüüpiline vastus:

{
  "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
  }
}

Peamised väljad

id

Vastuse kordumatu identifikaator formaadis resp-xxx. Kasutad seda järgmisteks tegevusteks:

  • Vestluste aheldamiseks kasutades previous_response_id
  • Salvestatud vastuse toomiseks päringuga GET /v1/responses/{id}
  • Vastuse kustutamiseks päringuga DELETE /v1/responses/{id}

status

Vastuse olek:

OlekTähendus
completedVastus genereeriti edukalt
failedViga genereerimise käigus
incompleteVastus katkestati (tokenite piirang, sisufilter)
in_progressGenereerimine pooleli (voogedastus)

Kontrolli alati olekut enne, kui kasutad vastuse sisu oma koodis.

output

Massiiv, mis sisaldab vastuse elemente. Igal elemendil on väli type:

  • message: Mudeli tekstivastus
  • function_call: Mudeli taotletud tööriista kutse

Tekstisisu asub aadressil output[0].content[0].text. Annotatsioonid (tsitaadid, lingid) paiknevad sama objekti massiivis annotations.

usage

Kasutusteave, mida käsitleme allpool täpsemalt.

Kasutusobjekti mõistmine

Objekt usage on kulude jälgimiseks ülioluline:

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

Sisend- ja väljundtokenid

  • input_tokens: Tokenite arv sinu vihjes (ja ajaloos, kui vestlusi aheldad)
  • output_tokens: Genereeritud tokenite koguarv, kaasa arvatud arutluskäik
  • total_tokens: Mõlema summa

Arutlustokenid

output_tokens_details.reasoning_tokens näitab, mitu tokenit mudel oma sisemiseks arutluskäiguks kasutas. Nende tokenite eest tasutakse, kuid need ei ole tekstivastuses nähtavad.

Ülaltoodud näites on 180 väljundtokenist 120 mõeldud arutluskäiguks ja vaid 60 moodustavad nähtava vastuse. See on arutlusmudelite jaoks tüüpiline suhe.

Kulu nano-USD-des

cost_in_nano_usd annab päringu täpse hinna. Teisendamine on lihtne:

Hind USD-des = cost_in_nano_usd / 1 000 000 000

Meie näite puhul: 500000 / 1 000 000 000 = 0,0005 USD (0,0005 dollarit).

Serveripoolne tööriistade kasutamine

Kui mudel kasutab sisseehitatud tööriistu, sisaldab objekt usage ka järgmist:

{
  "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
  }
}

See annab sulle täpse ülevaate, milliseid tööriistu ja mitu korda kutsuti.

Teksti eraldamine Pythonis

Siin on töökindel muster tekstisisu eraldamiseks:

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

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

# Kuva kasutusstatistika
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")

Peamised punktid

  • Igal vastusel on kordumatu id, mida saab kasutada aheldamiseks või taastamiseks
  • Kontrolli alati välja status enne sisu kasutamist
  • Tekst asub aadressil output[0].content[0].text
  • reasoning_tokens on tasulised, kuid vastuses nähtamatud
  • cost_in_nano_usd jagatuna ühe miljardiga annab hinna dollarites