OCR API od Mistralu
Na tejto strane
Aktualizované 2. novembra 2026 — OCR. Verzia OCR 4.0 (
mistral-ocr-4-0) bola vyradená 30. septembra 2026. Používaj OCR 4.1 (mistral-ocr-4-1), ktorá je všeobecne dostupná od 31. augusta za rovnakú cenu, alebo aliasmistral-ocr-latest, ktorý na ňu odkazuje od 16. júla. OCR 4.1 pridáva skóre spoľahlivosti na úrovni blokov. Dodatok z 3. novembra 2026: Ak chceš odoslať lokálny PDF súbor, zakóduj ho do formátu base64 ako{"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Typdocument_base64, ktorý sa nachádza v starších príkladoch, v dokumentácii ani v SDKmistralaineexistuje a tieto príklady by zlyhali. Zdroje: OCR Processor · Document QnA.
Jediný vstupný bod
Všetka extrakcia dokumentov prebieha cez jeden koncový bod: /v1/ocr, alebo jeho ekvivalent v Python SDK, client.ocr.process(). Či už spracovávaš fotografiu bločka alebo 800-stranovú výročnú správu, volanie je rovnaké. Táto lekcia podrobne popisuje, ako ho nakonfigurovať, tri spôsoby, ako mu odovzdať dokument, a čo vracia.
Inštalácia a konfigurácia
Inštalácia si vyžaduje jediný príkaz:
pip install mistralai
Ďalej inicializuj klienta pomocou svojho API kľúča:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
Tento prístup funguje pre rýchly test v notebooku, ale riskuješ náhodné commitnutie svojho kľúča. Hneď ako kód opustí tvoj stroj, použij premennú prostredia:
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
V všetkých nasledujúcich lekciách budeme používať túto druhú formu.
Parametre volania
Volanie client.ocr.process() vyžaduje iba dva parametre: model, vždy nastavený na "mistral-ocr-latest", a document, ktorý popisuje súbor na spracovanie v jednej z troch foriem podrobne uvedených nižšie.
Ďalšie parametre upravujú výstup podľa tvojich potrieb:
table_format: Formát tabuľky (null,"markdown","html")include_image_base64:Truepre prijímanie obrázkov v base64bbox_annotation_format: Schéma anotácií ohraničujúcich rámcovdocument_annotation_format: Schéma anotácií celého dokumentudocument_annotation_prompt: Inštrukcie vysokej úrovne pre anotáciu
Prvé dva sa týkajú samotného OCR a budeš sa im venovať v ďalších lekciách. Posledné tri súvisia s anotáciami, ktorými sa začneme zaoberať od Lekcie 9; zatiaľ si len zapamätaj, že ti umožňujú požadovať štruktúrovanú extrakciu v rámci toho istého volania bez potreby druhého round-tripu.
Tri spôsoby odoslania dokumentu
Prvý spôsob, verejná URL adresa, je najpriamejší, keď je súbor už dostupný online – publikovaná správa, príloha uložená vo verejnom úložisku:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
Druhý spôsob je nevyhnutný pre dokumenty, ktoré sa nachádzajú na tvojom stroji alebo v súkromnom úložisku. Zakóduješ ich do formátu base64 a odošleš v tele požiadavky. Toto je predvolená metóda pre čokoľvek dôverné, keďže nie je potrebné vystavovať žiadnu URL adresu:
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}"
}
)
Tretí spôsob využíva Files API. Súbor nahraješ raz, získaš jeho ID a následne naňho odkazuješ vo svojich volaniach. Výhoda sa prejaví pri veľkých dokumentoch alebo keď sa ten istý súbor musí spracovať viackrát – extrakcia OCR dnes, anotácia s inou schémou zajtra: pri každom pokuse nemusíš znovu prenášať 40 MB.
# Nahranie súboru
uploaded_file = client.files.upload(
file=open("my_document.pdf", "rb"),
purpose="ocr"
)
# Použitie nahraného súboru
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "file_id",
"file_id": uploaded_file.id
}
)
Čítanie odpovede
Odpoveď obsahuje zoznam stránok a každá stránka nesie svoj obsah spolu s metadátami. Na overenie, či extrakcia prebehla hladko, stačí jednoduchá slučka:
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}")
Zvykni si spúšťať tento typ slučky na vzorovom dokumente predtým, než niečo industrializuješ: do troch sekúnd ti povie, či súčet stránok sedí, či boli detegované obrázky a či sú hlavičky správne oddelené od hlavného textu.
Limity a chyby
Používanie riadia tri obmedzenia: maximálne 50 MB na súbor, 1 000 strán na dokument a vstupné formáty PDF, PNG, JPEG, AVIF, PPTX a DOCX. K tomu sa pridáva obmedzenie rýchlosti (rate limiting) s prahom, ktorý závisí od úrovne tvojho predplatného – tento bod si over pred masívnou paralelizáciou, inak riskuješ, že tvoje volania budú v návale odmietnuté.
Tieto limity, rovnako ako problémy so sieťou, sa prejavujú ako výnimky, ktoré musíš zachytávať. Dávková úloha, ktorá sa zastaví na faktúre číslo 300, pretože jeden súbor presahuje povolenú veľkosť, je zbytočnou stratou času, ktorej sa dá vyhnúť:
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}")
Rozlišovanie medzi týmito dvoma úrovňami výnimiek je užitočné: SDKError ti poskytne stavový kód, na základe ktorého sa rozhodneš, či skúsiť znova – pri 429 by si mal počkať a skúsiť to znova, pri 400 nikdy – zatiaľ čo všeobecný blok zachytáva lokálne problémy, ako je chýbajúci súbor alebo nemožné kódovanie.
Kľúčové poznatky
- Koncový bod OCR je
client.ocr.process()s modelommistral-ocr-latest - Tri spôsoby odoslania: verejná URL, base64, nahraný súbor
- Voliteľné parametre riadia formát tabuliek a zahrnutie obrázkov
- Odpoveď je štruktúrovaná po stránkach s Markdownom, obrázkami a metadátami
- Rešpektuj limity 50 MB a 1 000 strán na dokument