Przejdź do głównej treści
Polski— Wybierz język
Menu

Odpowiedź i wykorzystanie

Lekcja 4 z 16 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Zrozumienie tego, co zwraca API
  2. Pełna anatomia odpowiedzi
  3. Tablica choices
  4. Wartości finish_reason
  5. Obiekt usage – śledzenie kosztów
  6. Treść odpowiedzi
  7. Wdrożenie w praktyce
  8. Kluczowe wnioski

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 – length oznacza niekompletną odpowiedź
  • usage liczy tokeny wejściowe i wyjściowe oddzielnie, co pozwala na precyzyjne śledzenie kosztów
  • Skonfiguruj logowanie metryk od pierwszego wdrożenia produkcyjnego
  • Pole id jest niezbędne do debugowania i kontaktu z wsparciem technicznym