PDF-y w Claude Code: konwersja, tokeny i zachowanie struktury

Co dzieje się z plikiem PDF w Claude i dlaczego każda strona kosztuje 1 500–3 000 tokenów?#

Oficjalna dokumentacja Anthropic opisuje ten proces w trzech prostych krokach:

Brzmi logicznie, ale koszty przetwarzania rosną liniowo wraz z liczbą stron. A oto liczba, która wyjaśnia, dlaczego limit subskrypcji wyczerpuje się na jednym pliku PDF:

Aby pokazać skalę, Anthropic zmierzył ten sam 3-stronicowy plik PDF w Bedrock w dwóch trybach. W trybie tekstowym (Converse Document Chat) zużył około 1 000 tokenów. W trybie analizy wizualnej (Claude PDF Chat) — około 7 000 tokenów. Uwzględnienie obrazów sprawia, że przetwarzanie jest 7 razy droższe.

Zrzuty ekranu stron wypadają jeszcze gorzej. Zrzut ekranu o rozdzielczości 1000×1000 pikseli kosztuje około 1 300 tokenów.

Mechanizm jest prosty: pliki PDF są kosztowne, ponieważ Claude nie ufa w pełni OCR. Korzysta jednocześnie z tekstu i obrazu, by je porównać — płacisz więc za obie warstwy naraz. W przypadku dużych dokumentów możesz postąpić inaczej: zapisz plik jako Markdown w folderze projektu i powiedz Claude: „oto dokument z informacjami — rozłóż je na części”. Claude rozdzieli treść między własne pliki i będzie dalej pracować z uporządkowanym tekstem, zamiast zużywać wszystko naraz.

Ile tokenów zużywa PDF w typowym zadaniu?#

Konkretne liczby (model Sonnet 4.x, koszt wejściowy $3 za milion tokenów):

A to tylko jeden cykl 4 zapytań. Potem w grę wchodzi buforowanie promptów (domyślny TTL wynosi 5 minut, w rozszerzonym planie do 1 godziny, a powtarzane wywołania w tym czasie mogą być tańsze nawet o 90%) — oszczędności się mnożą.

Za każdym razem, gdy przesyłasz ten sam PDF w nowym czacie, Claude odczytuje go ponownie; pamięć podręczna nie przenosi się między czatami.

Jeśli ten sam 15-stronicowy PDF raz przekonwertujesz do Markdown i dodasz .md do każdego z czterech nowych czatów, przykład zużyje 15 × 300 × 4 = 18,000 tokenów wejścia zamiast 135,000. 300 tokenów na stronę po konwersji i 2,250 na stronę PDF to założenia obliczenia, nie zmierzone stałe każdego PDF. Przed szacowaniem oszczędności policz własny dokument i sprawdź jakość konwersji.

Różnica jest jeszcze większa w przypadku subskrypcji Claude Pro. Jeden 100-stronicowy raport może wyczerpać cały limit na 5 godzin. Po konwersji do Markdown w tym samym budżecie zmieści się ponad 10 takich dokumentów.

Jakie limity dotyczą PDF-ów w Anthropic API w 2026 roku?#

Dokumentacja Anthropic podaje limity na samej górze (stan na 31 maja 2026 roku):

Claude.ai (konsumencka aplikacja internetowa) ma inne limity: maksymalnie 500 MB na plik i do 20 plików w jednym czacie. Analiza wizualna działa jednak tylko w przypadku PDF-ów liczących do 100 stron — powyżej tego limitu Claude widzi wyłącznie tekst, bez wykresów i diagramów.

Trzy sposoby przesłania PDF-a przez API:

1. Przez URL - "source": {"type": "url", "url": "..."} - najprościej, gdy dokument jest dostępny online.
2. W Base64 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - dla plików lokalnych.
3. Przez Files API - "source": {"type": "file", "file_id": "file_abc123"} - do powtarzanych żądań; wymaga nagłówka beta anthropic-beta: files-api-2025-04-14.

Files API to główny sposób na oszczędności podczas pracy z tym samym PDF-em w różnych czatach. Prześlij go raz, uzyskaj file_id, a następnie używaj go we wszystkich interakcjach. Z cache_control: ephemeral powtarzane wywołania kosztują 10% standardowej ceny.

Anthropic podaje również oficjalne wskazówki dotyczące ograniczania zużycia:

Metoda 1: Jak skonfigurować MarkItDown w 5 minut?#

