Программа курса Урок 138 из 250 · Структурированные ответы и вызов функций/инструментов
Структурированные ответы и вызов функций/инструментов

Ограниченные / Схемно-зависимые результаты

Вы проверяли JSON модели вручную в прошлых уроках. Современная практика идет на один шаг раньше: не давать модели выдавать плохой JSON изначально. Это constrained decoding (также называемое структурированными выходами). Вы передаете API схему, и декодеру разрешено выбирать только те токены, которые сохраняют валидность вывода согласно ей. Модель буквально не может выдать отсутствующее поле или значение с неправильным типом.

С OpenAI-style API вы передаете response_format с JSON Schema и strict: true (только для иллюстрации -> мы не вызываем никакую модель здесь):

resp = client.chat.completions.create(
    model="...",
    messages=[...],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                "required": ["name", "age"],
            },
        },
    },
)

Остальная часть этого курса использует Anthropic, которая предлагает ту же гарантию через output_config для гарантированных ответов в формате JSON и strict для использования инструментов с идеальными входными данными по схеме:

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[...],
    output_config={"format": {
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
            "required": ["name", "age"],
        },
    }},
)

В любом случае, ограничения накладывает провайдер. Но constrained decoding все равно не может проверять ваши бизнес правила (реалистичен ли возраст? поддерживается ли эта валюта?), и не каждая модель или шлюз поддерживает это. Поэтому вы все равно валидируете данные на своей стороне. Этот валидатор и есть то, что вы строите сейчас.

На стороне Python де-факто стандартом для объявления и проверки этой формы является Pydantic. Вы пишете класс модели, а библиотека парсит, приводит типы и проверяет данные за вас:

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

record = Person.model_validate_json(text)   # raises if it does not fit

Pydantic недоступен в этом браузере, поэтому вы построите ту же идею вручную с помощью стандартной библиотеки. Именно это делают эти библиотеки внутри, и это делает правила невозможными для игнорирования. Вы пишете validate_against_schema(obj, schema).

schema - это словарь. Каждое значение - это либо строка с именем типа ("int", "float", "str", "bool", "list", "dict"), либо небольшой словарь спецификации, например {"type": "int", "default": 0}. Ваша функция возвращает словарь результатов {"ok": bool, "value": dict, "errors": list}:

  • Если obj не является dict, верните ok=False с одной ошибкой корня и пустым value.
  • Для каждого поля: если оно missing и в спецификации есть "default", заполните значение по умолчанию (coerce/default pass). Если оно отсутствует без значения по умолчанию, запишите ошибку.
  • Если присутствует, проверьте его type. При несовпадении запишите ошибку с названием поля.
  • Coerce обычный int до float когда нужен float (это без потерь и безопасно), но не приводите к типу ничего другого.
  • Если возникли ошибки, верните ok=False с собранными errors и пустым value; иначе верните ok=True с проверенными value.

Ловушка bool-is-int. В Python bool является подклассом int, поэтому isinstance(True, int) это True и JSON true декодируется в Python True. Наивная проверка типа пропустит "age": true через поле int. Отклоняйте bool явно везде, где требуется int или float:

if expected is int and isinstance(value, bool):
    errors.append(field + ": expected int, got bool")

Соберите это так, чтобы два разных правильно сформированных payload прошли, отсутствие поля и неверный тип попадают в errors, значение по умолчанию заполняется, int преобразуется в float, а скрытый bool отклоняется там, где требуется число.

Твоя очередь

Напишите validate_against_schema(obj, schema), возвращающий {"ok", "value", "errors"}. schema сопоставляет каждое поле со строкой типа-имени ("int"/"float"/"str"/"bool"/"list"/"dict") или словарем спецификации {"type": ..., "default": ...}. Отклоняйте не словарь obj, записывайте ошибку для каждого отсутствующего (без значения по умолчанию) или неверно типизированного поля, заполняйте значение по умолчанию, если оно дано, приводите обычный int к float и отклоняйте bool, где требуется int или float (ловушка bool-is-int). Возвращайте ok=True с проверенным value только тогда, когда ошибок нет.

Заметили проблему в этом уроке? Сообщите о ней · Спросить об этом уроке

Это упражнение откроется скоро

Закончи предыдущий урок, чтобы открылся этот. Весь курс бесплатный, аккаунт не нужен, и ты можешь прочитать этот урок прямо сейчас.