Răspuns și Utilizare
Pe această pagină
Înțelegeți ce returnează API-ul
Majoritatea dezvoltatorilor care descoperă API-ul citesc o singură linie din răspuns – textul generat – și ignoră tot restul. Aceasta este o greșeală. Fiecare apel către /v1/chat/completions returnează un obiect JSON bogat. Aici veți găsi datele necesare pentru a urmări costurile, pentru a detecta un răspuns trunchiat înainte ca acesta să ajungă la utilizator și pentru a identifica un apel specific atunci când deschideți un tichet de suport.
Anatomia completă a răspunsului
Să începem cu metadatele. Acestea sunt câmpurile pe care rareori le verificați, dar pe care vă veți dori să le fi înregistrat în ziua în care apare un 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}")
Câmpul id este un identificator unic atribuit fiecărei cereri. Aceasta este referința pe care o veți furniza suportului tehnic și cea care vă permite să legați o plângere a utilizatorului de un apel specific din jurnalele dumneavoastră. Câmpul model confirmă modelul care a fost utilizat efectiv. Acest aspect este mai important decât ați putea crede atunci când apelați un alias -latest, iar comportamentul se schimbă peste noapte fără nicio modificare de cod din partea dumneavoastră.
Tabloul choices
Nucleul răspunsului se află în choices. În mod implicit, acest tablou conține un singur element. Din acesta extrageți atât textul, cât și verdictul privind modul în care s-a încheiat generarea:
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"
Dacă solicitați mai multe răspunsuri folosind parametrul n, pe care îl vom aborda în lecția 15, choices va conține mai multe elemente, iar indexul va deveni din nou semnificativ.
Valorile finish_reason
Acest câmp determină fiabilitatea aplicației dumneavoastră. Există trei valori posibile. stop semnalează că modelul și-a finalizat răspunsul în mod natural. Acesta este cazul normal, în care puteți afișa conținutul fără rezerve. length înseamnă că generarea a fost întreruptă de max_tokens, deci răspunsul este potențial incomplet – un rezumat căruia îi lipsește concluzia sau o listă care se oprește la al șaptelea element. În final, tool_calls indică faptul că modelul solicită executarea unui instrument extern ca parte a apelului de funcție, iar mingea este acum în terenul dumneavoastră.
Fiecare dintre aceste cazuri necesită o gestionare distinctă, pe care ar trebui să o scrieți o dată pentru totdeauna:
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}")
Observați că ramura length nu se limitează la a lăsa textul să treacă mai departe. Fie reîncercați cu o limită mai mare, fie cereți modelului să continue, fie avertizați utilizatorul. Ceea ce nu trebuie să faceți niciodată este să afișați un text trunchiat ca și cum ar fi complet.
Obiectul usage – Urmăriți-vă costurile
Câmpul usage numără tokenii consumați de cerere, separând intrarea de ieșire:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Această distincție nu este cosmetică. Modelele Mistral au tarife diferite pentru intrare și ieșire. O funcționalitate care trimite un context lung pentru a primi trei cuvinte înapoi are un profil de cost complet diferit față de un draft lung generat dintr-un prompt scurt. Calculul necesită doar câteva linii:
# 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}")
Un singur apel costă o fracțiune de cent, ceea ce este fals reconfortant. Înmulțiți acest cost cu traficul real al unei aplicații, iar întrebarea devine: care funcționalitate consumă ce? Pentru a răspunde la aceasta, agregați metricile de utilizare încă de la prima dumneavoastră implementare. Înregistrați fiecare apel împreună cu numele funcționalității care l-a declanșat:
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")
Un fișier JSONL precum acesta, revizuit după două săptămâni, vă va spune fără ambiguitate care ecran din produsul dumneavoastră cântărește cel mai greu în factură – și câte apeluri se încheie cu length.
Conținutul răspunsului
Câmpul content al mesajului asistentului poate lua două forme, exact ca în partea de cerere:
# 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": "..."}]
În practică, pentru apelurile standard Chat Completions, content este întotdeauna un șir de caractere. Forma structurată este rezervată răspunsurilor multimodale.
Puneți în practică
Să reunim toate acestea într-o funcție utilitară – cea pe care o veți copia din proiect în proiect. Aceasta asamblează mesajele, efectuează apelul și returnează un dicționar care expune atât metricile, cât și textul:
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
}
Punctul cheie este ceea ce returnează funcția: niciodată doar textul. Prin propagarea către apelant a câmpurilor finish_reason, a numărului de tokeni și a ID-ului cererii, faceți imposibilă cea mai comună eroare – tratarea unui răspuns întrerupt ca fiind unul valid.
Puncte cheie
- Răspunsul conține
choices(conținut),usage(tokeni) și metadate (id,model) - Verificați întotdeauna
finish_reason–lengthînseamnă un răspuns incomplet usagenumără tokenii de intrare și de ieșire separat pentru o urmărire precisă a costurilor- Configurați înregistrarea metricilor încă de la prima implementare în producție
- Câmpul
ideste esențial pentru depanare și suport tehnic