Twój pierwszy wywołanie OCR w Pythonie
Na tej stronie
Zaktualizowano 2 listopada 2026 — OCR. Model OCR 4.0 (
mistral-ocr-4-0) został wycofany 30 września 2026 r. Używaj OCR 4.1 (mistral-ocr-4-1), który jest ogólnie dostępny od 31 sierpnia w tej samej cenie, lub aliasumistral-ocr-latest, który wskazuje na niego od 16 lipca. OCR 4.1 dodaje wyniki pewności (confidence scores) na poziomie bloków. Dodatkowa uwaga z 3 listopada 2026: Lokalny plik PDF jest przesyłany w formacie base64 jako{"type": "document_url", "document_url": "data:application/pdf;base64,…"}; typdocument_base64ze starszych przykładów nie istnieje ani w dokumentacji, ani w SDKmistralai, a te przykłady zakończyłyby się niepowodzeniem. Źródła: OCR Processor · Document QnA.
Od teorii do kodu
Znasz już punkt końcowy i jego parametry. Czas napisać kompletny skrypt, który ekstrahuje tekst z pliku PDF – od pierwszej linii importu aż po zapisanie pliku Markdown na dysku. Zacznijmy od najprostszego przypadku – dokumentu publicznego – a następnie przejdźmy do tego, z czym spotkasz się w praktyce: plików lokalnych, pojedynczych obrazów i dokumentów ilustrowanych wymagających rekonstrukcji.
Dwa warunki wstępne, już omówione, ale warto je zweryfikować, zanim stracisz dziesięć minut na błędy uwierzytelniania:
pip install mistralai
export MISTRAL_API_KEY="your-api-key"
Minimalny skrypt
Oto pełna ekstrakcja pliku PDF dostępnego online. Trzy użyteczne linie: inicjalizacja klienta, wywołanie process i iteracja po stronach.
import os
from mistralai.client import Mistral
# Inicjalizacja klienta
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Wywołanie OCR na publicznym pliku PDF
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://arxiv.org/pdf/2201.04234"
}
)
# Wyświetlenie liczby stron
print(f"Liczba stron: {len(ocr_response.pages)}")
# Wyświetlenie zawartości każdej strony
for page in ocr_response.pages:
print(f"\n--- Strona {page.index + 1} ---")
print(page.markdown)
Zwróć uwagę na page.index + 1: indeks zwracany przez API zaczyna się od zera, podczas gdy Twoi użytkownicy liczą od jeden. To niewielkie przesunięcie, dopóki o nim pamiętasz, ale źródło trwałego zamieszania, gdy odkryjesz je w raporcie dostarczonym klientowi.
Przetwarzanie pliku z Twojego komputera
W prawdziwym życiu dokumenty rzadko przychodzą przez publiczny adres URL. Masz je na dysku, są poufne, więc kodujesz je w formacie base64. Poniższy skrypt przetwarza fakturę od dostawcy i łączy wszystkie strony w jeden blok tekstu:
import os
import base64
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Odczyt i kodowanie pliku lokalnego
file_path = "supplier_invoice.pdf"
with open(file_path, "rb") as f:
document_base64 = base64.b64encode(f.read()).decode("utf-8")
# Wywołanie OCR
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{document_base64}"
}
)
# Połączenie całego tekstu
full_text = "\n\n".join(
page.markdown for page in ocr_response.pages
)
print(full_text)
Łączenie za pomocą "\n\n".join(...) działa dobrze do wyświetlania lub wyszukiwania pełnotekstowego. Jednak usuwa ono granicę między stronami: jeśli później będziesz potrzebować cytować źródło lub skierować użytkownika do właściwej strony umowy, zachowaj strukturę strona po stronie, zamiast tego pojedynczego bloku.
Zapisywanie ekstrakcji
Każde wywołanie OCR kosztuje pieniądze i zajmuje czas. Ponowne uruchamianie ekstrakcji tego samego dwustustronicowego raportu, ponieważ zapomniałeś zapisać wynik, to błąd, który popełnia się tylko raz. Poniższa funkcja zapisuje Markdown do pliku, oznaczając podziały stron komentarzem i separatorem:
import os
import base64
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
def extract_pdf(pdf_path: str, output_path: str) -> None:
"""Ekstrahuje tekst z pliku PDF i zapisuje go jako Markdown."""
with open(pdf_path, "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}"
}
)
with open(output_path, "w", encoding="utf-8") as f:
for page in ocr_response.pages:
f.write(f"<!-- Page {page.index + 1} -->\n\n")
f.write(page.markdown)
f.write("\n\n---\n\n")
print(f"Ekstrakcja zakończona: {len(ocr_response.pages)} stron")
print(f"Wynik zapisany w: {output_path}")
# Użycie
extract_pdf("annual_report.pdf", "annual_report.md")
Komentarz HTML <!-- Page N --> jest niewidoczny w widoku renderowanym, ale pozostaje obecny w pliku: możesz go znaleźć za pomocą wyrażenia regularnego, aby zrekonstruować paginację podczas indeksowania.
Przypadek pojedynczego obrazu
OCR 4 nie ogranicza się do plików PDF. Zdjęcie faktury zrobione telefonem, zeskanowany paragon, zrzut ekranu – wszystkie są wysyłane w ten sam sposób, używając typu image_base64:
import os
import base64
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Kodowanie obrazu
with open("scanned_invoice.png", "rb") as f:
image_base64 = base64.b64encode(f.read()).decode("utf-8")
# Wywołanie OCR na obrazie
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "image_base64",
"image_base64": image_base64
}
)
# Pojedyncza „strona“ dla obrazu
print(ocr_response.pages[0].markdown)
Odpowiedź zachowuje tę samą formę: lista stron, która w tym przypadku zawiera tylko jedną. Twój kod przetwarzania pozostaje więc identyczny niezależnie od typu pliku wejściowego, co znacznie upraszcza mieszane potoki danych.
Rekonstrukcja dokumentu ilustrowanego
Zwracany Markdown odwołuje się do obrazów jako , bez osadzania ich. Jeśli chcesz uzyskać samodzielny plik – raport czytelny offline, podgląd do wysłania e-mailem – poproś o obrazy w formacie base64 i zamień każde odwołanie na URI danych:
import os
import base64
import re
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://arxiv.org/pdf/2201.04234"
},
include_image_base64=True
)
for page in ocr_response.pages:
markdown = page.markdown
# Zamiana odwołań do obrazów na base64
for image in page.images:
placeholder = f""
data_uri = f""
markdown = markdown.replace(placeholder, data_uri)
print(markdown[:500])
Wynikowy plik szybko rośnie, ponieważ base64 waży około jednej trzeciej więcej niż oryginalny plik binarny. Zarezerwuj tę rekonstrukcję dla dokumentów, które muszą być samodzielne, a w potokach indeksowania przechowuj obrazy jako osobne pliki.
Zanim przejdziesz dalej, weź dokument, który posiadasz – fakturę, umowę, zeskanowaną stronę – i uruchom go przez skrypt ekstrakcji lokalnej. Porównaj wynikowy Markdown z oryginałem linia po linii: rozbieżności, które znajdziesz, źle zrekonstruowana tabela lub nagłówek wchłonięty przez treść główną, to dokładnie problemy, których nauczą Cię rozwiązywać kolejne trzy lekcje.
Kluczowe wnioski
- Wywołanie OCR zajmuje 3 linie: klient, process, odczyt stron
- Używaj base64 dla plików lokalnych, URL dla dokumentów publicznych
- Wynikiem jest ustrukturyzowany Markdown, gotowy do użycia
- Wyekstrahowane obrazy można ponownie połączyć z tekstem
- Zawsze zapisuj swoje ekstrakcje, aby uniknąć powtarzanych wywołań API