Перейти к основному содержимому

Структурированный вывод

Средний
What you'll learn
  • Объяснить, почему вывод с принудительной схемой превосходит промпт «попроси JSON и надейся»
  • Предоставить JSON Schema и распарсить ответ в типизированный объект (Pydantic / Zod)
  • Отличать структурированный вывод от использования инструментов по намерению, а не по механизму
  • Применять четыре совета для плотных, надёжных схем
  • Выбирать правильный инструмент по правилу одного вопроса

Когда вывод Claude поступает в другое ПО, вам нужна надёжная структура — валидный JSON, соответствующий известной форме, каждый раз. Не полагайтесь на «ответь в JSON» и надежду; используйте поддержку структурированного вывода платформы.

Этот урок проведёт вас от почему «промпт и молись» не работает к как принудительно применить схему и распарсить её в типизированный объект — а также как отличить структурированный вывод от использования инструментов, когда они выглядят одинаково. Проработайте его сверху вниз, затем проверьте себя в тесте ближе к концу.

Надёжный способ​

Предоставьте JSON Schema для вывода и позвольте API/SDK принудительно применить её, затем распарсите в типизированный объект (например, Pydantic в Python, Zod в TypeScript). Помощники парсинга SDK выдают вам типизированный результат вместо строки, которую вам пришлось бы JSON.parse и валидировать самостоятельно.

Guided walkthrough1 of 3
  1. Смоделируйте нужный вам вывод как JSON Schema — в Python через Pydantic BaseModel, в TypeScript через схему Zod.
# Conceptual shape — see the official docs for the current API surface.
from pydantic import BaseModel

class Ticket(BaseModel):
    title: str
    priority: str   # "low" | "medium" | "high"
    tags: list[str]

# Request the model to return data conforming to Ticket's JSON schema,
# then parse the response into a Ticket instance.

Хотите конкретный запрос для адаптации? Вот форма того, что вы передаёте модели — замените модель своей собственной схемой.

Запросите вывод, соответствующий схеме

Return the data conforming to this JSON Schema:

{
"title": "string",
"priority": "low | medium | high",
"tags": ["string"]
}

Do not include any prose outside the JSON.

Почему не просто попросить JSON в промпте?​

Вы можете попросить JSON в промпте, и для простых случаев это работает — но он может «уплывать»: лишняя проза, висячая запятая, отсутствующее поле. Вывод с принудительной схемой устраняет этот класс ошибок, что важно с того момента, как от него начинает зависеть нижестоящая система.

Watch out
  • JSON по промпту работает в демонстрациях и ломается в продакшене: сбой проявляется только тогда, когда нижестоящая система его парсит.
  • Три классических «уплывания», за которыми надо следить: лишняя проза вокруг JSON, висячая запятая и отсутствующее обязательное поле.

Структурированный вывод vs. использование инструментов​

Обе функции передают модели JSON Schema, поэтому они выглядят похоже — и люди выбирают не ту. Разница в намерении, а не в механизме:

Структурированный выводИспользование инструментов
Что вам нужноОкончательный ответ в фиксированной формеЧтобы модель задействовала возможность (вызвала функцию, получила данные, выполнила действие)
Кто это потребляетВаш код, напрямуюВаш код выполняет инструмент, затем возвращает результат модели
Форма ходаОдин ответ, готовоЦикл: модель спрашивает, вы выполняете, модель продолжает
Типичное применениеИзвлечение, классификация, парсингАгенты, живые запросы, побочные эффекты

Быстрое практическое правило:

Если JSON и есть конечный результат, используйте структурированный вывод. Если JSON — это модель, просящая ваш код что-то сделать, это использование инструментов. Агенты часто используют оба: инструменты — чтобы действовать, структурированный вывод — чтобы вернуть чистый окончательный результат.

Советы​

Pro tip
  • Держите схемы плотными — используйте перечисления для фиксированных вариантов; помечайте обязательные поля.
  • Описывайте поля — описания полей направляют модель как мини-промпты.
  • Всё равно валидируйте на границе — оборонительный парсинг — это дешёвая страховка.
  • Для задач извлечения структурированный вывод + ясная схема каждый раз превосходят свободную форму.
Key takeaways
  • Передавайте API/SDK JSON Schema и парсите в типизированный объект — не «промпт и молись».
  • JSON по промпту может «уплыть» (лишняя проза, висячая запятая, отсутствующее поле); принудительная схема устраняет этот класс ошибок.
  • Структурированный вывод vs. использование инструментов различаются по намерению: JSON ЕСТЬ ответ против JSON запрашивает действие.
  • Плотные схемы, описанные поля и валидация на границе делают извлечение и классификацию надёжными.

Закрепите термины​

Нажмите Enter или пробел, чтобы перевернуть карточку. Используйте стрелки влево и вправо для перехода между карточками.Показан термин.
1 / 5

Проверь себя

0/4
  1. Каков надёжный способ получить структурированный JSON от Claude?
  2. Почему запрашивать JSON в промпте рискованно, как только от него начинает зависеть нижестоящая система?
  3. Что на самом деле отличает структурированный вывод от использования инструментов?
  4. Какой совет по проектированию схем разумен?

Далее​