# PDF-y w Claude Code: konwersja, tokeny i zachowanie struktury > MarkItDown, PyMuPDF4LLM, MCP, kompletne skrypty konwersji, limity PDF oraz sytuacje, w których analiza wizualna jest ważniejsza niż oszczędzanie tokenów. Source: https://ailoot.ai/blog/pl/pdf-claude-code-markdown/ Canonical: https://ailoot.ai/blog/pl/pdf-claude-code-markdown/ Language: pl Publisher: Ailoot (https://ailoot.ai/) Translation: guide-196 Revision: sha256-9a7e8653b45b3a435caa09eeead42b6966b4ac0540e403a5d454233d9bff2304
Najważniejsze informacje Każda strona PDF w Claude Code kosztuje 1 500–3 000 tokenów, zanim zadasz pierwsze pytanie — Anthropic jasno opisuje to w swojej dokumentacji. W poniższym przykładzie obliczeniowym 15-stronicowy raport w 4 czatach zużywa 135,000 tokenów PDF za około $0.40 wobec 18,000 tokenów Markdown za $0.054, około 87% mniej. Zakłada to 2,250 tokenów PDF lub 300 tokenów Markdown na stronę przy przykładowej stawce wejścia; dokumenty różnią się. W tym poradniku opisujemy trzy metody konwersji (MarkItDown, PyMuPDF4LLM i serwer MCP) oraz gotowy do użycia skrypt bash do obsługi folderu dokumentów.
Praktyczne instrukcje korzystania z Ailoot znajdziesz w [dokumentacji](https://ailoot.ai/docs/).
## Co dzieje się z plikiem PDF w Claude i dlaczego każda strona kosztuje 1 500–3 000 tokenów?
Najważniejsze informacje Gdy przesyłasz PDF do Claude Code, nie czyta on go jak pliku tekstowego. Najpierw każda strona jest konwertowana na obraz, potem wyodrębniany jest z niej tekst, a obie warstwy — obraz i tekst — są razem dodawane do kontekstu. Dlatego jedna strona zajmuje 1 500–3 000 tokenów, a dokument liczący 50 stron może zużyć 75 000–150 000 tokenów, zanim zadasz pierwsze pytanie.
Oficjalna dokumentacja Anthropic opisuje ten proces w trzech prostych krokach:

System konwertuje każdą stronę dokumentu na obraz. Tekst z każdej strony jest wyodrębniany i udostępniany obok obrazu strony. Claude analizuje zarówno tekst, jak i obrazy, aby lepiej zrozumieć dokument.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
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:

Każda strona zużywa zwykle 1 500–3 000 tokenów, zależnie od gęstości treści. Ponieważ każda strona jest konwertowana na obraz, obowiązuje taki sam koszt jak w przypadku standardowych obrazów.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
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?
Najważniejsze informacje Rozważ 15-stronicowy raport publiczny w 4 kontekstach: analiza, cytaty, tłumaczenie i podsumowanie. Załóż 2,250 tokenów wejścia na stronę PDF, 300 na stronę Markdown i tę samą stawkę wejścia. Ponowne przesłania PDF dają 135,000 tokenów i około $0.40, a Markdown 18,000 i $0.054. Około 87% oszczędności wynika z tych założeń, nie pomiaru każdego PDF.
Konkretne liczby (model Sonnet 4.x, koszt wejściowy $3 za milion tokenów): | Podejście | Tokeny (15 stron, 4 czaty) | Koszt | |------------------------------|-----------------------------|-------------| | Bezpośrednie przesłanie PDF 4 razy | 15 × 2250 × 4 = **135,000** | ~$0.40 | | PDF → Markdown + 4 czaty | 15 × 300 × 4 = **18,000** | ~$0.054 | | Oszczędność | **−87%** | **−$0.35** | 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?
Najważniejsze informacje Anthropic ustala ścisłe limity: maksymalnie 32 MB na żądanie (łącznie z całą zawartością, nie tylko PDF-em) i maksymalnie 600 stron na żądanie. Jednak dla obecnych modeli Sonnet 4.x i Opus 4.x z kontekstem 200K limit jest niższy: **100 stron**. PDF można wysłać na trzy sposoby: przez URL, w Base64 lub przez Files API, aby ponownie używać pliku za pomocą `file_id`. Files API i podział na części stosuje się w przypadku długich dokumentów.
Dokumentacja Anthropic podaje limity na samej górze (stan na 31 maja 2026 roku): | Wymaganie | Limit | |-----------------------------|--------------------------------------------| | Maksymalny rozmiar żądania | 32 MB (zależnie od platformy) | | Maksymalna liczba stron na żądanie | 600 (100 dla modeli z kontekstem 200K tokenów) | | Format | Standardowy PDF bez hasła ani szyfrowania |

Oba limity dotyczą całego treści żądania, w tym zawartości przesyłanej razem z PDF-em. W przypadku dużych plików PDF użyj Files API i odwołuj się do nich za pomocą file_id, aby zmniejszyć treść żądania.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
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:

Gęste pliki PDF (z dużą ilością drobnego tekstu, złożonymi tabelami lub rozbudowaną grafiką) mogą zapełnić okno kontekstu, zanim osiągniesz limit stron. Spróbuj podzielić dokument na sekcje; w przypadku dużych plików zmniejsz rozdzielczość osadzonych obrazów przed przesłaniem.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
## Metoda 1: Jak skonfigurować MarkItDown w 5 minut?
Najważniejsze informacje MarkItDown to narzędzie w Pythonie od zespołu Microsoft AutoGen, które konwertuje pliki PDF, DOCX, PPTX, XLSX, HTML, audio, obrazy, a nawet filmy z YouTube do czystego Markdown. Ma 134 tysiące gwiazdek na GitHubie, licencję MIT i instaluje się jednym poleceniem: `pip install 'markitdown[all]'`. Używanie jest równie proste: `markitdown document.pdf > document.md`. To najbardziej wszechstronne narzędzie do konwersji plików przed użyciem Claude Code.
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:

Lekkie narzędzie w Pythonie do konwertowania plików na Markdown, przeznaczone do użycia z LLM-ami i potokami analizy tekstu.

— Microsoft, https://github.com/microsoft/markitdown
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). ```bash pip install 'markitdown[all]' ``` Jeśli nie potrzebujesz wszystkich formatów, możesz zainstalować tylko wybrane: ```bash pip install 'markitdown[pdf, docx, pptx]' ``` ### Konwersja pojedynczego pliku Najprostszy przypadek: ```bash 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: ```python 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](https://ailoot.ai/blog/pl/markitdown-pdf-word-to-text/). ## Metoda 2: Co oferuje PyMuPDF4LLM i kiedy jest lepszy?
Najważniejsze informacje PyMuPDF4LLM to projekt Artifex Software oparty na natywnym silniku MuPDF w C. Jest najszybszym konwerterem PDF (nie wymaga GPU); inteligentne OCR stosuje tylko do nieczytelnych obszarów, skracając czas przetwarzania o 50%. To jedyne popularne narzędzie, które zachowuje osadzone adresy URL i obrazy z PDF-ów. Wadą jest podwójna licencja AGPL v3 / komercyjna Artifex: w projektach SaaS licencja AGPL oznacza obowiązek opublikowania kodu.
MarkItDown oferuje szeroką obsługę formatów; PyMuPDF4LLM zapewnia głębsze możliwości przetwarzania PDF-ów.

