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

Ensimmäinen API-pyyntösi Pythonilla

Oppitunti 5 / 14 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Ensimmäinen vuorovaikutuksesi Mistral-mallin kanssa
  2. Asiakkaan alustus
  3. Pynnön lähetys metodilla chat.complete()
  4. Palautetun objektin lukeminen
  5. Mallin käytöksen säätäminen
  6. Tuotantovalmis kutsu
  7. Keskeiset asiat

Ensimmäinen vuorovaikutuksesi Mistral-mallin kanssa

SDK on asennettu ja API-avaimesi on valmiina: on aika lähettää todellinen pyyntö ja, mikä tärkeintä, ymmärtää, mitä vastauksena palautuu. Monet kehittäjät pysähtyvät vastauksen ensimmäiseen riviin ja jättävät huomiotta palautetun objektin loppuosan. Se on virhe, sillä kustannusten seuranta ja typistyneiden vastausten diagnostiikka löytyvät nimenomaan tuosta jäljellä olevasta datasta. Aloitamme minimaalisella koodilla ja etenemme kohti täyttä rakennetta.

Asiakkaan alustus

Asiakas (client) on sisäänkäyntipisteesi kaikkiin API-vuorovaikutuksiin:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Se hallitsee HTTP-yhteyksiä, uudelleenyrityksiä verkkovirheiden varalta ja pyyntöjen sarjoitusta. Luo instanssi vain kerran sovelluksen käynnistyessä. Asiakkaan luominen uudelleen jokaista kutsua varten pakottaa sinut maksamaan turhaan yhteyden muodostamisesta ja on yksi hienovaraisimmista liiallisen viiveen syistä.

Pynnön lähetys metodilla chat.complete()

Käytät useimmiten metodia chat.complete(). Se lähettää viestisi ja odottaa mallin täydellistä vastausta ennen kontrollin palauttamista:

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": "Selitä tokenisoinnin käsite kolmella lauseella."
        }
    ]
)

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

Tässä riittää kaksi parametria. model määrittää mallin tunnisteen: mistral-small-latest viittaa aina Mistral Small -mallin uusimpaan versioon, mikä tekee siitä luontevan valinnan aloittamiseen, sillä se on nopea ja edullinen. messages odottaa listaa strukturoituja viestejä, joista jokaisessa on role – system, user tai assistant – sekä tekstiä sisältävä content-kenttä. Tämä rakenne saattaa vaikuttaa raskaalta yhtä kysymystä varten, mutta se saa täyden merkityksensä, kun pääset monivaiheisten keskustelujen oppitunnille.

Palautetun objektin lukeminen

response-objekti sisältää paljon muutakin kuin pelkän generoidun tekstin:

# Vastausteksti
text = response.choices[0].message.content

# Rooli (vastauksessa aina "assistant")
role = response.choices[0].message.role

# Pysäytyssyy
finish = response.choices[0].finish_reason  # "stop", "length" jne.

# Token-tilastot
input_tokens = response.usage.prompt_tokens
output_tokens = response.usage.completion_tokens
total_tokens = response.usage.total_tokens

print(f"Vastaus ({output_tokens} tokenia): {text}")
print(f"Tokeneita kulutettu yhteensä: {total_tokens}")

Kiinnitä alusta asti erityistä huomiota usage-kenttään. Sen kirjaaminen jokaisessa kutsussa kertoo tarkasti, mikä sovelluksesi ominaisuus polttaa budjettiasi, ilman että sinun tarvitsee käänteissuunnitella laskuasi kuukauden lopussa.

finish_reason puolestaan ilmaisee, miksi malli pysähtyi, ja se saa yhden seuraavista arvoista:

  • stop: malli viimeisteli vastauksensa luonnollisesti
  • length: vastaus katkaistiin, koska se osui max_tokens-rajaan
  • model_length: koko konteksti (syöte + tuloste) saavutti mallin rajan

Kesken lauseen päättyvä vastaus ei ole mallin bugi: se on finish_reason-arvo length, jota kukaan ei tarkistanut. Tarkista tämä aina ennen kuin päättelet laadun olevan heikko.

Mallin käytöksen säätäminen

Kolme lisäparametria antaa sinun ohjata generointia:

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "user",
            "content": "Ehdota kolme nimeä koulutusteknologiayritykselle."
        }
    ],
    temperature=0.7,
    max_tokens=500,
    top_p=0.95,
)

Temperature hallitsee mallin vapausastetta. Arvolla 0.0 vastaukset ovat deterministisiä: sama kehote tuottaa aina saman tekstin, mikä on toivottavaa esimerkiksi tiedonpoiminnassa tai luokittelussa. Välillä 0.3–0.5 saat hyvän tasapainon faktoihin perustuviin tehtäviin. Välillä 0.7–1.0 vastaukset muuttuvat luovemmiksi ja vaihtelevammiksi – tätä aluetta käytetään yllä olevassa esimerkissä, sillä pyydämme nimiehdotuksia, ja sama idea kolmeen kertaan olisi hyödytön. Yli 1.0 generointi muuttuu erittäin satunnaiseksi ja harvoin käytännölliseksi.

max_tokens rajoittaa vastauksen pituutta, mikä auttaa hallitsemaan kustannuksia ja pitämään tulosteet hallittavina. Muista vain, että jos malli katkaistaan, finish_reason on "length". top_p vaikuttaa monimuotoisuuteen eri mekanismilla: se suodattaa pois epätodennäköisimmät tokenit. Arvo 0.95 tarkoittaa, että malli ottaa huomioon vain ne tokenit, jotka edustavat 95 % kumulatiivisesta todennäköisyydestä.

Tuotantovalmis kutsu

Todellisissa olosuhteissa verkko pätkii, avaimet vanhentuvat ja kiintiöt täyttyvät. Kääri aina kutsusi virheenkäsittelyn sisään:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

try:
    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[
            {"role": "user", "content": "Mikä on Ranskan pääkaupunki?"}
        ],
        max_tokens=100,
    )

    text = response.choices[0].message.content
    print(f"Vastaus: {text}")
    print(f"Käytetyt tokenit: {response.usage.total_tokens}")

except Exception as e:
    print(f"API-kutsun virhe: {e}")

Käytä tätä runkoa omiin kokeiluihisi korvaamalla vain viestin sisältö. Se on lähtökohta kaikelle, mitä tässä kurssissa seuraa.

Keskeiset asiat

  • client.chat.complete() on ensisijainen metodi mallien kanssa vuorovaikutukseen
  • Vastausteksti löytyy kohdasta response.choices[0].message.content
  • response.usage kertoo kulutettujen tokenien määrän (hyödyllinen kustannusten seurannassa)
  • temperature ohjaa luovuutta; max_tokens rajoittaa pituutta
  • Aloita mallilla mistral-small-latest: se on nopea, edullinen ja suorituskykyinen