Vastus ja kasutamine
Sellel lehel
Mõistke, mida API tagastab
Enamik arendajaid, kes API-ga alles alustavad, loevad vastusest vaid ühe rea – genereeritud teksti – ja ignoreerivad kõike muud. See on viga. Iga päring liidesesse /v1/chat/completions tagastab mahuka JSON-objekti. Just sealt leiad andmed, mida vajad kulude jälgimiseks, katkenud vastuse tuvastamiseks enne, kui see kasutajani jõuab, ning konkreetse päringu leidmiseks tugiteenusele pöördumisel.
Vastuse täielik anatoomia
Alustame metaandmetest. Need on väljad, mida sa harva kontrollid, kuid soovid hiljem, et oleksid need logisse kirjutanud just siis, kui juhtub intsident:
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}")
Väli id on kordumatu identifikaator, mis omistatakse igale päringule. See on viide, mille esitad tehnilisele toele, ja see, mis võimaldab sul seostada kasutaja kaebuse konkreetse päringuga oma logides. Väli model kinnitab, millist mudelit tegelikult kasutati. See on olulisem, kui arvata oskad, kui kasutad -latest aliast ja käitumine muutub üleöö ilma, et sa oleksid koodis midagi muutnud.
Massiiv choices
Vastuse tuum peitub väljas choices. Vaikimisi sisaldab see massiiv ühte elementi. Sealt ekstraheerid nii teksti kui ka otsuse selle kohta, kuidas genereerimine lõppes:
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"
Kui taotled parameetri n abil mitut vastust (mida käsitleme 15. tunnis), sisaldab choices mitut elementi ja indeks muutub taas tähenduslikuks.
Väärtused väljal finish_reason
See väli määrab sinu rakenduse usaldusväärsuse. Võimalikke väärtusi on kolm. stop annab märku, et mudel lõpetas vastuse loomulikul teel. See on normaalne juhtum, kus saad sisu ilma reservatsioonideta kuvada. length tähendab, et genereerimine katkestati parameetri max_tokens tõttu, seega on vastus potentsiaalselt mittetäielik – kokkuvõte, millest puudub järeldus, või loend, mis peatub seitsmendal üksusel. Lõpuks näitab tool_calls, et mudel taotleb funktsioonide kutsumise raames välise tööriista käivitamist ja pall on nüüd sinu poolväljakul.
Iga neist juhtumitest nõuab erinevat käsitlemist, mille peaksid kirjutama üks kord ja igaveseks:
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}")
Pane tähele, et haru length ei lase tekstil lihtsalt läbi minna. Sa kas proovid uuesti suurema piiranguga, palud mudelil jätkata või hoiatad kasutajat. Mida sa mitte kunagi teha ei tohi, on katkestatud teksti kuvamine nii, nagu oleks see täielik.
Objekt usage – jälgi oma kulusid
Väli usage loendab päringu tarbitud tokeneid, eristades sisendit ja väljundit:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
See eristus pole pelgalt kosmeetiline. Mistrali mudelitel on sisendi ja väljundi jaoks erinevad hinnad. Funktsioonil, mis saadab pika konteksti, et saada vastu kolm sõna, on hoopis teistsugune kuluprofiil võrreldes lühikesest vihjest genereeritud pika mustandiga. Arvutamine võtab vaid mõned read:
# 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}")
Üksik päring maksab murdosa sendist, mis on petlikult rahustav. Korruta see rakenduse tegeliku liiklusega ja küsimus muutub: milline funktsioon tarbib mida? Sellele vastamiseks koonda kasutusmõõdikud juba oma esimesest tootmisse viimisest alates. Logi iga päring koos selle käivitanud funktsiooni nimega:
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")
Selline JSONL-fail, mida kahe nädala pärast üle vaatad, ütleb sulle üheselt, milline ekraan sinu tootes arvet kõige rohkem koormab – ja kui palju päringuid lõpeb väärtusega length.
Vastuse sisu
Abilise sõnumi väli content võib võtta kaks vormi, täpselt nagu päringu poolelgi:
# 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": "..."}]
Praktikas on standardsete Chat Completions päringute puhul content alati string. Struktureeritud vorm on reserveeritud multimodaalsetele vastustele.
Rakenda praktikas
Viime kõik selle kokku ühte utiliidifunktsiooni – sellesse, mida kopeerid projektist projekti. See koostab sõnumid, teeb päringu ja tagastab sõnastiku, mis avaldab nii mõõdikud kui ka teksti:
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
}
Põhipunkt on selles, mida funktsioon tagastab: mitte kunagi ainult teksti. Tõstes finish_reason-i, tokenite arvud ja päringu ID ülespoole kutsujale, muudad kõige levinuma vea võimatuks – katkestatud vastuse käsitlemise kehtivana.
Peamised punktid
- Vastus sisaldab välju
choices(sisu),usage(tokenid) ja metaandmeid (id,model) - Kontrolli alati väärtust
finish_reason–lengthtähendab mittetäielikku vastust usageloendab sisendi ja väljundi tokeneid eraldi täpseks kulude jälgimiseks- Seadista mõõdikute logimine juba oma esimesest tootmisse viimisest alates
- Väli
idon hädavajalik silumiseks ja tehniliseks toeks