L-API OCR ta' Mistral
F'din il-paġna
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-aliasmistral-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-tipdocument_base64li jinstab f’eżempji aktar antiki ma jeżistix fid-dokumentazzjoni jew fl-SDKmistralai, 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:Truebiex tirċievi stampi f’base64bbox_annotation_format: Skema ta’ annotazzjoni tal-kaxxa tal-limitu (bounding box)document_annotation_format: Skema sħiħa ta’ annotazzjoni tad-dokumentdocument_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-mudellmistral-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