AI Prompt Engineering · Урок

JSON Schema в подсказках

Ограничение структуры вывода

«JSON Schema в подсказках» — бесплатный урок AI Prompt Engineering на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Prompt Engineering, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Prompt Engineering содержит 4 уроков всего.

Схема как контракт вывода

Схема JSON декларативно описывает форму корректного вывода: типы, обязательные ключи, ограничения значений и вложенность. При передаче в API структурированного вывода она становится жёстким контрактом, а при встраивании в запрос — строгой рекомендацией.

Умение создавать схемы — основной навык структурированной генерации.

Строгий флаг меняет всё

В строгом режиме поставщики требуют, чтобы каждое свойство было перечислено в required, а additionalProperties имело значение false. Необязательные поля задаются как объединение с null, а не пропускаются.

{
  'type': 'object',
  'properties': {
    'name': {'type': 'string'},
    'nickname': {'type': ['string', 'null']}
  },
  'required': ['name', 'nickname'],
  'additionalProperties': False
}

Ограничение скалярных значений

Переносите проверку в схему вместо постобработки:

enum — для фиксированного набора вариантов.
minimum/maximum — для числовых диапазонов.
pattern — для строк, проверяемых регулярным выражением.
format — для подсказок о формате, например date-time или email.

{
  'rating': {'type': 'integer', 'minimum': 1, 'maximum': 5},
  'sku': {'type': 'string', 'pattern': '^[A-Z]{3}-[0-9]{4}$'},
  'created': {'type': 'string', 'format': 'date-time'}
}

Массивы и кортежи

Используйте items для однородных массивов и добавляйте minItems/maxItems, чтобы ограничить длину. Для позиционных кортежей передавайте массив схем с помощью prefixItems.

{
  'tags': {
    'type': 'array',
    'items': {'type': 'string'},
    'minItems': 1,
    'maxItems': 5
  }
}

Дискриминируемые объединения с oneOf

Моделируйте полиморфные результаты с помощью oneOf и поля-дискриминатора. Модель выбирает ровно одну ветвь, а ваш десериализатор переключается по метке.

{
  'oneOf': [
    {'type': 'object', 'properties': {
        'kind': {'const': 'email'},
        'address': {'type': 'string', 'format': 'email'}},
     'required': ['kind', 'address']},
    {'type': 'object', 'properties': {
        'kind': {'const': 'phone'},
        'number': {'type': 'string'}},
     'required': ['kind', 'number']}
  ]
}

Создание схем из типов

Ручное написание схем чревато ошибками. Выводите их из типизированных моделей, чтобы схема и ваш код никогда не расходились.

from pydantic import BaseModel

class Invoice(BaseModel):
    total: float
    currency: str
    paid: bool

schema = Invoice.model_json_schema()
# pass schema directly to response_format

Описания тоже являются подсказками

Модель читает каждое поле description в схеме. Используйте их, чтобы направлять смысл, а не просто документировать поля.

Например, описание вроде «код страны ISO-3166 alpha-2, прописными буквами» заметно повышает точность заполнения поля. Рассматривайте описания как микроинструкции, встроенные в контракт.

{
  'country': {
    'type': 'string',
    'description': 'ISO-3166 alpha-2 code, uppercase, e.g. US, TR, DE'
  }
}

Встраивание схемы в запрос

Если у поставщика нет встроенной поддержки, вставьте схему в запрос и потребуйте соответствия ей. Добавьте один пример в контексте и явную инструкцию «только JSON, без прозы».

SYSTEM = (
  'You output ONLY JSON matching this schema. No markdown, no commentary.\n'
  'Schema:\n' + json.dumps(schema) + '\n'
  'If a value is unknown, use null.'
)

Как избежать разрастания схемы

Слишком глубокие схемы или схемы с большим количеством ветвей сбивают модель с толку и увеличивают стоимость токенов. Рекомендации:

Делайте вложенность неглубокой; по возможности упрощайте структуру.
Предпочитайте перечисления свободным строкам.
Разделяйте огромную схему на несколько целенаправленных вызовов.
Некоторые поставщики ограничивают глубину вложенности и общее число свойств; проверяйте эти ограничения.

Ссылки и повторное использование

Используйте $defs и $ref для повторного использования подсхем (например, Address, применяемого для выставления счёта и доставки). Учтите, что некоторые строгие режимы ограничивают глубину рекурсии, поэтому перед использованием самоссылочных ссылок проверьте поддержку.

{
  '$defs': {
    'Address': {'type': 'object', 'properties': {
        'city': {'type': 'string'}}, 'required': ['city'],
      'additionalProperties': False}
  },
  'type': 'object',
  'properties': {
    'billing': {'$ref': '#/$defs/Address'},
    'shipping': {'$ref': '#/$defs/Address'}
  },
  'required': ['billing', 'shipping'],
  'additionalProperties': False
}

Проверяйте саму схему

Существует незаметный класс ошибок: некорректна схема, а не вывод. Проверяйте схемы с помощью линтера и валидатора в CI на соответствие метасхеме JSON Schema, а перед выпуском прогоняйте пример объекта через средство проверки туда и обратно.

import jsonschema
jsonschema.Draft202012Validator.check_schema(schema)
# also: validate a known-good sample
jsonschema.validate(sample_obj, schema)

Быстрая проверка

Как правильно выразить необязательное поле в строгом режиме схемы JSON у поставщика?

Итоги

Теперь вы умеете создавать точные схемы:

строгий режим требует сделать все поля обязательными и отключить additionalProperties.
Ограничивайте скалярные значения с помощью перечислений, диапазонов, шаблонов и форматов.
Моделируйте полиморфизм с помощью дискриминаторов oneOf.
Создавайте схемы из типизированных моделей и рассматривайте описания как микроинструкции.
Проверяйте саму схему в CI.

Далее: применение схем к вызову инструментов и функций.

Часто задаваемые вопросы

Урок «JSON Schema в подсказках» бесплатный?

Да — полный текст урока «JSON Schema в подсказках» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Prompt Engineering, подпишись на CoddyKit PRO. Курс AI Prompt Engineering содержит 4 уроков всего.

Чему я научусь в уроке «JSON Schema в подсказках»?

Ограничение структуры вывода Ты практикуешь AI Prompt Engineering с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать AI Prompt Engineering?

Предыдущий опыт не требуется. AI Prompt Engineering на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.

Сколько времени занимает урок «JSON Schema в подсказках»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке AI Prompt Engineering?

Да. Каждый урок AI Prompt Engineering включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к AI Prompt Engineering