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

L-Aħjar Prattiki u Sommarju

Lezzjoni 12 / 12 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Sommarju tal-Kors
  2. L-Għażla tal-Approċċ Tiegħek
  3. L-Għaxar Regoli tad-Deheb
  4. Tliet Żbalji Għaljin
  5. X’Għandek Timmonitorja
  6. Immur Aktar ‘il Quddiem
  7. Pipeline Sħiħa
  8. Punti Ewlenin
  9. Ittestja l-Għarfien Tiegħek

Sommarju tal-Kors

Esplorajt il-firxa sħiħa ta’ mekkaniżmi ta’ output strutturat offruti mill-API ta’ Mistral. Din il-lezzjoni finali tiġbor flimkien dak li jagħmel id-differenza fix-xogħol ta’ kuljum: kif tagħżel bejn iż-żewġ approċċi, is-settings mhux negozjabbli, l-iżbalji l-aktar komuni, u x’għandek timmonitorja ladarba tkun fil-produzzjoni.

L-Għażla tal-Approċċ Tiegħek

Erba’ mistoqsijiet huma biżżejjed biex tiddeċiedi, f’dan l-ordni. Għandek skema ta’ output definita? Jekk it-tweġiba hija le, ibqa’ mal-Modalità JSON: qiegħed f’modalità ta’ esplorazzjoni jew prototipar, u li tissakka mudell tad-data ikun prematuru. Jekk iva, imxi għall-mistoqsija li jmiss.

Qed taħdem f’Python jew TypeScript? Jekk iva, l-Outputs Strutturati Personalizzati huma lesti għalik b’Pydantic jew Zod. Jekk le, il-Modalità JSON b’validazzjoni manwali tibqa’ t-triq tiegħek.

Int fil-produzzjoni? Jekk iva, l-Outputs Strutturati Personalizzati huma obbligatorji, dejjem. Inkella, il-Modalità JSON hija aktar minn biżżejjed għall-prototipar.

L-iskema tinbidem spiss? Skema li għadha tevolvi tagħmel il-Modalità JSON aktar prattika fil-bidu, sakemm ir-rekwiżiti jistabbilizzaw; skema fissa tiġġustifika l-Outputs Strutturati Personalizzati u l-affidabbiltà li jġibu magħhom.

L-Għaxar Regoli tad-Deheb

L-ewwel ħamsa jikkonċernaw kif tikteb is-sejħiet tiegħek. Dejjem issettja temperature=0 fil-produzzjoni: il-varjabbiltà tat-temperatura hija l-għadu tal-affidabbiltà, u l-estrazzjoni m’għandha l-ebda ħtieġa għall-kreattività.

# Produzzjoni: deterministika
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    temperature=0  # Riproduċibbiltà
)

Dejjem iċċekkja finish_reason. Dan huwa l-uniku indikatur li jwissik dwar tweġiba mqatgħa qabel ma tipprova tużaha.

if response.choices[0].finish_reason != "stop":
    # It-tweġiba hija mqatgħa — żid max_tokens
    raise ValueError(f"Tweġiba mhux kompluta: {response.choices[0].finish_reason}")

Fil-Modalità JSON, dejjem istruwixxi l-mudell fil-prompt. Il-parametru jiggarantixxi s-sintassi, mhux l-istruttura: huwa dmir tiegħek li tiddikjara ċ-ċwievet u t-tipi tagħhom.

# Modalità JSON — il-prompt IRID jiddeskrivi l-istruttura
messages = [
    {
        "role": "system",
        "content": "Irritorna JSON biċ-ċwievet: name (string), age (number), city (string)."
    },
    {"role": "user", "content": text}
]

Fil-modalità Personalizzata, iddokumenta l-oqsma tiegħek. Deskrizzjoni preċiża tiswi aktar minn prompt twil, u tivvjaġġa mal-iskema fiż-żewġ lingwi.

class Product(BaseModel):
    name: str = Field(description="Isem kummerċjali tal-prodott")
    price: float = Field(description="Prezz bl-EUR mingħajr tax, imqarreb għal 2 deċimali")
const ProductSchema = z.object({
  name: z.string().describe("Isem kummerċjali tal-prodott"),
  price: z.number().describe("Prezz bl-EUR mingħajr tax, imqarreb għal 2 deċimali"),
});

Iffreda l-kuntest mill-kontenut. L-istruzzjonijiet jgħixu fil-messaġġ tas-sistema, id-data li trid tipproċessa fil-messaġġ tal-utent—qatt bil-maqlub, inkella l-mudell iħawwad l-istruzzjoni mat-test sors.

