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

Prattiki Aħjar għall-Produzzjoni

Lezzjoni 16 / 16 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Mill-Prova tal-Kunċett għad-Dispjegament
  2. Awtentikazzjoni u Verżjonar tal-Mudell
  3. Klijent li Jimmaniġġja l-Inċidenti
  4. Traċċa l-Ispejjeż Hekk kif iseħħu
  5. Ivvvalida fiż-Żewġ Truf
  6. Żomm il-Tieqa tal-Kuntest
  7. X’tieħu miegħek minn dan il-Kors
  8. Punti Ewlenin
  9. Ittestja l-Għarfien Tiegħek

Mill-Prova tal-Kunċett għad-Dispjegament

Issa tgħallimt kull parametru tal-API tal-Kompletamenti taċ-Chat. L-aktar parti diffiċli tibqa’: li tgħaqqad in-notebook li jaħdem ma’ servizz li jużaw oħrajn mingħajr l-intervent tiegħek. Din il-lezzjoni finali tiġbor il-kors kollu f’lista ta’ kontroll operattiva għall-produzzjoni, imbagħad turi t-triq lejn korsijiet ta’ segwitu.

Awtentikazzjoni u Verżjonar tal-Mudell

Żewġ deċiżjonijiet jiġu qabel l-ewwel linja ta’ loġika tan-negozju. L-ewwel tikkonċerna ċ-ċavetta tal-API: din tgħix f’varjabbli tal-ambjent, qatt fil-kodiċi, u affermazzjoni fil-bidu taħdem aħjar minn None li tippropaga tliet saffi ‘l isal f’messaġġ ta’ żball inkomprensibbli. Ippjana għar-rotazzjoni wkoll—oħloq iċ-ċavetta l-ġdida, iddispjegahha, imbagħad irrevoka dik antika, f’dak l-ordni, jekk trid tevita li tħalli s-servizz offline.

import os

# DEJM: Ċavetta tal-API f'varjabbli tal-ambjent
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY mhux definita"

# QATT: Ċavetta hard-coded fil-kodiċi
# api_key = "sk-abc123..."  # IPPROIBIT fil-produzzjoni

# DEJM: Rotazzjoni regolari taċ-ċavetta
# Oħloq ċavetta ġdida, iddispjegahha, imbagħad irrevoka dik antika

It-tieni deċiżjoni tikkonċerna l-identifikatur tal-mudell. Fl-iżvilupp, -latest jagħtik titjib mingħajr sforz. Fil-produzzjoni, dak l-istess alias ifisser li bidla fil-verżjoni fuq in-naħa tal-fornitur tista’ tbiddel l-imġiba tal-applikazzjoni tiegħek mingħajr twissija, nhar Tlieta filgħodu, mingħajr l-ebda traċċa ta’ commit biex tispjegaha. Iffissa l-verżjoni.

# ŻVILUPP — l-aħħar verżjoni
model = "mistral-large-latest"

# PRODUZZJONI — verżjoni fissa għar-riproduċibbiltà
model = "mistral-large-2512"

# Għaliex? Bidla "latest" tista' tbiddel l-imġiba tal-applikazzjoni tiegħek
# mingħajr twissija.

Klijent li Jimmaniġġja l-Inċidenti

Il-qalba ta’ integrazzjoni tal-produzzjoni mhix is-sejħa tal-API iżda kollox madwarha. Il-klassi hawn taħt tgħaqqad tliet responsabbiltajiet f’punt uniku ta’ kontroll: retry b’backoff esponenzjali fuq 429s, pausa qasira fuq żbalji tas-server, u eskalazzjoni immedjata ta’ żbalji tal-klijent li l-ebda retry ma jsewwi. Hija tinnormalizza r-risposta f’dizzjunarju stabbli—kontenut, finish_reason, użu, mudell, ID—biex il-bqija tal-kodiċi tiegħek ma jiddependix aktar mill-forma eżatta tal-oġġett irritornat mill-SDK. Il-logger.warning fuq it-trunkament waħdu jiġġustifika l-inkapsulament: hija l-unika mod biex tiskopri li s-setting ta’ max_tokens huwa strett wisq qabel ma l-utenti jirrapportawh.