MarkItDown to oficjalny projekt Microsoftu utrzymywany przez zespół AutoGen. Na GitHubie ma 134 tysiące gwiazdek i 9,2 tysiąca forków (stan na koniec maja 2026 roku). Jego cel bezpośrednio opisano w pliku README:

Obsługiwane formaty:

• Dokumenty: PDF, DOCX, PPTX, XLSX
• Web: HTML, JSON, XML, CSV
• Media: audio z transkrypcją, obrazy z EXIF i OCR, filmy YouTube (przez napisy)
• Archiwa: ZIP, EPub
• Inne: wszystkie załączniki w plikach Outlook MSG

Instalacja

Wymaganie: Python 3.10+ (zwykle jest już zainstalowany w macOS; w systemie Windows trzeba zainstalować go osobno).

pip install 'markitdown[all]'

Jeśli nie potrzebujesz wszystkich formatów, możesz zainstalować tylko wybrane:

pip install 'markitdown[pdf, docx, pptx]'

Konwersja pojedynczego pliku

Najprostszy przypadek:

markitdown document.pdf > document.md

Po wykonaniu polecenia plik document.md pojawi się w bieżącym folderze. Dodaj go do Claude Code za pomocą @document.md albo po prostu umieść obok projektu.

Python API

Jeśli chcesz zintegrować narzędzie ze skryptem:

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("research-paper.pdf")
print(result.text_content)

# Możesz od razu zapisać wynik:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

Czego MarkItDown NIE POTRAFI

• OCR dla skanowanych PDF-ów - nie zwraca niczego. Skanowanie wymaga PyMuPDF4LLM lub Docling.
• Złożonych układów wielokolumnowych - może pomieszać kolejność czytania.
• Osadzonych adresów URL z PDF-ów - nie zachowuje ich.

W przypadku prostych plików PDF (raporty, artykuły, dokumentacja) MarkItDown będzie najlepszym wyborem: to wszechstronne narzędzie, które instaluje się w minutę i nie wymaga znajomości Pythona. Wyniki dla dokumentów z tekstem cyrylicą i skanów przedstawiono w pomiarach w analizie dotyczącej tego, jak konwertować PDF na tekst dla AI.

Metoda 2: Co oferuje PyMuPDF4LLM i kiedy jest lepszy?#

MarkItDown oferuje szeroką obsługę formatów; PyMuPDF4LLM zapewnia głębsze możliwości przetwarzania PDF-ów.

Wersja aktualna na 31 maja 2026 roku to 1.27.2.3 (wydana 24 kwietnia 2026 roku).

Co zawiera

• Strony wielokolumnowe z prawidłową kolejnością czytania
• Konwersję tabel do GitHub Flavored Markdown
• Automatyczne usuwanie nagłówków i stopek
• Wyodrębnianie obrazów z względnymi odnośnikami do osobnego folderu
• Inteligentne OCR: stosowane tylko do nieczytelnych obszarów, oszczędza około 50% czasu przetwarzania
• Natywny silnik w C, nie wymaga GPU

Instalacja

pip install pymupdf4llm

Użycie

import pymupdf4llm

# Podstawowe użycie - prosto do Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

# Zapis:
with open("document.md", "w") as f:
    f.write(md_text)

Jednym wierszem, zgodnie z obietnicą:

python3 -c "import pymupdf4llm; \
  open('document.md','w').write(pymupdf4llm.to_markdown('document.pdf'))"

Kiedy wybrać PyMuPDF4LLM zamiast MarkItDown

• Gdy PDF zawiera wiele linków, które chcesz zachować (MarkItDown je usuwa).
• Gdy dokument jest skanem i potrzebujesz OCR.
• Gdy potrzebujesz szybko przetworzyć lokalnie tysiące plików — natywny silnik w C działa szybciej niż opakowania Pythona.
• Gdy potrzebujesz obrazów z PDF-a w osobnym folderze do dalszego przetwarzania.

Szczegóły licencji (ważne w biznesie)

PyMuPDF4LLM jest objęty podwójną licencją: AGPL v3 LUB komercyjną licencją Artifex.

Co oznacza AGPL: jeśli używasz biblioteki w publicznej usłudze SaaS, musisz opublikować cały kod źródłowy usługi na tej samej licencji AGPL. W przypadku użytku wewnętrznego (np. własnego skryptu na laptopie) nie ma żadnych ograniczeń.

Aby prowadzić komercyjne prace rozwojowe bez ujawniania kodu, kup licencję od Artifex (artifex.com). Ceny nie są publikowane — skontaktuj się z działem sprzedaży.

