Премини към основното съдържание
Български— Изберете език
Меню

Най-добри практики за продукционна среда

Урок 17 от 22 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Най-добри практики за продукционна среда
  2. 1. Архитектура на клиента
  3. 2. Управление на подканите (Prompts)
  4. 3. Таймаути и лимити
  5. 4. Резервен модел (Fallback)
  6. 5. Пакетна обработка
  7. 6. Тестване и валидиране
  8. 7. Контролен списък за внедряване в продукционна среда
  9. Ключови изводи

Урокът е актуализиран на 3 ноември 2026 г. въз основа на документацията на OpenAI: параметрите temperature и top_p се приемат само при усилие за разсъждение (reasoning effort) със стойност none, докато моделите GPT-5.6 разсъждават по подразбиране (medium). Следователно заявките, които задават тези параметри, трябва изрично да посочват reasoning={"effort": "none"} (Responses API) или reasoning_effort="none" (Chat Completions). Източници: Използване на GPT-6 · GPT-5.6 Terra.

Най-добри практики за продукционна среда

Този урок обхваща основните най-добри практики за внедряване на приложение, базирано на OpenAI API, в продукционна среда. Разглеждайте това като своя контролен списък преди стартиране. Предишните уроци Ви предоставиха основните градивни елементи – обработка на грешки, лимити на честотата, устойчивост, наблюдаемост и разходи. Сега е време да ги сглобите в приложение, което колега може да поеме и управлява без Ваше участие.

1. Архитектура на клиента

Singleton с централизирана конфигурация

Създаването на екземпляр на OpenAI клиент при всяко извикване губи основната HTTP връзка и, което е по-сериозно, разпръсква конфигурацията Ви. В резултат получавате 30-секунден таймаут тук и стойност по подразбиране там, без начин да разберете кое се прилага в продукционната среда. Декораторът lru_cache гарантира един единствен екземпляр, конфигуриран на едно място.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Singleton клиент с продукционна конфигурация."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# Навсякъде във Вашия код:
client = get_client()

Променливи на средата

Същият принцип важи и за настройките, които варират между различните среди. Проверете за задължителните променливи при стартиране: по-добре е услугата да откаже да стартира с ясно съобщение, отколкото да стартира и да се провали при първото потребителско извикване. Това прави модела, лимита на токени и температурата регулируеми без повторно внедряване.

import os

# ЗАДЪЛЖИТЕЛНО: никога не вграждайте ключове в кода
REQUIRED_ENV = ["OPENAI_API_KEY"]

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

# Конфигурация, специфична за средата
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. Управление на подканите (Prompts)

Отделяне на подканите от кода

Една подкана (prompt) е бизнес актив, точно както едно бизнес правило. Заравянето ѝ във f-низ вътре във функция прави невъзможно някой, който познава бизнеса, но не и Python, да я прегледа. Изолирайте я като параметризиран шаблон: тогава функцията се свежда до форматиране и извикване, а температура от 0.0 прави класификацията възпроизводима.

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

Версионирайте Вашите подкани

Промяната на подкана променя поведението на системата със същата сигурност, както промяната на кода, но без никакъв модулен тест да го забележи. Пазете последователни версии и избирайте активната чрез конфигурация. Това Ви позволява да сравните две формулировки върху реален трафик и да се върнете към предишната с променлива на средата, ако новата влоши резултатите.

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

# В продукционна среда използвайте конкретна версия
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Таймаути и лимити

Ограничете всеки вход отвън, преди той да достигне до API. Потребител, който постави 200-страничен PDF във Вашето входно поле, не трябва да може да предизвика скъпо извикване или да причини провал на заявката поради преливане на контекста. Превантивното съкращаване, комбинирано с капачката за изход и температурата от конфигурацията, прави разходите и латентността на всяко извикване предвидими.

def appel_avec_garde_fous(prompt: str) -> str:
    """API извикване с всички предпазни мерки."""
    # Ограничаване на размера на подканата
    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)

Когато един модел е претоварен или временно недостъпен, връщането на грешка не е единствената Ви опция. Превключването към вторичен модел влошава качеството, но запазва услугата – компромис, често предпочитан за асистент за поддръжка, но по-малко за анализ на договори. Цикълът преминава през моделите в ред на предпочитание и поражда изключение само ако всички се провалят.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Опитва Terra, след което преминава към 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} unavailable: {e}")
            continue

    raise RuntimeError("All models are unavailable")

5. Пакетна обработка

За обработка на хиляда документа последователните извиквания са твърде бавни, а едновременните извиквания разрушават лимитите Ви на честота. Един семафор постига правилния баланс. Два детайла правят тази имплементация надеждна: return_exceptions=True предотвратява една единствена грешка да анулира целия пакет, а сортирането по индекс възстановява оригиналния ред, което asyncio.gather не гарантира във времето на изпълнение.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Обработва пакет от подкани с ограничена конкурентност."""
    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)

    # Сортиране по индекс за запазване на реда
    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. Тестване и валидиране

Нуждаете се от два различни вида тестове. Първият проверява инфраструктурата – ключът работи, мрежата преминава, моделът отговаря – и се вписва добре в проверка за здраве при стартиране. Вторият, по-оригинален, тества самото качество на подканата: подавате случай, за който знаете правилния отговор, и проверявате дали се появява. Тези твърдения са Вашата предпазна мрежа срещу регресии, когато преформулирате шаблон.

def test_api_disponible():
    """Проверява дали 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:
    """Проверява дали подкана връща консистентен резултат."""
    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

# Тестове за регресия на подканите
assert test_prompt_quality(
    "Classify 'excellent product': positive or negative?",
    "positive"
)

Изградете дузина такива тестови случая, представителни за Вашите реални употреби, и ги стартирайте всеки път, когато модифицирате подкана. Десетминутен тестов пакет ще Ви спести седмици съмнения относно възприеманото качество.

7. Контролен списък за внедряване в продукционна среда

Преди внедряване проверете всяка точка:

Инфраструктура

  • Конфигурирани променливи на средата (OPENAI_API_KEY и др.)
  • Конфигурирани таймаути и max_retries
  • Внедрено структурирано日志ване
  • Активиран мониторинг на разходите

Устойчивост

  • Пълна обработка на грешки (всички HTTP кодове)
  • Експоненциално отстъпване (backoff) за повторни опити
  • Прекъсвач на веригата (circuit breaker) за продължителни прекъсвания
  • Преминаване към алтернативен модел при нужда

Сигурност

  • API ключът никога не се излага в кода или логовете
  • Валидиране на потребителския вход
  • Ограничаване на честотата на клиентска страна
  • Липса на чувствителни данни в подканите

Производителност

  • Активирано стрийминг за потребителски интерфейси
  • Пакетна обработка за задачи с голям обем
  • Кеш за повтарящи се заявки
  • Избор на модел, адаптиран към всяка задача

Разходи

  • Дефиниран дневен бюджет
  • Конфигурирани известия
  • Зададен max_output_tokens, където е възможно
  • Избран най-рентабилният модел за всяка задача

Ключови изводи

  • Централизирайте конфигурацията на клиента със singleton
  • Отделете и версионирайте подканите си извън кода
  • Имплементирайте резервен модел за висока наличност
  • Използвайте пакетна обработка с ограничена конкурентност за големи обеми
  • Тествайте подканите си с твърдения за качество
  • Следвайте пълния контролен списък преди всяко внедряване в продукционна среда