Atsakymas ir naudojimas
Šiame puslapyje
Suprask, ką grąžina API
Dauguma kūrėjų, pirmą kartą susiduriančių su API, perskaito tik vieną atsakymo eilutę – sugeneruotą tekstą – ir ignoruoja viską kita. Tai klaida. Kiekvienas užklausimas į /v1/chat/completions grąžina išsamų JSON objektą. Būtent čia rasi duomenis, kurių tau reikia norint stebėti išlaidas, aptikti nukirptą atsakymą prieš jam pasiekiant vartotoją ir nustatyti konkretų užklausimą atidarant techninės pagalbos prašymą.
Pilna atsakymo sandara
Pradėkime nuo metaduomenų. Tai laukai, kuriuos retai tikrini, bet gailėsiesi jų nefiksavęs tą dieną, kai įvyks incidentas:
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}")
Laukas id yra unikalus identifikatorius, priskiriamas kiekvienai užklausai. Tai nuoroda, kurią pateiksi techninei pagalbai, ir kuri leidžia susieti vartotojo skundą su konkrečiu užklausimu tavo žurnaluose. Laukas model patvirtina, kuris modelis buvo faktiškai naudotas. Tai svarbiau, nei gali manyti, kai kvieti -latest aliasą ir elgsena pasikeičia per naktį be jokių tavo kodų pakeitimų.
Masyvas choices
Atsakymo šerdis yra choices. Pagal nutylėjimą šis masyvas turi vieną elementą. Iš jo ištrauki tiek tekstą, tiek verdiktą apie tai, kaip baigėsi generavimas:
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"
Jei paprašysi kelių atsakymų naudodamas parametrą n, apie kurį kalbėsime 15 pamokoje, choices turės kelis elementus, o indeksas vėl taps prasmingas.
finish_reason reikšmės
Šis laukas lemia tavo programos patikimumą. Yra trys galimos reikšmės. stop signalizuoja, kad modelis natūraliai baigė savo atsakymą. Tai įprastas atvejis, kai turinį gali rodyti be jokių išlygų. length reiškia, kad generavimas buvo nutrauktas dėl max_tokens, todėl atsakymas gali būti neišsamus – santrauka be išvados arba sąrašas, sustojęs ties septintu punktu. Galiausiai, tool_calls rodo, kad modelis prašo įvykdyti išorinį įrankį kaip funkcijų kvietimo dalį, ir dabar eilė tavo.
Kiekvienas iš šių atvejų reikalauja skirtingo apdorojimo, kurį turėtum parašyti vieną kartą ir visiems laikams:
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}")
Atkreipk dėmesį, kad length šaka tiesiog nepraleidžia teksto toliau. Tu arba bandai iš naujo su didesne riba, arba prašai modelio tęsti, arba įspėji vartotoją. Ko niekada neturėtum daryti – rodyti nukirpto teksto taip, lyg jis būtų pilnas.
Objektas usage – stebėk savo išlaidas
Laukas usage suskaičiuoja užklausos sunaudotus tokenus, atskirdamas įvestį nuo išvesties:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Šis skirtumas nėra tik kosmetinis. Mistral modeliai taiko skirtingus įkainius įvesties ir išvesties tokenams. Funkcija, siunčianti ilgą kontekstą, kad gautų tris žodžius atgal, turi visiškai kitokį išlaidų profilį nei ilgas juodraštis, sugeneruotas iš trumpo užuomazgos. Skaičiavimas užtrunka vos kelias eilutes:
# 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}")
Vienas užklausimas kainuoja centų dalį, kas klaidingai nuramina. Padaugink tai iš realaus programos srauto, ir kyla klausimas: kuri funkcija ką suvartoja? Norint į tai atsakyti, agreguok naudojimo metrikas nuo pat pirmojo diegimo. Fiksuok kiekvieną užklausą kartu su ją sukėlusios funkcijos pavadinimu:
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")
Toks JSONL failas, peržiūrėtas po dviejų savaičių, nedviprasmiškai parodys, kuris tavo produkto ekranas labiausiai apkrauna sąskaitą – ir kiek užklausų baigiasi su length.
Atsakymo turinys
Asistento žinutės laukas content gali įgyti dvi formas, lygiai taip pat kaip ir užklausos pusėje:
# 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": "..."}]
Praktiškai, standartinėms „Chat Completions“ užklausoms, content visada yra eilutė. Struktūruota forma skirta multimodaliems atsakymams.
Įgyvendink tai praktiškai
Sujunkime visa tai į pagalbinę funkciją – tą, kurią kopijuosi iš projekto į projektą. Ji surenka žinutes, atlieka užklausą ir grąžina žodyną, kuriame pateikiamos tiek metrikos, tiek tekstas:
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
}
Svarbiausia yra tai, ką funkcija grąžina: niekada ne tik tekstą. Iškeldamas finish_reason, tokenų skaičių ir užklausos ID kvietėjui aukštyn, padarai neįmanomą pačią dažniausią klaidą – traktuoti nutrauktą atsakymą kaip galiojantį.
Svarbiausi punktai
- Atsakyme yra
choices(turinys),usage(tokenai) ir metaduomenys (id,model) - Visada tikrink
finish_reason–lengthreiškia neišsamų atsakymą usageatskirai skaičiuoja įvesties ir išvesties tokenus tiksliam išlaidų stebėjimui- Nustatyk metrikų fiksavimą nuo pat pirmojo diegimo gamyboje
- Laukas
idyra būtinas derinimui ir techninei pagalbai