Mistral OCR API
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. — OCR. OCR 4.0 (
mistral-ocr-4-0) buvo nutrauktas 2026 m. rugsėjo 30 d. Naudokite OCR 4.1 (mistral-ocr-4-1), kuris visuotinai prieinamas nuo rugpjūčio 31 d. ta pačia kaina, arba aliasąmistral-ocr-latest, kuris į jį nukreiptas nuo liepos 16 d. OCR 4.1 prideda pasitikėjimo įverčius bloko lygmeniu. Priedas, 2026 m. lapkričio 3 d.: Norėdami siųsti vietinį PDF failą, užkoduokite jį base64 formatu kaip{"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Senesniuose pavyzdžiuose rastas tipasdocument_base64dokumentacijoje arbamistralaiSDK neegzistuoja, ir tokie pavyzdžiai būtų nepavykę. Šaltiniai: OCR procesorius · Dokumentų klausimai ir atsakymai.
Vienas įvesties taškas
Visas dokumentų išgavimas vyksta per vieną galinį tašką: /v1/ocr, arba jo ekvivalentą Python SDK – client.ocr.process(). Nesvarbu, ar apdorojate čekio nuotrauką, ar 800 puslapių metinę ataskaitą, kvietimas yra tas pats. Šioje pamokoje išsamiai aprašoma, kaip jį sukonfigūruoti, trys būdai perduoti dokumentą ir ką gaunate atsakyme.
Diegimas ir konfigūravimas
Diegimui pakanka vienos komandos:
pip install mistralai
Toliau sukurkite kliento instanciją naudodami savo API raktą:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
Šis būdas tinka greitam testavimui „notebook“ aplinkoje, tačiau kyla rizika netyčia įtraukti raktą į kodą. Kai tik kodas palieka jūsų kompiuterį, naudokite aplinkos kintamąjį:
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Visose tolesnėse pamokose naudosime būtent šią antrąją formą.
Kvietimo parametrai
Kvietimui client.ocr.process() reikia tik dviejų parametrų: model, kuris visada nustatomas kaip "mistral-ocr-latest", ir document, apibūdinantis apdorojamą failą vienu iš trijų žemiau detaliau aprašytų būdų.
Kiti parametrai pritaiko išvestį pagal jūsų poreikius:
table_format: Lentelės formatas (null,"markdown","html")include_image_base64:True, jei norite gauti vaizdus base64 formatubbox_annotation_format: Apribojančių dėžučių (bounding box) anotacijų schemadocument_annotation_format: Viso dokumento anotacijų schemadocument_annotation_prompt: Aukšto lygio instrukcijos anotacijoms
Pirmieji du susiję su pačiu OCR, juos nagrinėsite kitose pamokose. Paskutiniai trys susiję su anotacijomis, kurios aptariamos nuo 9 pamokos; kol kas tiesiog įsiminkite, kad jie leidžia prašyti struktūrizuoto išgavimo tame pačiame kvietime, nereikalaujant antrojo užklausos rato.
Trys dokumento siuntimo būdai
Pirmasis – viešas URL – yra tiesiogiausias, kai failas jau pasiekiamas internete: paskelbta ataskaita, priedas, saugomas viešame „bucket“ konteineryje:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
Antrasis būtinas dokumentams, esantiems jūsų kompiuteryje arba privačioje saugykloje. Juos užkoduojate base64 formatu ir siunčiate užklausos kūne. Tai numatytasis metodas bet kam konfidencialiam, nes nereikia atskleisti jokio URL:
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}"
}
)
Trečiasis naudoja „Files API“. Failą įkeliate vieną kartą, gaunate jo ID ir vėliau jį nurodote savo kvietimuose. Naudą pajusite dirbdami su dideliais dokumentais arba kai tą patį failą reikia apdoroti kelis kartus – šiandien OCR išgavimas, rytoj anotacija su kita schema: nereikia kiekvieną kartą iš naujo perduoti 40 MB duomenų.
# Įkelkite failą
uploaded_file = client.files.upload(
file=open("my_document.pdf", "rb"),
purpose="ocr"
)
# Naudokite įkeltą failą
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "file_id",
"file_id": uploaded_file.id
}
)
Atsakymo skaitymas
Atsakyme pateikiamas puslapių sąrašas, ir kiekvienas puslapis turi savo turinį bei metaduomenis. Minimalaus ciklo pakanka patikrinti, ar išgavimas pavyko sklandžiai:
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}")
Įpraskite paleisti tokį ciklą su bandomuoju dokumentu prieš industrializuojant procesą: tai per tris sekundes parodys, ar puslapių skaičius sutampa, ar aptikti vaizdai ir ar antraštės tinkamai atskirtos nuo pagrindinio teksto.
Ribos ir klaidos
Naudojimui taikomi trys apribojimai: maksimalus failo dydis – 50 MB, maksimalus puslapių skaičius dokumente – 1 000, o palaikomi įvesties formatai – PDF, PNG, JPEG, AVIF, PPTX ir DOCX. Be to, galioja užklausų dažnio ribojimas (rate limiting), kurio slenkstis priklauso nuo jūsų prenumeratos lygio – tai būtina patikrinti prieš masinį lygiagretų apdorojimą, kitaip rizikuojate, kad jūsų kvietimai bus atmesti staigaus srauto metu.
Šie apribojimai, kaip ir tinklo sutrikimai, pasireiškia išimtimis (exceptions), kurias turite sugauti. Grupinis darbas, sustojantis ties 300-ąja sąskaita, nes vienas failas viršija leistiną dydį, yra išvengiamas laiko švaistymas:
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}")
Skirti du išimčių lygmenis yra naudinga: SDKError suteikia būsenos kodą, pagal kurį sprendžiate, ar kartoti užklausą – po 429 klaidos reikia palaukti ir bandyti iš naujo, po 400 – niekada, – o bendrasis blokas sugauna vietines problemas, pavyzdžiui, trūkstamą failą arba neįmanomą kodavimą.
Svarbiausi punktai
- OCR galinis taškas yra
client.ocr.process()su modeliumistral-ocr-latest - Trys siuntimo būdai: viešas URL, base64, įkeltas failas
- Pasirenkami parametrai valdo lentelės formatą ir vaizdų įtraukimą
- Atsakymas struktūrizuotas puslapis po puslapio su „Markdown“, vaizdais ir metaduomenimis
- Laikykitės 50 MB ir 1 000 puslapių vienam dokumentui ribų