Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Parhaat käytännöt tuotantoympäristöön

Oppitunti 17 / 22 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Parhaat käytännöt tuotantoympäristöön
  2. 1. Asiakasarkkitehtuuri
  3. 2. Kehotusten hallinta
  4. 3. Aikakatkaisut ja rajoitukset
  5. 4. Mallien varmistus (Fallback)
  6. 5. Eräajot
  7. 6. Testaus ja validointi
  8. 7. Tuotantoon käyttöönoton tarkistuslista
  9. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: parametrit temperature ja top_p hyväksytään vain, kun päättelypyrkimys (reasoning effort) on none, kun taas GPT-5.6-mallit käyttävät oletusarvoisesti päättelyä (medium). Näitä parametreja asettavien kutsujen on siksi määritettävä reasoning={"effort": "none"} (Responses API) tai reasoning_effort="none" (Chat Completions). Lähteet: Using GPT-6 · GPT-5.6 Terra.

Parhaat käytännöt tuotantoympäristöön

Tämä oppitunti käsittelee olennaisia parhaita käytäntöjä OpenAI API -pohjaisen sovelluksen käyttöönotossa tuotantoympäristössä. Pidä tätä julkaisua edeltävänä tarkistuslistanasi. Aiemmat oppitunnit antoivat sinulle rakennuspalikat: virheenkäsittelyn, nopeusrajoitukset, joustavuuden, havainnoitavuuden ja kustannukset. Nyt on aika koota ne sovellukseksi, jonka kollegasi voi ottaa haltuunsa ja ajaa ilman apuasi.

1. Asiakasarkkitehtuuri

Singleton ja keskitetty konfiguraatio

OpenAI-asiakkaan luominen jokaisessa kutsussa tuhlaa taustalla olevan HTTP-yhteyden ja, mikä vakavampaa, hajauttaa konfiguraatiosi. Lopputuloksena on täällä 30 sekunnin aikakatkaisu ja siellä oletusarvo, ilman mahdollisuutta tietää, kumpaa sovelletaan tuotannossa. lru_cache-koriste takaa yhden ainoan esiintymän, joka on konfiguroitu yhteen paikkaan.

from openai import OpenAI
from functools import lru_cache

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

# Kaikkialla koodissasi:
client = get_client()

Ympäristömuuttujat

Sama periaate pätee asetuksiin, jotka vaihtelevat ympäristöjen välillä. Tarkista vaaditut muuttujat käynnistyksen yhteydessä: on parempi, että palvelu kieltäytyy käynnistymästä selkeällä viestillä, kuin että se käynnistyy ja epäonnistuu ensimmäisessä käyttäjäkutsussa. Tämä tekee mallista, token-rajoituksesta ja lämpötilasta säädettäviä ilman uudelleenkäyttöönottoa.

import os

# VAADITTU: älä koskaan kovakoodaa avaimia
REQUIRED_ENV = ["OPENAI_API_KEY"]

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

# Ympäristökohtainen konfiguraatio
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. Kehotusten hallinta

Erota kehotukset koodista

Kehote on liiketoimintavarallisuutta aivan kuten liiketoimintasääntökin. Sen hautaaminen f-merkkijonoon funktion sisälle tekee mahdottomaksi, että liiketoimintaa tunteva mutta Pythonia osaamaton henkilö voisi tarkistaa sen. Eristä se parametrisoituna mallina: funktio pelkistyy sitten muotoiluun ja kutsumiseen, ja lämpötila 0.0 tekee luokittelusta toistettavaa.

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

Versioi kehotuksesi

Kehotteen muuttaminen muuttaa järjestelmän toimintaa yhtä varmasti kuin koodin muuttaminen, mutta ilman että yksikkötesti huomaisi sitä. Pidä yllä peräkkäisiä versioita ja valitse aktiivinen versio konfiguraation kautta. Tämä antaa sinulle mahdollisuuden verrata kahta formulointia todellisessa liikenteessä ja palata edelliseen ympäristömuuttujan avulla, jos uusi heikentää tuloksia.

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

# Tuotannossa käytetään tiettyä versiota
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Aikakatkaisut ja rajoitukset

Rajoita kaikki ulkopuolelta tuleva syöte ennen kuin se saavuttaa API:n. Käyttäjän, joka liittää 200-sivuisen PDF-tiedoston syöttökenttääsi, ei tule pystyä laukaisemaan monien dollarien arvoista kutsua tai aiheuttamaan pyynnön epäonnistumista kontekstin ylivuodon vuoksi. Ennaltaehkäisevä typistäminen yhdistettynä tulostusrajoitukseen ja konfiguraatiosta tulevaan lämpötilaan tekee jokaisen kutsun kustannuksista ja viiveestä ennustettavia.