Lekkie rozszerzenie PyMuPDF, które przy minimalnej konfiguracji przekształca pliki PDF w czyste, uporządkowane dane.

— Artifex Software, https://pymupdf.readthedocs.io/en/latest/pymupdf4llm/
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 ```bash pip install pymupdf4llm ``` ### Użycie ```python 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ą: ```bash 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?
Najważniejsze informacje Serwer MarkItDown MCP to ten sam MarkItDown opakowany w protokół MCP, dzięki czemu Claude Code może konwertować pliki PDF w locie bez ładowania oryginalnego pliku do kontekstu. Połączysz go jednym poleceniem za pomocą uv; wersja jest przypięta: `markitdown-mcp@0.0.1a7`. Narzędzie dostępne dla Claude to `convert_to_markdown(uri)`. Koszt w stanie bezczynności to około 110 tokenów na opis umiejętności, a gdy nie jest potrzebne — zero.
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: ```bash 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:

Serwer nie obsługuje autoryzacji i działa z uprawnieniami użytkownika, który go uruchomił.

— Microsoft, https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
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?
Najważniejsze informacje MarkItDown to narzędzie uniwersalne, jeśli pracujesz z różnymi formatami (PDF + DOCX + PPTX + YouTube) i potrzebujesz szybkiego polecenia CLI. PyMuPDF4LLM to specjalista od PDF-ów: działa szybciej, obsługuje OCR i zachowuje linki, ale w SaaS licencja AGPL może być pułapką. Docling nadaje się do środowisk produkcyjnych i najlepiej radzi sobie z tabelami i formułami. Marker jest przeznaczony do artykułów naukowych z matematyką. Serwer MCP sprawdzi się, gdy nie chcesz myśleć o konwersji i wolisz, by Claude Code sam decydował.
Rozszerzona tabela porównawcza: | Narzędzie | Gwiazdki na GitHubie | Najlepsze do | Szybkość | Licencja | |----|----|----|----|----| | **MarkItDown** (Microsoft) | 134k | PDF + DOCX + PPTX + YouTube + audio | Średnia | MIT | | **PyMuPDF4LLM** (Artifex) | \- | Natywny PDF, OCR, osadzone adresy URL | Najszybsza (bez GPU) | AGPL v3 / komercyjna | | **Docling** (IBM Research) | 60.7k | Produkcyjne RAG, tabele, formuły | Średnia | MIT | | **Marker** (datalab.to) | 35.6k | Naukowe pliki PDF, arXiv, formuły | Wysoka (z GPU) | GPL-3.0 + Open Rail-M | | **MinerU** | \- | Dokumenty CJK (chiński/japoński) | Wysoka | Apache-2.0 | Marker podaje imponujące wyniki dokładności w testach porównawczych:

0.18 sekundy na stronę na GPU H100 (122 strony na sekundę). Dokładność 95.67% w porównaniu z Llamaparse (84.24%) i Mathpix (86.43%). W przypadku artykułów naukowych: 96.67%.

— datalab.to, https://github.com/datalab-to/marker
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?
Najważniejsze informacje Najwygodniejszym rozwiązaniem jest skrypt bash, który przegląda folder projektu, konwertuje wszystkie pliki PDF, DOCX i PPTX do Markdown i umieszcza je w podfolderze `_md/`. Skonfiguruj go raz, a każdy nowy folder dokumentów stanie się „czytelny dla Claude” po jednym przebiegu. Następnie dodaj `_md/` do Claude Code za pomocą `@_md/` i pracuj ze skompresowanym tekstem.
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: ```bash #!/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: ```bash chmod +x scripts/docs-to-md.sh ``` Uruchom go: ```bash 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: ```bash 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?
Najważniejsze informacje Konwersja do Markdown powoduje utratę trzech rzeczy: elementów wizualnych (diagramów, wykresów, planów), złożonych tabel z połączonymi komórkami i podpisami oraz pełnego formatowania dokumentu jako artefaktu (na przykład umowy, którą trzeba cytować, podając stronę). Jeśli mają one znaczenie dla zadania, zachowaj PDF, włącz analizę wizualną i świadomie zaakceptuj jej koszt.
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`.

Claude analizuje zarówno tekst, jak i obrazy, aby lepiej zrozumieć dokument.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
### 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?
Najważniejsze informacje Główne pułapki to ponowne przesyłanie tego samego PDF-a w różnych czatach zamiast jednorazowej konwersji, nieużywanie buforowania promptów przy powtarzanych zapytaniach, korzystanie ze zrzutów ekranu zamiast tekstu, brak OCR w skanowanych PDF-ach oraz ignorowanie limitu 100 stron w modelach z kontekstem 200K. Każdy z tych błędów bez powodu marnuje dziesiątki tysięcy tokenów.
### 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
Najważniejsze informacje Konwersja PDF-ów do Markdown to jedna z technik inżynierii kontekstu — nowej umiejętności pracy z AI. Prompt jest pytaniem. Kontekst to wszystko, co Claude widzi przed pytaniem i wokół niego: prompt systemowy, CLAUDE.md, pliki, serwery MCP i historia sesji. Im czystszy kontekst, tym dokładniejsza odpowiedź i niższy koszt. Przeczytaj pełną analizę w poradniku „Inżynieria kontekstu w 2026 roku”.
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](https://ailoot.ai/blog/pl/where-claude-code-tokens-go/) - 9 wzorców wycieku kontekstu, nie tylko PDF-y. - [Inżynieria kontekstu w 2026 roku](https://ailoot.ai/blog/pl/context-engineering/) - systematyczne zarządzanie kontekstem. - [Plan Mode w Claude Code](https://ailoot.ai/blog/pl/claude-code-plan-mode/) - tryb planowania używany przed rozpoczęciem pisania kodu przez Claude.
### Źródła - [Anthropic - obsługa PDF (platform.claude.com)](https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support) - [Anthropic - przesyłanie plików do Claude (support.claude.com)](https://support.claude.com/en/articles/8241126-upload-files-to-claude) - [Microsoft MarkItDown na GitHubie](https://github.com/microsoft/markitdown) - [Serwer MarkItDown MCP](https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp) - [PyMuPDF4LLM - oficjalna dokumentacja](https://pymupdf.readthedocs.io/en/latest/pymupdf4llm/) - [Docling na GitHubie (IBM Research)](https://github.com/DS4SD/docling) - [Marker na GitHubie (datalab.to)](https://github.com/datalab-to/marker)
Poznaj więcej możliwości Ailoot na stronie [ailoot.ai](https://ailoot.ai/).
## Pytania i odpowiedzi ### Ile tokenów Markdown zużywa przykład 15 stron i czterech czatów? Przy założeniu artykułu 300 tokenów na stronę po konwersji suma wynosi 15 × 300 × 4 = 18,000 tokenów wejścia. To ilustracyjne oszacowanie; dla własnego pliku policz tokeny przekonwertowanego dokumentu. ### Czy konwersja tekstowa wystarcza dla każdego PDF? Nie. Porównaj Markdown z PDF, zwłaszcza tabele, kolejność stron i treść zależną od obrazów. Zużycie tokenów porównuj dopiero po potwierdzeniu zachowania informacji potrzebnych zadaniu. ## Ailoot · Firma i jej portfel projektów Ailoot opiera się na zgromadzonym doświadczeniu operacyjnym, szerokiej bazie klientów, stabilnej usłudze i stałej kontroli KPI. Firma i jej portfel projektów: miliony klientów; miesięczna sprzedaż liczona w miliardach. Ailoot wykorzystuje to doświadczenie operacyjne, zapewniając dostęp przez API do funkcji AI w produktach klientów, agentach, aplikacjach i automatyzacjach.