Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Apibrėžkite funkcijas naudodami JSON schemą

Paskaita 3 iš 14 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Sutartis tarp tavo kodo ir modelio
  2. Įrankio specifikacijos sandara
  3. Palaikomi JSON schemos tipai
  4. Pilnas pavyzdys: dvi papildančios funkcijos
  5. Privalomi ir neprivalomi parametrai
  6. Geriausi aprašymų kūrimo būdai
  7. Svarbiausi punktai

Sutartis tarp tavo kodo ir modelio

Kad „Mistral“ modelis galėtų iškviesti tavo funkcijas, jis turi žinoti, kas egzistuoja ir kaip tuo naudotis. Čia ir įsikiša JSON schema: tai standartizuotas formatas, aprašantis kiekvieną funkciją – jos pavadinimą, paskirtį, laukiamus parametrus ir tai, kurie iš jų yra privalomi.

Visos šios pamokos metu turėk omenyje vieną dalyką: modelis niekada nemato tavo Python kodo. Jis mato tik šią specifikaciją. Jei tavo funkcija be klaidų apdoroja mažosiomis raidėmis rašomus ID, bet schema to nenurodo, modelis tą galimybę ignoruos. Kuo tikslesnė ir geriau dokumentuota tavo schema, tuo tikslesnius argumentus modelis sugeneruos.

Įrankio specifikacijos sandara

Kiekvienas „Mistral“ API siunčiamas įrankis turi tą pačią struktūrą:

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"]
        }
    }
}
LaukasVaidmuo
typeVisada "function" (ateityje gali atsirasti kitų tipų)
function.nameTikslus tavo Python funkcijos pavadinimas – būtent jį modelis grąžina lauke tool_calls
function.descriptionAiškus sakinys, padedantis modeliui pasirinkti tinkamą funkciją
function.parametersJSON schemos objektas, aprašantis laukiamus parametrus
requiredPrivalomų parametrų sąrašas

Palaikomi JSON schemos tipai

Parametrams aprašyti skirta žodyno tipų aibė sąmoningai ribota, ir kiekvienas tipas modelį nukreipia skirtingai. Ypač enum daro daugiau nei tik dokumentuoja: jis užkerta kelią sugalvotoms reikšmėms.

# String — laisvas tekstas arba apribotas
{"type": "string", "description": "Transaction ID"}

# String with enum — ribotos reikšmės
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — sveikasis skaičius
{"type": "integer", "description": "Number of results to return"}

# Number — dešimtainis skaičius
{"type": "number", "description": "Amount in euros"}

# Boolean — true/false
{"type": "boolean", "description": "Include canceled transactions"}

# Array — reikšmių sąrašas
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

# Object — įdėtasis objektas
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Shipping address"
}

Aiškiai atskirk integer ir number: suma eurais, pavyzdžiui, 125.50, reikalauja number, tuo tarpu grąžinamų rezultatų skaičius yra integer. Jei sumą apibrėši kaip integer, modelis ją suapvalins.

Pilnas pavyzdys: dvi papildančios funkcijos

Štai realistiškas pavyzdys su dviem su mokėjimais susijusiomis funkcijomis, paremtas oficialia „Mistral“ dokumentacija:

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

Abi funkcijos tikisi to paties parametro – transaction_id, tačiau modelis turi pasirinkti vieną iš jų. Šis pasirinkimas visiškai priklauso nuo funkcijos aprašymo. Klausimas „Ar šis mokėjimas įvyko?“ atitinka retrieve_payment_status, o „Kada jis įvyko?“ – retrieve_payment_date. Jei būtum parašęs du neaiškius, tarpusavyje keičiamus aprašymus, modelis klystų kas antrą kartą – ir kaltintum modelį, nors iš tikrųjų kaltė slypi schemoje.

Privalomi ir neprivalomi parametrai

Skirtumas tarp privalomų ir neprivalomų parametrų lemia, ką modelis gali praleisti.

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

Čia privalomas tik status; kiti parametrai įtraukiami tik tada, kai vartotojas juos pamina. Palygink du formulavimus. Užklausai „Rodyk nepavykusius mokėjimus“ modelis sugeneruoja tiesiog {"status": "failed"}. Užklausai „Rodyk nepavykusius mokėjimus nuo 2026 m. kovo mėn.“ jis savarankiškai pridės date_from ir date_to. Jei tas datas būtų nurodęs kaip privalomas, pirmoji užklausa būtų žlugusi, arba, dar blogiau, modelis būtų sugalvojęs datos diapazoną.

Geriausi aprašymų kūrimo būdai

Aprašymų kokybė tiesiogiai veikia modelio tikslumą. Toliau pateikti neteisingi pavyzdžiai yra informatyvesni nei bet kuri abstrakti taisyklė.

# Blogai – per daug neaišku
{"description": "Retrieves data"}

# Gerai – tikslu ir kontekstualu
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Blogai – nėra parametro aprašymo
{"transaction_id": {"type": "string"}}

# Gerai – aprašymas su pavyzdžiu
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Geras aprašymas vienu sakiniu nurodo, ką funkcija daro, nurodo laukiamą kiekvieno parametro formatą ir pateikia pavyzdį, kai formatas nėra akivaizdus – T1001 yra geriau nei „sandorio ID“. Kai galimos reikšmės yra ribotos, neaprašyk jų žodžiais: deklaruok jas naudodamas enum. Tai vienintelis būdas jas padaryti privalomomis.

Svarbiausi punktai

  • JSON schema yra sutartis tarp tavo kodo ir modelio – ji aprašo tavo funkcijas neatskleisdama kodo
  • Kiekvienas įrankis turi name, description ir tipizuotus parameters
  • Palaikomi tipai: string, integer, number, boolean, array ir object
  • Sąrašas required atskiria privalomus parametrus nuo neprivalomų
  • Tikslūs aprašymai su pavyzdžiais žymiai pagerina modelio tikslumą