Odgovor i korištenje
Na ovoj stranici
Razumijevanje onoga što API vraća
Većina developera koji tek počinju koristiti API pročita samo jedan redak odgovora – generirani tekst – i ignorira sve ostalo. To je pogreška. Svaki poziv na /v1/chat/completions vraća bogati JSON objekt. Upravo tu ćeš pronaći podatke potrebne za praćenje troškova, otkrivanje skraćenog odgovora prije nego što stigne do korisnika i precizno lociranje određenog poziva kada otvoriš tiket za podršku.
Potpuna anatomija odgovora
Započnimo s metapodacima. To su polja koja rijetko provjeravaš, a poželjet ćeš da si ih bilježio onog dana kada se dogodi incident:
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 jedinstveni je identifikator dodijeljen svakom zahtjevu. To je referenca koju ćeš dostaviti tehničkoj podršci i koja ti omogućuje povezivanje pritužbe korisnika s određenim pozivom u tvojim zapisnicima. Polje model potvrđuje koji je model zapravo korišten. To je važnije nego što možda misliš kada zoveš alias -latest, a ponašanje se promijeni preko noći bez ikakvih promjena u tvom kodu.
Niz choices
Srce odgovora nalazi se u choices. Prema zadanim postavkama, ovaj niz sadrži jedan element. Iz njega izvlačiš i tekst i presudu o tome kako je generiranje završilo:
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"
Ako zatražiš više odgovora korištenjem parametra n, što ćemo obraditi u lekciji 15, choices će sadržavati više elemenata, a indeks će ponovno dobiti smisao.
Vrijednosti finish_reason
Ovo polje određuje pouzdanost tvoje aplikacije. Postoje tri moguće vrijednosti. stop signalizira da je model prirodno završio svoj odgovor. To je uobičajeni slučaj u kojem možeš prikazati sadržaj bez zadrške. length znači da je generiranje prekinuto zbog max_tokens, pa je odgovor potencijalno nepotpun – sažetak kojem nedostaje zaključak ili popis koji staje na sedmoj stavci. Konačno, tool_calls ukazuje da model zahtijeva izvršenje vanjskog alata kao dio pozivanja funkcija, a lopta je sada na tvojoj strani.
Svaki od ovih slučajeva zahtijeva različito postupanje, koje trebaš napisati jednom zauvijek:
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}")
Primijeti da grana length ne propušta tekst tek tako. Ili pokušavaš ponovno s većom granicom, tražiš od modela da nastavi ili upozoravaš korisnika. Ono što nikada ne smiješ učiniti jest prikazati skraćeni tekst kao da je potpun.
Objekt usage – Praćenje tvojih troškova
Polje usage broji tokene potrošene zahtjevom, odvajajući ulaz od izlaza:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Ova razlika nije kozmetička. Mistral modeli imaju različite cijene za ulaz i izlaz. Značajka koja šalje dugačak kontekst da bi dobila tri riječi natrag ima potpuno drugačiji profil troškova od dugog nacrta generiranog iz kratkog upita. Izračun zahtijeva samo nekoliko redaka:
# 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}")
Jedan poziv košta djelić centa, što je varljivo umirujuće. Pomnoži li to sa stvarnim prometom aplikacije, pitanje postaje: koja značajka troši što? Da bi odgovorio na to, agregiraj metrike korištenja od samog prvog uvođenja u proizvodnju. Zabilježi svaki poziv zajedno s nazivom značajke koja ga je pokrenula:
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")
JSONL datoteka poput ove, pregledana nakon dva tjedna, nedvosmisleno će ti reći koji zaslon u tvom proizvodu najviše opterećuje račun – i koliko poziva završava s length.
Sadržaj odgovora
Polje content poruke asistenta može imati dva oblika, točno kao i na strani zahtjeva:
# 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": "..."}]
U praksi, za standardne pozive Chat Completions, content je uvijek niz znakova. Strukturirani oblik rezerviran je za multimodalne odgovore.
Primjena u praksi
Spojimo sve ovo u pomoćnu funkciju – onu koju ćeš kopirati iz projekta u projekt. Ona sastavlja poruke, izvršava poziv i vraća rječnik koji izlaže i metrike i tekst:
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 je stvar što funkcija vraća: nikada samo tekst. Podizanjem finish_reason, broja tokena i ID-ja zahtjeva do pozivatelja, činiš najčešću pogrešku nemogućom – tretiranje prekinutog odgovora kao valjanog.
Ključne točke
- Odgovor sadrži
choices(sadržaj),usage(tokeni) i metapodatke (id,model) - Uvijek provjeri
finish_reason–lengthznači nepotpun odgovor usagezasebno broji ulazne i izlazne tokene za precizno praćenje troškova- Postavi bilježenje metrika od prvog uvođenja u proizvodnju
- Polje
idključno je za otklanjanje pogrešaka i tehničku podršku