Antwoord en gebruik
Op deze pagina
Begrijp wat de API retourneert
De meeste ontwikkelaars die nieuw zijn met de API lezen slechts één regel van het antwoord: de gegenereerde tekst. De rest negeren ze. Dat is een fout. Elke aanroep van /v1/chat/completions retourneert een uitgebreid JSON-object. Hier vindt u de gegevens die u nodig hebt om kosten te volgen, een afgekapt antwoord te detecteren voordat het de gebruiker bereikt, en een specifieke aanroep te lokaliseren wanneer u een supportticket opent.
Volledige anatomie van het antwoord
Laten we beginnen met de metadata. Dit zijn de velden die u zelden controleert, maar waarvan u zult wensen dat u ze had gelogd op de dag dat er een incident optreedt:
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}")
Het veld id is een unieke identificatiecode die aan elke aanvraag wordt toegewezen. Dit is de referentie die u aan de technische support verstrekt, en die u in staat stelt een klacht van een gebruiker te koppelen aan een specifieke aanroep in uw logs. Het veld model bevestigt welk model daadwerkelijk is gebruikt. Dit is belangrijker dan u misschien denkt wanneer u een -latest-alias aanroept en het gedrag van het model van de ene op de andere dag verandert, zonder dat u code heeft gewijzigd.
De choices-array
Het hart van het antwoord ligt in choices. Standaard bevat deze array één element. Hieruit haalt u zowel de tekst als het oordeel over hoe de generatie is beëindigd:
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"
Als u meerdere antwoorden aanvraagt met de parameter n, wat we in les 15 behandelen, zal choices meerdere elementen bevatten en krijgt de index weer betekenis.
Waarden voor finish_reason
Dit veld bepaalt de betrouwbaarheid van uw applicatie. Er zijn drie mogelijke waarden. stop geeft aan dat het model zijn antwoord op natuurlijke wijze heeft voltooid. Dit is het normale geval, waarbij u de inhoud zonder voorbehoud kunt weergeven. length betekent dat de generatie is afgekapt door max_tokens, waardoor het antwoord potentieel onvolledig is: een samenvatting zonder conclusie, of een lijst die stopt bij het zevende item. Tot slot geeft tool_calls aan dat het model verzoekt om een externe tool uit te voeren als onderdeel van function calling; de bal ligt nu bij u.
Elk van deze gevallen vereist een afzonderlijke afhandeling, die u eenmalig moet implementeren:
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}")
Merk op dat de length-tak de tekst niet zomaar doorlaat. U probeert het opnieuw met een hogere limiet, vraagt het model om verder te gaan, of waarschuwt de gebruiker. Wat u nooit mag doen, is afgekapt tekst weergeven alsof deze compleet is.
Het usage-object: houd uw kosten bij
Het veld usage telt de tokens die door de aanvraag zijn verbruikt, met een scheiding tussen input en output:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Dit onderscheid is niet louter cosmetisch. Mistral-modellen hanteren verschillende tarieven voor input en output. Een functie die een lange context verstuurt om drie woorden terug te krijgen, heeft een heel ander kostenprofiel dan een lang concept dat wordt gegenereerd op basis van een korte prompt. De berekening kost slechts een paar regels code:
# 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}")
Een enkele aanroep kost een fractie van een cent, wat bedrieglijk geruststellend is. Vermenigvuldig dat met het reële verkeer van een applicatie, en de vraag wordt: welke functie verbruikt wat? Om dat te beantwoorden, aggregeert u gebruiksstatistieken vanaf uw allereerste implementatie. Log elke aanroep samen met de naam van de functie die deze heeft geactiveerd:
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")
Een JSONL-bestand als dit, na twee weken geëvalueerd, zal u ondubbelzinnig vertellen welk scherm in uw product het zwaarst op de factuur drukt – en hoeveel aanroepen eindigen met length.
Inhoud van het antwoord
Het veld content van het assistent-bericht kan twee vormen aannemen, precies zoals aan de kant van de aanvraag:
# 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": "..."}]
In de praktijk is content bij standaard Chat Completions-aanroepen altijd een string. De gestructureerde vorm is voorbehouden aan multimodale antwoorden.
Pas het toe
Laten we dit allemaal samenvoegen in een utility-functie: degene die u van project tot project zult kopiëren. Deze assembleert de berichten, doet de aanroep en retourneert een dictionary die zowel statistieken als tekst blootlegt:
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
}
Het belangrijkste punt is wat de functie retourneert: nooit alleen de tekst. Door finish_reason, tokentellingen en de aanvraag-ID door te geven aan de aanroeper, maakt u de meest voorkomende fout onmogelijk: een afgekapt antwoord behandelen alsof het geldig is.
Belangrijkste punten
- Het antwoord bevat
choices(inhoud),usage(tokens) en metadata (id,model) - Controleer altijd
finish_reason–lengthbetekent een onvolledig antwoord usagetelt input- en outputtokens apart voor nauwkeurige kostentracking- Stel statistieklogging in vanaf uw eerste productie-implementatie
- Het veld
idis essentieel voor debugging en technische support