messages = [
    {"role": "system", "content": "Int estrattur tad-data. [Istruzzjonijiet tal-format]"},
    {"role": "user", "content": "[Test biex jiġi pproċessat — L-EBDA istruzzjoni tal-format hawn]"}
]

Iż-żewġ regoli li jmiss jikkonċernaw ix-xibka ta’ sigurtà tiegħek. Implimenta mekkaniżmu ta’ retry: qatt tagħmel sejħa waħda mingħajr backup; ir-retry b’feedback huwa l-mudell minimu fil-produzzjoni. U valida lil hinn mill-iskema, peress li l-iskema tiggarantixxi l-istruttura filwaqt li l-validazzjoni semantika—limiti, konsistenza, loġika tan-negozju—tibqa’ r-responsabbiltà tiegħek.

L-aħħar tlieta jirrelataw mal-orkestrazzjoni. Agħżel il-mudell it-tajjeb għall-każ ta’ użu t-tajjeb: mistral-large-latest għal kompiti kumplessi u estrazzjoni multi-oqsma, mistral-small-latest għal klassifikazzjoni sempliċi u estrazzjoni bażika, ministral-8b-latest għal frekwenza għolja u latenza minima. Irreġistra kull sejħa fil-produzzjoni, tirrekordja l-mudell użat, it-tul, finish_reason, u r-riżultat: mingħajr logs, inti għami. Fl-aħħar nett, toptimizzax il-prompt kmieni wisq—ibda sempliċi, kejjel, itera; l-ottimizzazzjoni prematura tal-prompt hija nassa komuni, filwaqt li l-iskema u l-validazzjoni huma l-levi veri.

Tliet Żbalji Għaljin

L-ewwel wieħed huwa valur ta’ max_tokens baxx wisq. Il-JSON se jiġi mqatta’ fuq tweġibiet twal, u l-iżball jidher biss fuq dokumenti kbar, spiss wara li tmur live.

# Perikoluż — il-JSON se jiġi mqatta' għal tweġibiet twal
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    max_tokens=128  # Baxx wisq għal skema kumplessa
)

Isssettja max_tokens ibbażat fuq id-daqs mistenni tal-output tiegħek: fattura b’20 linja teħtieġ aktar tokens minn klassifikazzjoni sempliċi.

It-tieni wieħed huwa temperatura mhux żero, li tagħmel ir-riżultati tiegħek mhux riproduċibbli mingħajr ebda qligħ f’kompitu ta’ estrazzjoni.

# Perikoluż fil-produzzjoni — riżultati mhux riproduċibbli
response = client.chat.parse(
    ...,
    temperature=0.7  # Varjazzjoni mhux meħtieġa għall-estrazzjoni
)

It-tielet wieħed huwa r-rifless li tuża mudell wieħed. Tużax mistral-large għal kollox: klassifikazzjoni binarja ma teħtiġx l-aktar mudell qawwi, u ministral-8b jagħmel ix-xogħol 5 darbiet aktar mgħaġġel b’inqas spiża.

X’Għandek Timmonitorja

Erba’ metriki jgħidulek is-saħħa tal-pipeline tiegħek. Ir-rata ta’ suċċess tkejjel il-perċentwal ta’ sejħiet li jirritornaw oġġett validu fl-ewwel tentattiv; ir-rata ta’ retry, il-perċentwal ta’ sejħiet li kellhom bżonn ċans ieħor. Il-latenza P50/P95 tagħti l-ħin medju ta’ tweġiba u l-perċentil 95, li huwa aktar rivelatur mill-medja. L-ispiża għal kull estrazzjoni, espressa f’tokens ikkunsmati għal kull sejħa, iżżomm il-kontroll tal-fattura.

Fuq dawn il-metriki, ftit limiti ta’ allerta jibqgħu sodi: rata ta’ suċċess taħt 95% tiġġustifika allerta safra, taħt 85% allerta ħamra; latenza P95 akbar minn 10 s teħtieġ investigazzjoni; u circuit breaker miftuħ isejjaħ għal allerta immedjata.

Immur Aktar ‘il Quddiem

Erba’ direzzjonijiet jestendu dan il-kors b’mod naturali. Is-sejħa tal-funzjoni tuża outputs strutturati biex titma’ sejħiet ta’ funzjonijiet f’aġent. L-istreaming jippermettilek tirċievi l-output strutturat progressivament, li jimpotta għal tweġibiet twal. Il-fine-tuning jaġġusta mudell ta’ Mistral biex itejjeb il-kwalità tal-estrazzjoni fuq id-data speċifika tiegħek. L-evalwazzjoni, fl-aħħar nett, tikkonsisti fit-twaqqif ta’ qafas awtomatiku bbażat fuq sett tad-data tad-deheb u metriki—dan huwa dak li jgħidlek jekk bidla fil-prompt titjibx verament l-affarijiet.

