Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Teorainneacha agus Barrfheabhsú an API Fís

Ceacht 11 as 12 Nuashonraithe 29 Iúil 2026 Forbróir
Ar an leathanach seo
  1. Aithin na teorainneacha chun iad a shárú
  2. Teorainneacha teicniúla
  3. Hallúiciníse amhairc
  4. Costais a bharrfheabhsú
  5. Moill a bharrfheabhsú
  6. Seicliosta táirgeachta
  7. Príomhphointí

Aithin na teorainneacha chun iad a shárú

Chumhdaigh na deich gcacht roimhe seo cad a dhéanann an API Fís go maith. Pléifimid sa cheacht seo cá bhfuil deacrachtaí aige. Ní cleachtadh umhlaíochta é seo: is ar an bpointe seo go díreach a bhraitheann an difríocht idir fréamhshamhail taispeána a chuireann iontas ar dhaoine agus feidhmchlár a sheasann an fód sa táirgeadh. Anseo, foghlaimeoidh tú faoi shrianta teicniúla, faoi phitfall choitianta—hallúiciníse amhairc ina measc go háirithe—agus faoi straitéisí chun costas agus moill a bharrfheabhsú.

Teorainneacha teicniúla

Thagair muid do shrianta formáide cheana, ach déanaimis iad a chur le chéile. Tá gach íomhá teoranta do thart ar 20 MB agus athrófar a méid go hinmheánach ar any chás, de ghnáth go 768x768 nó a leithéid: ní fheabhsóidh íomhá 4K na torthaí. Is iad na formáidí a nglactar leo ná JPEG, PNG, GIF (an chéad fhráma amháin), agus WebP. Ní thacaíonn an API Fís le PDF go díreach—ní mór duit Glaoch a chur ar Document AI chuige sin, mar a pléadh i gCacht 8.

Is é an tomhaltas tocain an srian is struchtúrtha fós. Úsáideann gach íomhá líon suntasach tocain, agus aistríonn an fheidhm seo an meastachán sin go dollar seachas aonaid theibí:

# 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)

Déan comparáid idir an dá ghlao ag deireadh an scripte: costálann an dara ceann dosaen uair níos mó ná an chéad cheann. Méadaigh é sin de réir do mhéid laethúil sula ndéanann tú cinneadh. Ina theannta sin, tá teorainn na fuinneoige comhthéacs ann, nach mór don iomlán d’íomhánna + leid + freagra a bheith faoi—a uasteorainn a shroicheann íomhánna iolracha i bhfad níos tapúla ná téacs fada.

Hallúiciníse amhairc

Is féidir leis an tsamhail sonraí a “chruthú” nach bhfuil san íomhá. Seo an fhadhb is criticiúla sa táirgeadh toisc go bhfuil sí ciúin: tá an fhreagra dea-chumtha, inchreidte, agus mícheart.

Tarlaíonn ceithre phatrún go minic. Téacs cumtha, áit a léann an tsamhail focal nach bhfuil san íomhá. Uimhreacha neamhchruinne, áit a bhféadfadh luachanna a léitear ó ghrafa diall 5–15% ón réaltacht. Sonraí breise, áit a líonann an tsamhail isteach cad nach bhfeiceann sí go soiléir le faisnéis inchreidte—déantar uimhir SIRET doiléir a thiontú ina SIRET foirmithe go foirfe ach bréige. Ar deireadh, mearbhall eiliminte, áit a ndéantar dhá réad atá in aice le chéile a chumasc ina cheann amháin.

Tá trí fhreastal ann; comhcheangail iad de réir na criticiúlachta. Ar an gcéad dul síos, cuir iallach ar an tsamhail a cinnteacht féin a cháiliú. Ar an dara dul síos, iarr uirthi an íomhá a léamh arís tar éis í a thras-scríobh. Ar an tríú dul síos, cuir dhá shamhail i gcoinne a chéile ar an gceist chéanna agus coinnigh ach na rudaí a aontaíonn siad orthu.

# 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

