Odpowiedź i wykorzystanie
Na tej stronie
Zrozumienie tego, co zwraca API
Większość programistów zaczynających pracę z API odczytuje tylko jedną linię odpowiedzi – wygenerowany tekst – i ignoruje wszystko inne. To błąd. Każde wywołanie /v1/chat/completions zwraca bogaty obiekt JSON. To właśnie tutaj znajdziesz dane niezbędne do śledzenia kosztów, wykrycia uciętej odpowiedzi, zanim dotrze ona do użytkownika, oraz zidentyfikowania konkretnego wywołania podczas zgłaszania błędu do wsparcia technicznego.
Pełna anatomia odpowiedzi
Zacznijmy od metadanych. Są to pola, które rzadko sprawdzasz, ale będziesz żałować, że ich nie logowałeś, gdy tylko wystąpi incydent:
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}")
Pole id to unikalny identyfikator przypisywany każdemu żądaniu. To odniesienie, które podasz wsparciu technicznemu i które pozwoli Ci powiązać skargę użytkownika z konkretnym wywołaniem w Twoich logach. Pole model potwierdza, który model został faktycznie użyty. Ma to większe znaczenie, niż mogłoby się wydawać, gdy wywołujesz alias -latest, a zachowanie zmienia się z dnia na dzień bez żadnych zmian w Twoim kodzie.
Tablica choices
Sercem odpowiedzi jest tablica choices. Domyślnie zawiera ona jeden element. To z niego extracted zarówno tekst, jak i werdykt dotyczący sposobu zakończenia generowania:
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"
Jeśli poprosisz o wiele odpowiedzi, używając parametru n (omówimy to w lekcji 15), tablica choices będzie zawierać wiele elementów, a indeks ponownie nabierze znaczenia.
Wartości finish_reason
To pole decyduje o niezawodności Twojej aplikacji. Istnieją trzy możliwe wartości. stop sygnalizuje, że model naturalnie zakończył swoją odpowiedź. Jest to przypadek normalny, w którym możesz wyświetlić treść bez zastrzeżeń. length oznacza, że generowanie zostało przerwane przez max_tokens, więc odpowiedź jest potencjalnie niekompletna – podsumowanie bez wniosku lub lista urwana na siódmym elemencie. Wreszcie, tool_calls wskazuje, że model żąda wykonania zewnętrznego narzędzia w ramach wywoływania funkcji, a piłka jest teraz po Twojej stronie.
Każdy z tych przypadków wymaga odrębnego obsługi, którą powinieneś napisać raz na zawsze:
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}")
Zauważ, że gałąź length nie pozwala po prostu przepłynąć tekstowi. Albo ponawiasz próbę z wyższym limitem, prosisz model o kontynuację, albo ostrzegasz użytkownika. Czego nigdy nie wolno Ci robić, to wyświetlanie uciętego tekstu tak, jakby był kompletny.
Obiekt usage – śledzenie kosztów
Pole usage liczy tokeny zużyte przez żądanie, rozdzielając dane wejściowe od wyjściowych:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
To rozróżnienie nie jest kosmetyczne. Modele Mistral mają różne stawki za dane wejściowe i wyjściowe. Funkcja wysyłająca długi kontekst, aby otrzymać trzy słowa zwrotne, ma zupełnie inny profil kosztów niż długi szkic wygenerowany na podstawie krótkiego promptu. Obliczenie zajmuje zaledwie kilka linii kodu:
# 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}")
Pojedyncze wywołanie kosztuje ułamek centa, co jest fałszywie uspokajające. Pomnóż to przez rzeczywisty ruch aplikacji, a pytanie brzmi: która funkcja ile konsumuje? Aby na to odpowiedzieć, agreguj metryki wykorzystania od samego pierwszego wdrożenia. Loguj każde wywołanie wraz z nazwą funkcji, która je uruchomiła:
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")
Taki plik JSONL, przejrzany po dwóch tygodniach, powie Ci bez cienia wątpliwości, który ekran w Twoim produkcie najbardziej obciąża rachunek – i ile wywołań kończy się statusem length.
Treść odpowiedzi
Pole content wiadomości asystenta może przybrać dwie formy, dokładnie tak samo jak po stronie żądania:
# 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": "..."}]
W praktyce, w przypadku standardowych wywołań Chat Completions, content jest zawsze ciągiem znaków. Forma strukturalna jest zarezerwowana dla odpowiedzi multimodalnych.
Wdrożenie w praktyce
Połączmy to wszystko w funkcji użytkowej – takiej, którą będziesz kopiować z projektu do projektu. Składa ona wiadomości, wykonuje wywołanie i zwraca słownik udostępniający zarówno metryki, jak i tekst:
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
}
Kluczowe jest to, co funkcja zwraca: nigdy sam tekst. Wynosząc finish_reason, liczbę tokenów i ID żądania do wywołującego, czynisz najczęstszy błąd niemożliwym – traktowanie uciętej odpowiedzi jako poprawnej.
Kluczowe wnioski
- Odpowiedź zawiera
choices(treść),usage(tokeny) oraz metadane (id,model) - Zawsze sprawdzaj
finish_reason–lengthoznacza niekompletną odpowiedź usageliczy tokeny wejściowe i wyjściowe oddzielnie, co pozwala na precyzyjne śledzenie kosztów- Skonfiguruj logowanie metryk od pierwszego wdrożenia produkcyjnego
- Pole
idjest niezbędne do debugowania i kontaktu z wsparciem technicznym