Pipeline Sħiħa

Il-kodiċi li ġej jiġbor flimkien il-prattiki tal-kors f’fluss wieħed: skema deskritta qasam b’qasam, validatur li jiċħad punteġġi barra mill-limiti, mudell iddimesjonat għall-kompitu, temperature=0, max_tokens espliċitu, verifika ta’ finish_reason, u logging għaż-żewġ riżultati possibbli.

from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time

logger = logging.getLogger("pipeline")

class CustomerFeedback(BaseModel):
    sentiment: str = Field(description="pożittiv, negattiv, jew newtrali")
    score: float = Field(description="Punteġġ bejn -1.0 u 1.0")
    category: str = Field(description="prodott, servizz, konsenja, prezz, jew ieħor")
    action_required: bool = Field(description="True jekk tkun meħtieġa azzjoni")
    summary: str = Field(description="Sommarju f'sentenza waħda")

    @field_validator("score")
    @classmethod
    def score_in_range(cls, v):
        if not -1.0 <= v <= 1.0:
            raise ValueError(f"Punteġġ barra mill-limiti: {v}")
        return v

def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
    start = time.time()
    try:
        response = client.chat.parse(
            model="mistral-small-latest",
            messages=[
                {"role": "system", "content": "Analizza l-feedback tal-klijenti."},
                {"role": "user", "content": text}
            ],
            response_format=CustomerFeedback,
            temperature=0,
            max_tokens=256
        )
        assert response.choices[0].finish_reason == "stop"
        result = response.choices[0].message.parsed
        logger.info(f"OK f'{time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
        return result
    except Exception as e:
        logger.error(f"ŻBALL f'{time.time()-start:.2f}s — {e}")
        raise

Madwar tletin linja, u għandek komponent li jista’ jiġi mwaħħal b’mod sigur fin-nofs ta’ sistema: dan huwa eżattament dak li l-outputs strutturati jagħmlu possibbli.

Punti Ewlenin

  • Uża Outputs Strutturati Personalizzati fil-produzzjoni, Modalità JSON għall-prototipar
  • temperature=0, iċċekkjar ta’ finish_reason, u retry mhumiex negozjabbli
  • Agħżel il-mudell ibbażat fuq il-kumplessità tal-kompitu u l-baġit
  • Immonitorja r-rata ta’ suċċess, il-latenza, u l-ispiża
  • Ibda sempliċi, kejjel, imbagħad ottimizza

Ittestja l-Għarfien Tiegħek

Modalità JSON, skemi, retry: output strutturat taħt kontroll?

1. Modalità JSON vs Outputs Strutturati Personalizzati: x'inhi d-differenza?

Tweġiba: Il-Modalità JSON tiggarantixxi JSON validu sintattikament; l-Outputs Strutturati Personalizzati jinfurzaw ukoll l-iskema eżatta tiegħek—oqsma, tipi, struttura: il-kuntratt sħiħ.

2. X'jipprovdi client.chat.parse() ma' Pydantic?

Tweġiba: Iċ-ċiklu sħiħ: l-iskema Pydantic tiddikjara l-istruttura, l-API tillimita l-ġenerazzjoni, u t-tweġiba tasal diġà vvalidata u ttajpjata bħala oġġett Python—ebda parsing manwali.

3. U fuq in-naħa ta' TypeScript?

Tweġiba: L-istess kumdità ma’ Zod: l-iskema Zod tiddefinixxi u tivvalida l-istruttura—sors wieħed ta’ verità għall-ġenerazzjoni u t-tajpjar.

4. X'għandek tagħmel meta l-output ma jirrispettax l-iskema?

Tweġiba: Ivvvalida sistematikament, u ppjana strateġija ta’ retry: itlob mill-ġdid bl-iżball fil-kuntest, jew iddegrada b’mod grazzjuż—qatt ma tafdaw bl-għama fl-output.

5. Meta l-output strutturat ikun indispensabbli?

Tweġiba: Hekk kif programm jikkonsma t-tweġiba mingħajr reviżjoni umana: estrazzjoni, integrazzjonijiet, pipelines—il-format jieqaf ikun ġentilezza, isir interfaċċa.

Skema ddikjarata, ġenerazzjoni ristretta, validazzjoni tal-output: it-trijade li tagħmel lill-AI pluggabbli f’software reali.