API OCR Mistral
Na tej stronie
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 aliasumistral-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,…"}. Typdocument_base64występujący w starszych przykładach nie istnieje w dokumentacji ani w SDKmistralai, 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 base64bbox_annotation_format: Schemat adnotacji ramki ograniczającej (bounding box)document_annotation_format: Schemat pełnej adnotacji dokumentudocument_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 modelemmistral-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