Odgovor in uporaba
Na tej strani
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–lengthpomeni nepopoln odgovor usageločeno šteje vhodne in izhodne žetone za natančno sledenje stroškom- Vzpostavite beleženje metrik že ob prvem uvajanju v proizvodnjo
- Polje
idje bistveno za odpravljanje napak in tehnično podporo