Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Definiraj funkcije s shemo JSON

Lekcija 3 od 14 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Pogodba med tvojo kodo in modelom
  2. Anatomija specifikacije orodja
  3. Podprti tipi sheme JSON
  4. Celoten primer: dve komplementarni funkciji
  5. Obvezni proti izbirnim parametrom
  6. Najboljše prakse za opise
  7. Ključne ugotovitve

Pogodba med tvojo kodo in modelom

Da bi model Mistral lahko poklical tvoje funkcije, mora vedeti, kaj obstaja in kako jih uporabiti. To je vloga sheme JSON: standardizirane oblike, ki opisuje vsako funkcijo – njeno ime, kaj počne, katere parametre pričakuje in kateri so obvezni.

V tej lekciji imej vedno v mislih eno stvar: model nikoli ne vidi tvoje kode Python. Vidi le to specifikacijo. Če tvoja funkcija brez težav obravnava ID-je z malimi črkami, shema pa tega ne navaja, bo model to zmogljivost prezrl. Bolj natančna in dobro dokumentirana je tvoja shema, bolj natančni bodo generirani argumenti.

Anatomija specifikacije orodja

Vsako orodje, poslano API-ju Mistral, sledi isti strukturi:

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"]
        }
    }
}
PoljeVloga
typeVedno "function" (v prihodnosti bodo morda obstajale druge vrste)
function.nameTočno ime tvoje funkcije Python – to je tisto, kar model vrne v tool_calls
function.descriptionJasen stavek, ki modelu pomaga izbrati pravo funkcijo
function.parametersPredmet sheme JSON, ki opisuje pričakovane parametre
requiredSeznam obveznih parametrov

Podprti tipi sheme JSON

Slovar tipov, na voljo za opisovanje parametrov, je namerno omejen in vsak tip model usmerja drugače. enum še posebej naredi več kot le dokumentira: zapre vrata izmišljenim vrednostim.

# String — prosto besedilo ali omejeno
{"type": "string", "description": "ID transakcije"}

# String z enum — omejene vrednosti
{"type": "string", "enum": ["asc", "desc"], "description": "Vrstni red razvrščanja"}

# Integer — celo število
{"type": "integer", "description": "Število rezultatov za vrnitev"}

# Number — decimalno število
{"type": "number", "description": "Znesek v evrih"}

# Boolean — true/false
{"type": "boolean", "description": "Vključi preklicane transakcije"}

# Array — seznam vrednosti
{
    "type": "array",
    "items": {"type": "string"},
    "description": "Seznam ID-jev transakcij"
}

# Object — gnezden predmet
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Naslov za dostavo"
}

Jasno razlikuj med integer in number: znesek v evrih, kot je 125,50, zahteva number, medtem ko je število rezultatov za vrnitev integer. Če znesek določiš kot integer, bo model zaokrožil vrednost.

Celoten primer: dve komplementarni funkciji

Tukaj je realističen primer z dvema funkcijama, povezanima s plačili, ki temelji na uradni dokumentaciji Mistral:

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

Obe funkciji pričakujeta popolnoma enak parameter, transaction_id, vendar se mora model odločiti med njima. Ta izbira temelji izključno na opisu funkcije. „Ali je to plačilo uspelo?” se preslika v retrieve_payment_status; „Kdaj je bilo?” se preslika v retrieve_payment_date. Če bi napisal dva nejasna, zamenljiva opisa, bi se model polovico časa zmotil – in krivil bi model, čeprav je napaka v shemi.

Obvezni proti izbirnim parametrom

Razlika med obveznimi in izbirnimi parametri določa, kaj sme model izpustiti.

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

Tukaj je obvezen le status; drugi parametri so vključeni le, če jih uporabnik omeni. Primerjaj dve formulaciji. Za „Prikaži neuspela plačila” model generira preprosto {"status": "failed"}. Za „Prikaži neuspela plačila od marca 2026” samodejno doda date_from in date_to. Če bi bila ta datuma obvezna, bi se prvi poizvedbi pokvarila ali, kar je še huje, bi model prisililo k izmišljevanju časovnega obdobja.

Najboljše prakse za opise

Kakovost opisov neposredno vpliva na natančnost modela. Spodnji protiprimeri so bolj poučni kot katero koli abstraktno pravilo.

# Slabo — preveč nejasno
{"description": "Retrieves data"}

# Dobro — natančno in kontekstualno
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Slabo — brez opisa za parameter
{"transaction_id": {"type": "string"}}

# Dobro — opis s primerom
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Dober opis v enem stavku pove, kaj funkcija počne, določi pričakovano obliko za vsak parameter in kadar oblika ni očitna, navede primer – T1001 je bolje kot „ID transakcije”. Ko so možne vrednosti omejene, jih ne opisuj z besedilom: deklariraj jih z enum. To je edini način, da postanejo zavezujoče.

Ključne ugotovitve

  • Shema JSON je pogodba med tvojo kodo in modelom – opisuje tvoje funkcije, ne da bi razkrila kodo
  • Vsako orodje ima name, description in tipizirane parameters
  • Podprti tipi vključujejo string, integer, number, boolean, array in object
  • Seznam required razlikuje med obveznimi in izbirnimi parametri
  • Natančni opisi s primeri bistveno izboljšajo natančnost modela