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

Definice funkcí pomocí JSON Schema

Lekce 3 z 14 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Smlouva mezi tvým kódem a modelem
  2. Anatomie specifikace nástroje
  3. Podporované typy JSON Schema
  4. Kompletní příklad: dvě doplňkové funkce
  5. Povinné versus volitelné parametry
  6. Osvědčené postupy pro popisy
  7. Klíčové poznatky

Smlouva mezi tvým kódem a modelem

Aby model Mistral mohl volat tvé funkce, musí vědět, co existuje a jak to použít. To je role JSON Schema: standardizovaný formát, který popisuje každou funkci – její název, co dělá, jaké parametry očekává a které z nich jsou povinné.

Měj během celé této lekce na paměti jednu věc: model nikdy nevidí tvůj Python kód. Vidí pouze tuto specifikaci. Pokud tvoje funkce elegantně zpracovává ID v malých písmenech, ale schema to neříká, model tuto schopnost ignoruje. Čím přesnější a lépe zdokumentované je tvé schema, tím přesnější budou generované argumenty.

Anatomie specifikace nástroje

Každý nástroj odeslaný do API Mistral následuje stejnou strukturu:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Clear description of what the function does",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    }
}
PoleRole
typeVždy "function" (v budoucnu mohou existovat jiné typy)
function.namePřesný název tvé Python funkce – to je hodnota, kterou model vrací v tool_calls
function.descriptionJasná věta, která pomáhá modelu vybrat správnou funkci
function.parametersObjekt JSON Schema popisující očekávané parametry
requiredSeznam povinných parametrů

Podporované typy JSON Schema

Slovník typů dostupných pro popis parametrů je záměrně omezený a každý typ model jinak navádí. enum zejména dělá více než jen dokumentaci: zavírá dveře vymyšleným hodnotám.

# String — volný text nebo omezený
{"type": "string", "description": "ID transakce"}

# String s enum — omezené hodnoty
{"type": "string", "enum": ["asc", "desc"], "description": "Pořadí řazení"}

# Integer — celé číslo
{"type": "integer", "description": "Počet výsledků k vrácení"}

# Number — desetinné číslo
{"type": "number", "description": "Částka v eurech"}

# Boolean — true/false
{"type": "boolean", "description": "Zahrnout zrušené transakce"}

# Array — seznam hodnot
{
    "type": "array",
    "items": {"type": "string"},
    "description": "Seznam ID transakcí"
}

# Object — vnořený objekt
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Adresa pro doručení"
}

Jasně rozlišuj mezi integer a number: částka v eurech jako 125,50 vyžaduje number, zatímco počet výsledků k vrácení je integer. Deklarace částky jako integer způsobí, že ji model zaokrouhlí.

Kompletní příklad: dvě doplňkové funkce

Zde je realistický příklad se dvěma funkcemi souvisejícími s platbami, inspirovaný oficiální dokumentací Mistral:

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment (paid, pending, failed) "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date when a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Obě funkce očekávají přesně stejný parametr, transaction_id, přesto se mezi nimi musí model rozhodnout. Toto rozhodnutí závisí výhradně na popisu funkce. „Prošla tato platba?“ odpovídá retrieve_payment_status; „Kdy byla provedena?“ odpovídá retrieve_payment_date. Kdybys napsal dva vágní, zaměnitelné popisy, model by se v polovině případů spletl – a ty bys vinil model, zatímco chyba leží ve schématu.

Povinné versus volitelné parametry

Rozdíl mezi povinnými a volitelnými parametry určuje, co smí model vynechat.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Searches for transactions based on various criteria",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Filter by payment status"
                },
                "date_from": {
                    "type": "string",
                    "description": "Start date in YYYY-MM-DD format"
                },
                "date_to": {
                    "type": "string",
                    "description": "End date in YYYY-MM-DD format"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimum amount in euros"
                }
            },
            "required": ["status"]
        }
    }
}

Zde je povinný pouze status; ostatní parametry jsou zahrnuty pouze tehdy, pokud je uživatel zmíní. Porovnej dvě formulace. Pro „Ukaž mi neúspěšné platby“ model vygeneruje jednoduše {"status": "failed"}. Pro „Ukaž mi neúspěšné platby od března 2026“ sám přidá date_from a date_to. Kdyby byly tyto data povinná, první dotaz by selhal, nebo hůře, model by byl nucen vymyslet si rozsah dat.

Osvědčené postupy pro popisy

Kvalita popisů přímo ovlivňuje přesnost modelu. Níže uvedené protipříklady jsou poučnější než jakékoli abstraktní pravidlo.

# Špatně — příliš vágní
{"description": "Načítá data"}

# Dobře — přesné a kontextové
{"description": "Načítá stav platby (zaplaceno, čekající, neúspěšné) "
                "na základě unikátního ID transakce"}

# Špatně — žádný popis pro parametr
{"transaction_id": {"type": "string"}}

# Dobře — popis s příkladem
{"transaction_id": {
    "type": "string",
    "description": "Unikátní ID transakce (formát: T následované 4 číslicemi, např. T1001)"
}}

Dobrý popis v jedné větě uvádí, co funkce dělá, specifikuje očekávaný formát pro každý parametr a poskytuje příklad vždy, když není tento formát zřejmý – T1001 je lepší než „ID transakce“. Když jsou možné hodnoty omezené, nepopisuj je slovně: deklaruj je pomocí enum. To je jediný způsob, jak je učinit závaznými.

Klíčové poznatky

  • JSON Schema je smlouvou mezi tvým kódem a modelem – popisuje tvé funkce, aniž by odhalovalo kód
  • Každý nástroj má name, description a typované parameters
  • Mezi podporované typy patří string, integer, number, boolean, array a object
  • Seznam required rozlišuje povinné parametry od volitelných
  • Přesné popisy s příklady významně zlepšují přesnost modelu