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

Suorita ja palauta tulos

Oppitunti 6 / 14 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Vaihe, jonka hallitset täysin
  2. Suorita funktio asiakaspuolella
  3. Rakenna tool-viesti
  4. Lähetä tulos ja hae lopullinen vastaus
  5. Koko virtaus yhdessä lohkossa
  6. Viestirakenne jokaisessa vaiheessa
  7. Huomioi sisältömuoto
  8. Keskeiset asiat

Vaihe, jonka hallitset täysin

Olet vastaanottanut mallilta tool_call-pyynnön. Se kertoo, minkä funktion sinun tulee kutsua ja millä argumenteilla – ei mitään muuta. Nyt sinun koodisi ottaa ohjat: se suorittaa funktion, hakee tuloksen ja lähettää sen takaisin mallille viestinä, jonka rooli on tool. Tämä oppitunti kattaa koko tämän kierron. Tämä on syklin ainoa hetki, jolloin teet kaikki päätökset itse.

Suorita funktio asiakaspuolella

Kerrataan oppitunnin 4 dispatch-sanakirjaa ja yhdistetään se mallin vastaukseen.

import json
from functools import partial

# Funktiot on jo määritelty
available_functions = {
    "retrieve_payment_status": partial(retrieve_payment_status, df),
    "retrieve_payment_date": partial(retrieve_payment_date, df),
}

# Malli palautti tool_call-objektin
tool_call = response.choices[0].message.tool_calls[0]
function_name = tool_call.function.name
function_params = json.loads(tool_call.function.arguments)

# Suorita funktio
if function_name in available_functions:
    result = available_functions[function_name](**function_params)
    print(f"Result: {result}")
    # → '{"status": "paid"}'
else:
    result = json.dumps({"error": f"Function {function_name} not available"})

Tässä toimii kaksi mekanismia. Ensimmäinen on **function_params, joka purkaa JSONista saadun sanakirjan nimetyiksi argumenteiksi: jos malli tuotti {"transaction_id": "T1001"}, kutsu vastaa täsmälleen kutsua retrieve_payment_status(transaction_id="T1001"). Toinen mekanismi on else-lohko. Se ei ole yhtä näyttävä, mutta se on välttämätön. Malli saattaa hallusinoida funktion nimen, jota ei ole dispatch-sanakirjassasi; ilman tätä tarkistusta sovelluksesi heittää KeyError-virheen ja keskustelu pysähtyy tyystin. Tämän tarkistuksen ansiosta virhe muuttuu dataksi, jonka malli voi käsitellä hallitusti.

Rakenna tool-viesti

Tulos on lähetettävä takaisin mallille tietyssä muodossa – viestinä, jonka rooli on "tool":

tool_message = {
    "role": "tool",
    "name": function_name,
    "content": result,  # Tämän on oltava merkkijono
    "tool_call_id": tool_call.id
}
KenttäRooli
role"tool" – tunnistaa viestin funktion tulokseksi
nameSuoritetun funktion nimi
contentTulos JSON-merkkijonona
tool_call_idAlkuperäisen tool_callin ID – mahdollistaa mallille tuloksen yhdistämisen oikeaan kutsuun

Lähetä tulos ja hae lopullinen vastaus

Mallilla ei ole muistia kutsujen välillä: se ei muista pyytäneensä sinulta mitään. Siksi sinun on rakennettava sille koko keskustelu uudelleen, mukaan lukien sen oma pyyntö työkalukutsulle, ennen kuin esität tuloksen.

# 1. Lisää avustajan viesti (sisältää tool_callin)
messages.append(response.choices[0].message)

# 2. Lisää funktion tulos
messages.append({
    "role": "tool",
    "name": function_name,
    "content": result,
    "tool_call_id": tool_call.id
})

# 3. Kutsu mallia uudelleen koko kontekstilla
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

# 4. Näytä lopullinen vastaus
print(final_response.choices[0].message.content)
# → "Payment T1001 status is: paid."

