Mistralin OCR-API
Tällä sivulla
Päivitetty 2. marraskuuta 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) poistettiin käytöstä 30. syyskuuta 2026. Käytä OCR 4.1:tä (mistral-ocr-4-1), joka on ollut yleisesti saatavilla 31. elokuuta alkaen samaan hintaan, tai alias-nimeämistral-ocr-latest, joka on viitannut siihen 16. heinäkuuta lähtien. OCR 4.1 lisää luottamusluvut lohko tasolla. Lisäys 3. marraskuuta 2026: Lähettääksesi paikallisen PDF-tiedoston, koodaa se base64-muotoon muodossa{"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Vanhemmissa esimerkeissä esiintyväädocument_base64-tyyppiä ei ole dokumentaatiossa eikämistralai-SDK:ssa, ja kyseiset esimerkit olisivat epäonnistuneet. Lähteet: OCR Processor · Document QnA.
Yksi sisäänmenopiste
Kaikki dokumenttien ekstraktio kulkee yhden päätepisteen kautta: /v1/ocr, tai sen Python-SDK-vastineen client.ocr.process() kautta. Käsitteletpä sitten kuvaa kuitista tai 800-sivuista vuosikertomusta, kutsu on sama. Tämä oppitunti kertoo yksityiskohtaisesti, miten se konfiguroidaan, millä kolmella tavalla sille voi syöttää dokumentin ja mitä se palauttaa.
Asennus ja konfiguraatio
Asennus vaatii vain yhden komennon:
pip install mistralai
Seuraavaksi alusta asiakasohjelma API-avaimellasi:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
Tämä tapa toimii nopeaan testaukseen notebook-ympäristössä, mutta siihen sisältyy riski avaimen vahingossa julkistamisesta. Heti kun koodi poistuu koneeltasi, käytä ympäristömuuttujaa:
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Käytämme tätä jälkimmäistä muotoa kaikissa seuraavissa oppitunneissa.
Kutsuparametrit
client.ocr.process()-kutsu vaatii vain kaksi parametria: model, joka asetetaan aina arvoksi "mistral-ocr-latest", ja document, joka kuvaa käsiteltävän tiedoston jollakin alla yksityiskohtaisesti esitellyistä kolmesta tavasta.
Muut parametrit säätävät tulostetta tarpeidesi mukaan:
table_format: Taulukon muoto (null,"markdown","html")include_image_base64:True, jos haluat vastaanottaa kuvat base64-muodossabbox_annotation_format: Rajauslaatikon merkintäkaaviodocument_annotation_format: Koko dokumentin merkintäkaaviodocument_annotation_prompt: Yleiskäyttöiset ohjeet merkinnöille
Kaksi ensimmäistä liittyvät varsinaiseen OCR:ään, ja käsittelet niitä seuraavissa oppitunneissa. Kolme viimeistä liittyvät merkintöihin, joita käsitellään alkaen oppitunnista 9; toistaiseksi riittää, että muistat niiden avulla voivan pyytää strukturoitua ekstraktiota samassa kutsussa ilman toista verkkopyyntöä.
Kolme tapaa lähettää dokumentti
Ensimmäinen, julkinen URL-osoite, on suoraviivaisin, kun tiedosto on jo saatavilla verkossa – esimerkiksi julkaistu raportti tai julkisessa säilössä oleva liite:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
Toinen tapa on välttämätön dokumenteille, jotka sijaitsevat koneellasi tai yksityisessä säilössä. Koodaat ne base64-muotoon ja lähetät ne pyynnön rungossa. Tämä on oletusmenetelmä kaikelle luottamukselliselle datalle, sillä mitään URL-osoitetta ei tarvitse paljastaa:
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}"
}
)
Kolmas tapa käyttää Files API:a. Lataat tiedoston kerran, haet sen tunnisteen ja viittaat siihen kutsuissasi. Hyöty näkyy suurissa dokumenteissa tai silloin, kun samaa tiedostoa on käsiteltävä useita kertoja – esimerkiksi OCR-ekstraktio tänään ja merkintä eri kaaviolla huomenna: et joudu siirtämään 40 Mt dataa jokaisella yrityksellä.
# Lataa tiedosto
uploaded_file = client.files.upload(
file=open("my_document.pdf", "rb"),
purpose="ocr"
)
# Käytä ladattua tiedostoa
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "file_id",
"file_id": uploaded_file.id
}
)
Vastauksen lukeminen
Vastaus palauttaa sivujen listan, ja jokainen sivu sisältää sen sisällön sekä metatiedot. Minimikokoinen silmukka riittää varmistamaan, että ekstraktio sujui ongelmitta:
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}")
Tee tavaksi ajaa tämän kaltainen silmukka esimerkkidokumentilla ennen kuin skaalaat prosessia teolliseen mittakaavaan: se kertoo kolmessa sekunnissa, vastaako sivumäärä odotuksia, havaittiinko kuvia ja onko otsikot eristetty oikein päätekstistä.
Rajat ja virheet
Käyttöä rajoittavat kolme ehtoa: enimmäiskoko 50 Mt tiedostoa kohden, 1 000 sivua dokumenttia kohden sekä syötemuodot PDF, PNG, JPEG, AVIF, PPTX ja DOCX. Tämän päälle tulee nopeusrajoitus, jonka kynnysarvo riippuu tilaustasostasi – tarkista tämä ennen massiivista rinnakkaistamista, muuten riskinä on, että kutsusi hylätään ryöppynä.
Nämä rajat, kuten verkkohäiriötkin, ilmenevät poikkeuksina, jotka sinun on siepattava. Eräajo, joka pysähtyy laskuun numero 300, koska yksi tiedosto ylittää sallitun koon, on vältettävissä olevaa ajanhukkaa:
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}")
Poikkeustasojen erottaminen on hyödyllistä: SDKError antaa statuskoodin, jonka perusteella voit päättää, yritetäänkö uudelleen – 429 kannattaa yrittää uudelleen viiveen jälkeen, 400 ei koskaan – kun taas yleinen lohko sieppaa paikalliset ongelmat, kuten puuttuvan tiedoston tai mahdottoman koodauksen.
Keskeiset asiat
- OCR-päätepiste on
client.ocr.process()mallillamistral-ocr-latest - Kolme lähetystapaa: julkinen URL, base64, ladattu tiedosto
- Valinnaiset parametrit ohjaavat taulukon muotoa ja kuvien sisällyttämistä
- Vastaus on jäsennelty sivu kerrallaan sisältäen Markdownin, kuvat ja metatiedot
- Noudata rajoja: 50 Mt ja 1 000 sivua dokumenttia kohden