Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Tuiscint a fháil ar fhormáid na freagartha

Ceacht 4 as 16 Nuashonraithe 30 Iúil 2026 Forbróir
Ar an leathanach seo
  1. Anatamaíocht na freagartha
  2. Struchtúr iomlán
  3. Príomhréimsí
  4. Tuiscint a fháil ar an oibiacht usage
  5. Úsáid uirlisí taobh freastalaí
  6. Téacs a bhaint amach i bPython
  7. Príomhphointí

Anatamaíocht na freagartha

Nuair a sheolann tú iarratas chuig POST /v1/responses, filleann freastalaí xAI oibiacht JSON struchtúrtha. Tá sé ríthábhachtach gach réimse san oibiacht seo a thuiscint chun na torthaí a úsáid i gceart i d’fheidhmchlár.

Struchtúr iomlán

Seo sampla tipiciúil de fhreagra:

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

Príomhréimsí

id

Is é seo an t-aitheantóir uathúil don fhreagra, i bhformáid resp-xxx. Úsáidfidh tú é chun:

  • Comhráite a shlabhrú le previous_response_id
  • Freagra stóráilte a aisghabháil le GET /v1/responses/{id}
  • Freagra a scriosadh le DELETE /v1/responses/{id}

status

Stádas na freagartha:

StádasBrí
completedGineadh an fhreagra go rathúil
failedEarráid le linn na giniúna
incompleteBriseadh isteach ar an bhfreagra (teorainn token, scagaire ábhair)
in_progressGiniúint ar siúl (sruthú)

Seiceáil an stádas i gcónaí sula n-úsáideann tú ábhar na freagartha i do chód.

output

Eagar ina bhfuil eilimintí na freagartha. Tá type ag gach eilimint:

  • message: Freagra téacs ón tsamhail
  • function_call: Glao uirlise a d’iarr an tsamhail

Tá an t-ábhar téacs suite ag output[0].content[0].text. Tá nótaí tráchta (luanna, naisc) san eagar annotations san oibiacht chéanna.

usage

Faisnéis úsáide, atá mionsonraithe thíos.

Tuiscint a fháil ar an oibiacht usage

Tá an oibiacht usage ríthábhachtach chun do chostais a rianú:

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

Token ionchuir agus aschuir

  • input_tokens: Líon na token i do leid (agus sa stair má tá comhráite á slabhrú)
  • output_tokens: Líon iomlán na token a gineadh, réasúnaíocht san áireamh
  • total_tokens: Suim an dá cheann

Token réasúnaíochta

Léiríonn output_tokens_details.reasoning_tokens cé mhéad token a d’úsáid an tsamhail dá réasúnaíocht inmheánach. Gearrtar táille ar na token seo ach ní fheictear iad sa fhreagra téacs.

Sa sampla thuas, as 180 token aschuir, is do réasúnaíocht atá 120 acu agus ní dhéanann ach 60 suas an fhreagra infheicthe. Is cóimheas tipiciúil é seo do shamhlacha réasúnaíochta.

Costas i nano-USD

Tugann cost_in_nano_usd costas cruinn an iarratais. Tá an tiontú simplí:

Costas in USD = cost_in_nano_usd / 1,000,000,000

Don sampla againn: 500000 / 1,000,000,000 = 0.0005 USD ($0.0005).

Úsáid uirlisí taobh freastalaí

Nuair a úsáideann an tsamhail uirlisí ionsuite, áirítear an méid seo a leanas san oibiacht usage freisin:

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

Ligeann sé seo duit a fháil amach go beacht cé na huirlisí a glaodh orthu agus cé huaire.

Téacs a bhaint amach i bPython

Seo patrún láidir chun ábhar téacs a bhaint amach:

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

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

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

Príomhphointí

  • Tá id uathúil ag gach freagra is féidir a athúsáid chun slabhrú nó aisghabháil
  • Seiceáil an status i gcónaí sula n-úsáideann tú an t-ábhar
  • Tá an téacs suite ag output[0].content[0].text
  • Gearrtar táille ar reasoning_tokens ach tá siad dofheicthe sa fhreagra
  • Roinn cost_in_nano_usd ar aon billiún chun an costas i ndollair a fháil