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

Format odpowiedzi: id, choices i finish_reason

Lekcja 8 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Anatomia odpowiedzi Chat Completions
  2. Pełna struktura odpowiedzi
  3. Tablica choices
  4. Wartości finish_reason
  5. Obsługa różnych przypadków
  6. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 na podstawie dokumentacji API Chat Completions od xAI: dla pola finish_reason udokumentowano tylko wartości stop, length oraz, w trybie strumieniowania, end_turn lub null. Wartości tool_calls i content_filter znane ze starszej wersji nie są wymieniane, a wywołania narzędzi wykrywa się poprzez message.tool_calls. Parametr max_tokens jest przestarzały na rzecz max_completion_tokens. Źródło: Chat Completions.

Anatomia odpowiedzi Chat Completions

Każde wywołanie punktu końcowego Chat Completions zwraca obiekt JSON o ustandaryzowanej strukturze pól. Zrozumienie tej struktury jest kluczowe do poprawnego wydobywania danych, obsługi przypadków brzegowych i debugowania integracji.

id
Unikalny identyfikator
choices
Tablica odpowiedzi
usage
Liczniki tokenów
system_fingerprint
Odcisk systemu

Pełna struktura odpowiedzi

Oto przykład typowej odpowiedzi zwracanej przez API:

{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "grok-4.20-0309-reasoning",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Deep learning is a branch of machine learning..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 156,
    "total_tokens": 198
  },
  "system_fingerprint": "fp_abc123"
}

Pola najwyższego poziomu

  • id: Unikalny identyfikator uzupełnienia (format chatcmpl-...). Przydatny do śledzenia i debugowania.
  • object: Zawsze "chat.completion". Pozwala odróżnić ten typ odpowiedzi od innych punktów końcowych.
  • created: Znacznik czasu Unix momentu utworzenia odpowiedzi.
  • model: Model, który wygenerował odpowiedź. Może się nieznacznie różnić od żądanego modelu, jeśli używasz aliasu.
  • choices: Tablica zawierająca wygenerowaną odpowiedź lub odpowiedzi.
  • usage: Liczniki tokenów do celów rozliczeniowych.
  • system_fingerprint: Odcisk konfiguracji systemu użytej do generowania.

Tablica choices

Pole choices to tablica, która zazwyczaj zawiera jeden element (indeks 0). Każdy element zawiera:

  • index: Pozycja w tablicy (zaczyna się od 0)
  • message: Obiekt z polami role (zawsze "assistant") i content (wygenerowany tekst)
  • finish_reason: Powód zatrzymania generowania

Aby wydobyć tekstową odpowiedź:

# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;

Wartości finish_reason

Pole finish_reason wskazuje, dlaczego model przestał generować tekst:

stop

"finish_reason": "stop"

Model naturalnie zakończył swoją odpowiedź. Jest to najczęstszy i najbardziej pożądany przypadek: model powiedział wszystko, co miał do powiedzenia.

length

"finish_reason": "length"

Generowanie zostało przerwane, ponieważ osiągnięto limit wyjścia – max_completion_tokens, który zastępuje przestarzały już max_tokens i liczy tylko widoczną odpowiedź. Odpowiedź jest zatem ucięta: zwiększ limit lub uruchom ponownie żądanie kontynuacji.

end_turn lub null w trybie strumieniowania

W trybie strumieniowania każdy pośredni fragment („chunk“) niesie wartość "end_turn" lub null w polu finish_reason; tylko ostatni fragment wskazuje przyczynę zatrzymania.

Czego dokumentacja nie obejmuje

Dokumentacja API xAI wymienia tylko te wartości. Nie wspomina ani o content_filter, ani o wartości zwracanej podczas wywołania narzędzia: aby sprawdzić, czy model żąda użycia narzędzia, sprawdź obecność message.tool_calls, a nie wartość finish_reason.

Obsługa różnych przypadków

W środowisku produkcyjnym musisz sprawdzać finish_reason, aby dostosować swoje zachowanie:

choice = response.choices[0]

if choice.message.tool_calls:
    # Model chce wywołać jedno lub więcej narzędzi
    for tool_call in choice.message.tool_calls:
        print(f"Tool requested: {tool_call.function.name}")

elif choice.finish_reason == "length":
    # Odpowiedź ucięta: powiadom użytkownika lub kontynuuj
    print(choice.message.content)
    print("[Truncated response: increase max_completion_tokens]")

else:
    # Odpowiedź kompletna
    print(choice.message.content)

Kluczowe wnioski

  • Odpowiedź zawiera unikalne id, tablicę choices i obiekt usage
  • Wygenerowany tekst znajduje się w choices[0].message.content
  • finish_reason wskazuje przyczynę zatrzymania generowania: dokumentacja wymienia stop i length (oraz end_turn lub null w trybie strumieniowania)
  • Sprawdzaj finish_reason, aby wykryć ucięte odpowiedzi, a message.tool_calls w przypadku wywołań narzędzi
  • system_fingerprint identyfikuje konfigurację systemu użytą do generowania