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

Najlepsze praktyki produkcyjne

Lekcja 17 z 22 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Najlepsze praktyki produkcyjne
  2. 1. Architektura klienta
  3. 2. Zarządzanie promptami
  4. 3. Limity czasu i ograniczenia
  5. 4. Fallback modelu
  6. 5. Przetwarzanie wsadowe
  7. 6. Testowanie i walidacja
  8. 7. Lista kontrolna wdrożenia produkcyjnego
  9. Kluczowe wnioski

Lekcja zaktualizowana 3 listopada 2026 r. na podstawie dokumentacji OpenAI: parametry temperature i top_p są akceptowane wyłącznie przy wysiłku rozumowania (reasoning effort) ustawionym na none, podczas gdy modele GPT-5.6 domyślnie przeprowadzają rozumowanie (medium). Wywołania ustawiające te parametry muszą zatem określać reasoning={"effort": "none"} (Responses API) lub reasoning_effort="none" (Chat Completions). Źródła: Using GPT-6 · GPT-5.6 Terra.

Najlepsze praktyki produkcyjne

Ta lekcja omawia kluczowe najlepsze praktyki dotyczące wdrażania aplikacji opartej na API OpenAI w środowisku produkcyjnym. Potraktuj to jako swoją listę kontrolną przed uruchomieniem. Poprzednie lekcje dostarczyły Ci podstawowych elementów: obsługi błędów, limitów przepustowości, odporności, obserwowalności i kosztów. Teraz czas złożyć je w aplikację, którą Twój kolega będzie mógł przejąć i uruchomić bez Twojej pomocy.

1. Architektura klienta

Singleton ze scentralizowaną konfiguracją

Tworzenie instancji klienta OpenAI przy każdym wywołaniu marnuje podstawowe połączenie HTTP i, co poważniejsze, rozprasza konfigurację. Kończysz z 30-sekundowym limitem czasu tutaj i domyślnym tam, bez możliwości ustalenia, które ustawienie obowiązuje w produkcji. Dekorator lru_cache gwarantuje pojedynczą instancję, skonfigurowaną w jednym miejscu.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Klient singleton z konfiguracją produkcyjną."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# Wszędzie w kodzie:
client = get_client()

Zmienne środowiskowe

Ta sama zasada dotyczy ustawień, które różnią się w zależności od środowiska. Sprawdzaj wymagane zmienne podczas uruchamiania: lepiej, aby usługa odmówiła startu z jasnym komunikatem, niż uruchomiła się i zawiodła przy pierwszym wywołaniu użytkownika. Dzięki temu model, limit tokenów i temperatura są dostosowywane bez konieczności ponownego wdrażania.

import os

# WYMAGANE: nigdy nie hardkoduj kluczy
REQUIRED_ENV = ["OPENAI_API_KEY"]

for var in REQUIRED_ENV:
    if not os.environ.get(var):
        raise RuntimeError(f"Brak zmiennej {var}")

# Konfiguracja specyficzna dla środowiska
MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.6-terra")
MAX_TOKENS = int(os.environ.get("OPENAI_MAX_TOKENS", "4096"))
TEMPERATURE = float(os.environ.get("OPENAI_TEMPERATURE", "0.7"))

2. Zarządzanie promptami

Oddziel prompty od kodu

Prompt jest aktywem biznesowym, tak samo jak reguła biznesowa. Ukrycie go wewnątrz funkcji jako f-string uniemożliwia osobie znającej biznes, ale nie znającej Pythona, jego przegląd. Wyizoluj go jako szablon z parametrami: funkcja sprowadza się wtedy do formatowania i wywołania, a temperatura wynosząca 0.0 sprawia, że klasyfikacja jest powtarzalna.

# prompts/classification.txt
PROMPT_CLASSIFICATION = """You are a text classifier.
Classify the following text into one of these categories:
{categories}

Text: {texte}

Reply only with the category name."""

