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

Limiti u Ottimizzazzjoni tal-API tal-Viżjoni

Lezzjoni 11 / 12 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Magħruf il-limiti biex taħdem madwarhom
  2. Limiti tekniċi
  3. Alluċinazzjonijiet viżivi
  4. Ottimizza l-ispejjeż
  5. Ottimizza l-latency
  6. Lista ta’ kontroll għall-produzzjoni
  7. Punti Ewlenin

Magħruf il-limiti biex taħdem madwarhom

L-għaxar lezzjonijiet preċedenti koprew x’tagħmel l-API tal-Viżjoni tajjeb. Din tkopri fejn issib diffikultà. Din mhix eżerċizzju ta’ umiltà: id-differenza bejn prototip ta’ dimostrazzjoni li jħallik bla kliem u applikazzjoni li tħaddem fil-produzzjoni tiddependi eżattament fuq dan. Hawnhekk, se titgħallem dwar il-vincoli tekniċi, l-iżbalji komuni—l-alluċinazzjonijiet viżivi fuq kollox—u strateġiji biex tottimizza l-ispiża u l-latency.

Limiti tekniċi

Diġà messna l-vincoli tal-format qabel, imma ejja niġbruhom flimkien. Kull immaġni hija limitata għal madwar 20 MB u se tiġi mibdula fid-daqs internament anyway, tipikament għal 768x768 jew ekwivalenti: immaġni 4K ma tittejjibx ir-riżultati. Il-formati aċċettati huma JPEG, PNG, GIF (l-ewwel qafas biss), u WebP. L-API tal-Viżjoni ma tappoġġjax PDF direttament—għandek bżonn isejjaħ Document AI għal dan, kif diskuss fil-Lezzjoni 8.

L-aktar vincolo strutturali jibqa’ l-konsum tat-tokens. Kull immaġni tikkonsma numru sinifikanti ta’ tokens, u din il-funzjoni tikkonverti dik l-istima f’dollari minflok unitajiet astratti:

# Estimate the cost of a vision call
def estimate_cost(num_images=1, text_tokens=100, response_tokens=500,
                 tokens_per_image=1000, input_price=0.10, output_price=0.30):
    """Estimates the cost in dollars for a vision call (Small 3.2)."""
    input_tokens = (num_images * tokens_per_image) + text_tokens
    output_tokens = response_tokens

    input_cost = (input_tokens / 1_000_000) * input_price
    output_cost = (output_tokens / 1_000_000) * output_price
    total_cost = input_cost + output_cost

    print(f"Input tokens: {input_tokens} (${input_cost:.4f})")
    print(f"Output tokens: {output_tokens} (${output_cost:.4f})")
    print(f"Total cost: ${total_cost:.4f}")
    return total_cost

# 1 image with Small 3.2
estimate_cost(num_images=1)

# 5 images with Large 3
estimate_cost(num_images=5, input_price=2.00, output_price=6.00)

Qabbel iż-żewġ sejħiet fl-aħħar tal-iskript: it-tieni tispiża dozzini ta’ drabi aktar mill-ewwel. Immultiplika dan bil-volum ta’ kuljum tiegħek qabel ma tieħu deċiżjoni. Fuq kollox, hemm il-limitu tal-tieqa tal-kuntest, li t-total ta’ immaġni + prompt + tweġiba m’għandux jaqbeż—saqaf li immaġni multipli jilħqu ferm aktar malajr minn test twil.

Alluċinazzjonijiet viżivi

Il-mudell jista’ “jinventa” dettalji nieqsa mill-immaġni. Din hija l-aktar kwistjoni kritika fil-produzzjoni għax hija silenzjuża: it-tweġiba hija mibnija tajjeb, plawżibbli, u żbaljata.

Erba’ mudelli jerġgħu jidhru. Test inventat, fejn il-mudell jaqra kelma li ma teżistix fl-immaġni. Numri approssimattivi, fejn valuri moqrija minn grafika jistgħu jvarjaw 5–15% mir-realtà. Dettalji miżjuda, fejn il-mudell jimla dak li ma jarax ċar b’informazzjoni plawżibbli—numru SIRET imċajpar isir SIRET ifformat perfettament iżda falz. Fl-aħħar, konfużjoni ta’ elementi, fejn żewġ oġġetti viċin jingħaqdu f’wieħed.