Jeśli tworzysz produkt dla klientów, sprawdź licencję na samym początku. MarkItDown (MIT) i Docling (MIT) są bezpieczniejszym wyborem dla SaaS.

Metoda 3: Jak połączyć serwer MarkItDown MCP z Claude Code?#

MarkItDown w trybie CLI oznacza „ręcznie konwertuję pliki z wyprzedzeniem”; serwer MCP oznacza „Claude Code decyduje, kiedy konwertować”.

Instalacja

Potrzebujesz menedżera pakietów uv. Nie musisz instalować serwera osobno — uv pobierze go przy pierwszym uruchomieniu.

Konfiguracja w Claude Code

Jedno polecenie połączy serwer ze wszystkimi Twoimi projektami, a wersja będzie przypięta:

claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list

Wpis markitdown powinien mieć status „Connected”. Przy pierwszym uruchomieniu pobieranych jest około 70 pakietów, co może potrwać do minuty; później serwer uruchamia się w sekundę lub dwie.

Oto dlaczego polecenie wymaga tych dwóch zmiennych. ORT_DISABLE_TELEMETRY=1 wyłącza statystyki, które silnik onnxruntime w serwerze domyślnie wysyła do Microsoftu na Macu i Linuksie. UV_PYTHON=3.12 uruchamia serwer na Pythonie 3.12, dla którego dostępne są gotowe pakiety dla Windows, Linuksa i Maców z Apple Silicon. Na Intel Macach oraz macOS 13 i starszych serwer nie instaluje się na Pythonie 3.14. W przypadku Intela i Pythona 3.12 jest pewne zastrzeżenie: ponieważ od czerwca 2026 roku nie ma gotowego pakietu dla Intela, uv skompiluje bibliotekę cryptography ze źródeł. Instalacja potrwa dłużej i może się nie powieść. Jeśli nie masz Pythona 3.12, uv pobierze go za Ciebie.

Serwer działa bezpośrednio na Twoim komputerze i może otwierać wszystkie pliki, do których masz dostęp. Jeśli Claude Code był otwarty, uruchom go ponownie — wtedy markitdown pojawi się na liście serwerów MCP.

Jak z niego korzystać

W Claude Code po prostu powiedz:

Convert /Users/your-user/Documents/report.pdf to Markdown and analyze the main points.

Claude sam wywoła convert_to_markdown(uri), otrzyma Markdown i będzie na nim pracować — PDF w ogóle nie zostanie załadowany do kontekstu.

Obsługiwane URI

• file:// - pliki lokalne
• http://, https:// - dokumenty online
• data: - dane osadzone (Base64)

Bezpieczeństwo

Z oficjalnego pliku README:

Domyślnie nasłuchuje na localhost. Jeśli uruchamiasz go przez HTTP/SSE (opcja --http --host 127.0.0.1 --port 3001), nie udostępniaj portu na zewnątrz bez uwierzytelnionego reverse proxy.

Którą metodę wybrać do swojego zadania?#

Rozszerzona tabela porównawcza:

Marker podaje imponujące wyniki dokładności w testach porównawczych:

Marker wymaga jednak GPU, by zapewnić dobrą szybkość, i dołącza modele uczenia maszynowego. W przypadku większości zadań (zwykłych tekstowych PDF-ów) PyMuPDF4LLM lub MarkItDown załatwią sprawę w kilka sekund, bez GPU.

Prosta zasada wyboru

1. Jeden lub dwa PDF-y, potrzebne szybko - MarkItDown CLI.
2. Dziesiątki PDF-ów, potrzebna automatyzacja - serwer MarkItDown MCP lub PyMuPDF4LLM w skrypcie.
3. PDF-y z linkami i obrazami, w których ważne jest zachowanie struktury - PyMuPDF4LLM.
4. Produkcyjne RAG dla biznesu, gdzie liczy się stabilność tabel - Docling.
5. Artykuły naukowe z formułami - Marker.
6. Nie chcesz o tym myśleć i wolisz, żeby Claude konwertował pliki - serwer MarkItDown MCP.

Jak napisać gotowy do użycia skrypt, który automatycznie konwertuje folder dokumentów?#

