Przejdź do głównej treści
Polski— Wybierz język
Menu

API OCR Mistral

Lekcja 4 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Jeden punkt wejścia
  2. Instalacja i konfiguracja
  3. Parametry wywołania
  4. Trzy sposoby wysyłania dokumentu
  5. Odczytywanie odpowiedzi
  6. Limity i błędy
  7. Kluczowe wnioski

Aktualizacja z 2 listopada 2026 r. — OCR. Wersja OCR 4.0 (mistral-ocr-4-0) została wycofana 30 września 2026 r. Używaj wersji OCR 4.1 (mistral-ocr-4-1), która jest ogólnodostępna od 31 sierpnia w tej samej cenie, lub aliasu mistral-ocr-latest, który wskazuje na nią od 16 lipca. OCR 4.1 dodaje wyniki pewności (confidence scores) na poziomie bloków. Dodatek z 3 listopada 2026 r.: Aby wysłać lokalny plik PDF, zakoduj go w formacie base64 jako {"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Typ document_base64 występujący w starszych przykładach nie istnieje w dokumentacji ani w SDK mistralai, a takie przykłady zakończyłyby się niepowodzeniem. Źródła: OCR Processor · Document QnA.

Jeden punkt wejścia

Wszystkie operacje ekstrakcji dokumentów odbywają się przez jeden punkt końcowy: /v1/ocr lub jego odpowiednik w Python SDK, client.ocr.process(). Niezależnie od tego, czy przetwarzasz zdjęcie paragonu, czy 800-stronicowy raport roczny, wywołanie wygląda tak samo. W tej lekcji dowiesz się, jak go skonfigurować, jakie są trzy sposoby przekazania dokumentu i co otrzymasz w odpowiedzi.

Instalacja i konfiguracja

Instalacja wymaga tylko jednego polecenia:

pip install mistralai

Następnie utwórz instancję klienta, podając swój klucz API:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

To podejście sprawdza się do szybkich testów w notatniku, ale niesie ryzyko przypadkowego ujawnienia klucza. Gdy tylko kod opuści Twój komputer, użyj zmiennej środowiskowej:

export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

W wszystkich kolejnych lekcjach będziemy stosować tę drugą formę.

Parametry wywołania

Wywołanie client.ocr.process() wymaga tylko dwóch parametrów: model, zawsze ustawionego na "mistral-ocr-latest", oraz document, który opisuje plik do przetworzenia w jednej z trzech form przedstawionych poniżej.

Inne parametry pozwalają dostosować wynik do Twoich potrzeb:

  • table_format: Format tabel (null, "markdown", "html")
  • include_image_base64: True, aby otrzymać obrazy w formacie base64
  • bbox_annotation_format: Schemat adnotacji ramki ograniczającej (bounding box)
  • document_annotation_format: Schemat pełnej adnotacji dokumentu
  • document_annotation_prompt: Instrukcje wysokiego poziomu dotyczące adnotacji

Dwa pierwsze parametry dotyczą samego procesu OCR i zajmiesz się nimi w następnych lekcjach. Ostatnie trzy odnoszą się do adnotacji, które omówimy począwszy od lekcji 9; na razie zapamiętaj tylko, że pozwalają one żądać strukturalnej ekstrakcji w tym samym wywołaniu, bez konieczności drugiego round tripu.

Trzy sposoby wysyłania dokumentu

Pierwszy sposób, wykorzystujący publiczny adres URL, jest najbardziej bezpośredni, gdy plik jest już dostępny online – np. opublikowany raport lub załącznik przechowywany w publicznym magazynie obiektów:

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/document.pdf"
    }
)

Drugi sposób jest niezbędny dla dokumentów przechowywanych na Twoim komputerze lub w prywatnej przestrzeni dyskowej. Kodujesz je w formacie base64 i wysyłasz w treści żądania. Jest to domyślna metoda dla wszelkich danych poufnych, ponieważ nie trzeba udostępniać żadnego adresu 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}"
    }
)

Trzeci sposób wykorzystuje Files API. Przesyłasz plik raz, pobierasz jego identyfikator, a następnie odwołujesz się do niego w swoich wywołaniach. Zaleta tego rozwiązania ujawnia się przy dużych dokumentach lub gdy ten sam plik musi być przetwarzany wielokrotnie – ekstrakcja OCR dzisiaj, adnotacja z innym schematem jutro – nie musisz przesyłać ponownie 40 MB przy każdej próbie.

# Przesłanie pliku
uploaded_file = client.files.upload(
    file=open("my_document.pdf", "rb"),
    purpose="ocr"
)

# Użycie przesłanego pliku
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "file_id",
        "file_id": uploaded_file.id
    }
)

Odczytywanie odpowiedzi

Odpowiedź zawiera listę stron, a każda strona niesie ze sobą swoją treść wraz z metadanymi. Minimalna pętla wystarczy, aby zweryfikować, czy ekstrakcja przebiegła pomyślnie:

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}")

Wyrób sobie nawyk uruchamiania tego typu pętli na przykładowym dokumencie przed wdrożeniem rozwiązania na skalę przemysłową: w trzy sekundy dowiesz się, czy liczba stron się zgadza, czy wykryto obrazy i czy nagłówki zostały poprawnie odseparowane od treści głównej.

Limity i błędy

Korzystanie z usługi regulują trzy ograniczenia: maksymalnie 50 MB na plik, 1000 stron na dokument oraz obsługiwane formaty wejściowe: PDF, PNG, JPEG, AVIF, PPTX i DOCX. Do tego dochodzi limitowanie częstotliwości żądań (rate limiting), którego próg zależy od poziomu Twojej subskrypcji – punkt, który warto sprawdzić przed masową paralelizacją, inaczej ryzykujesz odrzucenie wywołań w serii.

Te limity, podobnie jak incydenty sieciowe, manifestują się jako wyjątki, które musisz obsłużyć. Zadanie wsadowe, które zatrzymuje się na fakturze numer 300, ponieważ jeden plik przekracza dozwolony rozmiar, to strata czasu, której można uniknąć:

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}")

Rozróżnienie dwóch poziomów wyjątków jest przydatne: SDKError dostarcza kod statusu, na podstawie którego decydujesz, czy ponowić próbę – kod 429 należy ponowić po opóźnieniu, kodu 400 nigdy – podczas gdy blok ogólny przechwytuje problemy lokalne, takie jak brakujący plik czy niemożliwe kodowanie.

Kluczowe wnioski

  • Punkt końcowy OCR to client.ocr.process() z modelem mistral-ocr-latest
  • Trzy metody wysyłania: publiczny URL, base64, przesłany plik
  • Parametry opcjonalne kontrolują format tabel i dołączanie obrazów
  • Odpowiedź jest ustrukturyzowana strona po stronie z Markdownem, obrazami i metadanymi
  • Przestrzegaj limitów: 50 MB i 1000 stron na dokument