Structured Output

Суть в двух словах

Структурированный вывод нужен, когда ответ должен быть не просто хорошим по смыслу, но и удобным по форме:

• список;
• таблица;
• memo;
• rubric;
• JSON / schema.

Главный вопрос не "нужна ли структура вообще", а "какая именно структура нужна downstream-потребителю". В одной задаче достаточно ясного markdown-отчёта. В другой нужен ответ, который приложение сможет принять без дополнительного парсинга и ручной чистки.

Два уровня structured output

Ошибка многих команд — просить "JSON" там, где нужен просто удобный markdown-отчёт, и наоборот, просить "список" там, где downstream-сервис ждёт строгую схему.

Практически structured output решает сразу три разных задачи:

1. Делает ответ повторяемым.
2. Упрощает проверку и ревью.
3. Уменьшает хрупкость следующего шага в пайплайне.

Когда этого нет, даже сильная модель начинает "дрейфовать" по форме ответа: в одном случае даёт список, в другом добавляет вступление, в третьем смешивает вывод, caveats и next steps в одном абзаце.

Как выбирать уровень структуры

На практике между этими полюсами есть промежуточная зона. Например, продуктовый аналитик может хотеть одновременно:

• краткий readable summary для человека;
• и отдельный блок decision_payload для автоматизации.

Тогда выгоднее не пытаться "впихнуть всё в один текст", а явно просить двухслойный ответ: сначала summary, затем strict payload.

Когда structured output особенно полезен

Лучше всего техника работает там, где нужно стабилизировать "поверхность" ответа:

• классификация;
• extraction;
• оценка по рубрике;
• handoff между системами;
• генерация action items;
• подготовка аргументов для инструмента.

Слабее всего structured output помогает там, где сама задача ещё неясна. Если вы не понимаете, какие поля реально нужны, схема почти всегда будет либо слишком узкой, либо слишком шумной.

Примеры

Readable structured output

Оцени идею продукта в формате:

## Summary
## Upside
## Risks
## Next experiment

Идея: AI-ассистент для разбора входящих sales call

Structured output для automation

Верни JSON с полями: category, priority, requires_human, summary.

Обращение: «Списали оплату дважды, нужен возврат сегодня»

Смешанный формат: readable + payload

Оцени запуск новой onboarding-версии.

Верни ответ в двух частях:
1. Короткий markdown summary для product team
2. JSON payload с полями decision, confidence, main_risk, next_test

{"decision":"continue_test","confidence":"medium","main_risk":"uplift может ограничиваться первым шагом funnel","next_test":"измерить retention и trial-to-paid через 14 дней"}

Такой смешанный формат часто лучше чистого JSON, если результат одновременно нужен и человеку, и системе.

Anti-patterns

Самые частые ошибки:

1. Просить строгий JSON там, где нужен просто ясный memo.
2. Просить "список" там, где downstream ждёт строгую схему.
3. Делать схему слишком широкой и расплывчатой.
4. Не различать optional, required и nullable поля.
5. Считать, что хороший формат автоматически гарантирует хорошие факты.

Отдельная ловушка — forcing format слишком рано. На сложных reasoning-задачах иногда полезно сначала дать модели коротко подумать, а уже потом просить финальный структурированный слой. Иначе качество рассуждения падает, потому что модель всё время "смотрит на форму", а не на смысл.

Practical rule

Выбирайте формат по downstream-потребителю:

• если ответ читает человек -> markdown/memo/table;
• если ответ читает код -> schema-first JSON;
• если ответ идёт в tool invocation -> strict tool args.

Техническая реализация

Простой rubric-format

prompt = """
Оцени решение в формате:

summary: одно предложение
main_risk: одно предложение
confidence: low | medium | high
next_step: одно действие

Решение: перенести поиск с PostgreSQL на отдельный search service.
"""

Такой уровень уже полезен для:

• внутренних ассистентов;
• review workflows;
• аналитических резюме;
• простых LLM judge-задач.

Когда переходить к schema-based output

def needs_schema(output_consumer: str) -> bool:
    return output_consumer in {"api", "workflow", "db-write", "tool-call"}

Если результат дальше парсится кодом, почти всегда выгоднее сразу использовать schema constraints, а не надеяться на "примерно такой же текст, как в прошлый раз".

Хороший contract для production

OUTPUT_CONTRACT = {
    "summary": "one short sentence",
    "decision": ["ship", "iterate", "reject"],
    "confidence": ["low", "medium", "high"],
    "main_risk": "string",
    "next_step": "string"
}

Даже если провайдер поддерживает strict schema, проекту обычно нужны ещё два слоя:

• app-side validation;
• semantic validation.

App-side validation

def validate_decision_payload(data: dict) -> dict:
    allowed_decisions = {"ship", "iterate", "reject"}
    allowed_confidence = {"low", "medium", "high"}

    if data["decision"] not in allowed_decisions:
        raise ValueError("invalid decision")
    if data["confidence"] not in allowed_confidence:
        raise ValueError("invalid confidence")
    if not data["summary"].strip():
        raise ValueError("empty summary")

    return data

Это важно, потому что даже при строгой схеме модель может вернуть формально валидный, но семантически бесполезный объект.

Когда structured output не надо переусложнять

Не переходите к schema-first без необходимости, если:

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

В таких случаях хороший markdown с фиксированными секциями чаще даёт лучший tradeoff, чем жёсткая схема.