Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Funktsioonide defineerimine JSON Schema abil

Õppetund 3 / 14 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Leping sinu koodi ja mudeli vahel
  2. Tööriista spetsifikatsiooni anatoomia
  3. Toetatud JSON Schema tüübid
  4. Täielik näide: kaks täiendavat funktsiooni
  5. Kohustuslikud vs valikulised parameetrid
  6. Parimad tavad kirjelduste koostamisel
  7. Peamised punktid

Leping sinu koodi ja mudeli vahel

Selleks, et Mistrali mudel saaks sinu funktsioone kutsuda, peab ta teadma, mis on olemas ja kuidas neid kasutada. Selle eest vastutab JSON Schema: standardiseeritud vorming, mis kirjeldab iga funktsiooni – selle nime, tegevust, oodatavaid parameetreid ja seda, millised neist on kohustuslikud.

Pea selle õppetüki vältel meeles üht asja: mudel ei näe kunagi sinu Pythoni koodi. Ta näeb ainult seda spetsifikatsiooni. Kui sinu funktsioon töötleb väiketähtedega ID-sid, kuid skeem seda ei maini, eirab mudel seda võimalust. Mida täpsem ja paremini dokumenteeritud on sinu skeem, seda täpsemad on genereeritud argumendid.

Tööriista spetsifikatsiooni anatoomia

Iga Mistrali API-le saadetav tööriist järgib sama struktuuri:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Selge kirjeldus sellest, mida funktsioon teeb",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameetri kirjeldus"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parameetri kirjeldus"
                }
            },
            "required": ["param1"]
        }
    }
}
VäliRoll
typeAlati "function" (tulevikus võivad eksisteerida ka muud tüübid)
function.nameSinu Pythoni funktsiooni täpne nimi – selle tagastab mudel väljal tool_calls
function.descriptionSelge lause, mis aitab mudelil valida õige funktsiooni
function.parametersJSON Schema objekt, mis kirjeldab oodatavaid parameetreid
requiredKohustuslike parameetrite loend

Toetatud JSON Schema tüübid

Parameetrite kirjeldamiseks kasutatav tüüpide sõnavara on tahtlikult piiratud ja iga tüüp suunab mudelit erinevalt. Eriti enum teeb enamat kui lihtsalt dokumenteerimine: see sulgeb ukse väljamõeldud väärtustele.

# String — vaba tekst või piiratud
{"type": "string", "description": "Tehingu ID"}

# String koos enumiga — piiratud väärtused
{"type": "string", "enum": ["asc", "desc"], "description": "Sorteerimise järjekord"}

# Integer — täisarv
{"type": "integer", "description": "Tagastatavate tulemuste arv"}

# Number — kümnendmurdarv
{"type": "number", "description": "Summa eurodes"}

# Boolean — tõene/väär
{"type": "boolean", "description": "Kaasa arvatud tühistatud tehingud"}

# Array — väärtuste loend
{
    "type": "array",
    "items": {"type": "string"},
    "description": "Tehingute ID-de loend"
}

# Object — pesastatud objekt
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Tarneaadress"
}

Tee selge vahet integer ja number vahel: summa eurodes, nagu 125.50, nõuab tüüpi number, samas kui tagastatavate tulemuste arv on integer. Summa deklareerimine kui integer paneb mudeli selle ümardama.

Täielik näide: kaks täiendavat funktsiooni

Siin on realistlik näide kahe maksetega seotud funktsiooniga, mis põhineb ametlikul Mistrali dokumentatsioonil:

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

Mõlemad funktsioonid eeldavad täpselt sama parameetrit, transaction_id, ometi peab mudel nende vahel valima. See valik tugineb täielikult funktsiooni kirjeldusele. Küsimus „Kas see makse õnnestus?“ viib funktsioonini retrieve_payment_status; küsimus „Millal see toimus?“ viib funktsioonini retrieve_payment_date. Kui oleksid kirjutanud kaks ebamäärast ja omavahel asendatavat kirjeldust, eksiks mudel pooltel juhtudel – ja süüdistaksid mudelit, kuigi viga peitub skeemis.

Kohustuslikud vs valikulised parameetrid

Erinevus kohustuslike ja valikuliste parameetrite vahel määrab, mida mudelil on lubatud välja jätta.

{
    "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": "Filtreeri makse staatuse järgi"
                },
                "date_from": {
                    "type": "string",
                    "description": "Alguskuupäev formaadis YYYY-MM-DD"
                },
                "date_to": {
                    "type": "string",
                    "description": "Lõppkuupäev formaadis YYYY-MM-DD"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimaalne summa eurodes"
                }
            },
            "required": ["status"]
        }
    }
}

Siin on ainult status kohustuslik; teised parameetrid lisatakse ainult siis, kui kasutaja neid mainib. Võrdle kahte formulatsiooni. Päringu „Näita ebaõnnestunud makseid“ korral genereerib mudel lihtsalt {"status": "failed"}. Päringu „Näita ebaõnnestunud makseid alates märtsist 2026“ korral lisab ta ise date_from ja date_to. Nende kuupäevade kohustuslikuks tegumine oleks rikkunud esimese päringu või, mis veel hullem, sundinud mudelit leiutama kuupäevavahemiku.

Parimad tavad kirjelduste koostamisel

Kirjelduste kvaliteet mõjutab otseselt mudeli täpsust. Allpool toodud vastunäited on õpetlikumad kui ükski abstraktne reegel.

# Halb — liiga ebamäärane
{"description": "Toob andmed"}

# Hea — täpne ja kontekstiga
{"description": "Toob makse staatuse (makstud, ootel, ebaõnnestunud) "
                "unikaalse tehingu ID põhjal"}

# Halb — parameetrile kirjeldus puudub
{"transaction_id": {"type": "string"}}

# Hea — kirjeldus koos näitega
{"transaction_id": {
    "type": "string",
    "description": "Unikaalne tehingu ID (formaadis: T, millele järgneb 4 numbrit, nt T1001)"
}}

Hea kirjeldus ütleb ühes lauses, mida funktsioon teeb, täpsustab iga parameetri oodatavat formaati ja toob näite, kui formaat pole ilmne – T1001 on parem kui „tehingu ID“. Kui võimalikud väärtused on piiratud, ära kirjelda neid proosas: deklareeri need kasutades enum. See on ainus viis muuta need siduvaks.

Peamised punktid

  • JSON Schema on leping sinu koodi ja mudeli vahel – see kirjeldab sinu funktsioone, paljastamata koodi ennast
  • Igal tööriistal on name, description ja tüübitud parameters
  • Toetatud tüüpide hulka kuuluvad string, integer, number, boolean, array ja object
  • Loend required eristab kohustuslikke parameetreid valikulistest
  • Täpsed kirjeldused koos näidetega parandavad oluliselt mudeli täpsust