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

Vastaus ja käyttö

Oppitunti 4 / 16 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Ymmärrä, mitä API palauttaa
  2. Vastauksen täydellinen anatomia
  3. choices-taulukko
  4. finish_reason-arvot
  5. usage-objekti – seuraa kustannuksiasi
  6. Vastauksen sisältö
  7. Ota käyttöön käytännössä
  8. Keskeiset asiat

Ymmärrä, mitä API palauttaa

Useimmat kehittäjät, jotka ovat uusia API:n käytössä, lukevat vastauksesta vain yhden rivin – generoidun tekstin – ja jättävät kaiken muun huomiotta. Se on virhe. Jokainen /v1/chat/completions-kutsu palauttaa laajan JSON-objektin. Täältä löydät tiedot, joita tarvitset kustannusten seurantaan, typistyneen vastauksen havaitsemiseen ennen kuin se reaches käyttäjälle, sekä tietyn kutsun paikantamiseen, kun avaat tukipyynnön.

Vastauksen täydellinen anatomia

Aloitetaan metatiedoista. Nämä ovat kenttiä, joita tarkistat harvoin, mutta toivot niiden olevan lokissa sinä päivänä, kun incidentti tapahtuu:

from mistralai.client import Mistral
import os

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

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "What is machine learning?"}],
    max_tokens=500
)

# Access metadata
print(f"Request ID : {response.id}")
print(f"Model used : {response.model}")
print(f"Created at : {response.created}")

id-kenttä on yksilöllinen tunniste, joka annetaan jokaiselle pyynnölle. Tämä on viite, jonka annat tekniselle tuelle, ja se, jonka avulla voit linkittää käyttäjän valituksen tiettyyn kutsuun lokeissasi. model-kenttä vahvistaa, mitä mallia todella käytettiin. Tämä on tärkeämpää kuin luuletkaan, kun kutsut -latest-aliasta ja käyttäytyminen muuttuu yön yli ilman, että koodissasi on tehty muutoksia.

choices-taulukko

Vastauksen ydin on choices-taulukossa. Oletusarvoisesti tämä taulukko sisältää yhden elementin. Siitä erotat sekä tekstin että tuomion siitä, miten generointi päättyi:

choice = response.choices[0]

# The generated message
print(choice.message.role)      # "assistant"
print(choice.message.content)   # The response text

# The index of this response in the array
print(choice.index)             # 0

# The stop reason
print(choice.finish_reason)     # "stop", "length", or "tool_calls"

Jos pyydät useita vastauksia käyttämällä n-parametria, jota käsittelemme oppitunnilla 15, choices sisältää useita elementtejä, ja indeksistä tulee jälleen merkityksellinen.

finish_reason-arvot

Tämä kenttä määrittää sovelluksesi luotettavuuden. Mahdollisia arvoja on kolme. stop ilmoittaa, että malli viimeisteli vastauksensa luonnollisesti. Tämä on normaali tapaus, jossa voit näyttää sisällön ilman varaumia. length tarkoittaa, että generointi katkaistiin max_tokens-rajoituksen vuoksi, joten vastaus on mahdollisesti epätäydellinen – yhteenveto, josta puuttuu johtopäätös, tai lista, joka pysähtyy seitsemänteen kohteeseen. Lopuksi tool_calls osoittaa, että malli pyytää ulkoisen työkalun suorittamista osana funktion kutsumista, ja pallo on nyt sinun kentälläsi.

Jokainen näistä tapauksista vaatii erilaista käsittelyä, joka sinun tulee kirjoittaa kerran ja lopullisesti:

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Write a detailed report."}],
    max_tokens=200
)

choice = response.choices[0]

if choice.finish_reason == "stop":
    # Complete response — normal processing
    result = choice.message.content

elif choice.finish_reason == "length":
    # Truncated response — retry with more tokens or warn the user
    print("Warning: The response was truncated.")
    # Option: Retry with a higher max_tokens limit
    # Option: Ask the model to continue

elif choice.finish_reason == "tool_calls":
    # The model requests a tool call
    for tool_call in choice.message.tool_calls:
        print(f"Requested tool: {tool_call.function.name}")

Huomaa, että length-haara ei vain anna tekstin mennä läpi. Joko yrität uudelleen suuremmalla rajalla, pyydät mallia jatkamaan tai varoitat käyttäjää. Sitä, mitä et koskaan saa tehdä, on näyttää typistynyttä tekstiä ikään kuin se olisi täydellinen.

usage-objekti – seuraa kustannuksiasi

usage-kenttä laskee pyynnön kuluttamat tokenit erottaen syötteen ja tulosteen:

