Salt la conținutul principal
Română— Alege o limbă
Meniu

Bune practici pentru mediul de producție

Lecția 17 din 22 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Bune practici pentru mediul de producție
  2. 1. Arhitectura clientului
  3. 2. Gestionarea prompturilor
  4. 3. Timeout-uri și limite
  5. 4. Fallback al modelului
  6. 5. Procesarea în loturi (Batch)
  7. 6. Testare și validare
  8. 7. Lista de verificare pentru implementarea în producție
  9. Puncte cheie

Lecție actualizată la 3 noiembrie 2026 pe baza documentației OpenAI: parametrii temperature și top_p sunt acceptați doar cu un efort de raționament de none, în timp ce modelele GPT-5.6 raționează implicit (medium). Apelurile care setează acești parametri trebuie, prin urmare, să specifice reasoning={"effort": "none"} (Responses API) sau reasoning_effort="none" (Chat Completions). Surse: Utilizarea GPT-6 · GPT-5.6 Terra.

Bune practici pentru mediul de producție

Această lecție acoperă bunele practici esențiale pentru implementarea unei aplicații bazate pe API-ul OpenAI în mediul de producție. Considerați acest material ca fiind lista dumneavoastră de verificare pre-lansare. Lecțiile anterioare v-au oferit blocurile de construcție—gestionarea erorilor, limitele de rată, reziliența, observabilitatea și costurile. Acum este momentul să le asamblați într-o aplicație pe care un coleg o poate prelua și rula fără intervenția dumneavoastră.

1. Arhitectura clientului

Singleton cu configurare centralizată

Instanțierea unui client OpenAI la fiecare apel risipește conexiunea HTTP subiacentă și, mai grav, împrăștie configurația. Ajungeți cu un timeout de 30 de secunde aici și valoarea implicită acolo, fără a avea nicio modalitate de a ști care se aplică în producție. Decoratorul lru_cache garantează o singură instanță, configurată într-un singur loc.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Client singleton cu configurație de producție."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# Oriunde în codul dumneavoastră:
client = get_client()

Variabile de mediu

Același principiu se aplică setărilor care variază între medii. Verificați variabilele necesare la pornire: este mai bine ca un serviciu să refuze pornirea cu un mesaj clar decât să pornească și să eșueze la primul apel al utilizatorului. Acest lucru face ca modelul, limita de tokeni și temperatura să fie ajustabile fără reimplementare.

import os

# OBLIGATORIU: nu codificați niciodată cheile direct
REQUIRED_ENV = ["OPENAI_API_KEY"]

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

# Configurare specifică mediului
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. Gestionarea prompturilor

Separarea prompturilor de cod

Un prompt este un activ de afaceri, la fel ca o regulă de business. Îngroparea acestuia într-un șir f-string în interiorul unei funcții face imposibilă revizuirea de către cineva care cunoaște afacerea, dar nu și Python. Izolați-l ca un șablon parametrizat: funcția se reduce apoi la formatare și apelare, iar o temperatură de 0.0 face clasificarea reproductibilă.

# 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()

Versiuneați prompturile

Modificarea unui prompt schimbă comportamentul sistemului la fel de sigur ca modificarea codului, dar fără ca niciun test unitar să observe acest lucru. Păstrați versiunile succesive și selectați-o pe cea activă prin configurare. Acest lucru vă permite să comparați două formulări pe trafic real și să reveniți la cea anterioară printr-o variabilă de mediu dacă noua formulare degradează rezultatele.

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

# În producție, utilizați o versiune specifică
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Timeout-uri și limite

Delimitați orice intrare din exterior înainte ca aceasta să ajungă la API. Un utilizator care lipește un PDF de 200 de pagini în câmpul de intrare nu trebuie să poată declanșa un apel costos de mai mulți dolari sau să provoace eșecul cererii din cauza depășirii contextului. Trunchierea preventivă, combinată cu limita de ieșire și temperatura din configurare, face ca costul și latența fiecărui apel să fie predictibile.

