Управление уровнем усилий модели рассуждения (Chat Completions)

Описание интерфейса

На основе заданного промпта (подсказки) модель возвращает один или несколько предсказанных вариантов ответа (поддерживается управление уровнем усилий/глубиной размышлений модели).

• Официальная документация: OpenAI Reasoning Guides
• Статус API: Опубликовано (released)

Спецификация запроса

• Метод запроса: POST
• URL запроса: https://api.codingplanx.ai/v1/chat/completions

Заголовки запроса (Headers)

Параметры тела запроса (Body)

Формат данных: application/json

Пример запроса

{
  "model": "o4-mini",
  "max_tokens": 500,
  "messages": [
    {
      "role": "user",
      "content": "Здравствуйте, пожалуйста, подробно объясните принципы квантовых вычислений."
    }
  ],
  "temperature": 1.0,
  "stream": false,
  "reasoning_effort": "medium"
}

---

Спецификация ответа

Параметры тела ответа

Формат данных: application/json

Пример ответа (HTTP 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

FAQs (Часто задаваемые вопросы)

1. Какова роль параметра reasoning_effort?

Параметр reasoning_effort используется для управления тем, сколько вычислительных ресурсов и времени модели с продвинутыми способностями к рассуждению (например, серии o1/o4 от OpenAI) тратят на внутреннее "обдумывание" перед выдачей окончательного ответа. Обычно поддерживаются три уровня: low (низкий), medium (средний) и high (высокий). При значении high модель проводит более глубокие логические выводы, что отлично подходит для решения сложных математических задач или программирования; однако время ожидания ответа при этом также увеличивается.

2. Почему при включении stream: true я не получаю стандартный JSON-ответ?

Когда включена потоковая передача (stream: true), API использует протокол Server-Sent Events (SSE) для непрерывного возврата фрагментов данных (Chunks). Каждый фрагмент отправляется в формате data: {...}, а когда передача всего содержимого завершена, отправляется сообщение data: [DONE]. Разработчикам необходимо построчно считывать и парсить JSON-строки, идущие после data:, чтобы склеить полный ответ.

3. В документации сказано, что рекомендуется изменять либо temperature, либо top_p. Почему?

Оба этих параметра используются для контроля случайности и разнообразия генерируемого моделью контента. temperature изменяет распределение вероятностей путем масштабирования логитов (logits), в то время как top_p (сэмплирование ядра) ограничивает пул кандидатов путем усечения слов с низкой совокупной вероятностью. Одновременная настройка обоих параметров делает поведение модели труднопредсказуемым и сложным для управления. Поэтому лучшая практика — зафиксировать один из них (обычно оставить по умолчанию) и настраивать только другой для удовлетворения требований к "случайности" вывода.

4. Что означает, если finish_reason возвращает "length"?

Это означает, что ответ модели был принудительно обрезан. Обычно на это есть две причины: первая — количество сгенерированных токенов достигло лимита, установленного в параметре max_tokens вашего запроса; вторая — ваш промпт (входной запрос) плюс сгенерированный моделью ответ в сумме превысили максимально допустимое контекстное окно для данной модели. В таком случае рекомендуется сократить историю диалога или увеличить параметр max_tokens.

5. Как принудительно заставить модель возвращать данные в формате JSON?

Вы можете включить режим JSON, передав в теле запроса "response_format": {"type": "json_object"}. Очень важно: при включении этого режима вы должны явно потребовать в messages (обычно в system или user промпте) вывод в формате JSON на естественном языке. В противном случае модель может попасть в бесконечный цикл генерации пробелов, пока не достигнет лимита токенов.