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

L-API OCR ta' Mistral

Lezzjoni 4 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. punt ta’ dħul wieħed
  2. Installazzjoni u konfigurazzjoni
  3. Parametri tas-sejħa
  4. Tliet modi kif tibgħat dokument
  5. Qari tar-rispons
  6. Limiti u żbalji
  7. Punti Ewlenin

Aġġornat fit-2 ta’ Novembru, 2026 — OCR. L-OCR 4.0 (mistral-ocr-4-0) ġie rtirat fit-30 ta’ Settembru, 2026. Uża l-OCR 4.1 (mistral-ocr-4-1), li ilu disponibbli ġeneralment mill-31 ta’ Awwissu bl-istess prezz, jew l-alias mistral-ocr-latest, li jipponta lejh mis-16 ta’ Lulju. L-OCR 4.1 iżid punteġġi ta’ kunfidenza fil-livell tal-blokki. Addendum fit-3 ta’ Novembru, 2026: Biex tibgħat PDF lokali, ikkodifikah f’base64 bħala {"type": "document_url", "document_url": "data:application/pdf;base64,…"}. It-tip document_base64 li jinstab f’eżempji aktar antiki ma jeżistix fid-dokumentazzjoni jew fl-SDK mistralai, u dawk l-eżempji kienu jfallu. Sorsi: OCR Processor · Document QnA.

punt ta’ dħul wieħed

L-estrazzjoni kollha tad-dokumenti tgħaddi minn endpoint wieħed: /v1/ocr, jew l-ekwivalenti tiegħu fl-SDK tal-Python, client.ocr.process(). Kemm jekk qed tipproċessa ritratt ta’ riċevuta jew rapport annwali ta’ 800 paġna, is-sejħa hija l-istess. Din il-lezzjoni tiddettalja kif tikkonfiguraha, it-tliet modi kif tgħaddi dokument lilha, u x’tirritorna.

Installazzjoni u konfigurazzjoni

L-installazzjoni tieħu kmand wieħed biss:

pip install mistralai

Imbagħad, istanzja l-klijent bil-key tal-API tiegħek:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

Dan l-approċċ jaħdem għal test mgħaġġel f’notebook, iżda jirriskja li timpenja l-key tiegħek b’mod aċċidentali. Hekk kif il-kodiċi joħroġ mill-magna tiegħek, uża varjabbli tal-ambjent:

export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Se nużaw din it-tieni forma fil-lezzjonijiet kollha li jmiss.

Parametri tas-sejħa

Is-sejħa client.ocr.process() teħtieġ żewġ parametri biss: model, dejjem imsettjat għal "mistral-ocr-latest", u document, li jiddeskrivi l-fajl li għandu jiġi pproċessat f’waħda mit-tliet forom iddettaljati hawn taħt.

Parametri oħra jaġġustaw l-output skont il-ħtiġijiet tiegħek:

  • table_format: Il-format tat-tabella (null, "markdown", "html")
  • include_image_base64: True biex tirċievi stampi f’base64
  • bbox_annotation_format: Skema ta’ annotazzjoni tal-kaxxa tal-limitu (bounding box)
  • document_annotation_format: Skema sħiħa ta’ annotazzjoni tad-dokument
  • document_annotation_prompt: Istruzzjonijiet ta’ livell għoli għall-annotazzjoni

L-ewwel żewġ parametri jikkonċernaw l-OCR innifsu, u se tittrattahom fil-lezzjonijiet li jmiss. L-aħħar tlieta jirrelataw mal-annotazzjonijiet, koperti mill-Lezzjoni 9 ‘il quddiem; għalissa, ftakar biss li jħalluk titlob estrazzjoni strutturata fl-istess sejħa, mingħajr vjaġġ ieħor (round trip).

Tliet modi kif tibgħat dokument

L-ewwel, URL pubblika, hija l-aktar diretta meta l-fajl diġà huwa aċċessibbli online—rapport ippubblikat, attachment maħżun f’bucket pubbliku:

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/document.pdf"
    }
)

