Definice funkcí pomocí JSON Schema
Na této stránce
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"]
}
}
}
| Pole | Role |
|---|---|
type | Vždy "function" (v budoucnu mohou existovat jiné typy) |
function.name | Přesný název tvé Python funkce – to je hodnota, kterou model vrací v tool_calls |
function.description | Jasná věta, která pomáhá modelu vybrat správnou funkci |
function.parameters | Objekt JSON Schema popisující očekávané parametry |
required | Seznam 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,descriptiona typovanéparameters - Mezi podporované typy patří
string,integer,number,boolean,arrayaobject - Seznam
requiredrozlišuje povinné parametry od volitelných - Přesné popisy s příklady významně zlepšují přesnost modelu