Премини към основното съдържание
Български— Изберете език
Меню

JSON схеми и валидация

Урок 2 от 20 Програмист
На тази страница
  1. JSON схеми и валидация
  2. Структура на схемата на функцията
  3. Строг режим (Strict Mode)
  4. Валидация на страната на клиента
  5. Ефективни описания
  6. Вложени схеми и референции
  7. Ключови изводи

JSON схеми и валидация

Схемата на функцията не е просто техническа подробност за валидация: тя е единственият договор между модела и Вашия код. Няма друг канал за комуникация. Моделът не чете Вашата имплементация, не познава Вашите вътрешни конвенции и няма да предположи, че полето date очаква ISO формат вместо френски такъв.

Всичко, което не е записано в схемата, ще бъде решено чрез случайни изводи на модела. Това обяснява дисбаланса в усилията, препоръчан в този урок: по-добре е да отделите десет минути за схема, отколкото два часа за дебъгване на erratic аргументи.

Структура на схемата на функцията

Всяка функция, декларирана в tools, следва формата на JSON Schema. Ето пълната структура:

tool_definition = {
    "type": "function",
    "name": "creer_facture",
    "description": "Create an invoice for an existing customer",
    "parameters": {
        "type": "object",
        "properties": {
            "client_id": {
                "type": "string",
                "description": "Unique customer identifier (format: CLI-XXXXX)"
            },
            "lignes": {
                "type": "array",
                "description": "List of billing line items",
                "items": {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string",
                            "description": "Product or service description"
                        },
                        "quantite": {
                            "type": "integer",
                            "minimum": 1,
                            "description": "Number of units"
                        },
                        "prix_unitaire": {
                            "type": "number",
                            "minimum": 0,
                            "description": "Unit price excluding tax in euros"
                        }
                    },
                    "required": ["description", "quantite", "prix_unitaire"]
                }
            },
            "devise": {
                "type": "string",
                "enum": ["EUR", "USD", "GBP"],
                "default": "EUR"
            },
            "echeance_jours": {
                "type": "integer",
                "enum": [30, 45, 60, 90],
                "description": "Payment deadline in days"
            }
        },
        "required": ["client_id", "lignes"],
        "additionalProperties": False
    },
    "strict": True
}

Строг режим (Strict Mode)

Строгият режим превръща вероятността в гаранция. Без него моделът обикновено генерира съвместими аргументи – и Вие откривате изключенията в продукцията, при гранични случаи. С него съвместимостта е осигурена по конструкция на ниво декодиране. Активирайте го по подразбиране: ограниченията, които той налага и които са описани подробно по-долу, са малка цена за елиминирането на цял клас бъгове.

tools = [{
    "type": "function",
    "name": "enregistrer_commande",
    "description": "Record a new order",
    "parameters": {
        "type": "object",
        "properties": {
            "produit": {"type": "string"},
            "quantite": {"type": "integer"},
            "urgent": {"type": "boolean"}
        },
        "required": ["produit", "quantite", "urgent"],
        "additionalProperties": False
    },
    "strict": True
}]

Ограничения на строгия режим

В строг режим важат определени правила:

  • Всички полета трябва да бъдат в required
  • additionalProperties трябва да бъде false
  • Незадължителните типове използват anyOf с null
  • Няма pattern, minLength, maxLength на най-високо ниво
# Незадължително поле в строг режим
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Валидация на страната на клиента

Строгият режим гарантира формата, но никога смисъла. Една добре форматирана дата може да е в миналото, добре типизиран идентификатор може да не съответства на никакъв клиент, а валидна сума може да надвишава разрешен лимит. Тези правила са бизнес логика: никоя JSON схема не ги изразява и те трябва да бъдат проверени във Вашия код – като в случай на отхвърляне се изпрати съобщение за грешка обратно към модела, обясняващо какво се е объркало.

import json
from jsonschema import validate, ValidationError

SCHEMA_FACTURE = {
    "type": "object",
    "properties": {
        "client_id": {"type": "string", "pattern": "^CLI-[0-9]{5}$"},
        "lignes": {
            "type": "array",
            "minItems": 1,
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string", "minLength": 1},
                    "quantite": {"type": "integer", "minimum": 1},
                    "prix_unitaire": {"type": "number", "minimum": 0}
                },
                "required": ["description", "quantite", "prix_unitaire"]
            }
        }
    },
    "required": ["client_id", "lignes"]
}

def executer_fonction(name: str, arguments: str) -> str:
    args = json.loads(arguments)

    try:
        validate(instance=args, schema=SCHEMA_FACTURE)
    except ValidationError as e:
        return json.dumps({"error": f"Invalid arguments: {e.message}"})

    # Бизнес логика след валидация
    return creer_facture(**args)

Ефективни описания

Напишете описанието на функцията като инструкции за нов колега: кога да я извика и особено кога да не я извиква. Именно втората част систематично забравяме, въпреки че тя решава повечето грешни извиквания – „не използвайте за архивирани поръчки“ предотвратява ненужно връщане на заявката, което три изречения с позитивно описание не биха спрели.

# Лошо: твърде общо
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Добро: конкретно и контекстуално
{
    "name": "rechercher_produits_catalogue",
    "description": "Search for products in the e-commerce catalog. "
                   "Returns name, price, stock, and category. "
                   "Use for questions about availability or pricing."
}

Описания на параметрите

На ниво параметър врагът е подразбирането. Единица (евро или центове?), формат (ISO или локален?), конвенция (вътрешен ID или референция на клиент?), които не са записани, ще бъдат отгатнати – понякога правилно, понякога не, без никакъв сигнал в нито една посока. enum е Вашият най-добър инструмент тук: то не описва очакваната стойност, а я ограничава.

"properties": {
    "date_debut": {
        "type": "string",
        "description": "Start date in ISO 8601 format (YYYY-MM-DD). "
                       "Defaults to today's date if not specified."
    },
    "statut": {
        "type": "string",
        "enum": ["actif", "inactif", "suspendu"],
        "description": "Filter by account status. "
                       "'actif' = accounts in service, "
                       "'suspendu' = temporarily frozen accounts."
    }
}

Вложени схеми и референции

Дълбоко вложената схема е трудна за повторно прочитане от Вас и за правилно попълване от модела. Ако стигнете до три нива, въпросът, който трябва да си зададете, не е как да я напишете по-добре, а дали функцията не прави твърде много: две функции с ясен обхват са почти винаги за предпочитане пред една конфигурируема функция, която покрива и двата случая.

adresse_schema = {
    "type": "object",
    "properties": {
        "rue": {"type": "string"},
        "code_postal": {"type": "string"},
        "ville": {"type": "string"},
        "pays": {"type": "string", "enum": ["FR", "BE", "CH", "LU"]}
    },
    "required": ["rue", "code_postal", "ville", "pays"]
}

tools = [{
    "type": "function",
    "name": "creer_livraison",
    "description": "Create a delivery with shipping and destination addresses",
    "parameters": {
        "type": "object",
        "properties": {
            "expedition": adresse_schema,
            "destination": adresse_schema,
            "poids_kg": {"type": "number", "minimum": 0.1}
        },
        "required": ["expedition", "destination", "poids_kg"],
        "additionalProperties": False
    },
    "strict": True
}]

Ключови изводи

  • Активирайте strict: true, за да гарантирате съвместимост на аргументите
  • Все пак валидирайте на страната на клиента с jsonschema за бизнес правила
  • Пишете точни описания: те са основният лост за качество
  • Използвайте enum, за да ограничите приемливите стойности
  • Разделете сложните схеми на многократно използваеми подструктури