Przejdź do głównej treści
Polski— Wybierz język
Menu

Zrozumienie formatu odpowiedzi

Lekcja 4 z 16 Zaktualizowano 30 lipca 2026 Programista
Na tej stronie
  1. Anatomia odpowiedzi
  2. Pełna struktura
  3. Główne pola
  4. Zrozumienie obiektu usage
  5. Wykorzystanie narzędzi po stronie serwera
  6. Ekstrakcja tekstu w Pythonie
  7. Kluczowe wnioski

Anatomia odpowiedzi

Gdy wyślesz żądanie do POST /v1/responses, serwer xAI zwraca strukturalny obiekt JSON. Zrozumienie każdego pola w tym obiekcie jest kluczowe, aby poprawnie wykorzystać wyniki w swojej aplikacji.

Pełna struktura

Oto typowa odpowiedź:

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

Główne pola

id

Unikalny identyfikator odpowiedzi w formacie resp-xxx. Wykorzystasz go do:

  • Łączenia rozmów za pomocą previous_response_id
  • Pobrania zapisanej odpowiedzi poprzez GET /v1/responses/{id}
  • Usunięcia odpowiedzi poprzez DELETE /v1/responses/{id}

status

Status odpowiedzi:

StatusZnaczenie
completedOdpowiedź wygenerowana pomyślnie
failedBłąd podczas generowania
incompleteOdpowiedź przerwana (limit tokenów, filtr treści)
in_progressGenerowanie w toku (strumieniowanie)

Zawsze sprawdzaj status przed użyciem treści odpowiedzi w swoim kodzie.

output

Tablica zawierająca elementy odpowiedzi. Każdy element posiada pole type:

  • message: Odpowiedź tekstowa od modelu
  • function_call: Wywołanie narzędzia zażądane przez model

Treść tekstowa znajduje się pod adresem output[0].content[0].text. Adnotacje (cytaty, linki) znajdują się w tablicy annotations tego samego obiektu.

usage

Informacje o zużyciu, szczegółowo opisane poniżej.

Zrozumienie obiektu usage

Obiekt usage jest kluczowy dla śledzenia Twoich kosztów:

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

Tokeny wejściowe i wyjściowe

  • input_tokens: Liczba tokenów w Twoim prompcie (oraz w historii, jeśli łączysz rozmowy)
  • output_tokens: Całkowita liczba wygenerowanych tokenów, włączając w to rozumowanie
  • total_tokens: Suma obu wartości

Tokeny rozumowania

output_tokens_details.reasoning_tokens wskazuje, ile tokenów model zużył na swoje wewnętrzne rozumowanie. Tokeny te są rozliczane, ale nie są widoczne w odpowiedzi tekstowej.

W powyższym przykładzie, na 180 tokenów wyjściowych, 120 przeznaczono na rozumowanie, a tylko 60 stanowi widoczną odpowiedź. Jest to typowy współczynnik dla modeli rozumujących.

Koszt w nano-USD

cost_in_nano_usd podaje dokładny koszt żądania. Konwersja jest prosta:

Koszt w USD = cost_in_nano_usd / 1 000 000 000

Dla naszego przykładu: 500000 / 1 000 000 000 = 0,0005 USD (0,0005 $).

Wykorzystanie narzędzi po stronie serwera

Gdy model korzysta z wbudowanych narzędzi, obiekt usage zawiera również:

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

Pozwala to dokładnie ustalić, które narzędzia zostały wywołane i ile razy.

Ekstrakcja tekstu w Pythonie

Oto solidny wzorzec ekstrakcji treści tekstowej:

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

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

# Wyświetl zużycie
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")

Kluczowe wnioski

  • Każda odpowiedź posiada unikalny id, który można wykorzystać do łączenia wątków lub pobierania danych
  • Zawsze sprawdzaj status przed użyciem treści
  • Tekst znajduje się pod adresem output[0].content[0].text
  • reasoning_tokens są rozliczane, ale niewidoczne w odpowiedzi
  • Podzielenie cost_in_nano_usd przez miliard daje koszt w dolarach