Praktyczny przykład: wyobraź sobie, że w jednym folderze masz 40 raportów klientów w formatach PDF i PPTX — wyciągi maklerskie, umowy, prezentacje. Bezpośrednie przesłanie folderu do Claude nie ma sensu: okno kontekstu wypełni się informacjami, zanim otrzymasz pierwszą odpowiedź. Najpierw przetwórz cały folder jednym przebiegiem za pomocą poniższego skryptu, a potem pracuj z lekkimi plikami .md zamiast z dużymi PDF-ami.

Zapisz skrypt jako scripts/docs-to-md.sh w katalogu głównym projektu:

#!/bin/bash
# docs-to-md.sh - konwertuje wszystkie dokumenty w folderze do Markdown za pomocą MarkItDown
# Użycie: bash docs-to-md.sh ./documents

set -e

INPUT_DIR="${1:-./documents}"
OUTPUT_DIR="${INPUT_DIR}/_md"

mkdir -p "$OUTPUT_DIR"

echo "Skanowanie $INPUT_DIR..."

for file in "$INPUT_DIR"/*.{pdf,docx,pptx,xlsx}; do
  [ -f "$file" ] || continue

  basename=$(basename "$file")
  name="${basename%.*}"
  output="$OUTPUT_DIR/${name}.md"

  if [ -f "$output" ] && [ "$output" -nt "$file" ]; then
    echo "Pomijanie $basename (już przekonwertowano)"
    continue
  fi

  echo "Konwertowanie $basename..."
  markitdown "$file" > "$output"
done

echo "Gotowe. Wyniki znajdują się w $OUTPUT_DIR"

Nadaj mu uprawnienia do wykonywania:

chmod +x scripts/docs-to-md.sh

Uruchom go:

bash scripts/docs-to-md.sh ./reports

Po uruchomieniu folder ./reports/_md/ będzie zawierać wersje .md wszystkich dokumentów. Dodaj je do Claude Code za pomocą @reports/_md/ i pracuj ze skompresowanym tekstem zamiast z PDF-ami.

Skrypt automatycznie pomija pliki, które zostały już przekonwertowane (jeśli plik .md jest nowszy niż źródło) — ponowne uruchomienie jest tanie i nie przelicza wszystkiego od nowa.

Idempotencja i konwersja przyrostowa

Jeśli chcesz, aby skrypt wykrywał zmiany w plikach PDF zapisanych ponownie pod tą samą nazwą, dodaj sprawdzanie skrótu treści:

hash=$(shasum -a 256 "$file" | cut -d' ' -f1)
hash_file="$OUTPUT_DIR/.${name}.sha256"

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "Pomijanie $basename (sumy kontrolne są zgodne)"
  continue
fi

markitdown "$file" > "$output"
echo "$hash" > "$hash_file"

Ta wersja konwertuje plik ponownie tylko wtedy, gdy zmieni się jego treść.

Kiedy PDF w Claude nadal sprawdza się lepiej niż Markdown?#

Trzy sytuacje, w których konwersja do Markdown nie wystarcza:

1. Analiza wizualna diagramów i wykresów

Jeśli Claude ma „odczytać” wykres — krzywą cenową, diagram procesu lub architektury — tych informacji nie ma w Markdown. Markdown zachowuje tylko podpisy ilustracji; sama ilustracja przepada.

Rozwiązanie: prześlij PDF i jawnie włącz tryb wizualny. W Claude API flaga działa automatycznie; w AWS Bedrock potrzebujesz flagi citations.

2. Złożone tabele z połączonymi komórkami

Tabele Markdown są płaskie. Jeśli PDF zawiera tabelę z połączonymi komórkami, wielopoziomowymi nagłówkami lub zagnieżdżonymi podtabelami, konwerter spłaszczy ją albo utraci powiązania między elementami.

Rozwiązanie: użyj bezpośrednio PDF-a, użyj Docling (najlepiej radzi sobie ze złożonymi tabelami) albo ręcznie sformatuj tabelę po konwersji.

3. Dokumenty jako artefakty z odwołaniami do stron

W przypadku dokumentów prawnych, umów i protokołów ważna jest możliwość cytowania „strona 7, akapit 3”. Numery stron znikają w Markdown.

Rozwiązanie: PDF + Files API + buforowanie promptów. Prześlij plik raz, a następnie odwołuj się do niego za pomocą file_id; Claude widzi paginację i może cytować konkretne strony.

Krótkie dokumenty

Jeśli PDF ma mniej niż 2 strony i używasz go raz, konwersja nie jest warta zachodu. PDF kosztujący 5 000 tokenów w porównaniu z Markdown za 800 tokenów nie daje oszczędności uzasadniających instalowanie MarkItDown.

Próg opłacalności to około 5+ stron lub 2+ użycia tego samego dokumentu. Poniżej tych wartości przesyłaj PDF bezpośrednio; powyżej — konwertuj go.

Jakie jest 5 najczęstszych błędów popełnianych przy pracy z PDF-ami w Claude?#

1. Każdorazowe przesyłanie tego samego PDF-a w nowym czacie

Claude Pro ma limit wiadomości na 5 godzin — jeden 50-stronicowy raport może go wyczerpać, zanim zadasz drugie pytanie.

Obowiązuje tu prosta zasada: jedno zadanie — jeden czat. Gdy AI zaczyna zużywać absurdalną liczbę tokenów, oznacza to, że upychasz wszystko w jednym czacie i w kółko dodajesz PDF. W każdym oknie zajmuj się jednym małym zadaniem. Raz przekonwertuj dokument do Markdown, a potem dodawaj plik .md do każdego nowego okna razem z projektem. Kółko okna kontekstu nie zmieni koloru na żółty.

Rozwiązanie: przekonwertuj dokument raz do Markdown albo użyj Files API z file_id i buforowaniem promptów.

2. Zrzut ekranu zamiast tekstu

Typowy przykład: ktoś chce pokazać Claude fragment kodu lub tabelę, robi zrzut całego ekranu 1920×1080, a potem zastanawia się, dlaczego limit wyczerpał się już po 5 zapytaniach.

Zrzut ekranu o rozdzielczości 1000×1000 pikseli kosztuje około 1 300 tokenów. Ten sam tekst skopiowany ręcznie kosztuje 50–100 tokenów. To różnica 13–26 razy.

Rozwiązanie: dokładnie przytnij zrzut ekranu, tak aby obejmował tylko ważny fragment, albo — jeszcze lepiej — skopiuj tekst bezpośrednio.

3. Skanowany PDF bez OCR

MarkItDown nie obsługuje OCR. Jeśli przekonwertujesz skan, otrzymasz pusty plik .md (albo 3 linie szumu).

Rozwiązanie: do skanów używaj PyMuPDF4LLM z wbudowanym inteligentnym OCR albo Docling.

4. Ignorowanie limitu 100 stron

Dokumentacja Anthropic podaje limit 600 stron na żądanie, ale w praktyce limit dla modeli z kontekstem 200K (Sonnet 4.x, Opus 4.x) wynosi 100 stron. Limit 600 stron jest przeznaczony dla starszych modeli lub specjalnych planów.

Jeśli prześlesz 150-stronicowy raport do Sonnet 4.6, otrzymasz błąd albo, co gorsza, Claude przetworzy tylko pierwsze 100 stron i będzie zachowywać się tak, jakby przeczytał cały dokument.

Rozwiązanie: podziel długie pliki PDF na części przed przesłaniem. Albo przekonwertuj je do Markdown — nie ma limitu stron, jest tylko limit tokenów.

5. Brak buforowania promptów przy powtarzanych zapytaniach

Jeśli pracujesz z tym samym dokumentem przez API, obejmij go ustawieniem cache_control: ephemeral. Powtarzane wywołania w ciągu 5 minut kosztują 10% ceny początkowej. Jedno zapytanie kosztuje więcej; pozostałe otrzymują 90% zniżki.

Rozwiązanie: domyślnie włącz buforowanie promptów dla wszystkiego, co przesyłasz więcej niż raz.

Co dalej: inżynieria kontekstu#

Konwersja PDF do Markdown to jeden ze sposobów oszczędzania tokenów. Sama w sobie nie zwiększa dokładności odpowiedzi Claude. Dokładność wynika z inżynierii kontekstu — dziedziny zajmującej się tym, co umieszczasz w kontekście modelu, zanim zadasz pytanie.

Jeśli Twój CLAUDE.md ma 800 wierszy, projekt zawiera 10 niepotrzebnych serwerów MCP, a Ty dodajesz 100-stronicowy PDF, konwersja do Markdown zapobiegnie jednemu wyciekowi, ale pozostałe trzy zostaną. Dlatego te poradniki omawiają:

• Gdzie trafiają tokeny w Claude Code - 9 wzorców wycieku kontekstu, nie tylko PDF-y.
• Inżynieria kontekstu w 2026 roku - systematyczne zarządzanie kontekstem.
• Plan Mode w Claude Code - tryb planowania używany przed rozpoczęciem pisania kodu przez Claude.