Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Vastus ja kasutamine

Õppetund 4 / 16 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Mõistke, mida API tagastab
  2. Vastuse täielik anatoomia
  3. Massiiv choices
  4. Väärtused väljal finish_reason
  5. Objekt usage – jälgi oma kulusid
  6. Vastuse sisu
  7. Rakenda praktikas
  8. Peamised punktid

Mõistke, mida API tagastab

Enamik arendajaid, kes API-ga alles alustavad, loevad vastusest vaid ühe rea – genereeritud teksti – ja ignoreerivad kõike muud. See on viga. Iga päring liidesesse /v1/chat/completions tagastab mahuka JSON-objekti. Just sealt leiad andmed, mida vajad kulude jälgimiseks, katkenud vastuse tuvastamiseks enne, kui see kasutajani jõuab, ning konkreetse päringu leidmiseks tugiteenusele pöördumisel.

Vastuse täielik anatoomia

Alustame metaandmetest. Need on väljad, mida sa harva kontrollid, kuid soovid hiljem, et oleksid need logisse kirjutanud just siis, kui juhtub intsident:

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}")

Väli id on kordumatu identifikaator, mis omistatakse igale päringule. See on viide, mille esitad tehnilisele toele, ja see, mis võimaldab sul seostada kasutaja kaebuse konkreetse päringuga oma logides. Väli model kinnitab, millist mudelit tegelikult kasutati. See on olulisem, kui arvata oskad, kui kasutad -latest aliast ja käitumine muutub üleöö ilma, et sa oleksid koodis midagi muutnud.

Massiiv choices

Vastuse tuum peitub väljas choices. Vaikimisi sisaldab see massiiv ühte elementi. Sealt ekstraheerid nii teksti kui ka otsuse selle kohta, kuidas genereerimine lõppes:

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"

Kui taotled parameetri n abil mitut vastust (mida käsitleme 15. tunnis), sisaldab choices mitut elementi ja indeks muutub taas tähenduslikuks.

Väärtused väljal finish_reason

See väli määrab sinu rakenduse usaldusväärsuse. Võimalikke väärtusi on kolm. stop annab märku, et mudel lõpetas vastuse loomulikul teel. See on normaalne juhtum, kus saad sisu ilma reservatsioonideta kuvada. length tähendab, et genereerimine katkestati parameetri max_tokens tõttu, seega on vastus potentsiaalselt mittetäielik – kokkuvõte, millest puudub järeldus, või loend, mis peatub seitsmendal üksusel. Lõpuks näitab tool_calls, et mudel taotleb funktsioonide kutsumise raames välise tööriista käivitamist ja pall on nüüd sinu poolväljakul.

Iga neist juhtumitest nõuab erinevat käsitlemist, mille peaksid kirjutama üks kord ja igaveseks:

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}")

Pane tähele, et haru length ei lase tekstil lihtsalt läbi minna. Sa kas proovid uuesti suurema piiranguga, palud mudelil jätkata või hoiatad kasutajat. Mida sa mitte kunagi teha ei tohi, on katkestatud teksti kuvamine nii, nagu oleks see täielik.

Objekt usage – jälgi oma kulusid

Väli usage loendab päringu tarbitud tokeneid, eristades sisendit ja väljundit:

usage = response.usage

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

See eristus pole pelgalt kosmeetiline. Mistrali mudelitel on sisendi ja väljundi jaoks erinevad hinnad. Funktsioonil, mis saadab pika konteksti, et saada vastu kolm sõna, on hoopis teistsugune kuluprofiil võrreldes lühikesest vihjest genereeritud pika mustandiga. Arvutamine võtab vaid mõned read:

# 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}")

Üksik päring maksab murdosa sendist, mis on petlikult rahustav. Korruta see rakenduse tegeliku liiklusega ja küsimus muutub: milline funktsioon tarbib mida? Sellele vastamiseks koonda kasutusmõõdikud juba oma esimesest tootmisse viimisest alates. Logi iga päring koos selle käivitanud funktsiooni nimega:

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")

Selline JSONL-fail, mida kahe nädala pärast üle vaatad, ütleb sulle üheselt, milline ekraan sinu tootes arvet kõige rohkem koormab – ja kui palju päringuid lõpeb väärtusega length.

Vastuse sisu

Abilise sõnumi väli content võib võtta kaks vormi, täpselt nagu päringu poolelgi:

# 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": "..."}]

Praktikas on standardsete Chat Completions päringute puhul content alati string. Struktureeritud vorm on reserveeritud multimodaalsetele vastustele.

Rakenda praktikas

Viime kõik selle kokku ühte utiliidifunktsiooni – sellesse, mida kopeerid projektist projekti. See koostab sõnumid, teeb päringu ja tagastab sõnastiku, mis avaldab nii mõõdikud kui ka teksti:

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
    }

Põhipunkt on selles, mida funktsioon tagastab: mitte kunagi ainult teksti. Tõstes finish_reason-i, tokenite arvud ja päringu ID ülespoole kutsujale, muudad kõige levinuma vea võimatuks – katkestatud vastuse käsitlemise kehtivana.

Peamised punktid

  • Vastus sisaldab välju choices (sisu), usage (tokenid) ja metaandmeid (id, model)
  • Kontrolli alati väärtust finish_reason – length tähendab mittetäielikku vastust
  • usage loendab sisendi ja väljundi tokeneid eraldi täpseks kulude jälgimiseks
  • Seadista mõõdikute logimine juba oma esimesest tootmisse viimisest alates
  • Väli id on hädavajalik silumiseks ja tehniliseks toeks