Svar och användning
På denna sida
Förstå vad API:t returnerar
De flesta utvecklare som är nya på API:t läser bara en enda rad i svaret – den genererade texten – och ignorerar allt annat. Det är ett misstag. Varje anrop till /v1/chat/completions returnerar ett rikt JSON-objekt. Här hittar du den data du behöver för att spåra kostnader, upptäcka ett avkortat svar innan det når användaren och identifiera ett specifikt anrop när du öppnar ett supportärende.
Hela uppbyggnaden av svaret
Låt oss börja med metadata. Detta är fält som du sällan kontrollerar, men som du kommer önska att du loggade den dag en incident inträffar:
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}")
Fältet id är en unik identifierare som tilldelas varje begäran. Detta är referensen du anger till teknisk support, och den som låter dig koppla ett användarklagomål till ett specifikt anrop i dina loggar. Fältet model bekräftar vilken modell som faktiskt användes. Detta är viktigare än du kanske tror när du anropar ett -latest-alias och beteendet ändras över en natt utan några kodändringar från din sida.
Arrayen choices
Hjärtat i svaret finns i choices. Som standard innehåller denna array ett enda element. Från detta extraherar du både texten och bedömningen av hur genereringen avslutades:
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"
Om du begär flera svar med hjälp av parametern n, vilket vi kommer att behandla i lektion 15, kommer choices att innehålla flera element och indexet blir återigen meningsfullt.
Värden för finish_reason
Detta fält avgör tillförlitligheten i din applikation. Det finns tre möjliga värden. stop signalerar att modellen avslutade sitt svar naturligt. Detta är det normala fallet, där du kan visa innehållet utan förbehåll. length betyder att genereringen kapades av max_tokens, så svaret är potentiellt ofullständigt – en sammanfattning som saknar sin slutsats, eller en lista som stannar vid det sjunde objektet. Slutligen indikerar tool_calls att modellen begär körning av ett externt verktyg som en del av funktionsanrop, och bollen ligger nu hos dig.
Varje av dessa fall kräver distinkt hantering, som du bör skriva en gång för alla:
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}")
Observera att grenen för length inte bara låter texten passera igenom. Du försöker antingen igen med en högre gräns, ber modellen fortsätta eller varnar användaren. Vad du aldrig får göra är att visa avkortad text som om den vore komplett.
Objektet usage – Spåra dina kostnader
Fältet usage räknar de token som förbrukades av begäran och skiljer på inmatning och utmatning:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Denna åtskillnad är inte bara kosmetisk. Mistral-modeller har olika priser för inmatning och utmatning. En funktion som skickar en lång kontext för att få tre ord tillbaka har en helt annan kostnadsprofil än ett långt utkast som genereras från en kort prompt. Beräkningen tar bara några rader:
# 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}")
Ett enskilt anrop kostar en bråkdel av en cent, vilket är falskt lugnande. Multiplicera det med den verkliga trafiken i en applikation, och frågan blir: vilken funktion konsumerar vad? För att svara på det börjar du aggregera användningsmätvärden från din allra första distribution. Logga varje anrop tillsammans med namnet på den funktion som utlöste det:
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")
En JSONL-fil som denna, granskad efter två veckor, kommer att berätta utan tvetydighet vilken skärm i din produkt som belastar fakturan mest – och hur många anrop som slutar med length.
Svarsinnehåll
Fältet content i assistentmeddelandet kan ha två former, precis som på begärandesidan:
# 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": "..."}]
I praktiken är content alltid en sträng för vanliga Chat Completions-anrop. Den strukturerade formen är reserverad för multimodala svar.
Sätt det i praktiken
Låt oss sammanfatta allt detta i en hjälpfunktion – den du kommer att kopiera från projekt till projekt. Den sätter ihop meddelandena, gör anropet och returnerar en ordbok som exponerar både mätvärden och 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
}
Nyckelpunkten är vad funktionen returnerar: aldrig bara texten. Genom att föra upp finish_reason, token-antal och begärans-ID till anroparen gör du det vanligaste felet omöjligt – att behandla ett avkortat svar som ett giltigt.
Viktiga punkter
- Svaret innehåller
choices(innehåll),usage(token) och metadata (id,model) - Kontrollera alltid
finish_reason–lengthbetyder ett ofullständigt svar usageräknar inmatnings- och utmatningstoken separat för exakt kostnadsspårning- Konfigurera loggning av mätvärden från din första produktionsdistribution
- Fältet
idär avgörande för felsökning och teknisk support