Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Funkciók definiálása JSON Schema segítségével

3. lecke 14 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. A szerződés a kódod és a modell között
  2. Egy eszközspecifikáció felépítése
  3. Támogatott JSON Schema típusok
  4. Teljes példa: két kiegészítő függvény
  5. Kötelező és opcionális paraméterek
  6. Legjobb gyakorlatok a leírásokhoz
  7. Főbb megállapítások

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
typeMindig "function" (a jövőben más típusok is létezhetnek)
function.nameA Python függvényed pontos neve – ezt adja vissza a modell a tool_calls objektumban
function.descriptionEgy világos mondat, amely segít a modellnek kiválasztani a megfelelő függvényt
function.parametersEgy JSON Schema objektum, amely leírja a várt paramétereket
requiredA 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, egy description és típusozott parameters mezővel
  • A támogatott típusok közé tartozik a string, integer, number, boolean, array és object
  • A required lista 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