Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Parimate tavade rakendamine tootmises

Õppetund 17 / 22 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Parimate tavade rakendamine tootmises
  2. 1. Kliendi arhitektuur
  3. 2. Sõnumite (Prompt) haldus
  4. 3. Aegumised ja piirangud
  5. 4. Mudeli varuvariant (Fallback)
  6. 5. Töötlemine pakettidena (Batch Processing)
  7. 6. Testimine ja valideerimine
  8. 7. Tootmisse kasutuselevõtu kontrollnimekiri
  9. Peamised punktid

Tund uuendatud 3. novembril 2026 vastavalt OpenAI dokumentatsioonile: parameetreid temperature ja top_p aktsepteeritakse ainult siis, kui arutluse jõupingutus (reasoning effort) on määratud väärtusega none, samas kui GPT-5.6 mudelid kasutavad vaikimisi arutlust (medium). Seetõttu peavad need parameetrid määravad päringud sisaldama sätet reasoning={"effort": "none"} (Responses API) või reasoning_effort="none" (Chat Completions). Allikad: GPT-6 kasutamine · GPT-5.6 Terra.

Parimate tavade rakendamine tootmises

See tund käsitleb olulisimaid parimaid tavasid OpenAI API-l põhineva rakenduse tootmiskeskkonda viimisel. Vaata seda kui oma käivitamiseelse kontrollnimekirja. Eelmistes tundides said kätte ehitusplokid – veahaldus, kiirusepiirangud, vastupidavus, jälgitavus ja kulud. Nüüd on aeg need kokku panna rakenduseks, mille saab sinu kolleeg üle võtta ja ilma sinuta käigus hoida.

1. Kliendi arhitektuur

Singleton ja tsentraliseeritud konfiguratsioon

OpenAI kliendi loomine iga päringu jaoks raiskab aluseks olevat HTTP-ühendust ja, mis veelgi tõsisem, hajutab sinu konfiguratsiooni. Lõpuks on sul siin 30-sekundiline aegumine ja seal vaikimisi säte, ilma et keegi teaks, mida tootmises tegelikult kasutatakse. Dekoraator lru_cache garanteerib üheainsa eksemplari, mis on konfigureeritud ühes kohas.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Singleton klient tootmise konfiguratsiooniga."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# Kasuta kõikjal oma koodis:
client = get_client()

Keskkonnamuutujad

Sama printsiip kehtib seadete puhul, mis erinevates keskkondades muutuvad. Kontrolli nõutavaid muutujaid käivitamisel: teenusel on parem selge veateatega käivitumisest keelduda kui käivituda ja esimese kasutaja päringul nurjuda. See võimaldab mudelit, tokenite piirangut ja temperatuuri kohandada ilma uut versiooni kasutusele võtmata.

import os

# KOHUSTUSLIK: ära kunagi kodeeri võtmeid otse koodi
REQUIRED_ENV = ["OPENAI_API_KEY"]

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

# Keskkonnaspetsiifiline konfiguratsioon
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. Sõnumite (Prompt) haldus

Eralda sõnumid koodist

Sõnum on ärivara täpselt nagu ärireegel. Selle peitmine funktsiooni sees olevasse f-stringi teeb võimatuks, et keegi, kes tunneb äri, kuid ei oska Pythonit, saaks seda üle vaadata. Eralda see parameetriseeritud mallina: funktsioon taandub siis vormindamisele ja kutsumisele, ning temperatuur 0.0 muudab klassifitseerimise korratavaks.

# prompts/classification.txt
PROMPT_CLASSIFICATION = """Oled teksti klassifitseerija.
Klassifitseeri järgnev tekst ühte neist kategooriatest:
{categories}

Tekst: {texte}

Vasta ainult kategooria nimega."""

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"},  # temperatuur nõuab jõupingutust none
        input=prompt,
        temperature=0.0
    )
    return response.output_text.strip()

Versioneeri oma sõnumeid

Sõnumi muutmine muudab süsteemi käitumist sama kindlalt kui koodi muutmine, kuid ilma et ükski unit-test seda märkaks. Hoia järjestikuseid versioone ja vali aktiivne versioon konfiguratsiooni kaudu. See võimaldab võrrelda kahte formulatsiooni reaalsel liiklusel ja taastada eelmise versiooni keskkonnamuutujaga, kui uus tulemusi halvendab.

PROMPTS = {
    "classification_v1": "Klassifitseeri: {texte}",
    "classification_v2": "Analüüsi ja klassifitseeri täpselt: {texte}",
}

# Tootmises kasuta kindlat versiooni
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Aegumised ja piirangud

Piira kõiki väljastpoolt tuleva sisendit enne, kui see API-ni jõuab. Kasutaja, kes kleepib sinu sisendväljale 200-leheküljelise PDF-i, ei tohi suuta käivitada mitme dollari suurust kulu ega põhjustada päringu nurjumist konteksti ületäitumise tõttu. Ennetav lühendamine koos väljundi piirangu ja konfiguratsioonist pärit temperatuuriga muudab iga päringu kulu ja latentsuse ennustatavaks.