from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging

logger = logging.getLogger(__name__)

class MistralClient:
    """Klijent tal-produzzjoni b'retry, timeout, u logging."""

    def __init__(self, api_key: str, max_retries: int = 3):
        self.client = Mistral(api_key=api_key)
        self.max_retries = max_retries

    def complete(self, messages: list, **kwargs) -> dict:
        for attempt in range(self.max_retries):
            try:
                response = self.client.chat.complete(
                    messages=messages,
                    **kwargs
                )

                result = {
                    "content": response.choices[0].message.content,
                    "finish_reason": response.choices[0].finish_reason,
                    "usage": {
                        "prompt": response.usage.prompt_tokens,
                        "completion": response.usage.completion_tokens,
                        "total": response.usage.total_tokens,
                    },
                    "model": response.model,
                    "id": response.id,
                }

                # Avviża jekk ir-risposta tkun tronkata
                if result["finish_reason"] == "length":
                    logger.warning(f"Risposta tronkata — req_id={response.id}")

                return result

            except SDKError as e:
                if e.status_code == 429:
                    wait = 2 ** attempt
                    logger.warning(f"Limitu tar-rata, retry {attempt+1}/{self.max_retries} f'{wait}s")
                    time.sleep(wait)
                elif e.status_code >= 500:
                    logger.error(f"Żball tas-server {e.status_code}, retry {attempt+1}")
                    time.sleep(1)
                else:
                    logger.error(f"Żball tal-klijent {e.status_code}: {e.message}")
                    raise

        raise Exception(f"Falliment wara {self.max_retries} tentattivi")

Traċċa l-Ispejjeż Hekk kif iseħħu

Li tiskopri l-konsum tiegħek fil-kont mensili huwa lussu li ftit timijiet jistgħu jaffordjaw. It-tracker hawn taħt jikteb linja JSONL waħda għal kull sejħa—timestamp, mudell, tokens tal-input u tal-output, finish_reason, ID tat-talba—u jżomm total tas-sessjoni li tista’ tikkonsulta fi kwalunkwe ħin. Il-format JSONL mhix dettall: jaggrega ma’ kwalunkwe għodda analitika mingħajr pass ta’ parsing, u l-preżenza tal-ID tat-talba tippermettilek torbot anomaliija fl-ispejjeż ma’ sejħa speċifika.

import json
from datetime import datetime, timezone

class CostTracker:
    """Traċċar tal-ispejjeż tal-API f'ħin reali."""

    def __init__(self, log_path: str = "api_costs.jsonl"):
        self.log_path = log_path
        self.session_tokens = {"prompt": 0, "completion": 0}

    def log(self, response_data: dict):
        usage = response_data["usage"]
        self.session_tokens["prompt"] += usage["prompt"]
        self.session_tokens["completion"] += usage["completion"]

        entry = {
            "ts": datetime.now(timezone.utc).isoformat(),
            "model": response_data["model"],
            "prompt_tokens": usage["prompt"],
            "completion_tokens": usage["completion"],
            "finish_reason": response_data["finish_reason"],
            "id": response_data["id"],
        }

        with open(self.log_path, "a") as f:
            f.write(json.dumps(entry) + "\n")

    def report(self) -> str:
        total = self.session_tokens["prompt"] + self.session_tokens["completion"]
        return (
            f"Sessjoni — Prompt: {self.session_tokens['prompt']:,} | "
            f"Kompletament: {self.session_tokens['completion']:,} | "
            f"Total: {total:,} tokens"
        )

Ivvvalida fiż-Żewġ Truf