def appel_avec_garde_fous(prompt: str) -> str:
    """API-kutsu kaikilla suojauksilla."""
    # Rajoita kehotteen kokoa
    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. Mallien varmistus (Fallback)

Kun malli on ylikuormitettu tai väliaikaisesti saatavilla, virheen palauttaminen ei ole ainoa vaihtoehto. Vaihtaminen toissijaiseen malliin heikentää laatua, mutta säilyttää palvelun – kompromissi, joka on usein suositeltava tukiasistentille, vähemmän sopiva sopimusanalyysiin. Silmukka käy läpi malleja mieltymysjärjestyksessä ja nostaa poikkeuksen vain, jos kaikki epäonnistuvat.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Yrittää Terra-mallia ja siirtyy tarvittaessa Lunaan."""
    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. Eräajot

Tuhannen dokumentin käsittelyyn peräkkäiset kutsut ovat liian hitaita ja samanaikaiset kutsut räjäyttävät nopeusrajoituksesi. Semafori löytää oikean tasapainon. Kaksi yksityiskohtaa tekee tästä toteutuksesta vankan: return_exceptions=True estää yhden epäonnistumisen peruuttamasta koko erää, ja indeksiin lajittelu palauttaa alkuperäisen järjestyksen, jota asyncio.gather ei takaa suoritusajassa.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Käsittelee kehotuserän rajoitetulla samanaikaisuudella."""
    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)

    # Lajittele indeksin mukaan järjestyksen säilyttämiseksi
    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. Testaus ja validointi

Tarvitset kahta erityyppistä testiä. Ensimmäinen tarkistaa putkistot – avain toimii, verkko läpäisee, malli vastaa – ja sopii hyvin käynnistyksen terveystarkistukseen. Toinen, omaperäisempi, testaa itse kehotteen laatua: lähetät tapauksen, jossa tiedät oikean vastauksen, ja varmistat sen ilmestyvän. Nämä väittämät ovat turvaverkkosi regressioita vastaan, kun muotoilet mallia uudelleen.

def test_api_disponible():
    """Varmistaa, että API on käytettävissä."""
    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:
    """Varmistaa, että kehotus palauttaa johdonmukaisen tuloksen."""
    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

# Kehotuksen regressiotestit
assert test_prompt_quality(
    "Classify 'excellent product': positive or negative?",
    "positive"
)

Rakenna tusinan verran tällaisia testitapauksia, jotka edustavat todellisia käyttötapauksiasi, ja aja ne joka kerta, kun muokkaat kehotetta. Kymmenen minuutin testisarja säästää sinut viikoilta epäilyksiä koetusta laadusta.

7. Tuotantoon käyttöönoton tarkistuslista

Ennen käyttöönottoa varmista jokainen kohta:

Infrastruktuuri

  • Ympäristömuuttujat konfiguroitu (OPENAI_API_KEY jne.)
  • Aikakatkaisut ja max_retries asetettu
  • Jäsennelty lokitus käytössä
  • Kustannusseuranta aktivoitu

Joustavuus

  • Täydellinen virheenkäsittely (kaikki HTTP-koodit)
  • Eksponentiaalinen viive uudelleenyrityksille
  • Katkaisija (circuit breaker) pitkittyneitä katkoja varten
  • Varmistus vaihtoehtoiseen malliin

Turvallisuus

  • API-avain ei koskaan paljastettu koodissa tai lokeissa
  • Käyttäjän syötteen validointi
  • Asiakaspuolen nopeusrajoitus
  • Ei arkaluonteisia tietoja kehotteissa

Suorituskyky

  • Suoratoisto (streaming) käytössä käyttöliittymille
  • Eräajot suurivolyymisille tehtäville
  • Välimuisti toistuville pyynnöille
  • Mallin valinta mukautettu kuhunkin tehtävään

Kustannukset

  • Päivittäinen budjetti määritelty
  • Hälytykset konfiguroitu
  • max_output_tokens asetettu mahdollisuuksien mukaan
  • Kustannustehokkain malli valittu tehtävää kohden

Keskeiset asiat

  • Keskitä asiakaskonfiguraatio singletonilla
  • Erota kehotteet koodista ja versioi ne erikseen
  • Toteuta mallien varmistus korkean saatavuuden takaamiseksi
  • Käytä eräajoja rajoitetulla samanaikaisuudella volyymien käsittelyyn
  • Testaa kehotteitasi laatuvaatimuksilla
  • Noudata täydellistä tarkistuslistaa ennen jokaista tuotantoon käyttöönottoa