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

Roolit ja viestit

Oppitunti 2 / 16 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Keskusteluprotokollan ydin
  2. Neljä roolia
  3. Monivaiheisen vuorovaikutuksen täydellinen rakenne
  4. Jäsennelty sisältö
  5. Etuliite-lippu (Prefix Flag)
  6. Keskeiset asiat

Keskusteluprotokollan ydin

Chat Completions -API ei hyväksy raakatekstiä. Se odottaa jäsenneltyjen viestien taulukkoa, jossa jokaiselle on määritetty tietty rooli. Tämä roolijärjestelmä antaa mallille mahdollisuuden erottaa, kuka puhuu, mikä on konteksti ja miten sen tulee vastata. Sama teksti – “Vastaa aina JSON-muodossa” – painaa eri lailla riippuen siitä, saapuuko se kehittäjän ohjeena vai käyttäjän syötteenä. Tämän rakenteen hallitseminen on se, mikä erottaa johdonmukaisen chatbotin järjestelmästä, joka ajautuu aiheen vierestä kolmen vuorovaikutuksen jälkeen.

Neljä roolia

Mistralin API tunnistaa neljä erillistä roolia, joista jokaisella on tarkka tehtävä keskustelussa.

system-rooli

Järjestelmäviesti määrittelee mallin yleisen käyttäytymisen. Se sijoitetaan ensimmäiseksi, ja malli lukee sen ennen kuin mitään vuorovaikutusta tapahtuu. Täällä määrität sovelluksesi sävyn, rajoitukset ja kontekstin. Kuvittele lakitoimistolle suunniteltu avustaja; järjestelmäviesti vastaa muistiota, jonka antaisit uudelle harjoittelijalle ennen hänen ensimmäistä tapaustaan.

messages = [
    {
        "role": "system",
        "content": "You are a legal assistant specializing in French law. "
                   "Respond precisely and cite relevant legal articles. "
                   "If you are unsure, state it explicitly."
    }
]

Kehittäjä hallinnoi tätä viestiä, ei koskaan loppukäyttäjä, eikä se koskaan näy sovelluksesi käyttöliittymässä.

user-rooli

Seuraavaksi tulee ihmiskäyttäjän viesti: kysymys, ohje tai käsiteltävä teksti. Tämä on ainoa osa keskustelua, jota käyttäjäsi voivat suoraan hallita.

messages.append({
    "role": "user",
    "content": "What are the statutes of limitations in civil law?"
})

assistant-rooli

Tämä rooli sisältää mallin aiemmat vastaukset. Se muuttuu välttämättömäksi, kun keskustelu ylittää yhden vuoron. Ilman sitä käyttäjä, joka kysyy “Entä kaupalliset velat?”, saisi aiheen vierestä olevan vastauksen, koska malli ei tietäisi, mistä keskusteltiin.

messages.append({
    "role": "assistant",
    "content": "In French civil law, the standard statute of limitations is 5 years..."
})

tool-rooli

Viimeinen rooli astuu kuvaan funktiokutsujen aikana. Kun malli pyytää ulkoisen funktion suorittamista – esimerkiksi sää-API:n kyselyä – suoritat kyseisen funktion omassa päässäsi ja palautat tuloksen tämän roolin alla viitaten tietyn kutsun tunnisteeseen:

messages.append({
    "role": "tool",
    "content": '{"temperature": 22, "city": "Paris"}',
    "tool_call_id": "call_abc123"
})

Monivaiheisen vuorovaikutuksen täydellinen rakenne

Katsotaan näitä rooleja toiminnassa aidossa keskustelussa, jossa käyttäjä tarkentaa pyyntöään alkuperäisen vastauksen jälkeen:

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

conversation = [
    {
        "role": "system",
        "content": "You are a French chef. Propose simple and tasty recipes."
    },
    {
        "role": "user",
        "content": "I want to make a dessert with apples."
    }
]

# First turn
response = client.chat.complete(
    model="mistral-large-latest",
    messages=conversation
)

assistant_reply = response.choices[0].message.content
print(assistant_reply)

# Add response to history
conversation.append({"role": "assistant", "content": assistant_reply})

# Second turn
conversation.append({
    "role": "user",
    "content": "Can you adapt this recipe for 8 people?"
})

response = client.chat.complete(
    model="mistral-large-latest",
    messages=conversation
)

print(response.choices[0].message.content)

Huomaa, mitä tämä koodi todella tekee: jokaisella vuorolla se lähettää takaisin koko historian. Mallilla ei ole pysyvää muistia pyyntöjen välillä. “Tämä resepti” on järkevä vain, koska edellinen vastaus on edelleen taulukossa. Olet täysin vastuussa keskustelutilan hallinnasta.

Jäsennelty sisältö

content-kenttä hyväksyy kahta muotoa. Yleisin on yksinkertainen merkkijono. Mutta heti kun lähetät jotain muuta kuin tekstiä – esimerkiksi kuvan kuvailtavaksi – siirrytään tyypitettyjen lohkojen listaan:

# Simple content (text)
{"role": "user", "content": "Describe this image."}

# Structured content (multimodal)
{"role": "user", "content": [
    {"type": "text", "text": "Describe this image."},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

Etuliite-lippu (Prefix Flag)

Mistral tarjoaa ainutlaatuisen ominaisuuden: etuliite-lipun. Kirjoitat itse avustajan vastauksen alun, ja malli pakotetaan jatkamaan siitä eteenpäin. Tämä on uskomattoman tehokasta, kun tarvitset tuloksen jäsentämistä ilman pienintäkään virhemarginaalia.

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "system", "content": "You always respond in JSON."},
        {"role": "user", "content": "List 3 European capitals."},
        {"role": "assistant", "content": '{"capitals": [', "prefix": True}
    ]
)

Malli jatkaa generointia kohdan {"capitals": [ jälkeen, mikä poistaa välittömästi riskin nähdä tekstiä kuten “Tässä on JSON-tiedostosi:” ennen avaavaa aaltosulkuja. Tuotantoympäristössä tämä muototakuu on usein arvokkaampi kuin järjestelmäviestiin kolme kertaa toistettu ohje.

Omaksu heti kaksi tapaa. Pidä järjestelmäviesti ytimekkäänä: yksi hyvin kirjoitettu kappale tuottaa parempia tuloksia kuin kaksi sivua sääntöjä, joista osan malli lopulta ignoroisi. Älä koskaan keksi vääriä avustajan vastauksia mallin ohjaamiseksi, yhtä poikkeusta lukuun ottamatta – few-shot learning, jota käsittelemme oppitunnilla 10. Pitkissä keskusteluissa lähetä koko historia, mutta valvo konteksti-ikkunaa ja karsi vanhimpia vuoroja ennen kuin ylität sen rajan.

Keskeiset asiat

  • Neljä roolia: system (käyttäytyminen), user (pyyntö), assistant (vastaus), tool (funktion tulos)
  • Järjestelmäviesti tulee ensimmäisenä ja määrittelee sovelluksen puitteet
  • Mallilla ei ole muistia: lähetä koko historia jokaisen pyynnön mukana
  • Etuliite-lippu pakottaa vastauksen alun hallitsemaan tulosteen muotoa