Definē funkcijas ar JSON shēmu
Šajā lapā
Līgums starp tavu kodu un modeli
Lai Mistral modelis varētu izsaukt tavas funkcijas, tam ir jāzina, kas pastāv un kā to izmantot. Tieši šo uzdevumu veic JSON shēma: standartizēts formāts, kas apraksta katru funkciju — tās nosaukumu, darbību, gaidītos parametrus un to, kuri no tiem ir obligāti.
Visas šīs nodarbības laikā paturi prātā vienu lietu: modelis nekad neredz tavu Python kodu. Tas redz tikai šo specifikāciju. Ja tava funkcija veiksmīgi apstrādā ID mazajos burtos, bet shēmā tas nav norādīts, modelis šo iespēju ignorēs. Jo precīzāka un labāk dokumentēta ir tava shēma, jo precīzāki būs ģenerētie argumenti.
Rīka specifikācijas uzbūve
Katrs rīks, kas tiek nosūtīts Mistral API, ievēro vienu un to pašu struktūru:
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"]
}
}
}
| Lauks | Loma |
|---|---|
type | Vienmēr "function" (nākotnē var parādīties citi tipi) |
function.name | Tavas Python funkcijas precīzs nosaukums — tieši to modelis atgriež laukā tool_calls |
function.description | Skaidrs teikums, kas palīdz modelim izvēlēties pareizo funkciju |
function.parameters | JSON shēmas objekts, kas apraksta gaidītos parametrus |
required | Obligāto parametru saraksts |
Atbalstītie JSON shēmas tipi
Tipu vārdnīca, ko var izmantot parametru aprakstīšanai, ir apzināti ierobežota, un katrs tips modeli virza citādāk. Jo īpaši enum dara vairāk nekā tikai dokumentē: tas aizver durvis izdomātām vērtībām.
# String — brīvs teksts vai ierobežots
{"type": "string", "description": "Darījuma ID"}
# String ar enum — ierobežotas vērtības
{"type": "string", "enum": ["asc", "desc"], "description": "Kārtošanas secība"}
# Integer — vesels skaitlis
{"type": "integer", "description": "Atgriežamo rezultātu skaits"}
# Number — decimālskaitlis
{"type": "number", "description": "Summa eiro"}
# Boolean — patiess/nepatiess
{"type": "boolean", "description": "Iekļaut atceltos darījumus"}
# Array — vērtību saraksts
{
"type": "array",
"items": {"type": "string"},
"description": "Darījumu ID saraksts"
}
# Object — ligzdots objekts
{
"type": "object",
"properties": {
"city": {"type": "string"},
"country": {"type": "string"}
},
"description": "Piegādes adrese"
}
Skaidri nošķir integer un number: summai eiro, piemēram, 125.50, ir nepieciešams number, savukārt atgriežamo rezultātu skaits ir integer. Ja summu deklarēsi kā integer, modelis to noapaļos.
Pilns piemērs: divas papildinošas funkcijas
Lūk, reālistisks piemērs ar divām ar maksājumiem saistītām funkcijām, kas iedvesmotas no oficiālās Mistral dokumentācijas:
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"]
}
}
}
]
Abas funkcijas sagaida tieši to pašu parametru transaction_id, tomēr modelim ir jāizvēlas starp tām. Šī izvēle balstās vienīgi uz funkcijas aprakstu. Jautājums „Vai šis maksājums ir veikts?” atbilst funkcijai retrieve_payment_status, bet „Kad tas notika?” — funkcijai retrieve_payment_date. Ja būtu uzrakstījis divus neskaidrus, savstarpēji aizvietojamus aprakstus, modelis kļūdītos katru otro reizi — un tu vainotu modeli, lai gan patiesībā vainīga būtu shēma.
Obligātie un neobligātie parametri
Atšķirība starp obligātajiem un neobligātajiem parametriem nosaka, ko modelim ir atļauts izlaist.
{
"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": "Filtrēt pēc maksājuma statusa"
},
"date_from": {
"type": "string",
"description": "Sākuma datums formātā YYYY-MM-DD"
},
"date_to": {
"type": "string",
"description": "Beigu datums formātā YYYY-MM-DD"
},
"min_amount": {
"type": "number",
"description": "Minimālā summa eiro"
}
},
"required": ["status"]
}
}
}
Šeit tikai status ir obligāts; pārējie parametri tiek iekļauti tikai tad, ja lietotājs tos piemin. Salīdzini divus formulējumus. Pieprasījumam „Parādi man neveiktos maksājumus” modelis ģenerēs vienkārši {"status": "failed"}. Pieprasījumam „Parādi man neveiktos maksājumus kopš 2026. gada marta” tas pats no sevis pievienos date_from un date_to. Ja šos datumus būtu padarījis par obligātiem, tas būtu sabojājis pirmo vaicājumu vai, vēl ļaunāk, spiestu modeli izdomāt datumu diapazonu.
Labākā prakse aprakstu veidošanā
Aprakstu kvalitāte tieši ietekmē modeļa precizitāti. Zemāk esošie pretpiemēri ir mācošāki par jebkuru abstraktu likumu.
# Slikti — pārāk neskaidri
{"description": "Iegūst datus"}
# Labi — precīzi un kontekstuāli
{"description": "Iegūst maksājuma statusu (apmaksāts, gaida, neizdevās), "
"izmantojot unikālo darījuma ID"}
# Slikti — parametram nav apraksta
{"transaction_id": {"type": "string"}}
# Labi — apraksts ar piemēru
{"transaction_id": {
"type": "string",
"description": "Unikāls darījuma ID (formāts: T, kam seko 4 cipari, piem., T1001)"
}}
Labs apraksts vienā teikumā norāda, ko funkcija dara, precizē katra parametra gaidīto formātu un sniedz piemēru, kad formāts nav acīmredzams — T1001 ir labāk nekā tikai „darījuma ID”. Ja iespējamās vērtības ir ierobežotas, neapraksti tās prozā: deklarē tās, izmantojot enum. Tas ir vienīgais veids, kā padarīt tās saistošas.
Galvenās atziņas
- JSON shēma ir līgums starp tavu kodu un modeli — tā apraksta tavas funkcijas, neatklājot pašu kodu
- Katram rīkam ir
name,descriptionun tipētiparameters - Atbalstītie tipi ir
string,integer,number,boolean,arrayunobject - Saraksts
requirednošķir obligātos parametrus no neobligātajiem - Precīzi apraksti ar piemēriem būtiski uzlabo modeļa precizitāti