def classifier(texte: str, categories: list[str]) -> str:
    prompt = PROMPT_CLASSIFICATION.format(
        categories=", ".join(categories),
        texte=texte
    )
    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # temperature requires effort none
        input=prompt,
        temperature=0.0
    )
    return response.output_text.strip()

Wersjonuj swoje prompty

Zmiana promptu zmienia zachowanie systemu tak samo pewnie jak zmiana kodu, ale żaden test jednostkowy tego nie wykryje. Przechowuj kolejne wersje i wybieraj aktywną za pomocą konfiguracji. Pozwala to porównać dwa sformułowania na rzeczywistym ruchu i wrócić do poprzedniego za pomocą zmiennej środowiskowej, jeśli nowy pogorszy wyniki.

PROMPTS = {
    "classification_v1": "Classify: {texte}",
    "classification_v2": "Analyze and classify precisely: {texte}",
}

# W produkcji użyj określonej wersji
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Limity czasu i ograniczenia

Ogranicz wszelkie dane wejściowe pochodzące z zewnątrz, zanim dotrą do API. Użytkownik wklejający 200-stronicowy plik PDF do pola wprowadzania nie może mieć możliwości wywołania kosztownego zapytania za kilka dolarów ani spowodowania niepowodzenia żądania z powodu przepełnienia kontekstu. Prewencyjne przycinanie w połączeniu z limitem wyjścia i temperaturą z konfiguracji sprawia, że koszt i opóźnienie każdego wywołania są przewidywalne.

def appel_avec_garde_fous(prompt: str) -> str:
    """Wywołanie API ze wszystkimi zabezpieczeniami."""
    # Ogranicz rozmiar promptu
    MAX_PROMPT_CHARS = 50000
    if len(prompt) > MAX_PROMPT_CHARS:
        prompt = prompt[:MAX_PROMPT_CHARS]
        print(f"Prompt skrócony do {MAX_PROMPT_CHARS} znaków")

    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # temperature requires effort none
        input=prompt,
        max_output_tokens=MAX_TOKENS,
        temperature=TEMPERATURE,
    )

    return response.output_text

4. Fallback modelu

Gdy model jest przeciążony lub tymczasowo niedostępny, zwrócenie błędu nie jest jedyną opcją. Przełączenie się na model zapasowy obniża jakość, ale utrzymuje działanie usługi – jest to kompromis często preferowany dla asystenta wsparcia, mniej zaś dla analizy umów. Pętla iteruje przez modele w kolejności preferencji i zgłasza wyjątek tylko wtedy, gdy wszystkie zawiodą.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Próbuje Terra, a w razie błędu przechodzi na Luna."""
    modeles = ["gpt-5.6-terra", "gpt-5.6-luna"]

    for modele in modeles:
        try:
            response = get_client().responses.create(
                model=modele,
                input=prompt
            )
            return response.output_text
        except (RateLimitError, InternalServerError) as e:
            print(f"{modele} niedostępny: {e}")
            continue

    raise RuntimeError("Wszystkie modele są niedostępne")

5. Przetwarzanie wsadowe

Aby przetworzyć tysiąc dokumentów, wywołania sekwencyjne są zbyt wolne, a jednoczesne powodują przekroczenie limitów przepustowości. Semafory zapewniają właściwy balans. Dwa szczegóły sprawiają, że ta implementacja jest odporna: return_exceptions=True zapobiega anulowaniu całego wsadu przez pojedynczą awarię, a sortowanie według indeksu przywraca pierwotną kolejność, której asyncio.gather nie gwarantuje w czasie wykonania.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Przetwarza wsad promptów z ograniczoną współbieżnością."""
    client = AsyncOpenAI()
    semaphore = asyncio.Semaphore(max_concurrent)
    resultats = []

    async def traiter_un(index: int, prompt: str):
        async with semaphore:
            response = await client.responses.create(
                model="gpt-5.6-terra",
                input=prompt
            )
            return index, response.output_text

    tasks = [traiter_un(i, p) for i, p in enumerate(prompts)]
    results = await asyncio.gather(*tasks, return_exceptions=True)

    # Sortuj według indeksu, aby zachować kolejność
    sorted_results = sorted(
        [(idx, res) for idx, res in results if not isinstance(res, Exception)],
        key=lambda x: x[0]
    )
    return [res for _, res in sorted_results]