Jeżistu tliet kontromiżuri; għaqqadhom skont il-kritikalità. L-ewwel, sfurza lill-mudell jikkwalifika ċ-ċertezza tiegħu stess. It-tieni, agħmlu jerġa’ jaqra l-immaġni wara li jittrascrievi. It-tielet, qabbel żewġ mudelli fuq l-istess mistoqsija u żomm biss dak li jaqblu fuqu.

# 1. Ask for a confidence level
prompt_confiance = """Analyze this image. For each piece of extracted information, indicate your confidence level:
- [CERTAIN]: clearly visible
- [PROBABLE]: partially visible or inferred
- [INCERTAIN]: barely legible, estimated

If an element is illegible, mark it [ILLISIBLE] rather than guessing."""

# 2. Ask for cross-verification
prompt_verification = """Read the text in this document. After transcribing, reread the image and verify every number and proper noun. Correct any detected errors."""

# 3. Double reading with two models
def double_verification(image_uri, question):
    """Sends the same image to two models and compares results."""
    resultats = {}
    for modele in ["mistral-small-latest", "mistral-large-latest"]:
        response = client.chat.complete(
            model=modele,
            messages=[{
                "role": "user",
                "content": [
                    {"type": "text", "text": question},
                    {"type": "image_url", "image_url": image_uri}
                ]
            }]
        )
        resultats[modele] = response.choices[0].message.content

    return resultats

Il-qari doppju jirdoppja l-ispiża: irriżervah għal ammonti, identifikaturi, u kull ma jipprovoka azzjoni irreversibbli.

Ottimizza l-ispejjeż

L-aktar ottimizzazzjoni effiċjenti f’termini ta’ spiża ġiet koperta fil-Lezzjoni 5, u hija l-aktar sempliċi: naqqas id-daqs tal-immaġni qabel ma tibgħatha. Ritratt ta’ 6 MB imbidel għal 1024 pixel ma jitlif xejn għall-finijiet tal-analiżi u jħaffef iċ-ċirkwit kollu.

from PIL import Image
from io import BytesIO
import base64

def optimiser_image(chemin, taille_max=1024, qualite=80):
    """Resizes and compresses an image for the Vision API."""
    img = Image.open(chemin)
    taille_originale = img.size

    # Resize
    if max(img.size) > taille_max:
        img.thumbnail((taille_max, taille_max))

    # Compress as JPEG
    buffer = BytesIO()
    img.convert("RGB").save(buffer, format="JPEG", quality=qualite)
    taille_fichier = buffer.tell()

    b64 = base64.standard_b64encode(buffer.getvalue()).decode("utf-8")

    print(f"Original: {taille_originale} | Optimized: {img.size} | Size: {taille_fichier/1024:.0f} KB")
    return f"data:image/jpeg;base64,{b64}"

Imbagħad jiġi r-routing skont il-kumplessità: mhux kull kompitu jistħoqqilu l-aktar mudell għali. Funzjoni ta’ tliet linji biżżejjed biex tiddeċiedi, sakemm ikklassifikajt il-kompiti tiegħek minn qabel.

def choose_model(task):
    """Selects the optimal model based on the task."""
    simple_tasks = ["classification", "ocr_simple", "description", "triage"]
    complex_tasks = ["extraction_json", "comparaison", "analyse_graphique", "raisonnement"]

    if task in simple_tasks:
        return "mistral-small-latest"  # ~$0.10/M tokens
    else:
        return "mistral-large-latest"  # ~$2.00/M tokens

It-tielet leva hija l-aktar waħda li tintesa spiss: tħallasx darbtejn għall-istess analiżi. Fil-produzzjoni, l-istess immaġni terġa’ tidher aktar spiss milli taħseb—eżekuzzjoni mill-ġdid ta’ proċess, ibgħat doppju, jew tipprova mill-ġdid wara inċident. Cache tad-disk indicizzat fuq l-hash tal-fajl u l-prompt jelimina dawn is-sejħiet redundanti.

import hashlib
import json
from pathlib import Path

