Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Odgovor in uporaba

Lekcija 4 od 16 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Razumevanje vsebine odgovora API-ja
  2. Popolna anatomija odgovora
  3. Polje choices
  4. Vrednosti finish_reason
  5. Objekt usage – Sledenje stroškom
  6. Vsebina odgovora
  7. Uvedba v prakso
  8. Ključne ugotovitve

Razumevanje vsebine odgovora API-ja

Večina razvijalcev, ki se prvič sreča z API-jem, prebere le eno vrstico odgovora – generirano besedilo – in prezre vse ostalo. To je napaka. Vsak klic na /v1/chat/completions vrne bogat objekt JSON. Tu najdete podatke, ki jih potrebujete za sledenje stroškom, zaznavanje obrezanih odgovorov, preden pridejo do uporabnika, in natančno določitev specifičnega klica pri odpiranju zahtevka za podporo.

Popolna anatomija odgovora

Začnimo z metapodatki. To so polja, ki jih redko preverite, a si boste želeli, da bi jih beležili, ko pride do incidenta:

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

Polje id je edinstven identifikator, dodeljen vsaki zahtevi. To je referenca, ki jo boste posredovali tehnični podpori, in tista, ki vam omogoča povezavo pritožbe uporabnika z določenim klicem v vaših dnevnikih. Polje model potrjuje, kateri model je bil dejansko uporabljen. To je pomembneje, kot si morda mislite, ko kličete alias -latest in se vedenje čez noč spremeni brez kakršnih koli sprememb kode na vaši strani.

Polje choices

Srce odgovora leži v polju choices. Privzeto to polje vsebuje en sam element. Iz njega izvlečete tako besedilo kot sodbo o tem, kako se je generiranje končalo:

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"

Če zahtevate več odgovorov z uporabo parametra n, kar bomo obravnavali v lekciji 15, bo choices vseboval več elementov in indeks bo spet postal smiseln.

Vrednosti finish_reason

To polje določa zanesljivost vaše aplikacije. Obstajajo tri možne vrednosti. stop signalizira, da je model naravno zaključil svoj odgovor. To je običajen primer, ko lahko vsebino prikažete brez zadržkov. length pomeni, da je bilo generiranje prekinjeno zaradi max_tokens, zato je odgovor potencialno nepopoln – povzetek brez zaključka ali seznam, ki se ustavi pri sedmi postavki. Nazadnje, tool_calls kaže, da model zahteva izvedbo zunanjega orodja kot del klicanja funkcij, in žoga je zdaj na vaši strani.

Vsak od teh primerov zahteva drugačno obravnavo, ki jo morate zapisati enkrat za vselej:

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

Opazite, veja length ne dopušča zgolj prehoda besedila naprej. Ali poskusite znova z višjo omejitvijo, prosite model za nadaljevanje ali opozorite uporabnika. Česar nikoli ne smete storiti, je prikazovanje obrezanega besedila, kot da bi bilo popolno.

Objekt usage – Sledenje stroškom

Polje usage šteje žetone, porabljene za zahtevo, in ločuje vhod od izhoda:

usage = response.usage

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

Ta razlika ni le kozmetična. Modeli Mistral imajo različne cene za vhod in izhod. Funkcija, ki pošlje dolg kontekst, da dobi tri besede nazaj, ima popolnoma drugačen profil stroškov kot dolg osnutek, generiran iz kratkega poziva. Izračun traja le nekaj vrstic kode:

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

En sam klic stane delček centa, kar je varljivo pomirjujoče. Pomnožite to z dejanskim prometom aplikacije in vprašanje postane: katera funkcija porabi koliko? Da bi na to odgovorili, agregirajte metrike uporabe že od prvega uvajanja v proizvodnjo. Beležite vsak klic skupaj z imenom funkcije, ki ga je sprožila:

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

Datoteka JSONL, kot je ta, pregledana po dveh tednih, vam bo nedvoumno povedala, kateri zaslon v vašem izdelku najbolj obremenjuje račun – in koliko klicev se konča z length.

Vsebina odgovora

Polje content sporočila asistenta ima lahko dve obliki, popolnoma enako kot na strani zahteve:

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

V praksi je pri standardnih klicih Chat Completions content vedno niz. Strukturirana oblika je rezervirana za multimodalne odgovore.

Uvedba v prakso

Združimo vse to v uporabni funkciji – tisti, ki jo boste kopirali iz projekta v projekt. Sestavi sporočila, opravi klic in vrne slovar, ki razkriva tako metrike kot besedilo:

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
    }

Ključna točka je, kaj funkcija vrne: nikoli samo besedila. S tem, ko posredujete finish_reason, število žetonov in ID zahteve klicatelju navzgor, onemogočite najpogostejšo napako – obravnavanje prekinjenega odgovora kot veljavnega.

Ključne ugotovitve

  • Odgovor vsebuje choices (vsebina), usage (žetoni) in metapodatke (id, model)
  • Vedno preverite finish_reason – length pomeni nepopoln odgovor
  • usage ločeno šteje vhodne in izhodne žetone za natančno sledenje stroškom
  • Vzpostavite beleženje metrik že ob prvem uvajanju v proizvodnjo
  • Polje id je bistveno za odpravljanje napak in tehnično podporo