Как настроить reasoning_format в Groq API: parsed, raw или hidden

Перед внедрением откройте страницы Models и Limits своей организации. Модельный каталог и персональные квоты меняются, поэтому статья не подменяет живую проверку. Зафиксируйте model id, версию SDK и контрольный вход в журнале теста.

Подтвержденные факты

• parsed отделяет рассуждение в message.reasoning.
• raw помещает reasoning в <think> внутри content.
• hidden возвращает только финальный ответ.
• include_reasoning и reasoning_format взаимно исключаются; raw несовместим с JSON mode и tool use.

Groq использует OpenAI-подобную структуру Chat Completions: массив messages, выбранную model, choices, finish_reason и usage. При этом совместимость не означает равенство всех параметров. Проверяйте документацию конкретной возможности и не отправляйте неизвестные поля «на всякий случай».

Пошаговая настройка

1. Сформулируйте машинный критерий: точная строка, валидная JSON Schema, допустимый tool call или определенный HTTP-код. Субъективное «ответ нормальный» не подходит.
2. Создайте отдельный ключ для dev/stage/prod и храните его как GROQ_API_KEY на backend. Не включайте Authorization в логи, браузерный bundle и репозиторий.
3. Скопируйте актуальный model id из Groq Console и проверьте поддержку нужной функции. Возможность Chat Completion не гарантирует structured output, reasoning или кэш.
4. Выполните минимальный пример ниже. На первом прогоне отключите собственные retry и middleware, чтобы увидеть исходный HTTP-код и тело ошибки.
5. Сравните ответ с условием: Пользователь получает краткий финальный вывод о снижении на 4%, без <think>; ответ проверяется независимым расчетом 1.2×0.8=0.96.
6. Проведите отрицательный тест: неподдерживаемый параметр, невалидные аргументы, испорченная строка JSONL или искусственный 429/498. Ошибка должна обрабатываться явно.
7. Затем добавьте ограниченные повторы, jitter, таймаут и метрики. Не повторяйте 400; исправляйте тело. Для 429 уважайте retry-after, для Flex отдельно обрабатывайте 498.

Рабочий пример

r=client.chat.completions.create(
 model="qwen/qwen3.8-27b", reasoning_format="hidden",
 reasoning_effort="medium",
 messages=[{"role":"user","content":"Реши: товар подорожал на 20%, затем подешевел на 20%. Как изменился итог?"}],
 max_completion_tokens=256)
assert "<think>" not in (r.choices[0].message.content or "")

Значения в угловых скобках требуют замены на идентификаторы из актуальной документации. Пример намеренно не содержит настоящего ключа. Код бизнес-функций и хранилищ также должен иметь собственную авторизацию — модель не является системой контроля доступа.

Готовый промпт для проверки

Ты инженер приемки Groq API. Проверь приложенные request и response для сценария «как настроить reasoning Groq API».
Верни таблицу: проверка | фактическое значение | PASS/FAIL | исправление.
Обязательно проверь HTTP-код, model, finish_reason, usage и условие результата.
Не восстанавливай отсутствующие поля и не считай HTTP 200 достаточным.

Перед передачей логов удалите ключ, персональные данные и лишний prompt. Решение о PASS принимает код по заданным правилам; языковая модель может только помочь найти несоответствия.

Контрольный вход и ожидаемый результат

Контрольный вход встроен в пример. Сохраните точные messages, model id и параметры. Сначала выполните пять одинаковых запросов, затем меняйте ровно один параметр. Это отделяет случайность генерации от ошибки конфигурации.

Ожидаемый результат: Пользователь получает краткий финальный вывод о снижении на 4%, без <think>; ответ проверяется независимым расчетом 1.2×0.8=0.96.

HTTP 200 подтверждает транспорт, но не формат и смысл. Проверяйте choices, finish_reason, непустой content, JSON Schema, аргументы инструментов или полноту batch-результатов. Отсутствующее поле нельзя молча заменять нулем: это скроет обрыв streaming или изменение SDK.

Критерии приемки

• модель поддержана
• параметр effort допустим
• content не пуст
• reasoning не утек
• ответ проверен