Nagłówki, stopki i paginacja
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 na poziomie bloku.
Oddziel ozdobniki od treści
Od wersji OCR 2512 (grudzień 2025) model OCR firmy Mistral wydobywa nagłówki i stopki osobno dla każdej strony. Funkcja ta może wydawać się trywialna, dopóki nie zaindeksujesz 120-stronicowej umowy: nazwa kancelarii prawnej, oznaczenie „Poufne“ oraz numery stron pojawiają się 120 razy, zanieczyszczając każdy wynik wyszukiwania. W przypadku dokumentów formalnych – umów, raportów rocznych, tekstów regulacyjnych – to rozdzielenie transformuje jakość wszystkiego, co następuje potem.
Dylemat jest realny. Elementy te powtarzają się mechanicznie na każdej stronie, tworząc szum zarówno w indeksowaniu, jak i w odpowiedziach systemów RAG. Czasami jednak zawierają jedyne wiarygodne metadane dokumentu: numer wersji, datę wydania, poziom klasyfikacji. Wydobycie ich osobno, zamiast usuwania lub pozostawiania w treści głównej, pozwala decydować indywidualnie w każdym przypadku.
Dostęp do pól
Pola header i footer są dostępne bezpośrednio na każdej stronie odpowiedzi:
import os
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://exemple.com/contrat.pdf"
}
)
for page in ocr_response.pages:
print(f"--- Strona {page.index + 1} ---")
if page.header:
print(f"Nagłówek: {page.header}")
print(f"Treść: {page.markdown[:100]}...")
if page.footer:
print(f"Stopka: {page.footer}")
print()
Sprawdzenia if page.header nie są zbędne: nie każda strona posiada nagłówek, zaczynając od stron tytułowych, w którym to przypadku pole to ma wartość None.
Rekonstrukcja paginacji
Każda strona jest indeksowana od zera. W przypadku wielostronicowego dokumentu, który planujesz przechowywać lub zwrócić do aplikacji, lepiej jest niezwłocznie znormalizować strukturę: numer czytelny dla człowieka, treść, ozdobniki, wymiary i liczba obrazów.
def extract_with_pagination(ocr_response) -> dict:
"""Wydobądź treść, zachowując paginację."""
document = {
"page_count": len(ocr_response.pages),
"pages": []
}
for page in ocr_response.pages:
page_data = {
"number": page.index + 1,
"content": page.markdown,
"header": page.header or "",
"footer": page.footer or "",
"dimensions": {
"width": page.dimensions.width if page.dimensions else None,
"height": page.dimensions.height if page.dimensions else None,
},
"image_count": len(page.images) if page.images else 0,
}
document["pages"].append(page_data)
return document
Operatory or "" i zabezpieczenia dla page.dimensions konwertują potencjalne wartości null na neutralne domyślne. Zapobiega to wystąpieniu błędu AttributeError w połowie przetwarzania wsadowego, np. przy 80. dokumencie.
Wymiary są wyrażone w punktach PDF, gdzie jeden punkt równa się 1/72 cala. Formaty, z którymi spotkasz się najczęściej:
- A4: 595 x 842 punkty
- Letter: 612 x 792 punkty
- A3: 842 x 1191 punktów
Informacja ta pomaga wykryć strony odstające w partii – np. rysunek techniczny w formacie A3 wmieszany wśród arkuszy A4 lub skan w nietypowej skali. Konwersja na centymetry sprawia, że diagnoza jest natychmiastowa:
for page in ocr_response.pages:
if page.dimensions:
width_cm = page.dimensions.width * 2.54 / 72
height_cm = page.dimensions.height * 2.54 / 72
print(f"Strona {page.index + 1}: {width_cm:.1f} x {height_cm:.1f} cm")
Czysta treść dla systemów RAG
W zależności od dokumentu, nagłówek i stopka mogą pojawić się również w głównym polu markdown. Przed indeksowaniem usuń je, jeśli faktycznie otaczają treść:
def main_content(ocr_response) -> str:
"""Wydobądź tylko główną treść, bez nagłówków i stopek."""
parts = []
for page in ocr_response.pages:
content = page.markdown
# Opcjonalnie: usuń nagłówki/stopy z markdown,
# jeśli są zawarte w głównej treści
if page.header and content.startswith(page.header):
content = content[len(page.header):].strip()
if page.footer and content.endswith(page.footer):
content = content[:-len(page.footer)].strip()
parts.append(content)
return "\n\n".join(parts)
Warunki startswith i endswith są celowo ostrożne: usuwamy ciąg znaków tylko wtedy, gdy rzeczywiście pojawia się on na początku lub na końcu strony. Ślepe usuwanie poprzez replace niesie ryzyko wymazania legalnego wystąpienia nazwy firmy w środku tekstu.
Wykorzystaj metadane ze stopki
Gdy stopki są już wyizolowane, kilka wyrażeń regularnych wystarczy, aby wydobyć ustrukturyzowane metadane: paginację w formacie „3 / 40“, datę wydania, numer wersji i poziom klasyfikacji.
import re
def extract_footer_metadata(ocr_response) -> dict:
"""Wydobierz metadane ze stopek."""
metadata = {
"page_numbers": [],
"dates": [],
"versions": [],
"classifications": [],
}
for page in ocr_response.pages:
footer = page.footer or ""
# Wyszukiwanie numeru strony
match_page = re.search(r"(\d+)\s*/\s*(\d+)", footer)
if match_page:
metadata["page_numbers"].append(
f"{match_page.group(1)}/{match_page.group(2)}"
)
# Wyszukiwanie daty
match_date = re.search(r"\d{2}/\d{2}/\d{4}", footer)
if match_date:
metadata["dates"].append(match_date.group())
# Wyszukiwanie wersji
match_version = re.search(r"v(?:ersion)?\s*(\d+\.?\d*)", footer, re.I)
if match_version:
metadata["versions"].append(match_version.group(1))
# Klasyfikacja (Poufne, Publiczne itp.)
for classification in ["confidential", "public", "internal", "secret"]:
if classification in footer.lower():
metadata["classifications"].append(classification)
return metadata
Wartość tego wykracza poza ciekawostkę dokumentalną. Wykryta tu klasyfikacja może sterować przetwarzaniem downstream: kieruj elementy oznaczone jako „poufne“ do indeksu o ograniczonym dostępie lub odmów ich wysyłania do usługi zewnętrznej. Oczywiście dostosuj słownictwo do terminologii używanej w Twojej organizacji.
Przetwarzaj tylko część dokumentu
W przypadku dużych dokumentów często potrzebujesz tylko sekcji – np. finansowych załączników raportu lub podpisanego rozdziału umowy. Filtrowanie odbywa się po wydobyciu, na już otrzymanej odpowiedzi:
def extract_range(ocr_response, start: int, end: int) -> str:
"""Wydobierz treść z zakresu stron (indeksowanie od 1)."""
parts = []
for page in ocr_response.pages:
number = page.index + 1
if start <= number <= end:
parts.append(page.markdown)
return "\n\n---\n\n".join(parts)
# Wydobądź strony od 5 do 10
partial_content = extract_range(ocr_response, 5, 10)
Funkcja używa numeracji czytelnej dla człowieka, zaczynając od 1: żądanie stron od 5 do 10 zwraca dokładnie te strony. Pamiętaj jednak, że cały dokument został już przetworzony – i obciążony opłatą – przed tym filtrowaniem. Jeśli z góry wiesz, że interesuje Cię tylko kilka stron, podziel plik PDF wcześniej, zamiast wysyłać wszystkie 1000 stron do API.
Kluczowe wnioski
- Nagłówki i stopki są wydobywane osobno od wersji OCR 2512
- Filtruj je, aby uniknąć szumu w potokach RAG
- Wymiary stron są podane w punktach PDF (72 punkty = 1 cal)
- Stopki często zawierają przydatne metadane (wersja, data, klasyfikacja)
- Przetwarzaj zakresy stron w przypadku dużych dokumentów