CACHE_DIR = Path("cache_vision/")
CACHE_DIR.mkdir(exist_ok=True)

def analyser_avec_cache(image_path, prompt, modele="mistral-small-latest"):
    """Analyzes an image with disk caching."""
    # Generate a cache key
    with open(image_path, "rb") as f:
        image_hash = hashlib.md5(f.read()).hexdigest()
    cache_key = hashlib.md5(f"{image_hash}{prompt}{modele}".encode()).hexdigest()
    cache_file = CACHE_DIR / f"{cache_key}.json"

    # Check cache
    if cache_file.exists():
        return json.loads(cache_file.read_text())

    # API call
    response = client.chat.complete(
        model=modele,
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": prompt},
                {"type": "image_url", "image_url": encoder_image(image_path)}
            ]
        }]
    )

    resultat = response.choices[0].message.content

    # Save to cache
    cache_file.write_text(json.dumps(resultat, ensure_ascii=False))
    return resultat

Iċ-ċavetta tinkludi l-prompt u l-mudell, mhux biss l-immaġni: tibdel il-mistoqsija fuq l-istess ritratt għandu effettivament jipprovoka sejħa ġdida.

Ottimizza l-latency

Għal applikazzjoni interattiva, erba’ settings jaffettwaw il-ħin ta’ rispons perċepit. Ibiddel id-daqs tal-immaġnijiet fuq in-naħa tal-klijent għal massimu ta’ 1024 pixel, li jqassar il-ħin tat-tlugħ. Agħżel Small jew Ministral, peress li l-ġenerazzjoni tagħhom hija ferm aktar mgħaġġla. Għaddi l-immaġnijiet permezz ta’ URL meta jkunu diġà ospitati biex tevita li tibgħat korp ta’ talba Base64 kbir. Fl-aħħar, ippermetti l-istreaming, li ma jnaqqasx il-ħin totali iżda juri t-tweġiba hekk kif tinbena:

# Streaming for a progressive response
stream = client.chat.stream(
    model="mistral-small-latest",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image."},
            {"type": "image_url", "image_url": image_url}
        ]
    }]
)

for chunk in stream:
    if chunk.data.choices[0].delta.content:
        print(chunk.data.choices[0].delta.content, end="", flush=True)

Huwa chat.stream li jissostitwixxi chat.complete; il-bqija tal-messaġġ huwa eżattament l-istess.

Lista ta’ kontroll għall-produzzjoni

Qabel ma tiddispjega applikazzjoni tal-Viżjoni fil-produzzjoni, ivverifika kull wieħed minn dawn il-punti:

  • Bidla awtomatika fid-daqs tal-immaġni (massimu 1024px)
  • Validazzjoni tal-format u d-daqs qabel l-ibgħat
  • Ġestjoni tal-iżbalji tal-API (ipprova mill-ġdid, timeout, fallback)
  • Caching tar-riżultati għal immaġnijiet identiċi
  • Routing intelliġenti (Small għal sempliċi, Large għal kumpless)
  • Monitoraġġ tal-ispiża u l-latency
  • Ittestjar b’immaġnijiet ta’ kwalità fqira (imċajpra, riżoluzzjoni baxxa, mdawra)
  • Strateġija kontra l-alluċinazzjonijiet (livelli ta’ kunfidenza, verifika doppja)

It-tieni punt mill-aħħar huwa dak li l-aktar jintesa, u dak li jikkawża l-aktar ħsara: ibni dataset ta’ immaġnijiet deliberatament ħżiena u mexxieha qabel kull dispjegament.

Punti Ewlenin

  • L-immaġnijiet jiġu mibdula fid-daqs internament—m’hemmx bżonn tibgħat riżoluzzjoni għolja ħafna
  • L-alluċinazzjonijiet viżivi huma r-riskju primarju—itlob livelli ta’ kunfidenza
  • Il-bidla fid-daqs fuq in-naħa tal-klijent hija l-aktar ottimizzazzjoni effiċjenti f’termini ta’ spiża
  • Ir-routing skont il-kumplessità (Small vs. Large) inaqqas l-ispejjeż b’90% fuq kompiti sempliċi
  • Il-caching tad-disk jevita sejħiet API redundanti fuq l-istess immaġnijiet