Definiraj funkcije s JSON Shemom
Na ovoj stranici
Ugovor između tvog koda i modela
Da bi Mistral model mogao pozvati tvoje funkcije, mora znati što postoji i kako se to koristi. Tu nastupa JSON Schema: standardizirani format koji opisuje svaku funkciju—njezino ime, što radi, koje parametre očekuje i koji su od njih obavezni.
Imaj na umu jednu stvar tijekom cijele ove lekcije: model nikada ne vidi tvoj Python kod. On vidi samo ovu specifikaciju. Ako tvoja funkcija glatko obrađuje ID-ove u malim slovima, ali shema to ne navodi, model će ignorirati tu mogućnost. Što je tvoja shema preciznija i bolje dokumentirana, to će generirani argumenti biti točniji.
Anatomija specifikacije alata
Svaki alat poslan Mistral API-ju slijedi istu strukturu:
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"]
}
}
}
| Polje | Uloga |
|---|---|
type | Uvijek "function" (druge vrste mogu postojati u budućnosti) |
function.name | Točan naziv tvoje Python funkcije—to je ono što model vraća u tool_calls |
function.description | Jasna rečenica koja pomaže modelu odabrati pravu funkciju |
function.parameters | JSON Schema objekt koji opisuje očekivane parametre |
required | Popis obaveznih parametara |
Podržane vrste u JSON Shemi
Rječnik vrsta dostupnih za opisivanje parametara namjerno je ograničen, a svaka vrsta vodi model na drugačiji način. enum posebno čini više od dokumentiranja: on zatvara vrata izmišljenim vrijednostima.
# String — slobodan tekst ili ograničen
{"type": "string", "description": "ID transakcije"}
# String s enumom — ograničene vrijednosti
{"type": "string", "enum": ["asc", "desc"], "description": "Redoslijed sortiranja"}
# Integer — cijeli broj
{"type": "integer", "description": "Broj rezultata za vraćanje"}
# Number — decimalni broj
{"type": "number", "description": "Iznos u eurima"}
# Boolean — true/false
{"type": "boolean", "description": "Uključi otkazane transakcije"}
# Array — popis vrijednosti
{
"type": "array",
"items": {"type": "string"},
"description": "Popis ID-ova transakcija"
}
# Object — ugniježđeni objekt
{
"type": "object",
"properties": {
"city": {"type": "string"},
"country": {"type": "string"}
},
"description": "Adresa za dostavu"
}
Jasno razlikuj integer i number: iznos u eurima poput 125,50 zahtijeva number, dok je broj rezultata za vraćanje integer. Ako iznos proglasiš integerom, model će ga zaokružiti.
Potpuni primjer: dvije komplementarne funkcije
Evo realističnog primjera s dvije funkcije vezane uz plaćanja, inspiriranog službenom Mistral dokumentacijom:
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"]
}
}
}
]
Obje funkcije očekuju točno isti parametar, transaction_id, no model mora odabrati između njih. Taj izbor u potpunosti ovisi o opisu funkcije. „Je li ovo plaćanje prošlo?“ mapira se na retrieve_payment_status; „Kada je bilo?“ mapira se na retrieve_payment_date. Da si napisao dva nejasna, zamjenjiva opisa, model bi pogriješio u pola slučajeva—i krivio bi model, a greška bi zapravo bila u shemi.
Obavezni nasuprot opcionalnim parametrima
Razlika između obaveznih i opcionalnih parametara određuje što model smije izostaviti.
{
"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"]
}
}
}
Ovdje je samo status obavezan; ostali parametri uključeni su samo ako ih korisnik spomene. Usporedi dvije formulacije. Za „Prikaži mi neuspjela plaćanja“, model generira jednostavno {"status": "failed"}. Za „Prikaži mi neuspjela plaćanja od ožujka 2026.“, sam dodaje date_from i date_to. Da su ti datumi obavezni, prva upit bi bila pokvarena, ili još gore, model bi bio prisiljen izmisliti raspon datuma.
Najbolje prakse za opise
Kvaliteta opisa izravno utječe na točnost modela. Protuprimjeri u nastavku poučniji su od bilo kojeg apstraktnog pravila.
# Loše — preopćenito
{"description": "Dohvaća podatke"}
# Dobro — precizno i kontekstualno
{"description": "Dohvaća status plaćanja (plaćeno, na čekanju, neuspjelo) "
"na temelju jedinstvenog ID-a transakcije"}
# Loše — nema opisa za parametar
{"transaction_id": {"type": "string"}}
# Dobro — opis s primjerom
{"transaction_id": {
"type": "string",
"description": "Jedinstveni ID transakcije (format: T praćen s 4 znamenke, npr. T1001)"
}}
Dobar opis u jednoj rečenici navodi što funkcija radi, specificira očekivani format za svaki parametar i pruža primjer kad god taj format nije očigledan—T1001 je bolje od „ID transakcije“. Kada su moguće vrijednosti ograničene, ne opisuj ih prozom: proglasi ih s enum. To je jedini način da postanu obvezujuće.
Ključne točke
- JSON Schema je ugovor između tvog koda i modela—opisuje tvoje funkcije bez otkrivanja koda
- Svaki alat ima
name,descriptioni tipiziraneparameters - Podržane vrste uključuju
string,integer,number,boolean,arrayiobject - Popis
requiredrazlikuje obavezne parametre od opcionalnih - Precizni opisi s primjerima značajno poboljšavaju točnost modela