Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Definovanie funkcií pomocou JSON Schema

Lekcia 3 z 14 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Zmluva medzi tvojím kódom a modelom
  2. Anatómia špecifikácie nástroja
  3. Podporované typy JSON Schema
  4. Kompletný príklad: dve doplnkové funkcie
  5. Povinné versus voliteľné parametre
  6. Osvedčené postupy pre popisy
  7. Kľúčové poznatky

Zmluva medzi tvojím kódom a modelom

Aby model Mistral mohol volať tvoje funkcie, musí vedieť, čo existuje a ako to používať. To je úlohou JSON Schema: štandardizovaného formátu, ktorý opisuje každú funkciu – jej názov, čo robí, aké parametre očakáva a ktoré z nich sú povinné.

Počas tejto lekcie maj na pamäti jednu vec: model nikdy nevidí tvoj Python kód. Vidí iba túto špecifikáciu. Ak tvoja funkcia elegantne spracováva ID v malých písmenách, ale schema to nehovorí, model túto schopnosť ignoruje. Čím presnejšie a lepšie zdokumentované je tvoje schema, tým presnejšie budú vygenerované argumenty.

Anatómia špecifikácie nástroja

Každý nástroj odoslaný do API Mistral má rovnakú štruktúru:

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"]
        }
    }
}
PoleÚloha
typeVždy "function" (iné typy môžu existovať v budúcnosti)
function.namePresný názov tvojej Python funkcie – toto model vráti v tool_calls
function.descriptionJasná veta, ktorá pomáha modelu vybrať správnu funkciu
function.parametersObjekt JSON Schema opisujúci očakávané parametre
requiredZoznam povinných parametrov

Podporované typy JSON Schema

Slovná zásoba typov dostupná na opis parametrov je zámerne obmedzená a každý typ usmerňuje model inak. enum robí viac než len dokumentáciu: zatvára dvere vymysleným hodnotám.

# String — voľný text alebo obmedzený
{"type": "string", "description": "Transaction ID"}

# String s enum — obmedzené hodnoty
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — celé číslo
{"type": "integer", "description": "Number of results to return"}

# Number — desatinné číslo
{"type": "number", "description": "Amount in euros"}

# Boolean — true/false
{"type": "boolean", "description": "Include canceled transactions"}

# Array — zoznam hodnôt
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

# Object — vnorený objekt
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Shipping address"
}

Jasne rozlišuj medzi integer a number: suma v eurách, ako 125,50, vyžaduje number, zatiaľ čo počet výsledkov na vrátenie je integer. Deklarovanie sumy ako integer spôsobí, že ju model zaokrúhli.

Kompletný príklad: dve doplnkové funkcie

Tu je realistický príklad s dvoma funkciami týkajúcimi sa platieb, inšpirovaný oficiálnou dokumentáciou 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"]
            }
        }
    }
]

Obe funkcie očakávajú presne ten istý parameter, transaction_id, no model si musí medzi nimi vybrať. Táto voľba závisí výlučne od popisu funkcie. „Prebehla táto platba?“ sa mapuje na retrieve_payment_status; „Kedy sa uskutočnila?“ sa mapuje na retrieve_payment_date. Ak by si napísal dva vágne, zameniteľné popisy, model by sa polovicu času pomýlil – a obviňoval by si model, hoci chyba leží v schéme.

Povinné versus voliteľné parametre

Rozdiel medzi povinnými a voliteľnými parametrami určuje, čo môže model vynechať.

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

Tu je povinný iba status; ostatné parametre sú zahrnuté len vtedy, ak ich používateľ spomenie. Porovnaj dve formulácie. Pre „Ukáž mi neúspešné platby“ model vygeneruje jednoducho {"status": "failed"}. Pre „Ukáž mi neúspešné platby od marca 2026“ sám pridá date_from a date_to. Keby boli tieto dátumy povinné, prvý dotaz by zlyhal, alebo čo horšie, model by bol nútený vymyslieť si časové rozmedzie.

Osvedčené postupy pre popisy

Kvalita popisov priamo ovplyvňuje presnosť modelu. Nižšie uvedené protipríklady sú poučnejšie než akékoľvek abstraktné pravidlá.

# Zlé — príliš vágne
{"description": "Retrieves data"}

# Dobré — presné a kontextové
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Zlé — žiadny popis pre parameter
{"transaction_id": {"type": "string"}}

# Dobré — popis s príkladom
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Dobrý popis jednou vetou uvádza, čo funkcia robí, špecifikuje očakávaný formát pre každý parameter a poskytuje príklad vždy, keď nie je formát zrejmý – T1001 je lepšie než „ID transakcie“. Keď sú možné hodnoty obmedzené, nepopisuj ich prózou: deklaruj ich pomocou enum. Je to jediný spôsob, ako ich urobiť záväznými.

Kľúčové poznatky

  • JSON Schema je zmluvou medzi tvojím kódom a modelom – opisuje tvoje funkcie bez odhaľovania kódu
  • Každý nástroj má name, description a typované parameters
  • Medzi podporované typy patria string, integer, number, boolean, array a object
  • Zoznam required odlišuje povinné parametre od voliteľných
  • Presné popisy s príkladmi výrazne zlepšujú presnosť modelu