Applikazzjoni robusta ma tifda la dak li jidħol u lanqas dak li joħroġ. Fuq l-input, irrifjuta messaġġi vojta, illimita t-tul għal 10,000 karattru biex tipprevjeni copy-paste sfortunat li jneffaħ il-kont tiegħek, u neħħi karattri ta’ kontroll li jfixklu t-tokenizzazzjoni. Fuq l-output, tirrifjuta xejn iżda qajjem twissijiet: risposta potenzjalment tronkata, risposta abnormalment qasira taħt ħames karattri, risposta abnormalment twila ‘l fuq minn 50,000. Dawn it-tliet sinjali jaqbdu l-biċċa l-kbira tal-fallimenti silenzjużi.

def validate_input(user_message: str) -> str:
    """Ivvalida u nnaddaf l-input tal-utent."""
    if not user_message or not user_message.strip():
        raise ValueError("Messaġġ vojt")

    if len(user_message) > 10_000:
        raise ValueError("Messaġġ twil wisq (massimu 10,000 karattru)")

    # Naddaf karattri ta' kontroll
    cleaned = "".join(c for c in user_message if c.isprintable() or c in "\n\t")
    return cleaned.strip()

def validate_output(content: str, finish_reason: str) -> dict:
    """Ivvalida l-output tal-API."""
    warnings = []

    if finish_reason == "length":
        warnings.append("Risposta potenzjalment tronkata")

    if not content or len(content.strip()) < 5:
        warnings.append("Risposta abnormalment qasira")

    if len(content) > 50_000:
        warnings.append("Risposta abnormalment twila")

    return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}

Żomm il-Tieqa tal-Kuntest

Kwistjoni finali: id-drift bil-mod ta’ konversazzjonijiet twal. Il-funzjoni hawn taħt tistma l-volum f’token wieħed għal kull erba’ karattri bil-Malti—approssimazzjoni ħarxa iżda biżżejjed bħala guardrail—u tħalli t-talbiet jgħaddu sakemm jibqgħu taħt 80% tal-limitu. Lil hinn minn hekk, iżżomm il-prompt tas-sistema u tneħħi l-eqdem messaġġi sakemm terġa’ tinżel taħt 70%. Dan il-vojt bejn iż-żewġ limiti huwa deliberat: li taqta’ biss sal-limitu tal-attivazzjoni kien iġib lura l-funzjoni fil-ħamra fuq il-messaġġ li jmiss.

def manage_context(messages: list, max_tokens: int = 100_000) -> list:
    """Żomm il-messaġġi fil-limitu tat-tokens tal-mudell."""
    # Stima: 1 token ~ 4 karattri bil-Malti
    total_chars = sum(len(m["content"]) for m in messages)
    estimated_tokens = total_chars // 4

    if estimated_tokens < max_tokens * 0.8:
        return messages  # Kollox joqgħod

    # Żomm is-sistema + l-ewwel u l-aħħar messaġġi
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"]

    # Neħħi l-eqdem messaġġi
    while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
        removed = history.pop(0)
        estimated_tokens -= len(removed["content"]) // 4

    return system + history

X’tieħu miegħek minn dan il-Kors

Il-vjaġġ segwa erba’ passi. L-ewwel, il-fundamentali: l-endpoint, ir-rwoli, il-parametri bażiċi, u l-istruttura tar-risposta. Imbagħad, l-istreamjar, bil-protokoll SSE, l-implimentazzjoni Python tiegħu, is-sekwenzi ta’ waqfien, u t-tisħiħ permezz ta’ safe_prompt u guardrails. Il-Prompting okkupa t-tielet fażi—prompts tas-sistema tal-produzzjoni, few-shot, strutturar XML u Markdown, anti-patterns. Il-parametri avvanzati għalqu ċ-ċirku: it-temperatura u Top P fid-dettall, penali tal-preżenza u tal-frekwenza, N kompletamenti, u din il-lista ta’ kontroll tal-produzzjoni.

Il-konfigurazzjoni hawn taħt tiddestilla dawn il-għażliet f’punt tat-tluq difendibbli għal ewwel dispjegament tal-produzzjoni: verżjoni fissa, saqaf ta’ tokens adattat għall-każ tal-użu, temperatura baxxa għall-konsistenza fattwali, top_p mhux mimsus peress li t-temperatura hija aġġustata, penali newtrali sakemm ħtieġa speċifika ma tiġġustifikahomx, u safe_prompt attivat.

