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

Prosessi viidessä vaiheessa

Oppitunti 2 / 14 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Selkeä protokolla sinun ja mallin välillä
  2. Vuokaavio yksityiskohtaisesti
  3. Vuokaavioiden mallit
  4. Keskeiset asiat

Selkeä protokolla sinun ja mallin välillä

Mistralin funktionkutsu noudattaa hyvin määriteltyä viisivaiheista prosessia. Protokollan luettavuus perustuu siihen, että jokaisella vaiheella on vain yksi vastuuhenkilö: joko sinä (kehittäjä), malli tai käyttäjä. Mikään vaihe ei ole jaettu, eikä mikään ole epäselvä. Käytä hetki tämän työnjaon opetteluun ennen kuin kirjoitat riviäkään koodia: useimmat funktionkutsuihin liittyvät virheet johtuvat siitä, että kehittäjä odottaa mallin hoitavan vaiheen, joka kuuluu itse asiassa hänen omalle vastuulleen.

1

Määritä funktiot (Kehittäjä)

Kuvaat jokaisen käytettävissä olevan funktion JSON-skeemalla: nimi, kuvaus, parametrit, tyypit ja vaaditut kentät. Malli näkee vain tämän määrityksen, ei koodiasi.

2

Käyttäjä esittää kysymyksen (Käyttäjä)

Käyttäjä esittää kysymyksensä luonnollisella kielellä. Lähetät tämän pyynnön Mistral-mallille yhdessä käytettävissä olevien työkalujen listan kanssa.

3

Generoi argumentit (Malli)

Malli analysoi pyynnön, valitsee sopivan funktion ja generoi argumentit JSON-muodossa. Se ei suorita funktiota – se kertoo sinulle vain, mitä funktiota kutsua ja millä parametreilla.

4

Suorita funktio (Kehittäjä)

Koodisi poimii funktion nimen ja argumentit mallin vastauksesta, suorittaa vastaavan funktion ja hakee tuloksen.

5

Generoi lopullinen vastaus (Malli)

Lähetät funktion tuloksen takaisin mallille. Se integroi tuloksen keskustelukontekstiin ja muotoilee luonnollisen vastauksen käyttäjälle.

Vuokaavio yksityiskohtaisesti

Nämä viisi vaihetta vastaavat suoraan koodia. Käydään ne läpi yhden tarkoituksellisen yksinkertaisen esimerkin avulla: käyttäjä haluaa tietää maksun T1001 tilan. Käytämme tätä samaa esimerkkiä punaisena lankana aina ”Python-toteutus” -osion loppuun asti, joten tutustu sen tunnisteisiin nyt.

Vaihe 1: Määrität työkalut

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_payment_status",
            "description": "Retrieves the status of a payment given its transaction ID",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Tässä ei ole mitään suoritettavaa koodia: kyseessä on kuvaus. Malli oppii, että funktio nimeltä get_payment_status on olemassa, mitä se tekee ja että se vaatii merkkijonotyyppisen transaction_id:n. Se ei koskaan opi, miten funktio on toteutettu.

Vaihe 2: Käyttäjä esittää kysymyksensä

messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

Vaihe 3: Malli generoi argumentit

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

# The model returns a tool_call:
# function.name = "get_payment_status"
# function.arguments = '{"transaction_id": "T1001"}'

Malli poimi lauseesta arvon “T1001” ja sijoitti sen oikeaan kenttään. Huomaa, että arguments saapuu merkkijonona, ei sanakirjana: käsittelet tämän yksityiskohdan seuraavassa vaiheessa.

Vaihe 4: Suoritat funktion

import json

tool_call = response.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = get_payment_status(**args)
# → {"status": "paid", "date": "2026-03-15"}

Vaihe 5: Malli muotoilee vastauksen

messages.append(response.choices[0].message)
messages.append({
    "role": "tool",
    "name": "get_payment_status",
    "content": json.dumps(result),
    "tool_call_id": tool_call.id
})

final = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)
print(final.choices[0].message.content)
# → "Payment T1001 was made on March 15, 2026."

Historiaan lisätään kaksi viestiä, ei koskaan vain yhtä: avustajan viesti, joka sisältää kutsupyynnön, ja sitä seuraava viesti, joka sisältää tuloksen. tool_call_id yhdistää nämä kaksi toisiinsa. Jos jompikumpi puuttuu, API hylkää pyynnön tai malli vastaa aiheen ohi.

Vuokaavioiden mallit

Pyynnön monimutkaisuudesta riippuen tämä virta voi saada erilaisia muotoja. Yksinkertaisin tapaus on se, jossa funktiota ei käytetä lainkaan: käyttäjä esittää yleisen kysymyksen – “Mitä voit tehdä?” – ja malli vastaa suoraan koskematta koskaan työkaluihin. Seuraavaksi tulee juuri käymämme yksinkertainen kutsu: yksi funktio, yksi tulos, yksi vastaus.

Seuraavat kaksi muotoa ovat mielenkiintoisempia. Peräkkäisessä ketjussa malli kutsuu ensin funktion, lukee tuloksen ja käyttää sitä päättääkseen toisesta kutsusta – tyypillisesti se hakee ensin asiakastunnuksen ennen laskujen kyselyä. Rinnakkaiskutsussa se pyytää useiden funktioiden suorittamista samanaikaisesti, koska mikään niistä ei riipu toisesta. Omistamme kokonaiset oppitunnit näille kahdelle mallille; toistaiseksi riittää, kun muistat, että molemmat perustuvat täsmälleen edellä kuvattuihin viiteen vaiheeseen, jotka vain toistuvat.

Keskeiset asiat

  • Funktionkutsu noudattaa viisivaiheista prosessia, jossa vastuut ovat selkeät
  • Malli ei voi koskaan suorittaa funktiota suoraan – se vain generoi argumentit
  • Koodisi toimii portinvartijana: se päättää, suoritetaanko funktio vai ei
  • Funktion tulos lähetetään takaisin mallille, jotta se voi muotoilla luonnollisen vastauksen
  • Virta voi olla yksinkertainen (yksi kutsu) tai monimutkainen (peräkkäinen, rinnakkainen)