def appel_avec_garde_fous(prompt: str) -> str:
    """API väljakutse kõigi kaitsemeetmetega."""
    # Piira sõnumi suurust
    MAX_PROMPT_CHARS = 50000
    if len(prompt) > MAX_PROMPT_CHARS:
        prompt = prompt[:MAX_PROMPT_CHARS]
        print(f"Sõnum lühendatud {MAX_PROMPT_CHARS} tähemärgini")

    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # temperatuur nõuab jõupingutust none
        input=prompt,
        max_output_tokens=MAX_TOKENS,
        temperature=TEMPERATURE,
    )

    return response.output_text

4. Mudeli varuvariant (Fallback)

Kui mudel on ülekoormatud või ajutiselt kättesaamatu, ei ole vea tagastamine ainus võimalus. Üleminek teisele mudelile halvendab kvaliteeti, kuid säilitab teenuse – kompromiss, mis on tugiteenuse assistendi puhul sageli eelistatav, lepingute analüüsimisel aga vähem. Tsükkel läbib mudelid eelistuste järjekorras ja tõstab erandi ainult siis, kui kõik ebaõnnestuvad.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Proovib Terrat ja ebaõnnestumisel läheb üle Lunale."""
    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} pole saadaval: {e}")
            continue

    raise RuntimeError("Ükski mudel pole saadaval")

5. Töötlemine pakettidena (Batch Processing)

Tuhande dokumendi töötlemiseks on järjestikused päringud liiga aeglased ja samaaegsed päringud lõhuvad sinu kiirusepiirangud. Semaphor leiab õige tasakaalu. Kaks detaili teevad selle teostuse robustseks: return_exceptions=True hoiab ära olukorra, kus üks ebaõnnestumine tühistab kogu paketi, ja indeksi järgi sorteerimine taastab algse järjekorra, mida asyncio.gather täitmise aja osas ei garanteeri.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Töötleb sõnumite paketi piiratud samaaegsusega."""
    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)

    # Sorteeri indeksi järgi järjekorra säilitamiseks
    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 = ["Küsimus 1", "Küsimus 2", "Küsimus 3"]
# résultats = asyncio.run(traiter_batch(prompts))

6. Testimine ja valideerimine

Vajad kahte erinevat tüüpi teste. Esimene kontrollib taristut – võti toimib, võrk läbib, mudel vastab – ja sobib hästi käivitamise tervisekontrolli. Teine, originaalsem, testib sõnumi enda kvaliteeti: esitad juhtumi, kus tead õiget vastust, ja kontrollid, kas see ilmub. Need väited on sinu ohutusvõrguks taandarengute vastu, kui malli ümber sõnastad.

def test_api_disponible():
    """Kontrollib, kas API on kättesaadav."""
    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:
    """Kontrollib, kas sõnum tagastab järjepideva tulemuse."""
    response = get_client().responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperatuur nõuab jõupingutust none
        input=prompt,
        temperature=0.0
    )
    resultat = response.output_text.lower()
    return attendu.lower() in resultat

# Sõnumi taandarengu testid
assert test_prompt_quality(
    "Klassifitseeri ' suurepärane toode': positiivne või negatiivne?",
    "positiivne"
)

Koosta tosin sellist testjuhtumit, mis on esinduslikud sinu tegelikele kasutusjuhtudele, ja käivita need iga kord, kui sõnumit muudad. Kümne minuti pikkune testikomplekt säästab sind nädalatest kahtlustest tajutava kvaliteedi osas.

7. Tootmisse kasutuselevõtu kontrollnimekiri

Enne kasutuselevõttu kontrolli iga punkti:

Taristu

  • Keskkonnamuutujad konfigureeritud (OPENAI_API_KEY jne)
  • Aegumised ja max_retries seadistatud
  • Struktureeritud logimine olemas
  • Kulude jälgimine lubatud

Vastupidavus

  • Täielik veahaldus (kõik HTTP koodid)
  • Eksponentsiaalne tagasiminek (backoff) korduste jaoks
  • Vooluahela katkestaja (circuit breaker) pikaajaliste katkestuste jaoks
  • Varuvariant alternatiivsele mudelile

Turvalisus

  • API võti mitte kunagi koodis või logides avalikustatud
  • Kasutaja sisendi valideerimine
  • Kliendipoolne kiirusepiirang
  • Tundlikke andmeid ei sisaldu sõnumites

Jõudlus

  • Voogedastus (streaming) lubatud kasutajaliideste jaoks
  • Paketttöötlus suure mahuga ülesannete jaoks
  • Vahemällu salvestamine korduvate päringute jaoks
  • Mudeli valik kohandatud iga ülesande jaoks

Kulud

  • Päevane eelarve defineeritud
  • Hoiatused seadistatud
  • max_output_tokens määratud, kus võimalik
  • Iga ülesande jaoks valitud kuluefektiivseim mudel

Peamised punktid

  • Tsentraliseeri kliendi konfiguratsioon singletoni abil
  • Eralda ja versioneeri oma sõnumid väljaspool koodi
  • Rakenda mudeli varuvariant kõrge kättesaadavuse tagamiseks
  • Kasuta mahukate ülesannete jaoks piiratud samaaegsusega paketttöötlust
  • Testi oma sõnumeid kvaliteedikontrollidega
  • Järgi enne iga tootmisse viimist täielikku kontrollnimekirja