# Konfigurazzjoni tipika għal applikazzjoni tal-produzzjoni
PRODUCTION_CONFIG = {
    "model": "mistral-large-2512",      # Verżjoni fissa
    "max_tokens": 2000,                  # Adattat għall-każ tal-użu
    "temperature": 0.3,                  # Konsistenti u fattwali
    "top_p": 1.0,                        # Mhux mimsus jekk it-temperatura tiġi aġġustata
    "presence_penalty": 0.0,             # Default sakemm ma jkunx hemm ħtieġa speċifika
    "frequency_penalty": 0.0,            # Default sakemm ma jkunx hemm ħtieġa speċifika
    "safe_prompt": True,                 # Sigurtà attivata
}

Biex tmur aktar ‘il quddiem mal-API ta’ Mistral, erba’ korsijiet komplementari jsegwu fuq Corsen Academy:

  • Embeddings u RAG — Tiftix semantiku b’mistral-embed u databases vettorjali
  • Function Calling — Qabbad il-mudell mal-għodod tiegħek u APIs esterni
  • Fine-tuning — Adatta mudell għad-dominju speċifiku tiegħek
  • Produzzjoni u Evalwazzjoni — Metriċi, evalwazzjonijiet awtomatizzati, ottimizzazzjoni tal-ispejjeż

Punti Ewlenin

  • Uża mudelli b’verżjoni fil-produzzjoni, qatt -latest
  • Implimenta retry + backoff + logging mill-ewwel dispjegament
  • Ivvvalida kemm l-inputs KIF UKOLL l-outputs ta’ kull sejħa tal-API
  • Traċċa l-ispejjeż f’ħin reali b’tracker tat-tokens
  • Immaniġġja t-tieqa tal-kuntest għal konversazzjonijiet twal
  • Attiva safe_prompt bħala netwerk minimu ta’ sigurtà
  • Ittestja l-prompts tiegħek b’każijiet limitu qabel kull rilaxx tal-produzzjoni

Ittestja l-Għarfien Tiegħek

L-ebda sigriet ieħor fl-endpoint chat/completions? Ejja nivverifikaw.

1. Liema rwoli jistrutturaw il-lista tal-messaġġi?

Tweġiba: system (il-qafas), user (it-talbiet), assistant (ir-risposti tal-mudell)—l-istorja sħiħa terġa’ tibda ma’ kull sejħa, peress li l-API hija mingħajr stat.

2. X'tara fil-qasam tal-użu tar-risposta?

Tweġiba: Tokens ikkunsmati fuq l-input u l-output—il-bażi għall-fatturar u l-metrika biex tosserva għad-daqs u l-ispejjeż.

3. Kif jaħdem l-istreamjar SSE?

Tweġiba: Ir-risposta tasal bħala Server-Sent Events, framment b’framment: turi hekk kif tiġi u tikkonkatena biex tikseb il-messaġġ finali.

4. Għal xiex iservu s-sekwenzi ta' waqfien?

Tweġiba: Biex taqta’ l-ġenerazzjoni hekk kif tidher stringa mogħtija: ikkontrolla t-tul, waqaf f’delimitatur, iggarantixxi formati nodfa.

5. Temperatura, Top P, penali: liema użu fil-produzzjoni?

Tweġiba: It-Temperatura/Top P jistabbilixxu d-determiniżmu skont il-kompitu; il-penali tal-preżenza/frekwenza jillimitaw ir-ripetizzjoni—settings biex tiffissa skont il-każ tal-użu u tiddokumenta flimkien mal-prompts tiegħek.

Rwoli, użu, istreamjar, waqfien, tuning: il-fundamentali jżommu—il-prattiki aħjar tal-produzzjoni hawn fuq iqiegħduhom f’ordni.