Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Definiraj funkcije s JSON Shemom

Lekcija 3 od 14 Ažurirano 29. srpnja 2026. Programer
Na ovoj stranici
  1. Ugovor između tvog koda i modela
  2. Anatomija specifikacije alata
  3. Podržane vrste u JSON Shemi
  4. Potpuni primjer: dvije komplementarne funkcije
  5. Obavezni nasuprot opcionalnim parametrima
  6. Najbolje prakse za opise
  7. Ključne točke

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"]
        }
    }
}
PoljeUloga
typeUvijek "function" (druge vrste mogu postojati u budućnosti)
function.nameTočan naziv tvoje Python funkcije—to je ono što model vraća u tool_calls
function.descriptionJasna rečenica koja pomaže modelu odabrati pravu funkciju
function.parametersJSON Schema objekt koji opisuje očekivane parametre
requiredPopis 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, description i tipizirane parameters
  • Podržane vrste uključuju string, integer, number, boolean, array i object
  • Popis required razlikuje obavezne parametre od opcionalnih
  • Precizni opisi s primjerima značajno poboljšavaju točnost modela