It-tieni meħtieġ għal dokumenti li jinsabu fuq il-magna tiegħek jew f’ħażna privata. Tikkodifikahom f’base64 u tibgħathom fil-korp tat-talba. Dan huwa l-metodu default għal kull ma huwa kunfidenzjali, peress li l-ebda URL m’għandha tiġi esposta:

import base64

with open("my_document.pdf", "rb") as f:
    document_base64 = base64.b64encode(f.read()).decode("utf-8")

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": f"data:application/pdf;base64,{document_base64}"
    }
)

It-tielet juża l-API tal-Fajls. Ittellgħa l-fajl darba, tirrikupra ID, u mbagħad tirreferenzjah fis-sejħiet tiegħek. Il-benefiċċju jidher ma’ dokumenti kbar, jew meta l-istess fajl irid jiġi pproċessat diversi drabi—estrazzjoni OCR illum, annotazzjoni b’skema differenti għada—ma terġax tittrasferixxi 40 MB f’kull tentattiv.

# Ittella' l-fajl
uploaded_file = client.files.upload(
    file=open("my_document.pdf", "rb"),
    purpose="ocr"
)

# Uża l-fajl imtellgħa
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "file_id",
        "file_id": uploaded_file.id
    }
)

Qari tar-rispons

Ir-rispons jesponi lista ta’ paġni, u kull paġna ġġorr il-kontenut tagħha flimkien mal-metadejta tagħha. Ċiklu minimu huwa biżżejjed biex tivverifika li l-estrazzjoni marret sew:

for page in ocr_response.pages:
    print(f"Page {page.index}")
    print(f"Content: {page.markdown[:200]}...")
    print(f"Images: {len(page.images)} found")
    print(f"Header: {page.header}")
    print(f"Footer: {page.footer}")
    print(f"Dimensions: {page.dimensions}")

Agħmilha drawwa li tħaddem dan it-tip ta’ ċiklu fuq dokument kampjun qabel ma tindustrializza xejn: jgħidlek fi tliet sekondi jekk in-numru ta’ paġni jaqbilx, jekk instabux stampi, u jekk l-intestaturi humiex iżolati sew mit-test tal-korp.

Limiti u żbalji

Tliet restrizzjonijiet jirregolaw l-użu: 50 MB kull fajl bħala massimu, 1,000 paġna kull dokument, u formati ta’ input PDF, PNG, JPEG, AVIF, PPTX, u DOCX. Fuq dan jiżdied il-limitazzjoni tar-rata (rate limiting), b’threshold li tiddependi mill-livell tas-sottoskrizzjoni tiegħek—punt li għandek tiċċekkja qabel parallelizzazzjoni massiva, inkella tirriskja li tara s-sejħiet tiegħek miċħuda f’daqqa.

Dawn il-limiti, bħall-inċidenti tan-netwerk, jidhru bħala eċċezzjonijiet li trid taqbad. Xogħol bil-batch li jieqaf fl-invoice numru 300 għax fajl wieħed jaqbeż id-daqs permess huwa telf ta’ ħin li jista’ jiġi evitat:

from mistralai.client import Mistral
from mistralai.client.errors import SDKError

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

try:
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": "https://example.com/document.pdf"
        }
    )
except SDKError as e:
    print(f"API Error: {e.status_code} - {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

Id-distinzjoni bejn iż-żewġ livelli ta’ eċċezzjoni hija utli: SDKError jagħtik kodiċi ta’ status li fuqu tiddeċiedi jekk terġax tipprova—429 għandu jiġi ppruvat mill-ġdid wara dewmien, 400 qatt—filwaqt li l-blokk ġenerali jaqbad problemi lokali, bħal fajl nieqes jew kodifikazzjoni impossibbli.

Punti Ewlenin

  • L-endpoint tal-OCR huwa client.ocr.process() bil-mudell mistral-ocr-latest
  • Tliet metodi ta’ bagħat: URL pubblika, base64, fajl imtellgħa
  • Parametri opzjonali jikkontrollaw il-format tat-tabella u l-inklużjoni tal-istampi
  • Ir-rispons huwa strutturat paġna b’paġna b’Markdown, stampi, u metadejta
  • Irrispetta l-limiti ta’ 50 MB u 1,000 paġna kull dokument