Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

L-Aħjar Prattiki għall-Produzzjoni

Lezzjoni 17 / 22 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. L-Aħjar Prattiki għall-Produzzjoni
  2. 1. Arkitettura tal-Klijent
  3. 2. Ġestjoni tal-Prompts
  4. 3. Timeouts u Limiti
  5. 4. Fallback tal-Mudell
  6. 5. Ipproċessar Batch
  7. 6. Ittestjar u Validazzjoni
  8. 7. Checklist tad-Dispjega fil-Produzzjoni
  9. Punti Ewlenin

Lezzjoni aġġornata fit-3 ta’ Novembru 2026 ibbażata fuq id-dokumentazzjoni ta’ OpenAI: temperature u top_p huma aċċettati biss b’sforz ta’ raġunar ta’ none, filwaqt li l-mudelli GPT-5.6 jirraġunaw b’mod awtomatiku (medium). Għalhekk, is-sejħiet li jistabbilixxu dawn il-parametri jridu jispeċifikaw reasoning={"effort": "none"} (Responses API) jew reasoning_effort="none" (Chat Completions). Sorsi: L-Użu ta’ GPT-6 · GPT-5.6 Terra.

L-Aħjar Prattiki għall-Produzzjoni

Din il-lezzjoni tkopri l-aħjar prattiki essenzjali biex tiddispjega applikazzjoni bbażata fuq l-API ta’ OpenAI fil-produzzjoni. Ħu din bħala ċ-checklist tiegħek qabel it-tnedija. Il-lezzjonijiet preċedenti tawk il-blokki tal-bini—ġestjoni tal-iżbalji, limiti tar-rata, reżiljenza, osservabbiltà u spejjeż. Issa wasal iż-żmien biex tgħaqqadhom f’applikazzjoni li kollega jista’ jieħu f’idejh u jmexxi mingħajrek.

1. Arkitettura tal-Klijent

Singleton b’Konfigurazzjoni Ċentralizzata

Li tistanzja klijent ta’ OpenAI f’kull sejħa tiħela l-konnessjoni HTTP sottostanti u, aktar serjament, tferrex il-konfigurazzjoni tiegħek. tispiċċa b’timeout ta’ 30 sekonda hawn u d-default hemm, mingħajr ma tkun taf liema wieħed japplika fil-produzzjoni. Id-dekoratur lru_cache jiggarantixxi istanza waħda, ikkonfigurata f’post wieħed.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Klijent singleton b'konfigurazzjoni għall-produzzjoni."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# Kullimkien fil-kodiċi tiegħek:
client = get_client()

Varjabbli tal-Ambjent

L-istess prinċipju japplika għall-issettjar li jvarja bejn l-ambjenti. Iċċekkja l-varjabbli meħtieġa meta tibda: huwa aħjar li servjut jirrifjuta li jibda b’messaġġ ċar milli jibda u jfalli fl-ewwel sejħa tal-utent. Dan jagħmel il-mudell, il-limitu tat-token u t-temperatura aġġustabbli mingħajr ma terġa’ tiddispjega.

import os

# MEĦTIEĠ: qatt ma tħalli ċ-ċwievet hard-coded
REQUIRED_ENV = ["OPENAI_API_KEY"]

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

# Konfigurazzjoni speċifika għall-ambjent
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. Ġestjoni tal-Prompts

Separa l-Prompts mill-Kodiċi

Prompt huwa assi tan-negozju, eżatt bħal regola tan-negozju. Li tidfnu f’f-string ġewwa funzjoni jagħmilha impossibbli għal xi ħadd li jaf in-negozju iżda mhux Python biex jirrevedih. Iżolah bħala mudell parametrizzat: il-funzjoni mbagħad tonqos għall-iffurmar u s-sejħa, u temperatura ta’ 0.0 tagħmel il-klassifikazzjoni riproduċibbli.

# prompts/classification.txt
PROMPT_CLASSIFICATION = """Inti klassifikatur tat-test.
Ikklassifika t-test li ġej f'waħda minn dawn il-kategoriji:
{categories}

Test: {texte}

Wieġeb biss bl-isem tal-kategorija."""

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"},  # it-temperatura teħtieġ sforz none
        input=prompt,
        temperature=0.0
    )
    return response.output_text.strip()

Agħmel Verżjonijiet tal-Prompts Tiegħek

Il-bidla ta’ prompt tbiddel l-imġiba tas-sistema bl-istess certezza li tbiddel il-kodiċi, iżda mingħajr ma xi test tal-unità jinnota. Żomm verżjonijiet suċċessivi u agħżel dik attiva permezz tal-konfigurazzjoni. Dan jippermettilek tqabbel żewġ formulazzjonijiet fuq traffiku reali u terġa’ lura għal dik ta’ qabel b’varjabbli tal-ambjent jekk dik il-ġdida tnaqqas ir-riżultati.

PROMPTS = {
    "classification_v1": "Ikklassifika: {texte}",
    "classification_v2": "Analiża u kklassifika b'mod preċiż: {texte}",
}

# Fil-produzzjoni, uża verżjoni speċifika
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Timeouts u Limiti

Illimita kwalunkwe input minn barra qabel ma jilħaq l-API. Utent li jpejstja PDF ta’ 200 paġna fil-kamp tal-input tiegħek m’għandux ikun jista’ jikkawża sejħa ta’ diversi dollari jew jikkawża li t-talba tfalli minħabba eċċess tal-kuntest. It-tronkament preventiv, flimkien mal-kapp tal-output u t-temperatura mill-konfigurazzjoni, jagħmel l-ispiża u l-latency ta’ kull sejħa prevedibbli.

