Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Mistralin OCR-API

Oppitunti 4 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Yksi sisäänmenopiste
  2. Asennus ja konfiguraatio
  3. Kutsuparametrit
  4. Kolme tapaa lähettää dokumentti
  5. Vastauksen lukeminen
  6. Rajat ja virheet
  7. Keskeiset asiat

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-muodossa
  • bbox_annotation_format: Rajauslaatikon merkintäkaavio
  • document_annotation_format: Koko dokumentin merkintäkaavio
  • document_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() mallilla mistral-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