def appel_avec_garde_fous(prompt: str) -> str:
    """Apel API cu toate măsurile de siguranță."""
    # Limitați dimensiunea promptului
    MAX_PROMPT_CHARS = 50000
    if len(prompt) > MAX_PROMPT_CHARS:
        prompt = prompt[:MAX_PROMPT_CHARS]
        print(f"Prompt truncated to {MAX_PROMPT_CHARS} characters")

    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 al modelului

Când un model este saturat sau temporar indisponibil, returnarea unei erori nu este singura opțiune. Comutarea la un model secundar degradează calitatea, dar păstrează serviciul funcțional—un compromis adesea preferabil pentru un asistent de suport, mai puțin pentru analiza contractelor. Bucla iterază prin modele în ordinea preferinței și ridică o excepție doar dacă toate eșuează.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Încearcă Terra, apoi trece la Luna în caz de eroare."""
    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} unavailable: {e}")
            continue

    raise RuntimeError("All models are unavailable")

5. Procesarea în loturi (Batch)

Pentru a procesa o mie de documente, apelurile secvențiale sunt prea lente, iar apelurile simultane vă epuizează limitele de rată. Un semafor realizează echilibrul corect. Două detalii fac această implementare robustă: return_exceptions=True previne ca o singură eroare să anuleze întregul lot, iar sortarea după index restabilește ordinea originală, pe care asyncio.gather nu o garantează în timpul execuției.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Procesează un lot de prompturi cu concurență limitată."""
    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)

    # Sortați după index pentru a menține ordinea
    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. Testare și validare

Aveți nevoie de două tipuri diferite de teste. Primul verifică infrastructura—cheia funcționează, rețeaua trece, modelul răspunde—și se potrivește bine într-o verificare de sănătate la pornire. Al doilea, mai original, testează calitatea promptului în sine: trimiteți un caz pentru care cunoașteți răspunsul corect și verificați dacă apare. Aceste afirmații sunt plasa dumneavoastră de siguranță împotriva regresiei atunci când reformulați un șablon.

def test_api_disponible():
    """Verifică faptul că API-ul este accesibil."""
    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:
    """Verifică dacă un prompt returnează un rezultat consistent."""
    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

# Teste de regresie pentru prompturi
assert test_prompt_quality(
    "Classify 'excellent product': positive or negative?",
    "positive"
)

Construiți o duzină de cazuri de test ca acesta, reprezentative pentru cazurile dumneavoastră reale de utilizare, și rulați-le de fiecare dată când modificați un prompt. O suită de teste de zece minute vă va economisi săptămâni de îndoieli legate de calitatea percepută.

7. Lista de verificare pentru implementarea în producție

Înainte de implementare, verificați fiecare punct:

Infrastructură

  • Variabile de mediu configurate (OPENAI_API_KEY, etc.)
  • Timeout-uri și max_retries configurate
  • Jurnalizare structurată pusă în aplicare
  • Monitorizarea costurilor activată

Reziliență

  • Gestionare completă a erorilor (toate codurile HTTP)
  • Backoff exponențial pentru reîncercări
  • Întrerupător de circuit (circuit breaker) pentru întreruperi prelungite
  • Fallback la un model alternativ

Securitate

  • Cheia API nu este niciodată expusă în cod sau jurnale
  • Validarea intrărilor utilizatorului
  • Limitarea ratei la nivelul clientului
  • Fără date sensibile în prompturi

Performanță

  • Streaming activat pentru interfețele de utilizator
  • Procesare în loturi pentru sarcini cu volum mare
  • Cache pentru cereri repetitive
  • Alegerea modelului adaptată fiecărei sarcini

Costuri

  • Buget zilnic definit
  • Alertă configurate
  • max_output_tokens setat acolo unde este posibil
  • Cel mai eficient model din punct de vedere al costurilor selectat pentru fiecare sarcină

Puncte cheie

  • Centralizați configurarea clientului cu un singleton
  • Separați și versiunați prompturile în afara codului
  • Implementați fallback al modelului pentru disponibilitate ridicată
  • Utilizați procesarea în loturi cu concurență limitată pentru volume mari
  • Testați prompturile cu afirmații de calitate
  • Urmați lista completă de verificare înainte de fiecare implementare în producție