def appel_avec_garde_fous(prompt: str) -> str:
    """Sejħa API bil-garanziji kollha."""
    # Illimita d-daqs tal-prompt
    MAX_PROMPT_CHARS = 50000
    if len(prompt) > MAX_PROMPT_CHARS:
        prompt = prompt[:MAX_PROMPT_CHARS]
        print(f"Prompt imqassar għal {MAX_PROMPT_CHARS} karattru")

    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # it-temperatura teħtieġ sforz none
        input=prompt,
        max_output_tokens=MAX_TOKENS,
        temperature=TEMPERATURE,
    )

    return response.output_text

4. Fallback tal-Mudell

Meta mudell ikun saturat jew temporanjament mhux disponibbli, ir-ritorn ta’ żball mhix l-unika għażla tiegħek. L-ibdil għal mudell sekondarju jnaqqas il-kwalità iżda jippreserva s-servizz—kompromess spiss preferibbli għal assistent tas-support, inqas għall-analiżi tal-kuntratti. Il-linja tgħaddi mill-mudelli f’ordni ta’ preferenza u tqajjem eċċezzjoni biss jekk ifallu kollha.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Jipprova Terra imbagħad jagħmel fallback għal Luna fuq żball."""
    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} mhux disponibbli: {e}")
            continue

    raise RuntimeError("Il-mudelli kollha mhumiex disponibbli")

5. Ipproċessar Batch

Biex tipproċessa elf dokument, is-sejħiet sekwenzjali huma wisq bil-mod u s-sejħiet simultanji jfaqqgħu l-limiti tar-rata tiegħek. Semaphor jolqot il-bilanċ it-tajjeb. Żewġ dettalji jagħmlu din l-implimentazzjoni robusta: return_exceptions=True jipprevjeni li falliment wieħed jikkanċella l-batch kollu, u s-sortjar skont l-indiċi jerġa’ jistabbilixxi l-ordni oriġinali, li asyncio.gather ma jiggarantixxix fil-ħin ta’ eżekuzzjoni.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Jipproċessa batch ta' prompts b'konkorrenza limitata."""
    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)

    # Issortja skont l-indiċi biex iżżomm l-ordni
    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 = ["Mistoqsija 1", "Mistoqsija 2", "Mistoqsija 3"]
# résultats = asyncio.run(traiter_batch(prompts))

6. Ittestjar u Validazzjoni

Għandek bżonn żewġ tipi differenti ta’ testijiet. L-ewwel jiċċekkja l-plumbing—iċ-ċavetta taħdem, in-netwerk jgħaddi, il-mudell iwieġeb—u joqgħod tajjeb f’kontroll tas-saħħa meta tibda. It-tieni, aktar oriġinali, jittestja l-kwalità tal-prompt innifsu: tissottometti każ fejn tkun taf it-tweġiba korretta u tivverifika li tidher. Dawn l-asserzjonijiet huma n-netwerk tas-sigurtà tiegħek kontra r-regressjonijiet meta terġa’ tifformula mudell.

def test_api_disponible():
    """Jivverifika li l-API hija aċċessibbli."""
    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:
    """Jivverifika li prompt jirritorna riżultat konsistenti."""
    response = get_client().responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # it-temperatura teħtieġ sforz none
        input=prompt,
        temperature=0.0
    )
    resultat = response.output_text.lower()
    return attendu.lower() in resultat

# Testijiet ta' regressjoni tal-Prompt
assert test_prompt_quality(
    "Ikklassifika 'prodott eċċellenti': pożittiv jew negattiv?",
    "pożittiv"
)

Ibni dożżina ta’ każijiet ta’ test bħal dawn, rappreżentattivi tal-każijiet reali tal-użu tiegħek, u ġarrihom kull darba li timmodifika prompt. Suite ta’ test ta’ għaxar minuti se tiffrankalek ġimgħat ta’ dubju dwar il-kwalità perċepita.

7. Checklist tad-Dispjega fil-Produzzjoni

Qabel ma tiddispjega, ivverifika kull punt:

Infrastruttura

  • Varjabbli tal-ambjent ikkonfigurati (OPENAI_API_KEY, eċċ.)
  • Timeouts u max_retries ikkonfigurati
  • Reġistrazzjoni strutturata fis-seħħ
  • Monitoraġġ tal-ispejjeż attivat

Reżiljenza

  • Ġestjoni sħiħa tal-iżbalji (il-kodiċijiet HTTP kollha)
  • Backoff esponenzjali għar-ritenti
  • Circuit breaker għal interruzzjonijiet fit-tul
  • Fallback għal mudell alternattiv

Sigurtà

  • Iċ-ċavetta tal-API qatt ma tkun esposta fil-kodiċi jew fir-reġistri
  • Validazzjoni tal-input tal-utent
  • Limitazzjoni tar-rata fuq in-naħa tal-klijent
  • L-ebda data sensittiva fil-prompts

Prestazzjoni

  • Streaming attivat għall-interfaċċi tal-utent
  • Ipproċessar batch għal kompiti b’volum għoli
  • Caching għal talbiet ripetittivi
  • Għażla tal-mudell adattata għal kull kompitu

Spejjeż

  • Baġit ta’ kuljum iddefinit
  • Avviżi kkonfigurati
  • max_output_tokens issettjat fejn possibbli
  • L-aktar mudell kost-effettiv magħżul għal kull kompitu

Punti Ewlenin

  • Iċċentralizza l-konfigurazzjoni tal-klijent b’singleton
  • Separa u agħmel verżjonijiet tal-prompts tiegħek barra mill-kodiċi
  • Implimenta fallback tal-mudell għal disponibbiltà għolja
  • Uża l-ipproċessar batch b’konkorrenza limitata għall-volum
  • Ittestja l-prompts tiegħek b’asserzjonijiet tal-kwalità
  • Segwi ċ-checklist sħiħa qabel kull dispjega fil-produzzjoni