Válasz és használat
Ezen az oldalon
Értsd meg, mit ad vissza az API
A legtöbb fejlesztő, aki most ismerkedik az API-val, csak a válasz egyetlen sorát olvassa el – a generált szöveget –, és figyelmen kívül hagy minden mást. Ez hiba. A /v1/chat/completions végponthoz intézett minden hívás egy gazdag JSON-objektumot ad vissza. Itt találod meg azokat az adatokat, amelyekkel nyomon követheted a költségeket, észlelheted a csonkított választ, mielőtt az eljutna a felhasználóhoz, és beazonosíthatsz egy konkrét hívást, amikor támogatási jegyet nyitsz.
A válasz teljes felépítése
Kezdjük a metaadatokkal. Ezek azok a mezők, amelyeket ritkán ellenőrzöl, de biztosan kívánni fogod, hogy naplózd őket, amikor egyszer incidens történik:
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}")
Az id mező egy egyedi azonosító, amelyet minden kéréshez rendelnek. Ez az a hivatkozás, amelyet a technikai támogatásnak adsz meg, és amely lehetővé teszi, hogy összeköss egy felhasználói panaszt a naplóidban szereplő konkrét hívással. A model mező megerősíti, melyik modellt használták valójában. Ez fontosabb, mint gondolnád, amikor egy -latest aliast hívsz meg, és a viselkedés egyik napról a másikra megváltozik anélkül, hogy te bármit is módosítottál volna a kódodban.
A choices tömb
A válasz szíve a choices mezőben rejlik. Alapértelmezés szerint ez a tömb egyetlen elemet tartalmaz. Ebből nyerheted ki mind a szöveget, mind pedig azt az ítéletet, hogyan fejeződött be a generálás:
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"
Ha több választ kérsz az n paraméter segítségével (amiről a 15. leckében lesz szó), a choices több elemet fog tartalmazni, és az index ismét jelentőséggel bír.
A finish_reason értékei
Ez a mező határozza meg alkalmazásod megbízhatóságát. Három lehetséges érték létezik. A stop azt jelzi, hogy a modell természetesen fejezte be a választ. Ez a normál eset, amikor fenntartások nélkül megjelenítheted a tartalmat. A length azt jelenti, hogy a generálást a max_tokens levágta, így a válasz potenciálisan hiányos – például egy összefoglalóból hiányzik a következtetés, vagy egy lista a hetedik tételnél megszakad. Végül a tool_calls azt jelzi, hogy a modell külső eszköz végrehajtását kéri a függvényhívás részeként, és most rajtad a sor.
Mindegyik eset eltérő kezelést igényel, amelyet egyszer és mindenkorra meg kell írnod:
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}")
Figyeld meg, hogy a length ág nem engedi egyszerűen tovább a szöveget. Vagy újra próbálkozol magasabb korláttal, vagy megkéred a modellt a folytatásra, vagy figyelmezteted a felhasználót. Amit soha nem szabad tenned, az az, hogy csonkított szöveget teljesként jelenítesz meg.
A usage objektum – Kövesd nyomon a költségeidet
A usage mező megszámolja a kérés által felhasznált tokeneket, különválasztva a bemenetet a kimenettől:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Ez a megkülönböztetés nem csupán kozmetikai. A Mistral modellek eltérő díjazást alkalmaznak a bemeneti és kimeneti tokenekre. Egy olyan funkció, amely hosszú kontextust küld, hogy három szót kapjon vissza, teljesen más költségprofillal rendelkezik, mint egy hosszú taszlat, amelyet egy rövid promptból generáltak. A számítás mindössze néhány sorba kerül:
# 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}")
Egyetlen hívás költsége a cent töredéke, ami megtévesztően megnyugtató. Szorozd ezt fel egy alkalmazás valós forgalmával, és a kérdés ez lesz: melyik funkció mennyit fogyaszt? Ennek megválaszolásához már az első éles bevezetéstől kezdve aggregáld a használati metrikákat. Naplózz minden hívást együtt azzal a funkció nevével, amely kiváltotta azt:
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")
Egy ilyen JSONL fájl, amelyet két hét múlva átnézel, egyértelműen megmutatja, melyik képernyő terheli leginkább a számládat a termékedben – és hány hívás végződik length állapottal.
Válasz tartalma
Az asszisztens üzenetének content mezője két formát ölthet, pontosan úgy, mint a kérés oldalon:
# 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": "..."}]
A gyakorlatban a szabványos Chat Completions hívások esetén a content mindig karakterlánc. A strukturált forma a multimodális válaszoknak van fenntartva.
Alkalmazd a gyakorlatban
Foglaljuk össze mindezt egy segédfüggvényben – ebben, amelyet projektről projektre másolni fogsz. Ez összeállítja az üzeneteket, végrehajtja a hívást, és visszaad egy szótárat, amely hozzáférhetővé teszi mind a metrikákat, mind a szöveget:
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
}
A lényeg abban rejlik, mit ad vissza a függvény: soha ne csak a szöveget. Azzal, hogy a finish_reason-t, a tokenszámokat és a kérés azonosítóját feljebb buborékoltatod a hívó félhez, lehetetlenné teszed a leggyakoribb hibát – azt, hogy egy levágott választ érvényesként kezelj.
Főbb megállapítások
- A válasz tartalmazza a
choices(tartalom),usage(tokenek) és metaadat (id,model) mezőket - Mindig ellenőrizd a
finish_reasonértéket – alengthhiányos választ jelent - A
usagekülön számolja a bemeneti és kimeneti tokeneket a pontos költségkövetés érdekében - Már az első éles bevezetéstől állítsd be a metrikák naplózását
- Az
idmező elengedhetetlen a hibakereséshez és a technikai támogatáshoz