Näiden kahden append-operaation järjestys on ehdoton: tool_callin sisältävän avustajan viestin on tultava ennen sitä vastaavaa tool-viestiä. Järjestyksen vaihtaminen luo epäjohdonmukaisen historian, jonka API hylkää.

Koko virtaus yhdessä lohkossa

Tässä on koko prosessi käyttäjän kysymyksestä lopulliseen vastaukseen:

import os
import json
from mistralai.client import Mistral
from functools import partial

# Konfiguraatio
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"

# Funktiot ja työkalut (määritelty aiemmin)
available_functions = {
    "retrieve_payment_status": partial(retrieve_payment_status, df),
    "retrieve_payment_date": partial(retrieve_payment_date, df),
}

# Vaiheet 1-2: Käyttäjän kysymys + API-kutsu
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

response = client.chat.complete(
    model=model, messages=messages, tools=tools
)

# Vaiheet 3-4: Pura tool_call ja suorita se
message = response.choices[0].message

if message.tool_calls:
    tool_call = message.tool_calls[0]
    function_name = tool_call.function.name
    function_params = json.loads(tool_call.function.arguments)

    # Asiakaspuolen suoritus
    result = available_functions[function_name](**function_params)

    # Vaihe 5: Lähetä tulos takaisin mallille
    messages.append(message)
    messages.append({
        "role": "tool",
        "name": function_name,
        "content": result,
        "tool_call_id": tool_call.id
    })

    final_response = client.chat.complete(
        model=model, messages=messages, tools=tools
    )
    print(final_response.choices[0].message.content)
else:
    print(message.content)

Viestirakenne jokaisessa vaiheessa

On hyvä tarkastella messages-listaa kierron päätyttyä, sillä se on paras tapa vianetsiä toimivaa funktionkutsua. Lista sisältää neljä viestiä.

# Viesti 1: Käyttäjän kysymys
{"role": "user", "content": "What is the status of payment T1001?"}

# Viesti 2: Mallin vastaus tool_callilla
{"role": "assistant", "tool_calls": [{"id": "call_abc123", ...}]}

# Viesti 3: Funktion tulos
{"role": "tool", "name": "retrieve_payment_status",
 "content": '{"status": "paid"}', "tool_call_id": "call_abc123"}

# Viesti 4 (implisiittinen): Mallin lopullinen vastaus
# → "Payment T1001 status is: paid."

Seuraa ID:tä call_abc123: se syntyy viestissä 2 ja ilmestyy uudelleen viestissä 3. Tämä lanka yhdistää pyynnön vastaukseen. Tämä rakenne on funktionkutsun peruskaava; jokainen myöhemmin kohtaamasi variaatio, olipa kyseessä monivaiheinen tai rinnakkainen käsittely, vain toistaa tai monistaa sitä.

Huomioi sisältömuoto

Yksi virhe toistuu useammin kuin muut, ja se liittyy content-kentän tietotyyppiin: sen on oltava aina merkkijono.

# Oikein – JSON-merkkijono
{"content": '{"status": "paid"}'}

# Oikein – pelkkä teksti
{"content": "The status is paid"}

# Väärin – Python-sanakirja (aiheuttaa virheen)
{"content": {"status": "paid"}}

Ero ensimmäisen ja kolmannen esimerkin välillä on JSONia ympäröivissä lainausmerkeissä. Jos funktiosi palauttaa sanakirjan, muunna se json.dumps()-funktiolla ennen lähetystä – juuri siksi oppitunnin 4 kaikki funktiot päättyivät json.dumps()-kutsuun.

Keskeiset asiat

  • Funktion suoritus tapahtuu asiakaspuolella, sinun koodissasi – ei koskaan mallin toimesta
  • Tulos lähetetään takaisin viestinä, jonka rooli on "tool" ja jossa on vastaava tool_call_id
  • Tool-viestin content-kentän on oltava merkkijono (JSON-merkkijono)
  • Tuloksen lähettämisen jälkeen kutsut chat.complete()-metodia uudelleen, jotta malli voi muotoilla lopullisen vastauksen
  • Varmista aina, että pyydetty funktio on olemassa dispatch-sanakirjassasi