Antywzorce w API
Na tej stronie
- Błędy, które kosztują pieniądze w produkcji
- Traktowanie uciętej odpowiedzi jako kompletnej
- Pozwalanie na nieograniczony wzrost historii rozmowy
- Zakładanie, że sieć zawsze odpowiada
- Proszenie modelu o zrobienie czegoś, czego nie potrafi
- Wdrażanie bez pozostawiania śladu
- Procedura debugowania
- Kluczowe wnioski
Błędy, które kosztują pieniądze w produkcji
Po omówieniu najlepszych praktyk czas przyjrzeć się drugiej stronie medalu. Poniższe antywzorce to najczęstsze pułapki podczas korzystania z API Chat Completions i łączy je jedna nieprzyjemna cecha: nie ujawniają się podczas rozwoju. Na dziesięć żądań testowych wszystko działa poprawnie. To w środowisku produkcyjnym wybuchają, powodując nieoczekiwane koszty, niespójne odpowiedzi, wysokie opóźnienia lub, co gorsza, wycieki poufnych danych.
Traktowanie uciętej odpowiedzi jako kompletnej
Najczęstszym błędem jest ignorowanie pola finish_reason. Prosisz o umowę, otrzymujesz fragment tekstu, zapisujesz go w bazie danych – z wyjątkiem tego, że max_tokens=100 ucięło generowanie w środku klauzuli, a nikt tego nie zauważa, dopóki klient nie podpisze dokumentu. Naprawa wymaga trzech linii kodu i powinna stać się odruchem.
# ŹLE — brak weryfikacji
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=100 # Zbyt mało dla umowy!
)
contract = response.choices[0].message.content # Potencjalnie ucięte!
# DOBRZE — systematyczna weryfikacja
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=4000
)
if response.choices[0].finish_reason == "length":
print("WARNING: Response truncated, increase max_tokens")
else:
contract = response.choices[0].message.content
Pozwalanie na nieograniczony wzrost historii rozmowy
Druga pułapka uruchamia się powoli. Pętla czatu wysyłająca całą historię rozmowy przy każdym obrocie działa idealnie przez pierwszych dziesięć wymian, kosztuje dwa razy więcej przy dwudziestej, a w końcu przekracza okno kontekstowe przy setnej – przy czym rachunek rośnie według tej samej krzywej. Rozwiązaniem jest zachowanie monitu systemowego (nienegocjowalne) i przechowywanie tylko ostatnich N wiadomości.
# ŹLE — historia rośnie bez ograniczeń
conversation = []
while True:
user_input = input("You: ")
conversation.append({"role": "user", "content": user_input})
response = client.chat.complete(
model="mistral-large-latest",
messages=conversation # 100 obrotów = tysiące tokenów!
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
# DOBRZE — przesuwne okno z przycinaniem
MAX_MESSAGES = 20
def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
"""Zachowuje monit systemowy + ostatnie N wiadomości."""
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
if len(history) > max_messages:
history = history[-max_messages:]
return system + history
Zakładanie, że sieć zawsze odpowiada
Zwykłe wywołanie API zakłada, że nic nie pójdzie źle: żadnych przekroczeń czasu oczekiwania, żadnych kodów 429, żadnych 500. W produkcji wszystkie trzy sytuacje mają miejsce, a ta trzecia zdarza się w najgorszym możliwym momencie. Zwróć uwagę na rozróżnienie w kodzie: kod 429 uzasadnia wykładnicze opóźnienie (backoff), błąd serwera wymaga sekundy cierpliwości, ale błędu klienta, takiego jak 400 lub 401, nigdy nie należy powtarzać – Twój klucz nie stanie się ważny przy trzeciej próbie; jedynie opóźnisz diagnozę.
# ŹLE — brak obsługi błędów
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
# Awaria przy timeout, 429, 500...
# DOBRZE — ponawianie z wykładniczym opóźnieniem
from mistralai.client.errors import SDKError
import time
def safe_complete(client, messages, max_retries=3, **kwargs):
"""Wywołanie API z ponawianiem i wykładniczym opóźnieniem."""
for attempt in range(max_retries):
try:
return client.chat.complete(messages=messages, **kwargs)
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
print(f"Rate limit hit, waiting {wait}s...")
time.sleep(wait)
elif e.status_code >= 500:
time.sleep(1)
else:
raise # Błąd klienta (400, 401) — nie powtarzaj
raise Exception("Failed after 3 attempts")
Proszenie modelu o zrobienie czegoś, czego nie potrafi
Zbiegają się tu trzy antywzorce. Pierwszy to język subiektywny: „krótki“, „wiele“, „ciekawy“ nie odnoszą się do niczego weryfikowalnego, a model będzie podejmował różne decyzje przy każdym wywołaniu. Zamień każdy przymiotnik na liczbę lub obserwowalne kryterium.
# ŹLE — subiektywne, niemierzalne
"Write a short summary." # Krótki = 1 zdanie? 1 akapit?
"Give many examples." # Wiele = 3? 10? 50?
"Answer in an interesting way." # Ciekawy według jakich kryteriów?
# DOBRZE — obiektywne kryteria
"Write a summary of 50 to 80 words."
"Give exactly 5 examples, one per line."
"Start every response with a relevant statistic."
Drugi to pozwalanie modelowi na liczenie. LLM są notorycznie złe w liczeniu słów, znaków i elementów: prośba o „dokładnie 280 znaków“ wygeneruje tekst mający 240 lub 310. Liczenie należy do Twojej aplikacji, a nie do modelu.
# ŹLE — model nie potrafi liczyć precyzyjnie
"Write exactly 280 characters for a tweet."
# DOBRZE — liczenie po stronie aplikacji
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a tweet about AI in France."}],
max_tokens=100
)
tweet = response.choices[0].message.content
if len(tweet) > 280:
tweet = tweet[:277] + "..."
print(f"Tweet ({len(tweet)} chars): {tweet}")
Trzeci należy do tej samej rodziny: skale liczbowe. „Oceń od 1 do 5“ zakłada, że model ma stabilne przedstawienie różnicy między 3 a 4, co nie jest prawdą. Skala słowna, w której każdy krok jest zdefiniowany przez kryterium, daje znacznie bardziej powtarzalne oceny.
# ŹLE — modele źle interpretują skale liczbowe
"Rate the quality of this text from 1 to 5."
# DOBRZE — skala słowna z definicjami
"""Rate the quality of this text according to the following scale:
- EXCELLENT: Clear, well-structured, no errors
- GOOD: Generally correct, minor improvements possible
- AVERAGE: Understandable but lacks structure or contains errors
- POOR: Difficult to understand, significant errors
- VERY POOR: Incomprehensible or off-topic
Respond only with the label in uppercase."""
Wdrażanie bez pozostawiania śladu
Ostatni antywzorzec jest najbardziej dyskretny: wywołanie API, zwrócenie treści i niezachowywanie niczego. W dniu, w którym użytkownik zgłosi aberracyjną odpowiedź, nie masz ani ID żądania, ani nazwy faktycznie użytego modelu, ani danych o zużyciu tokenów. Ustrukturyzowane logowanie każdego wywołania kosztuje kilka milisekund i umożliwia przeprowadzenie dochodzenia.
# ŹLE — brak śladu
response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
return response.choices[0].message.content
# DOBRZE — ustrukturyzowane logowanie
import logging
import json
logger = logging.getLogger("mistral_api")
def logged_complete(client, messages, **kwargs):
"""Wywołanie API z ustrukturyzowanym logowaniem."""
response = client.chat.complete(messages=messages, **kwargs)
logger.info(json.dumps({
"request_id": response.id,
"model": response.model,
"prompt_tokens": response.usage.prompt_tokens,
"completion_tokens": response.usage.completion_tokens,
"finish_reason": response.choices[0].finish_reason
}))
return response
Procedura debugowania
Gdy odpowiedź nie spełnia Twoich oczekiwań, pokusa polega na przepisaniu monitu. Zamiast tego zacznij od pięciu mechanicznych sprawdzeń, w kolejności: Czy odpowiedź jest kompletna? Czy odpowiedział właściwy model? Ile tokenów zostało zużytych? Czy odpowiedź jest pusta? Czy stosunek wyjścia do wejścia jest wiarygodny? Stosunek poniżej 1% przy dużym monicie prawie zawsze sygnalizuje, że model odmówił przetworzenia żądania, a nie że je źle obsłużył.
def debug_response(response):
"""Lista kontrolna debugowania dla nieoczekiwanych odpowiedzi."""
choice = response.choices[0]
# 1. Czy odpowiedź jest kompletna?
if choice.finish_reason == "length":
print("ISSUE: Response truncated — increase max_tokens")
# 2. Czy użyto właściwego modelu?
print(f"Model: {response.model}")
# 3. Ile tokenów zużyto?
print(f"Input tokens: {response.usage.prompt_tokens}")
print(f"Output tokens: {response.usage.completion_tokens}")
# 4. Czy odpowiedź jest pusta?
if not choice.message.content or not choice.message.content.strip():
print("ISSUE: Empty response")
# 5. Podejrzany stosunek wejścia/wyjścia?
ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
if ratio < 0.01:
print(f"WARNING: Very low output/input ratio ({ratio:.4f})")
Kluczowe wnioski
- Zawsze sprawdzaj
finish_reason, aby wykryć ucięcie - Ogranicz historię rozmowy za pomocą przesuwnego okna
- Wdróż mechanizm ponawiania z wykładniczym opóźnieniem dla błędów sieciowych
- Używaj obiektywnych, mierzalnych kryteriów w swoich monitach
- Nigdy nie pozwalaj modelowi na liczenie – waliduj po stronie aplikacji
- Loguj każde wywołanie API w środowisku produkcyjnym w celu debugowania i śledzenia kosztów