Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Schémata JSON a validace

Lekce 2 z 20 Vývojář
Na této stránce
  1. Schémata JSON a validace
  2. Struktura schématu funkce
  3. Přísný režim (Strict Mode)
  4. Validace na straně klienta
  5. Efektivní popisy
  6. Vnořená schémata a reference
  7. Klíčové poznatky

Schémata JSON a validace

Schéma funkce není jen technická záležitost pro validaci: je to jediná smlouva mezi modelem a tvým kódem. Neexistuje žádný jiný kanál komunikace. Model nečte tvou implementaci, nezná tvé interní konvence a nebude hádat, že pole date očekává formát ISO místo francouzského formátu.

Vše, co není zapsáno ve schématu, nechává model na jeho náhodných odvozováních. To vysvětluje nerovnováhu v úsilí doporučenou v této lekci: je lepší strávit deset minut tvorbou schématu než dvě hodiny laděním erratických argumentů.

Struktura schématu funkce

Každá funkce deklarovaná v tools následuje formát JSON Schema. Zde je úplná struktura:

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
}

Přísný režim (Strict Mode)

Přísný režim mění pravděpodobnost v záruku. Bez něj model obvykle generuje vyhovující argumenty – a ty zjistíš výjimky až v produkci u hraničních případů. S ním je soulad zajištěn již při dekódování. Povol jej ve výchozím nastavení: omezení, která ukládá (podrobně popsána níže), jsou malou cenou za odstranění celé třídy chyb.

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
}]

Omezení přísného režimu

V přísném režimu platí určitá pravidla:

  • Všechna pole musí být v required
  • additionalProperties musí být false
  • Volitelné typy používají anyOf s null
  • Žádné pattern, minLength, maxLength na nejvyšší úrovni
# Volitelné pole v přísném režimu
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Validace na straně klienta

Přísný režim zaručuje formu, nikdy však význam. Správně formátované datum může být v minulosti, správně typovaný identifikátor nemusí odpovídat žádnému zákazníkovi a platná částka může překročit povolený limit. Tato pravidla jsou součástí obchodní logiky: žádné JSON schema je nevyjádří a musíš je ověřit ve svém kódu – v případě zamítnutí odešli modelu zpět chybovou zprávu vysvětlující, co se pokazilo.

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}"})

    # Obchodní logika po validaci
    return creer_facture(**args)

Efektivní popisy

Piš popis funkce jako instrukce pro nového kolegu: kdy ji volat, a především kdy ji nevolat. Právě tuto druhou část systematicky zapomínáme, přestože řeší většinu chybných volání – „nepoužívat pro archivované objednávky“ zabrání zbytečnému round-tripu, který by tři věty pozitivního popisu nezastavily.

# Špatně: příliš vágní
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Dobře: specifické a kontextuální
{
    "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."
}

Popisy parametrů

Na úrovni parametrů je nepřítelem implicitnost. Jednotka (eura nebo centy?), formát (ISO nebo lokální?), konvence (interní ID nebo reference zákazníka?), které nejsou zapsány, budou odhadnuty – někdy správně, někdy ne, bez jakéhokoli signálu. enum je zde tvým nejlepším nástrojem: nepopisuje očekávanou hodnotu, ale omezuje ji.

"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."
    }
}

Vnořená schémata a reference

Hluboce vnořené schéma je těžké znovu číst pro tebe a správně vyplnit pro model. Pokud dosáhneš tří úrovní, otázka nezní, jak to lépe napsat, ale zda funkce nedělá příliš mnoho: dvě funkce s jasným rozsahem jsou téměř vždy lepší než jedna konfigurovatelná funkce pokrývající oba případy.

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
}]

Klíčové poznatky

  • Povol strict: true pro zaručení souladu argumentů
  • Stále validuj na straně klienta pomocí jsonschema pro obchodní pravidla
  • Piš přesné popisy: jsou hlavním pákou kvality
  • Používej enum k omezení přijímaných hodnot
  • Rozděl složité schémata na znovu použitelné podstruktury