Mistral OCR API
Ezen az oldalon
Frissítve: 2026. november 2. — OCR. Az OCR 4.0 (
mistral-ocr-4-0) modell támogatása 2026. szeptember 30-án megszűnt. Használd az OCR 4.1 (mistral-ocr-4-1) modellt, amely augusztus 31. óta általánosan elérhető ugyanazon az áron, vagy amistral-ocr-latestálnevet, amely július 16. óta erre mutat. Az OCR 4.1 blokk szintű megbízhatósági pontszámokat (confidence scores) is biztosít. Kiegészítés: 2026. november 3.: Helyi PDF küldéséhez kódold azt base64 formátumba így:{"type": "document_url", "document_url": "data:application/pdf;base64,…"}. A régebbi példákban szereplődocument_base64típus nem létezik sem a dokumentációban, sem amistralaiSDK-ban; ezek a példák hibát okoztak volna. Források: OCR Processor · Document QnA.
Egyetlen belépési pont
Minden dokumentum-kinyerés egyetlen végponton keresztül történik: /v1/ocr, vagy annak Python SDK-beli megfelelője, a client.ocr.process(). Akár egy számla fotóját, akár egy 800 oldalas éves jelentést dolgozol fel, a hívás ugyanaz. Ez a lecke részletezi a konfigurálást, a dokumentum átadásának három módját, valamint a visszakapott adatok szerkezetét.
Telepítés és konfiguráció
A telepítés egyetlen parancsot igényel:
pip install mistralai
Ezután hozd létre a klienst az API-kulcsoddal:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
Ez a módszer gyors tesztekhez megfelelő egy notebookban, de fennáll a veszélye, hogy véletlenül commitolod a kulcsot. Amint a kód kikerül a gépedről, használj környezeti változót:
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
A következő leckékben ezt a második formátumot használjuk.
Hívási paraméterek
A client.ocr.process() hívás csak két paramétert igényel: a model-t, amelyet mindig "mistral-ocr-latest" értékre kell állítani, és a document-ot, amely az alább részletezett három forma egyikében írja le a feldolgozandó fájlt.
További paraméterekkel a kimenetet az igényeidhez igazíthatod:
table_format: Táblázat formátuma (null,"markdown","html")include_image_base64:True, ha base64 kódolású képeket szeretnél kapnibbox_annotation_format: Bounding box annotációs sémadocument_annotation_format: Teljes dokumentum annotációs sémadocument_annotation_prompt: Magas szintű utasítások az annotációhoz
Az első kettő magát az OCR-t érinti, ezekkel a következő leckékben foglalkozunk. Az utolsó három az annotációkhoz kapcsolódik, amelyet a 9. leckétől kezdve tárgyalunk; egyelőre csak jegyezd meg, hogy ezek lehetővé teszik a strukturált kinyerést ugyanabban a hívásban, második kör nélkül.
Dokumentum küldésének három módja
Az első módszer egy nyilvános URL használata, ami akkor a legkézenfekvőbb, ha a fájl már elérhető online – például egy közzétett jelentés vagy egy nyilvános tárolón lévő melléklet:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
A második módszer olyan dokumentumok esetén szükséges, amelyek a gépeden vagy privát tárolóban vannak. Ezeket base64-re kódolod, és a kérés törzsében küldöd el. Ez az alapértelmezett módszer minden bizalmas adat esetén, mivel így nem kell URL-t nyilvánossá tenni:
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}"
}
)
A harmadik módszer a Files API-t használja. Egyszer feltöltöd a fájlt, lekérdezed az azonosítóját (ID), majd a hívásokban erre hivatkozol. Az előnye nagy dokumentumoknál vagy ismételt feldolgozásnál mutatkozik meg – ma egy OCR-kinyerés, holnap egy másik sémájú annotáció: nem kell minden próbálkozásnál újra átvinni 40 MB-ot.
# Fájl feltöltése
uploaded_file = client.files.upload(
file=open("my_document.pdf", "rb"),
purpose="ocr"
)
# Feltöltött fájl használata
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "file_id",
"file_id": uploaded_file.id
}
)
A válasz olvasása
A válasz oldalak listáját tartalmazza, és minden oldal hordozza a tartalmát valamint a metaadatait. Egy minimális ciklus is elég annak ellenőrzésére, hogy a kinyerés simán lezajlott-e:
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}")
Szoktasd rá magad, hogy mielőtt bármit ipari méretűvé tennél, futtass le egy ilyen ciklust egy mintadokumentumon: három másodperc alatt kiderül, hogy stimmel-e az oldalszám, észleltek-e képeket, és hogy a fejlécek megfelelően el vannak-e különítve a törzsszövegtől.
Korlátok és hibák
A használatot három korlát szabályozza: fájlonként maximum 50 MB, dokumentumonként 1000 oldal, valamint a bemeneti formátumok: PDF, PNG, JPEG, AVIF, PPTX és DOCX. Ehhez járul még a sebességkorlátozás (rate limiting), amelynek küszöbértéke az előfizetési csomagodtól függ – ezt érdemes ellenőrizni a masszív párhuzamosítás előtt, különben kockáztatod, hogy a hívásaidat egy roham során elutasítják.
Ezek a korlátok, akárcsak a hálózati incidensek, kivételként (exception) jelentkeznek, amelyeket el kell kapnod. Egy kötegelt feladat, amely a 300. számlánál áll meg, mert egy fájl túllépi a megengedett méretet, elkerülhető időpocsékolás:
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}")
Hasznos megkülönböztetni a két kivételszintet: az SDKError státuszkódot ad, ami alapján eldöntheted, érdemes-e újrapróbálkozni – egy 429-es kód esetén várakozás után igen, egy 400-as esetén soha –, míg az általános blokk a helyi problémákat fogja el, mint például egy hiányzó fájl vagy lehetetlen kódolás.
Főbb megállapítások
- Az OCR végpont a
client.ocr.process(), amistral-ocr-latestmodellel - Három küldési módszer: nyilvános URL, base64, feltöltött fájl
- Opcionális paraméterek szabályozzák a táblázat formátumát és a képek beillesztését
- A válasz oldalanként strukturált, Markdown tartalommal, képekkel és metaadatokkal
- Tartsd be a dokumentumonkénti 50 MB-os és 1000 oldalas korlátokat