usage = response.usage

print(f"Input tokens  : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total         : {usage.total_tokens}")

Tämä ero ei ole kosmeettinen. Mistral-malleilla on eri hinnat syötteelle ja tulosteelle. Ominaisuudella, joka lähettää pitkän kontekstin saadakseen takaisin kolme sanaa, on täysin erilainen kustannusprofiili kuin pitkällä luonnoksella, joka generoidaan lyhyestä kehotteesta. Laskenta vie vain muutaman rivin:

# Hypothetical rates per million tokens (check current pricing)
RATE_INPUT = 2.0    # $/M tokens input
RATE_OUTPUT = 6.0   # $/M tokens output

cost_input = (usage.prompt_tokens / 1_000_000) * RATE_INPUT
cost_output = (usage.completion_tokens / 1_000_000) * RATE_OUTPUT
cost_total = cost_input + cost_output

print(f"Cost of this call: ${cost_total:.6f}")

Yksi kutsu maksaa murto-osan sentistä, mikä on petollisen rauhoittavaa. Kerro tämä sovelluksen todellisella liikenteellä, ja kysymys kuuluu: mikä ominaisuus kuluttaa mitä? Vastataksesi tähän, kokoa käyttömittarit heti ensimmäisestä käyttöönotostasi alkaen. Lokita jokainen kutsu yhdessä sen ominaisuuden nimen kanssa, joka sen laukaisi:

import json
from datetime import datetime

def log_usage(response, endpoint_name: str):
    """Logs usage metrics for each API call."""
    log_entry = {
        "timestamp": datetime.utcnow().isoformat(),
        "endpoint": endpoint_name,
        "model": response.model,
        "prompt_tokens": response.usage.prompt_tokens,
        "completion_tokens": response.usage.completion_tokens,
        "total_tokens": response.usage.total_tokens,
        "finish_reason": response.choices[0].finish_reason,
        "request_id": response.id
    }

    with open("api_usage.jsonl", "a") as f:
        f.write(json.dumps(log_entry) + "\n")

# Usage
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello"}]
)
log_usage(response, "main_chatbot")

Tällainen JSONL-tiedosto, jota tarkastellaan kahden viikon kuluttua, kertoo sinulle yksiselitteisesti, mikä näyttö tuotteessasi rasittaa laskua eniten – ja kuinka monta kutsua päättyy arvoon length.

Vastauksen sisältö

Avustajaviestin content-kenttä voi olla kahdessa muodossa, aivan kuten pyyntöpuolellakin:

# Simple form — string
content = response.choices[0].message.content
# "Machine learning is a branch of artificial intelligence..."

# Structured form — list of blocks (rare in standard chat)
# [{"type": "text", "text": "..."}]

Käytännössä tavallisissa Chat Completions -kutsuissa content on aina merkkijono. Jäsennelty muoto on varattu multimodaalisille vastauksille.

Ota käyttöön käytännössä

Kootaan kaikki tämä hyötyfunktioksi – sellaiseksi, jonka kopioit projektista toiseen. Se kokoaa viestit, tekee kutsun ja palauttaa sanakirjan, joka paljastaa sekä mittarit että tekstin:

from mistralai.client import Mistral

def chat_complete(
    client: Mistral,
    prompt: str,
    system: str = "",
    model: str = "mistral-large-latest",
    max_tokens: int = 1000
) -> dict:
    """Chat Completions call with error handling and metrics."""
    messages = []
    if system:
        messages.append({"role": "system", "content": system})
    messages.append({"role": "user", "content": prompt})

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

    return {
        "content": response.choices[0].message.content,
        "finish_reason": response.choices[0].finish_reason,
        "tokens_in": response.usage.prompt_tokens,
        "tokens_out": response.usage.completion_tokens,
        "model": response.model,
        "id": response.id
    }

Avainasia on se, mitä funktio palauttaa: ei koskaan pelkkää tekstiä. Nostamalla finish_reason-arvon, token-määrät ja pyynnön tunnisteen kutsujalle teet yleisimmästä virheestä mahdotonta – katkaistun vastauksen kohtelemisen kelvollisena.

Keskeiset asiat

  • Vastaus sisältää choices (sisältö), usage (tokenit) ja metatiedot (id, model)
  • Tarkista aina finish_reason – length tarkoittaa epätäydellistä vastausta
  • usage laskee syöte- ja tulostetokenit erikseen tarkkaa kustannusseurantaa varten
  • Määritä mittareiden lokitus heti ensimmäisestä tuotantokäyttöönotosta alkaen
  • id-kenttä on välttämätön vianetsinnässä ja teknisessä tuessa