# prompts = ["Question 1", "Question 2", "Question 3"]
# résultats = asyncio.run(traiter_batch(prompts))

6. Testowanie i walidacja

Potrzebujesz dwóch różnych rodzajów testów. Pierwszy sprawdza infrastrukturę – klucz działa, sieć przepuszcza ruch, model odpowiada – i dobrze pasuje do kontroli zdrowia przy uruchamianiu. Drugi, bardziej oryginalny, testuje samą jakość promptu: przesyłasz przypadek, dla którego znasz poprawną odpowiedź, i weryfikujesz, czy się pojawi. Te asercje są Twoją siatką bezpieczeństwa przed regresjami podczas przeredagowywania szablonu.

def test_api_disponible():
    """Weryfikuje dostępność API."""
    try:
        response = get_client().responses.create(
            model="gpt-5.6-terra",
            input="test",
            max_output_tokens=5
        )
        assert response.output_text is not None
        print("API OK")
        return True
    except Exception as e:
        print(f"API KO: {e}")
        return False

def test_prompt_quality(prompt: str, attendu: str) -> bool:
    """Weryfikuje, czy prompt zwraca spójny wynik."""
    response = get_client().responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        input=prompt,
        temperature=0.0
    )
    resultat = response.output_text.lower()
    return attendu.lower() in resultat

# Testy regresji promptów
assert test_prompt_quality(
    "Classify 'excellent product': positive or negative?",
    "positive"
)

Stwórz tuzin takich przypadków testowych, reprezentatywnych dla Twoich rzeczywistych zastosowań, i uruchamiaj je za każdym razem, gdy modyfikujesz prompt. Dziesięciominutowy zestaw testów zaoszczędzi Ci tygodni wątpliwości co do postrzeganej jakości.

7. Lista kontrolna wdrożenia produkcyjnego

Przed wdrożeniem zweryfikuj każdy punkt:

Infrastruktura

  • Skonfigurowane zmienne środowiskowe (OPENAI_API_KEY itp.)
  • Skonfigurowane limity czasu i max_retries
  • Wdrożone strukturalne logowanie
  • Włączony monitoring kosztów

Odporność

  • Kompleksowa obsługa błędów (wszystkie kody HTTP)
  • Wykładnicze opóźnienia przy ponownych próbach
  • Wyłącznik awaryjny (circuit breaker) przy długotrwałych przerwach
  • Fallback do alternatywnego modelu

Bezpieczeństwo

  • Klucz API nigdy nieujawniony w kodzie ani logach
  • Walidacja danych wejściowych użytkownika
  • Ograniczanie przepustowości po stronie klienta
  • Brak danych wrażliwych w promptach

Wydajność

  • Włączony streaming dla interfejsów użytkownika
  • Przetwarzanie wsadowe dla zadań o dużej objętości
  • Buforowanie (caching) dla powtarzalnych żądań
  • Dobór modelu dostosowany do każdego zadania

Koszty

  • Zdefiniowany dzienny budżet
  • Skonfigurowane alerty
  • Ustawione max_output_tokens tam, gdzie to możliwe
  • Wybór najbardziej opłacalnego modelu dla każdego zadania

Kluczowe wnioski

  • Scentralizuj konfigurację klienta za pomocą wzorca singleton
  • Oddziel i wersjonuj swoje prompty poza kodem
  • Zaimplementuj fallback modelu dla wysokiej dostępności
  • Używaj przetwarzania wsadowego z ograniczoną współbieżnością dla dużych wolumenów
  • Testuj swoje prompty za pomocą asercji jakościowych
  • Przestrzegaj pełnej listy kontrolnej przed każdym wdrożeniem produkcyjnym