Apibrėžkite funkcijas naudodami JSON schemą
Šiame puslapyje
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"]
}
}
}
| Laukas | Vaidmuo |
|---|---|
type | Visada "function" (ateityje gali atsirasti kitų tipų) |
function.name | Tikslus tavo Python funkcijos pavadinimas – būtent jį modelis grąžina lauke tool_calls |
function.description | Aiškus sakinys, padedantis modeliui pasirinkti tinkamą funkciją |
function.parameters | JSON schemos objektas, aprašantis laukiamus parametrus |
required | Privalomų 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,descriptionir tipizuotusparameters - Palaikomi tipai:
string,integer,number,boolean,arrayirobject - Sąrašas
requiredatskiria privalomus parametrus nuo neprivalomų - Tikslūs aprašymai su pavyzdžiais žymiai pagerina modelio tikslumą