Prattiki Aħjar għall-Produzzjoni
F'din il-paġna
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-embedu 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_promptbħ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.