Funkciók definiálása JSON Schema segítségével
Ezen az oldalon
A szerződés a kódod és a modell között
Ahhoz, hogy a Mistral modell meghívja a függvényeidet, tudnia kell, mi létezik és hogyan kell használni őket. Ezt a szerepet tölti be a JSON Schema: ez egy szabványosított formátum, amely leírja az egyes függvényeket – a nevüket, funkciójukat, a várt paramétereket és azt, hogy melyek kötelezőek.
Egész lesson során tartsd észben: a modell sosem látja a Python kódodat. Csak ezt a specifikációt látja. Ha a függvényed kezeli a kisbetűs azonosítókat, de a schema nem említi ezt, a modell figyelmen kívül hagyja ezt a képességet. Minél pontosabb és jobban dokumentált a schemad, annál pontosabbak lesznek a generált argumentumok.
Egy eszközspecifikáció felépítése
Minden, a Mistral API-nak küldött eszköz ugyanazt a szerkezetet követi:
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"]
}
}
}
| Mező | Szerep |
|---|---|
type | Mindig "function" (a jövőben más típusok is létezhetnek) |
function.name | A Python függvényed pontos neve – ezt adja vissza a modell a tool_calls objektumban |
function.description | Egy világos mondat, amely segít a modellnek kiválasztani a megfelelő függvényt |
function.parameters | Egy JSON Schema objektum, amely leírja a várt paramétereket |
required | A kötelező paraméterek listája |
Támogatott JSON Schema típusok
A paraméterek leírására rendelkezésre álló típuskészlet szándékosan korlátozott, és minden típus másképp irányítja a modellt. Az enum például többet tesz, mint csupán dokumentál: lezárja az utat a kitalált értékek előtt.
# String — szabad szöveg vagy korlátozott
{"type": "string", "description": "Tranzakció azonosító"}
# String enummal — korlátozott értékek
{"type": "string", "enum": ["asc", "desc"], "description": "Rendezési sorrend"}
# Integer — egész szám
{"type": "integer", "description": "Visszaadandó találatok száma"}
# Number — tizedes szám
{"type": "number", "description": "Összeg euróban"}
# Boolean — igaz/hamis
{"type": "boolean", "description": "Törölt tranzakciók 포함ezése"}
# Array — értékek listája
{
"type": "array",
"items": {"type": "string"},
"description": "Tranzakció azonosítók listája"
}
# Object — beágyazott objektum
{
"type": "object",
"properties": {
"city": {"type": "string"},
"country": {"type": "string"}
},
"description": "Szállítási cím"
}
Tegyél éles különbséget az integer és a number között: egy 125,50 eurós összeghez number típus szükséges, míg a visszaadandó találatok száma integer. Ha az összeget integer-ként deklarálod, a modell lekerekíti azt.
Teljes példa: két kiegészítő függvény
Íme egy valós példa két, fizetésekkel kapcsolatos függvénnyel, amely a hivatalos Mistral dokumentáción alapul:
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"]
}
}
}
]
Mindkét függvény pontosan ugyanazt a paramétert várja, a transaction_id-t, mégis a modellnek választania kell közöttük. Ez a választás kizárólag a függvény leírásán múlik. A „Meg történt ez a fizetés?“ kérdés a retrieve_payment_status függvényhez vezet, míg a „Mikor történt?“ a retrieve_payment_date-hez. Ha két homályos, felcserélhető leírást írtál volna, a modell az esetek felében hibázna – és te a modellt hibáztatnád, pedig a hiba a schemában rejlik.
Kötelező és opcionális paraméterek
A kötelező és opcionális paraméterek közötti különbség határozza meg, hogy mit hagyhat ki a modell.
{
"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": "Szűrés fizetési státusz szerint"
},
"date_from": {
"type": "string",
"description": "Kezdő dátum ÉÉÉÉ-HH-NN formátumban"
},
"date_to": {
"type": "string",
"description": "Záró dátum ÉÉÉÉ-HH-NN formátumban"
},
"min_amount": {
"type": "number",
"description": "Minimális összeg euróban"
}
},
"required": ["status"]
}
}
}
Itt csak a status kötelező; a többi paraméter csak akkor kerül bele, ha a felhasználó említi őket. Hasonlítsd össze a két megfogalmazást. A „Mutasd a sikertelen fizetéseket“ kérésre a modell egyszerűen ezt generálja: {"status": "failed"}. A „Mutasd a 2026 márciusi sikertelen fizetéseket“ kérésre viszont saját maga hozzáadja a date_from és date_to értékeket. Ha ezeket a dátumokat kötelezővé tetted volna, az tönkretette volna az első lekérdezést, vagy ami rosszabb, rákényszerítette volna a modellt, hogy kitaláljon egy dátumtartományt.
Legjobb gyakorlatok a leírásokhoz
A leírások minősége közvetlenül befolyásolja a modell pontosságát. Az alábbi ellenpéldák tanulságosabbak, mint bármilyen elvont szabály.
# Rossz — túl homályos
{"description": "Adatok lekérése"}
# Jó — pontos és kontextusba helyezett
{"description": "Egy fizetés státuszának (fizetve, függőben, sikertelen) lekérése "
"a egyedi tranzakció azonosító alapján"}
# Rossz — nincs leírás a paraméterhez
{"transaction_id": {"type": "string"}}
# Jó — leírás példával
{"transaction_id": {
"type": "string",
"description": "Egyedi tranzakció azonosító (formátum: T betűt követően 4 számjegy, pl. T1001)"
}}
Egy jó leírás egy mondatban közli, mit csinál a függvény, meghatározza az egyes paraméterek várt formátumát, és példát is hoz, amikor a formátum nem egyértelmű – a T1001 jobb, mint pusztán a „tranzakció azonosító“. Ha a lehetséges értékek korlátozottak, ne írd le őket szövegesen: deklaráljd őket enum segítségével. Ez az egyetlen módja annak, hogy kötelező érvényűvé tedd őket.
Főbb megállapítások
- A JSON Schema a szerződés a kódod és a modell között – leírja a függvényeidet anélkül, hogy felfedné a kódot
- Minden eszköz rendelkezik egy
name, egydescriptionés típusozottparametersmezővel - A támogatott típusok közé tartozik a
string,integer,number,boolean,arrayésobject - A
requiredlista választja el a kötelező paramétereket az opcionálisaktól - A példákkal kiegészített pontos leírások jelentősen javítják a modell pontosságát