Премини към основното съдържание
Български— Изберете език
Меню

Формат на отговора: id, choices и finish_reason

Урок 8 от 12 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Анатомия на отговора от Chat Completions
  2. Пълна структура на отговора
  3. Масивът choices
  4. Стойности на finish_reason
  5. Какво не е документирано в справочника
  6. Обработка на различни случаи
  7. Ключови изводи

Обновено на 3 ноември 2026 г. въз основа на справочната документация на xAI Chat Completions API: за finish_reason са документирани само стойностите stop, length и, при стрийминг, end_turn или null. Стойностите tool_calls и content_filter от по-старата версия не са изброени, а извикванията на инструменти се откриват чрез message.tool_calls. Параметърът max_tokens е остарял в полза на max_completion_tokens. Източник: Chat Completions.

Анатомия на отговора от Chat Completions

Всяко извикване към крайната точка на Chat Completions връща JSON обект, структуриран със стандартизирани полета. Разбирането на тази структура е от съществено значение за правилното извличане на данни, обработката на специфични случаи и отстраняването на грешки във вашите интеграции.

id
Уникален идентификатор
choices
Масив с отговори
usage
Броячи на токени
system_fingerprint
Системен отпечатък

Пълна структура на отговора

Ето пример за типичен отговор, върнат от API:

{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "grok-4.20-0309-reasoning",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Дълбокото обучение е клон на машинното обучение..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 156,
    "total_tokens": 198
  },
  "system_fingerprint": "fp_abc123"
}

Полета от най-високо ниво

  • id: Уникален идентификатор за завършването (формат chatcmpl-...). Полезен е за проследяване и отстраняване на грешки.
  • object: Винаги е "chat.completion". Позволява ви да разграничите този тип отговор от други крайни точки.
  • created: Unix времеви печат (timestamp) на момента на създаване на отговора.
  • model: Моделът, генерирал отговора. Може леко да се различава от поискания модел, ако използвате псевдоним (alias).
  • choices: Масив, съдържащ генерирания отговор или отговори.
  • usage: Броячи на токени за фактуриране.
  • system_fingerprint: Отпечатък на използваната системна конфигурация.

Масивът choices

Полето choices е масив, който обикновено съдържа един единствен елемент (индекс 0). Всеки елемент съдържа:

  • index: Позиция в масива (започва от 0)
  • message: Обект с role (винаги "assistant") и content (генерираният текст)
  • finish_reason: Причината за спиране на генерирането

За да извлечете текстовия отговор:

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

Стойности на finish_reason

Полето finish_reason показва защо моделът е спрял да генерира текст:

stop

"finish_reason": "stop"

Моделът е завършил отговора си естествено. Това е най-честият и желан случай: моделът е казал всичко необходимо.

length

"finish_reason": "length"

Генерирането е спряло, защото е достигнат лимитът за изход – max_completion_tokens, който замества вече остарелия max_tokens и брои само видимия отговор. Следователно отговорът е съкратен: увеличете лимита или рестартирайте заявката за продължение.

end_turn или null при стрийминг

При стрийминг всеки междинен чанк (chunk) носи "end_turn" или null в finish_reason; само последният чанк указва причината за спиране.

Какво не е документирано в справочника

Справочната документация на xAI API описва само тези стойности. Тя не споменава нито content_filter, нито стойността, връщана по време на извикване на инструмент: за да разберете дали моделът иска инструмент, проверете наличието на message.tool_calls, а не стойността на finish_reason.

Обработка на различни случаи

В производствена среда трябва да проверявате finish_reason, за да адаптирате поведението си:

choice = response.choices[0]

if choice.message.tool_calls:
    # Моделът иска да извика един или повече инструменти
    for tool_call in choice.message.tool_calls:
        print(f"Tool requested: {tool_call.function.name}")

elif choice.finish_reason == "length":
    # Съкратен отговор: уведомете потребителя или продължете
    print(choice.message.content)
    print("[Съкратен отговор: увеличете max_completion_tokens]")

else:
    # Пълен отговор
    print(choice.message.content)

Ключови изводи

  • Отговорът съдържа уникален id, масив choices и обект usage
  • Генерираният текст се намира в choices[0].message.content
  • finish_reason показва защо генерирането е спряло: справочникът документира stop и length (както и end_turn или null при стрийминг)
  • Проверявайте finish_reason, за да откриете съкратени отговори, и message.tool_calls за извиквания на инструменти
  • system_fingerprint идентифицира системната конфигурация, използвана за генерирането