Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Määrittele funktiot JSON Scheman avulla

Oppitunti 3 / 14 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Sopimus koodisi ja mallin välillä
  2. Työkalumäärittelyn anatomia
  3. Tuetut JSON Schema -tyypit
  4. Täydellinen esimerkki: kaksi toisiaan täydentävää funktiota
  5. Pakolliset vs. valinnaiset parametrit
  6. Parhaat käytännöt kuvauksille
  7. Keskeiset asiat

Sopimus koodisi ja mallin välillä

Jotta Mistral-malli pystyy kutsumaan funktioitasi, sen on tiedettävä, mitä on olemassa ja miten niitä käytetään. Tässä tulee avuksi JSON Schema: standardoitu muoto, joka kuvaa jokaisen funktion – sen nimen, tehtävän, odotetut parametrit ja pakolliset kentät.

Pidä tämä mielessäsi koko oppitunnin ajan: malli ei koskaan näe Python-koodiasi. Se näkee ainoastaan tämän määrittelyn. Jos funktiosi käsittelee pienillä kirjaimilla kirjoitetut tunnisteet virheettömästi, mutta schema ei mainitse tätä, malli ignoroi tämän mahdollisuuden. Mitä tarkempi ja paremmin dokumentoitu schema on, sitä tarkempia generoidut argumentit ovat.

Työkalumäärittelyn anatomia

Jokainen Mistral API:lle lähetettävä työkalu noudattaa samaa rakennetta:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Selkeä kuvaus siitä, mitä funktio tekee",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parametrin kuvaus"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parametrin kuvaus"
                }
            },
            "required": ["param1"]
        }
    }
}
KenttäRooli
typeAina "function" (muita tyyppejä voi tulla tulevaisuudessa)
function.namePython-funktiosi tarkka nimi – tämän malli palauttaa kohdassa tool_calls
function.descriptionSelkeä lause, joka auttaa mallia valitsemaan oikean funktion
function.parametersJSON Schema -objekti, joka kuvaa odotetut parametrit
requiredLuettelo pakollisista parametreista

Tuetut JSON Schema -tyypit

Parametrien kuvaamiseen käytettävä tyyppisanasto on tarkoituksellisesti rajoitettu, ja jokainen tyyppi ohjaa mallia eri tavalla. Erityisesti enum tekee enemmän kuin vain dokumentoi: se sulkee oven keksityiltä arvoilta.

# String — vapaa teksti tai rajoitettu
{"type": "string", "description": "Transaktiotunniste"}

# String, jossa enum — rajoitetut arvot
{"type": "string", "enum": ["asc", "desc"], "description": "Lajittelujärjestys"}

# Integer — kokonaisluku
{"type": "integer", "description": "Palautettavien tulosten määrä"}

# Number — desimaaliluku
{"type": "number", "description": "Summa euroina"}

# Boolean — tosi/epätosi
{"type": "boolean", "description": "Sisällytä peruutetut transaktiot"}

# Array — arvolista
{
    "type": "array",
    "items": {"type": "string"},
    "description": "Transaktiotunnisteiden lista"
}

# Object — sisäkkäinen objekti
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Toimitusosoite"
}

Tee selkeä ero integer- ja number-tyyppien välillä: euron määrä kuten 125,50 vaatii tyypin number, kun taas palautettavien tulosten lukumäärä on integer. Jos määrittelet summan tyypiksi integer, malli pyöristää sen.

Täydellinen esimerkki: kaksi toisiaan täydentävää funktiota

Tässä on realistinen esimerkki kahdesta maksuihin liittyvästä funktiosta, jotka on inspiroitu virallisesta Mistral-dokumentaatiosta:

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Hakee maksun tilan (maksettu, odottaa, epäonnistunut) "
                           "transaktiotunnisteen perusteella.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Unikki transaktiotunniste (esim. T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Hakee päivämäärän, jolloin maksu suoritettiin "
                           "transaktiotunnisteen perusteella.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Unikki transaktiotunniste (esim. T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Molemmat funktiot odottavat täsmälleen samaa parametria, transaction_id, mutta mallin on valittava niiden välillä. Tämä valinta perustuu täysin funktion kuvaukseen. Kysymys “Onko tämä maksu mennyt läpi?” vastaa funktiota retrieve_payment_status; kysymys “Milloin se tapahtui?” vastaa funktiota retrieve_payment_date. Jos olisit kirjoittanut kaksi epämääräistä ja keskenään vaihdettavaa kuvausta, malli olisi väärässä puolet ajasta – ja syyttäisit mallia, vaikka vika olisi schemassa.

Pakolliset vs. valinnaiset parametrit

Ero pakollisten ja valinnaisten parametrien välillä määrittää, mitä malli saa jättää pois.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Hakee transaktioita eri kriteerien perusteella",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Suodata maksutilan perusteella"
                },
                "date_from": {
                    "type": "string",
                    "description": "Aloituspäivä muodossa YYYY-MM-DD"
                },
                "date_to": {
                    "type": "string",
                    "description": "Lopetuspäivä muodossa YYYY-MM-DD"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimisumma euroina"
                }
            },
            "required": ["status"]
        }
    }
}

Tässä vain status on pakollinen; muut parametrit sisällytetään vain, jos käyttäjä mainitsee ne. Vertaa kahta formulointia. Kysymykseen “Näytä epäonnistuneet maksut” malli generoi yksinkertaisesti {"status": "failed"}. Kysymykseen “Näytä epäonnistuneet maksut maaliskuulta 2026” se lisää itse date_from- ja date_to-kentät. Jos olisit määritellyt nämä päivämäärät pakollisiksi, ensimmäinen kysely olisi epäonnistunut, tai pahempaa, malli olisi keksinyt päivämäärävälin.

Parhaat käytännöt kuvauksille

Kuvausten laatu vaikuttaa suoraan mallin tarkkuuteen. Alla olevat vastaesimerkit ovat opettavaisempia kuin mikään abstrakti sääntö.

# Huono — liian epämääräinen
{"description": "Hakee dataa"}

# Hyvä — tarkka ja kontekstuaalinen
{"description": "Hakee maksun tilan (maksettu, odottaa, epäonnistunut) "
                "unikin transaktiotunnisteen perusteella"}

# Huono — ei kuvausta parametrille
{"transaction_id": {"type": "string"}}

# Hyvä — kuvaus esimerkin kera
{"transaction_id": {
    "type": "string",
    "description": "Unikki transaktiotunniste (muoto: T ja 4 numeroa, esim. T1001)"
}}

Hyvä kuvaus kertoo yhdellä lauseella, mitä funktio tekee, määrittää jokaisen parametrin odotetun muodon ja tarjoaa esimerkin aina, kun muoto ei ole ilmeinen – T1001 on parempi kuin pelkkä “transaktiotunniste”. Kun mahdolliset arvot ovat rajoitettuja, älä kuvaile niitä prosemina: määrittele ne käyttämällä enum:ia. Se on ainoa tapa tehdä niistä sitovia.

Keskeiset asiat

  • JSON Schema on sopimus koodisi ja mallin välillä – se kuvaa funktioitasi paljastamatta koodia
  • Jokaisella työkalulla on name, description ja tyypitetyt parameters
  • Tuetut tyypit ovat string, integer, number, boolean, array ja object
  • required-lista erottaa pakolliset parametrit valinnaisista
  • Tarkat kuvaukset esimerkkeineen parantavat merkittävästi mallin tarkkuutta