Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Vision API:n rajat ja optimointi

Oppitunti 11 / 12 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Tunne rajat kiertääksesi ne
  2. Tekniset rajat
  3. Visuaaliset hallusinaatiot
  4. Kustannusten optimointi
  5. Viiveen optimointi
  6. Tuotantotarkistuslista
  7. Keskeiset asiat

Tunne rajat kiertääksesi ne

Kymmenen edellistä oppituntia käsittelivät sitä, mitä Vision API tekee hyvin. Tämä oppitunti käsittelee sen heikkouksia. Kyse ei ole nöyryysharjoituksesta: ero häkellyttävän demo-prototyypin ja tuotannossa kestävän sovelluksen välillä tiivistyy juuri tähän. Tässä opit teknisistä rajoitteista, yleisimmistä sudenkuopista – joista visuaaliset hallusinaatiot ovat tärkein – sekä strategioista kustannusten ja viiveen optimoimiseksi.

Tekniset rajat

Olemme käsitelleet muotorajoituksia aiemmin, mutta niputetaan ne nyt yhteen. Jokaisen kuvan koko on rajoitettu noin 20 megatavuun, ja se skaalataan sisäisesti joka tapauksessa, tyypillisesti kokoon 768×768 tai vastaavaan: 4K-kuva ei paranna tuloksia. Hyväksytyt muodot ovat JPEG, PNG, GIF (vain ensimmäinen kehys) ja WebP. Vision API ei tue suoraan PDF-tiedostoja – sitä varten tarvitset Document AI:n, kuten oppitunnilla 8 käsiteltiin.

Rakenteellisin rajoite on edelleen tokenien kulutus. Jokainen kuva kuluttaa merkittävän määrän tokeneita, ja tämä funktio muuntaa arvion dollareiksi abstraktien yksiköiden sijaan:

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

Vertaa skriptin lopun kahta kutsua: toinen maksaa kymmeniä kertoja enemmän kuin ensimmäinen. Kerro tämä päivittäisellä volyymilläsi ennen päätöksen tekemistä. Tämän päälle tulee konteksti-ikkunan rajoitus, jonka kokonaisrajan (kuvat + kehote + vastaus) ei saa ylittää – raja, jonka useat kuvat saavuttavat paljon nopeammin kuin pitkä teksti.

Visuaaliset hallusinaatiot

Malli voi “keksiä” yksityiskohtia, joita kuvassa ei ole. Tämä on kriittisin ongelma tuotannossa, koska se on hiljainen: vastaus on hyvin muotoiltu, uskottava ja väärä.

Neljä toistuvaa mallia erottuu. Keksitty teksti, jossa malli lukee sanan, jota kuvassa ei ole. Likimääräiset numerot, joissa kaaviosta luetut arvot voivat poiketa todellisuudesta 5–15 %. Lisätyt yksityiskohdat, joissa malli täydentää epäselvät kohdat uskottavalla informaatiolla – sumea SIRET-numero muuttuu täydellisesti muotoilluksi mutta väärennetyksi SIRET-numeroksi. Lopuksi elementtien sekaannus, jossa kaksi lähekkäistä objektia sulautetaan yhdeksi.

Kolme vastatoimenpidettä on olemassa; yhdistä niitä kriittisyyden mukaan. Ensinnäkin pakota malli arvioimaan oma varmuutensa. Toiseksi pyydä sitä lukemaan kuva uudelleen transkription jälkeen. Kolmanneksi aseta kaksi mallia samaa kysymystä vasten ja pidä vain ne tulokset, joista ne ovat samaa mieltä.

# 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

Kaksoislukeminen kaksinkertaistaa kustannukset: varaa se summille, tunnisteille ja kaikelle, mikä laukaisee peruuttamattoman toiminnon.

Kustannusten optimointi

Kustannustehokkain optimointi käsiteltiin oppitunnilla 5, ja se on yksinkertaisin: pienennä kuvan kokoa ennen lähetystä. 6 megatavun valokuva, joka skaalataan 1024 pikseliin, ei menetä mitään analyysin kannalta ja keventää koko ketjua.

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

Seuraavaksi tulee reititys vaativuuden mukaan: jokainen tehtävä ei ansaitse kalleinta mallia. Kolmen rivin funktio riittää päätökseen, kunhan olet luokitellut tehtäväsi etukäteen.

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

Kolmas vipu on useimmiten unohdettu: älä maksa kahdesti samasta analyysista. Tuotannossa sama kuva palaa useammin kuin luulet – prosessin uudelleensuoritus, kaksoislähetykset tai yritykset häiriön jälkeen. Levylle tallennettu välimuisti, joka on indeksoitu tiedostohashin ja kehotteen perusteella, eliminoi nämä tarpeettomat kutsut.

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

Avain sisältää kehotteen ja mallin, ei vain kuvan: kysymyksen muuttaminen samasta kuvasta pitäisi todellakin laukaista uusi kutsu.

Viiveen optimointi

Interaktiivisessa sovelluksessa neljä asetusta vaikuttaa koettuun vasteaikaan. Skaalaa kuvat asiakaspuolella enintään 1024 pikseliin, mikä lyhentää lähetysaikaa. Valitse Small tai Ministral, sillä niiden generointi on huomattavasti nopeampaa. Lähetä kuvat URL-osoitteina, kun ne ovat jo hostattuna, välttääksesi suuren Base64-kokonaisuuden lähettämisen. Lopuksi ota käyttöön suoratoisto (streaming), joka ei vähennä kokonaisaikaa, mutta näyttää vastauksen sen rakentuessa:

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

Kyseessä on chat.stream, joka korvaa chat.complete-komennon; muu viestin osa on täsmälleen sama.

Tuotantotarkistuslista

Ennen Vision-sovelluksen käyttöönottoa tuotannossa varmista seuraavat kohdat:

  • Kuvien automaattinen skaalaus (enintään 1024 px)
  • Muodon ja koon validointi ennen lähetystä
  • API-virheiden käsittely (uudelleenyritys, aikakatkaisu, varasuunnitelma)
  • Tulosten välimuistitus identtisille kuville
  • Älykäs reititys (Small yksinkertaisiin, Large monimutkaisiin tehtäviin)
  • Kustannusten ja viiveen seuranta
  • Testaus heikkolaatuisilla kuvilla (sumeat, matala resoluutio, käännetty)
  • Hallusinaatioiden torjuntastrategia (varmuustasot, kaksoisvarmistus)

Toiseksi viimeinen kohta on se, joka useimmiten ohitetaan, ja se, joka aiheuttaa eniten vahinkoa: rakenna tietojoukko tarkoituksellisesti huonoista kuvista ja aja se läpi ennen jokaista käyttöönottoa.

Keskeiset asiat

  • Kuvat skaalataan sisäisesti – erittäin korkeaa resoluutiota ei tarvitse lähettää
  • Visuaaliset hallusinaatiot ovat ensisijainen riski – pyydä varmuustasoja
  • Asiakaspuolen skaalaus on kustannustehokkain optimointi
  • Vaativuuden mukainen reititys (Small vs. Large) leikkaa kustannuksia 90 % yksinkertaisissa tehtävissä
  • Levyn välimuisti välttää tarpeettomat API-kutsut samoille kuville