Definovanie funkcií pomocou JSON Schema
Na tejto strane
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 |
|---|---|
type | Vždy "function" (iné typy môžu existovať v budúcnosti) |
function.name | Presný názov tvojej Python funkcie – toto model vráti v tool_calls |
function.description | Jasná veta, ktorá pomáha modelu vybrať správnu funkciu |
function.parameters | Objekt JSON Schema opisujúci očakávané parametre |
required | Zoznam 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,descriptiona typovanéparameters - Medzi podporované typy patria
string,integer,number,boolean,arrayaobject - Zoznam
requiredodlišuje povinné parametre od voliteľných - Presné popisy s príkladmi výrazne zlepšujú presnosť modelu