Déanann an léamh dúbailte an costas a dhúbailt: coinnigh é do shuimeanna, d’aitheantóirí, agus do rud ar bith a spreagann gníomh dochúlaithe.

Costais a bharrfheabhsú

Cumhdaíodh an barrfheabhsú is cost-éifeachtaí i gCacht 5, agus is é an ceann is simplí é: laghdaigh méid na híomhá sula seolann tú í. Cailleann grianghraf 6 MB a athraítear go 1024 picteilín aon rud chun críche anailíse agus éalaíonn sé an slabhra iomlán.

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}"

Ansin tagann ródaíocht de réir castachta: ní tuilleann gach tasc an tsamhail is costasaí. Tá feidhm trí líne sách maith chun cinneadh a dhéanamh, ar choinníoll go bhfuil do chuid tascanna aicmithe agat cheana féin.

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

Is é an tríú giuirléid an ceann is minice a dhéantar dearmad de: ná híoc faoi dhó as an anailís chéanna. Sa táirgeadh, filleann an íomhá chéanna níos minice ná a shílfeá—próiseas a athrith, seoltaí dúbailte, nó iarracht arís tar éis teagmhais. Cuireann taisce diosca atá innéacsaithe ar hais an chomhaid agus ar an leid deireadh leis na glaonna iomarcacha seo.

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

Áirítear an leid agus an tsamhail sa eochair, ní hamháin an íomhá: ba chóir go spreagfadh athrú na ceiste ar an ngrianghraf céanna glao nua go deimhin.

Moill a bharrfheabhsú

I gcás feidhmchlár idirghníomhach, bíonn tionchar ag ceithre shocrú ar an am freagartha a mhothaítear. Athraigh méid na n-íomhánna ar thaobh an chliaint go dtí uasmhéid 1024 picteilín, rud a ghiorraíonn an t-am uaslódála. Roghnaigh Small nó Ministral, toisc go bhfuil a nginiúint i bhfad níos tapúla. Seol íomhánna trí URL nuair atá siad óstáilte cheana féin chun seachaint comhlacht iarratais Base64 mór a sheoladh. Ar deireadh, cumasaigh sruthú, rud nach laghdaíonn an t-am iomlán ach a thaispeánann an fhreagra de réir mar a chruthaítear í:

# 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)

Is é chat.stream atá in ionad chat.complete; tá an chuid eile den teachtaireacht díreach mar an gcéanna.

Seicliosta táirgeachta

Sula ndéanann tú feidhmchlár Fís a imlonnú go táirgeadh, fíoraigh gach ceann de na pointí seo:

  • Athrú méide uathoibríoch íomhá (uas 1024px)
  • Bailíochtú formáide agus méide sula seoltar
  • Láimhseáil earráidí API (athiarracht, teora ama, cúltaca)
  • Torthaí a chur i dtaisce d’íomhánna comhionanna
  • Ródaíocht chliste (Small do rudaí simplí, Large do rudaí casta)
  • Monatóireacht ar chostas agus ar mhoill
  • Tástáil le híomhánna droch-chaighdeáin (doiléir, ísealtaighdeán, rothlaithe)
  • Straitéis frith-hallúiciníse (leibhéil muiníne, fíorú dúbailte)

Is é an dara pointe ón deireadh an ceann is minice a scipeáiltear, agus an ceann is mó damáiste a dhéanann: tóg tacar sonraí d’íomhánna go dánta dona agus rith é roimh gach imlonnú.

Príomhphointí

  • Athraítear méid na n-íomhánna go hinmheánach—ní gá íomhánna an-ardtaighdeáin a sheoladh
  • Is iad hallúiciníse amhairc an príomhriosca—iarr leibhéil muiníne
  • Is é athrú méide ar thaobh an chliaint an barrfheabhsú is cost-éifeachtaí
  • Gearrann ródaíocht de réir castachta (Small vs. Large) costais 90% ar thascanna simplí
  • Seachnaíonn taisce diosca glaonna API iomarcacha ar na híomhánna céanna