Odpoveď a použitie
Na tejto strane
Pochopte, čo API vracia
Väčšina vývojárov, ktorí začínajú s API, prečíta iba jeden riadok odpovede – vygenerovaný text – a ignoruje všetko ostatné. To je chyba. Každé volanie /v1/chat/completions vracia bohatý objekt JSON. Práve tu nájdete údaje potrebné na sledovanie nákladov, odhalenie orezanej odpovede skôr, než sa dostane k používateľovi, a identifikáciu konkrétneho volania pri otváraní tiketu podpory.
Úplná anatómia odpovede
Začnime metadátami. Toto sú polia, ktoré zriedka kontrolujete, no budete ľutovať, že ste ich nelogovali v deň, keď nastane 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}")
Pole id je jedinečný identifikátor priradený každej požiadavke. Toto je referencia, ktorú poskytnete technickej podpore, a tá, ktorá vám umožní prepojiť sťažnosť používateľa s konkrétnym volaním vo vašich logoch. Pole model potvrdzuje, ktorý model sa skutočne použil. Na tom záleží viac, než si myslíte, keď voláte alias -latest a správanie sa cez noc zmení bez akýchkoľvek zmien vo vašom kóde.
Pole choices
Srdcom odpovede je choices. Predvolene toto pole obsahuje jeden prvok. Z neho extrahujete text aj verdikt o tom, ako sa generovanie skonč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"
Ak požiadate o viacero odpovedí pomocou parametra n, ktorým sa budeme zaoberať v lekcii 15, choices bude obsahovať viacero prvkov a index sa opäť stane významným.
Hodnoty finish_reason
Toto pole určuje spoľahlivosť vašej aplikácie. Existujú tri možné hodnoty. stop signalizuje, že model prirodzene dokončil svoju odpoveď. Toto je bežný prípad, keď môžete obsah zobraziť bez výhrad. length znamená, že generovanie bolo prerušené limitom max_tokens, takže odpoveď je potenciálne neúplná – zhrnutie chýbajúce záverom alebo zoznam, ktorý sa zastaví na siedmej položke. Nakoniec, tool_calls indikuje, že model žiada vykonanie externého nástroja v rámci volania funkcií a lopta je teraz na vašej strane.
Každý z týchto prípadov si vyžaduje odlišné zaobchádzanie, ktoré by ste mali napísať raz a navždy:
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}")
Všimnite si, že vetva length len tak neprepustí text ďalej. Buď to skúsite znova s vyšším limitom, požiadate model o pokračovanie, alebo používateľa upozorníte. Čo nikdy nesmiete urobiť, je zobraziť orezaný text, akoby bol úplný.
Objekt usage – Sledujte svoje náklady
Pole usage počíta tokeny spotrebované požiadavkou a oddeľuje vstup od výstupu:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Tento rozdiel nie je len kozmetický. Modely Mistral majú rôzne sadzby pre vstup a výstup. Funkcia, ktorá odosiela dlhý kontext, aby získala tri slová späť, má úplne iný profil nákladov než dlhý koncept vygenerovaný z krátkeho promptu. Výpočet zaberie len niekoľko riadkov:
# 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}")
Jedno volanie stojí zlomok centu, čo falošne upokojuje. Vynásobte to skutočnou premávkou aplikácie a otázka znie: ktorá funkcia čo spotrebúva? Aby ste na to odpovedali, agregujte metriky využitia už od prvého nasadenia. Logujte každé volanie spolu s názvom funkcie, ktorá ho spustila:
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")
Súbor JSONL ako tento, po dvoch týždňoch preskúmaný, vám jednoznačne povie, ktorá obrazovka vo vašom produkte najviac zaťažuje účet – a koľko volaní končí s hodnotou length.
Obsah odpovede
Pole content správy asistenta môže mať dve formy, presne ako na strane požiadavky:
# 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 praxi je pri štandardných volaniach Chat Completions content vždy reťazec. Štruktúrovaná forma je vyhradená pre multimodálne odpovede.
Dajte to do praxe
Poďme to všetko spojiť do utility funkcie – tej, ktorú budete kopírovať z projektu do projektu. Zostaví správy, vykoná volanie a vráti slovník, ktorý exponuje metriky aj text:
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
}
Kľúčový je návratový typ funkcie: nikdy nie len text. Tým, že vytiahnete finish_reason, počty tokenov a ID požiadavky až k volajúcemu, znemožníte najčastejšiu chybu – považovať prerušenú odpoveď za platnú.
Kľúčové poznatky
- Odpoveď obsahuje
choices(obsah),usage(tokeny) a metadáta (id,model) - Vždy kontrolujte
finish_reason–lengthznamená neúplnú odpoveď usagepočíta vstupné a výstupné tokeny oddelene pre presné sledovanie nákladov- Nastavte si logovanie metrík už od prvého produkčného nasadenia
- Pole
idje nevyhnutné pre ladenie a technickú podporu