Что такое max_tokens и что будет, если его не задать?
Разница между max_tokens, max_completion_tokens и max_output_tokens, а также настройка лимита выходных tokens. С настройкой, примерами и устранением ошибок.
Короткий ответ
max_tokens ограничивает, сколько tokens модель может сгенерировать за один ответ. В разных API и моделях отличаются названия поля, обязательность параметра и поведение по умолчанию.
Чтобы получать стабильный вывод, задавайте явный лимит для длинных ответов, генерации кода и документации. Для Claude / Anthropic-compatible API обычно нужно передавать max_tokens явно.
Базовые понятия
| Понятие | Значение |
|---|---|
| Input tokens | Ваши сообщения, контекст, содержимое файлов, результаты tools и другой ввод |
| Output tokens | Видимый ответ, который генерирует модель |
| Reasoning tokens | Скрытые tokens для внутреннего reasoning у некоторых reasoning-моделей |
| Context window | Общий лимит для ввода, вывода и части внутренних tokens |
| Output limit | Максимальный видимый вывод за один ответ |
Если output limit слишком мал, ответ может оборваться. Если лимит очень большой, модель не обязана использовать его целиком, но длинные задачи могут стоить дороже.
Разные имена параметров
| Параметр | Частый сценарий |
|---|---|
max_tokens | Claude / Anthropic Messages API и часть Chat Completions-настроек |
max_completion_tokens | Некоторые OpenAI reasoning-модели через Chat Completions |
max_output_tokens | Частое поле лимита вывода в OpenAI Responses API |
Если вы используете Codex CLI или другой инструмент на Responses API, ориентируйтесь на поле, которое сейчас поддерживает инструмент или provider. Не задавайте одно и то же имя параметра для всех моделей.
Что будет, если не задать лимит
Поведение зависит от provider и API:
| Сценарий | Возможный результат |
|---|---|
| Claude / Anthropic-compatible API | Может потребоваться явное значение max_tokens |
| OpenAI-compatible Chat Completions | Может использоваться поведение модели по умолчанию |
| OpenAI Responses API | Может использоваться max_output_tokens или дефолт инструмента |
| Другие модели | Могут иметь собственный лимит вывода по умолчанию |
Один и тот же код после смены модели может давать ответы разной длины. Для production-вызовов лучше задавать явный лимит вывода.
Рекомендуемые диапазоны
| Задача | Диапазон |
|---|---|
| Обычные вопросы | 1024 - 4096 |
| Объяснение кода / небольшие правки | 4096 - 8192 |
| Длинный текст / сложные coding-задачи | 8192 и выше, с учетом лимита модели |
| Пакетные задачи | Меньший лимит, чтобы отдельный запрос не сгенерировал слишком длинный ответ |
Фактический максимум проверяйте в model plaza и документации upstream-модели. Максимальный вывод может меняться между версиями.
Что делать, если ответ обрывается
Если в ответе есть finish_reason: "length", модель обычно достигла лимита вывода.
Проверяйте в таком порядке:
- Увеличьте поле лимита вывода, которое поддерживает текущий API.
- Проверьте, что использовали правильное имя параметра.
- Сузьте prompt, чтобы убрать лишний вывод.
- Выберите модель с большим output window.
- Разбейте длинную задачу на несколько шагов.
Частые ошибки
- Считать, что большее значение
max_tokensвсегда заставит модель писать длиннее. - Повторять запрос после обрыва и не проверять
finish_reason. - Использовать старое имя поля с reasoning-моделью.
- Не учитывать hidden reasoning tokens при оценке контекста и стоимости.
- Игнорировать собственный максимальный лимит вывода у модели.
О BetterToken
BetterToken записывает usage на уровне API Key и model request. В dashboard можно смотреть расход tokens по моделям и задачам.
Но поле лимита вывода всё равно определяется API-форматом и моделью. При настройке проверяйте модель, Base URL, API-формат и имя параметра вместе.