Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Mistral OCR API

4. lecke 16 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Egyetlen belépési pont
  2. Telepítés és konfiguráció
  3. Hívási paraméterek
  4. Dokumentum küldésének három módja
  5. A válasz olvasása
  6. Korlátok és hibák
  7. Főbb megállapítások

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 a mistral-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_base64 típus nem létezik sem a dokumentációban, sem a mistralai SDK-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 kapni
  • bbox_annotation_format: Bounding box annotációs séma
  • document_annotation_format: Teljes dokumentum annotációs séma
  • document_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(), a mistral-ocr-latest modellel
  • 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