Как получить строгий JSON по JSON Schema через Groq API

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

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

• Strict Mode включается strict:true в response_format.json_schema.
• В строгой схеме все поля должны быть required.
• Объекты строгой схемы требуют additionalProperties:false.
• Best-effort возвращает JSON, но не гарантирует полное соответствие схеме.

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. Сравните ответ с условием: Получен объект ровно с topic и priority; priority входит в enum, дополнительных полей и Markdown-ограды нет.
6. Проведите отрицательный тест: неподдерживаемый параметр, невалидные аргументы, испорченная строка JSONL или искусственный 429/498. Ошибка должна обрабатываться явно.
7. Затем добавьте ограниченные повторы, jitter, таймаут и метрики. Не повторяйте 400; исправляйте тело. Для 429 уважайте retry-after, для Flex отдельно обрабатывайте 498.

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

response_format={"type":"json_schema","json_schema":{"name":"ticket","strict":True,
 "schema":{"type":"object","properties":{
  "topic":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high"]}},
 "required":["topic","priority"],"additionalProperties":False}}}
r=client.chat.completions.create(model="<SUPPORTED_MODEL>",
 messages=[{"role":"user","content":"Не пришел чек после оплаты. Классифицируй заявку."}],
 response_format=response_format)
data=json.loads(r.choices[0].message.content)

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

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

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

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

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

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

Ожидаемый результат: Получен объект ровно с topic и priority; priority входит в enum, дополнительных полей и Markdown-ограды нет.

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

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

• модель поддерживает режим
• JSON декодируется
• schema проходит
• enum допустим
• бизнес-правила проверены