PDF failai Claude Code aplinkoje: konvertavimas, tokenai ir struktūros išsaugojimas

Kas nutinka PDF failui Claude aplinkoje ir kodėl kiekvienas puslapis kainuoja 1 500–3 000 tokenų?#

Oficialioje Anthropic dokumentacijoje procesas aprašytas trimis aiškiais žingsniais:

Skamba logiškai, tačiau apdorojimo sąnaudos auga tiesiškai didėjant puslapių skaičiui. O štai skaičius, paaiškinantis, kodėl vienas PDF failas išeikvoja jūsų prenumeratos limitą:

Kad suprastume, kiek tai yra, Anthropic išbandė tą patį 3 puslapių PDF failą sistemoje Bedrock dviem režimais. Tekstiniu režimu (Converse Document Chat) sunaudota ~1 000 tokenų. Naudojant vaizdinę analizę (Claude PDF Chat) — ~7 000 tokenų. Įtraukus vaizdus, apdorojimas kainuoja 7 kartus daugiau.

Puslapių ekrano kopijos kainuoja dar daugiau. 1 000×1 000 pikselių ekrano kopija kainuoja apie 1 300 tokenų.

Mechanizmas paprastas: PDF failai brangūs, nes Claude nepasitiki savo OCR. Jis naudoja ir tekstą, ir vaizdą, kad galėtų juos palyginti, o jūs vienu metu mokate už abu sluoksnius. Dideliems dokumentams galima rinktis kitą būdą: išsaugokite failą Markdown formatu savo projekto aplanke ir pasakykite Claude: „štai dokumentas su informacija — išdėstyk ją“. Jis paskirstys turinį savo failuose ir toliau dirbs su sutvarkytu tekstu, užuot sunaudojęs visą informaciją iš karto.

Kiek tokenų sunaudoja PDF įprastoje užduotyje?#

Tikslūs skaičiai (Sonnet 4.x modelis, įvestis kainuoja 3 USD už milijoną tokenų):

Tai tik vienas 4 užklausų ciklas. Vėliau pradeda veikti užklausų podėlis (numatytasis TTL yra 5 minutės, išplėstiniame plane — iki 1 valandos, o pakartotinės užklausos per šį laikotarpį kainuoja iki 90 % mažiau), todėl sutaupoma dar daugiau.

Kaskart įkėlus tą patį PDF naujame pokalbyje, Claude perskaito jį iš naujo; podėlio turinys tarp pokalbių neišsaugomas.

Jei tą patį 15 puslapių PDF vieną kartą konvertuosite į Markdown ir pridėsite kaip .md į kiekvieną iš keturių naujų pokalbių, šiame pavyzdyje sunaudosite 15 × 300 × 4 = 18 000 įvesties tokenų vietoj 135 000. 300 tokenų vienam konvertuotam puslapiui ir 2 250 vienam PDF puslapiui yra šio skaičiavimo prielaidos, o ne išmatuotos konstantos visiems PDF. Prieš vertindami sutaupymą suskaičiuokite tikrą dokumentą ir patvirtinkite konvertavimo kokybę.

Šis skaičiavimas dar reikšmingesnis turint Claude Pro prenumeratą. Viena 100 puslapių ataskaita gali išeikvoti visą 5 valandų limitą. Konvertavus į Markdown, į tą patį biudžetą telpa daugiau nei 10 tokių dokumentų.

Kokie yra Anthropic API PDF apribojimai 2026 m.?#

Anthropic dokumentacijoje apribojimai išvardyti pačioje pradžioje (duomenys galiojo 2026 m. gegužės 31 d.):

Claude.ai (vartotojams skirtoje žiniatinklio programoje) taikomi kitokie apribojimai: vienas failas gali būti iki 500 MB, o pokalbyje galima naudoti iki 20 failų. Tačiau vaizdinė analizė veikia tik su iki 100 puslapių PDF failais — ilgesniuose Claude mato tik tekstą, be diagramų ir grafikų.

PDF pateikimo per API būdai:

1. Per URL - "source": {"type": "url", "url": "..."} - paprasčiausia, kai dokumentas pasiekiamas internete.
2. Base64 formatu - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - vietiniams failams.
3. Per Files API - "source": {"type": "file", "file_id": "file_abc123"} - pakartotinėms užklausoms; būtina beta antraštė anthropic-beta: files-api-2025-04-14.

Files API yra pagrindinis būdas sutaupyti dirbant su tuo pačiu PDF skirtinguose pokalbiuose. Įkelkite jį vieną kartą, gaukite file_id, o tada naudokite jį visose sąveikose. Nustačius cache_control: ephemeral, pakartotinės užklausos kainuoja 10 % įprastos kainos.

Anthropic taip pat pateikia oficialių patarimų, kaip sumažinti sąnaudas:

1 metodas: kaip per 5 minutes nustatyti MarkItDown?#

MarkItDown yra oficialus Microsoft projektas, kurį prižiūri AutoGen komanda. GitHub platformoje jis turi 134 tūkst. žvaigždučių ir 9,2 tūkst. šakojimų (2026 m. gegužės pabaigos duomenimis). Jo paskirtis tiesiogiai aprašyta README faile:

Palaikomi formatai:

• Dokumentai: PDF, DOCX, PPTX, XLSX
• Žiniatinklis: HTML, JSON, XML, CSV
• Medija: garso įrašai su transkripcija, vaizdai su EXIF ir OCR, YouTube vaizdo įrašai (naudojant subtitrus)
• Archyvai: ZIP, EPub
• Kita: visi Outlook MSG failuose esantys priedai

Diegimas

Reikalavimas: Python 3.10+ (macOS sistemoje jis paprastai jau įdiegtas; Windows sistemoje reikia įdiegti atskirai).

pip install 'markitdown[all]'

Jei nereikia visų formatų, galima įdiegti tik pasirinktus:

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

Vieno failo konvertavimas

Paprasčiausias atvejis:

markitdown document.pdf > document.md

Po to dabartiniame aplanke atsiras document.md. Įkelkite jį į Claude Code naudodami @document.md arba tiesiog padėkite šalia projekto.

Python API

Jei norite integruoti į savo scenarijų:

from markitdown import MarkItDown

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

# You can save it straight away:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

Ko MarkItDown NEGALI

• Atlikti nuskenuotų PDF failų OCR — jis nieko negrąžina. Nuskenuotiems failams reikia PyMuPDF4LLM arba Docling.
• Išsaugoti sudėtingo kelių stulpelių išdėstymo — gali būti sumaišyta skaitymo tvarka.
• Išsaugoti PDF failuose esančių URL — jų neišsaugo.

Paprastiems PDF failams (ataskaitoms, straipsniams, dokumentacijai) MarkItDown yra geriausias pasirinkimas: universalus įrankis, įdiegiamas per minutę ir nereikalaujantis Python žinių. Jo veikimas su dokumentais, kuriuose yra kirilicos teksto ir nuskenuotų puslapių, parodytas analizėje apie tai, kaip konvertuoti PDF į tekstą, skirtą DI.

2 metodas: ką siūlo PyMuPDF4LLM ir kada jis geresnis?#

MarkItDown pasižymi formatų įvairove, o PyMuPDF4LLM — PDF apdorojimo išsamumu.

2026 m. gegužės 31 d. versija yra 1.27.2.3 (išleista 2026 m. balandžio 24 d.).

Kas įtraukta

• Kelių stulpelių puslapiai su taisyklinga skaitymo tvarka
• Lentelės konvertuojamos į GitHub pritaikytą Markdown formatą
• Antraštės ir poraštės pašalinamos automatiškai
• Vaizdai ištraukiami ir susiejami santykinėmis nuorodomis atskirame aplanke
• Išmanusis OCR: taikomas tik neįskaitomoms sritims, sutaupant ~50 % apdorojimo laiko
• Savuoju C varikliu, GPU nereikia

Diegimas

pip install pymupdf4llm

Naudojimas

import pymupdf4llm

# Basic use - straight to Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

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

Vienos eilutės komanda, kaip žadėta:

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

Kada rinktis PyMuPDF4LLM, o ne MarkItDown

• Kai PDF faile yra daug nuorodų, kurias reikia išsaugoti (MarkItDown jas praranda).
• Kai dokumentas nuskenuotas ir reikia OCR.
• Kai tūkstančius failų reikia greitai apdoroti vietoje — savasis C variklis veikia greičiau už Python apvalkalus.
• Kai reikia iš PDF failo išgauti vaizdus ir sudėti juos į atskirą aplanką tolesniam apdorojimui.

Licencijos detalės (svarbu verslui)

PyMuPDF4LLM turi dvigubą licenciją: AGPL v3 ARBA komercinė Artifex licencija.

AGPL reiškia: jei biblioteką naudojate viešame SaaS, turite paskelbti visą savo paslaugos pirminį kodą su ta pačia AGPL licencija. Naudojant viduje (pavyzdžiui, paleidžiant scenarijų savo nešiojamajame kompiuteryje), apribojimų nėra.

Norėdami kurti komercinius produktus neatskleisdami kodo, įsigykite licenciją iš Artifex (artifex.com). Kainos viešai neskelbiamos — jų teiraukitės pardavimo skyriaus.

Jei kuriate produktą klientams, licenciją patikrinkite iš anksto. SaaS projektams saugiau rinktis MarkItDown (MIT) arba Docling (MIT).

3 metodas: kaip prijungti MarkItDown MCP serverį prie Claude Code?#

MarkItDown CLI režimas reiškia „failus iš anksto konvertuoju rankiniu būdu“, o MCP serveris — „Claude Code pats nusprendžia, kada konvertuoti“.

Diegimas

Reikalinga uv paketų tvarkyklė. Serverio atskirai diegti nereikia; pirmą kartą paleidžiant uv jį atsisiunčia.

Konfigūravimas Claude Code aplinkoje

Viena komanda prijungia serverį prie visų jūsų projektų ir užfiksuoja jo versiją:

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

Prie markitdown įrašo turėtų būti rodoma „Connected“. Pirmą kartą paleidus atsisiunčiama apie septyniasdešimt paketų, tai trunka iki minutės; vėliau serveris paleidžiamas per sekundę ar dvi.

Štai kodėl komandai reikalingi abu kintamieji. ORT_DISABLE_TELEMETRY=1 išjungia statistiką, kurią serverio viduje veikiantis onnxruntime variklis pagal numatytuosius nustatymus siunčia Microsoft sistemose Mac ir Linux. UV_PYTHON=3.12 paleidžia serverį Python 3.12 aplinkoje, kuriai yra paruošti paketai, skirti Windows, Linux ir Apple Silicon turintiems Mac kompiuteriams. Intel Mac kompiuteriuose ir macOS 13 bei ankstesnėse versijose serveris neįdiegiamas naudojant Python 3.14. Intel kompiuteriams ir Python 3.12 yra viena išlyga: uv sukurs cryptography biblioteką iš šaltinio kodo, nes nuo 2026 m. birželio Intel sistemoms nebėra paruoštų paketų. Diegimas trunka ilgiau ir gali nepavykti. Jei neturite Python 3.12, uv jį atsisiųs už jus.

Serveris veikia tiesiai jūsų kompiuteryje ir gali atidaryti visus failus, prie kurių turite prieigą. Jei Claude Code buvo atidarytas, paleiskite jį iš naujo — MCP serverių sąraše atsiras markitdown.

Kaip naudoti

Claude Code tiesiog pasakykite:

Konvertuokite /Users/your-user/Documents/report.pdf į Markdown ir išanalizuokite pagrindines mintis.

Claude pats iškviečia convert_to_markdown(uri), gauna Markdown tekstą ir dirba su juo — PDF į kontekstą visai neįkeliamas.

Palaikomi URI

• file:// - vietiniai failai
• http://, https:// - internetiniai dokumentai
• data: - įterptieji duomenys (Base64)

Sauga

Iš oficialaus README:

Pagal numatytuosius nustatymus jis susiejamas su localhost. Jei paleidžiate jį per HTTP/SSE (parinktis --http --host 127.0.0.1 --port 3001), neatverkite prievado išoriniam tinklui be autentifikuoto atvirkštinio tarpinio serverio.

Kurį metodą rinktis savo užduočiai?#

Išplėstinė palyginimo lentelė:

Marker pateikia įspūdingus tikslumo etalonų skaičius:

Tačiau norint, kad Marker veiktų greitai, reikia GPU, be to, kartu naudojami mašininio mokymosi modeliai. Daugumai užduočių (įprastiems tekstiniams PDF failams) PyMuPDF4LLM arba MarkItDown darbą atliks per kelias sekundes ir be GPU.

Paprasta pasirinkimo taisyklė

1. Vienas ar du PDF failai, reikia greitai - MarkItDown CLI.
2. Dešimtys PDF failų, reikia automatizuoti - MarkItDown MCP serveris arba PyMuPDF4LLM scenarijuje.
3. PDF failai su nuorodomis ir vaizdais, kai svarbu išsaugoti struktūrą - PyMuPDF4LLM.
4. Produkcinei RAG verslui, kai svarbus lentelių stabilumas - Docling.
5. Moksliniai straipsniai su formulėmis - Marker.
6. Nenorite apie tai galvoti ir norite, kad Claude pats konvertuotų - MarkItDown MCP serveris.

Kaip parašyti paruoštą naudoti scenarijų, kuris automatiškai konvertuoja dokumentų aplanką?#

Praktinis pavyzdys: įsivaizduokite, kad viename aplanke turite 40 klientų PDF ir PPTX ataskaitų — tarpininkavimo sąskaitų išrašų, sutarčių, pristatymų. Įkelti visą aplanką tiesiai į Claude beprasmiška: konteksto langas prisipildys informacijos dar prieš pirmąjį atsakymą. Vienu veiksmu paleiskite toliau pateikiamą scenarijų visam aplankui, o tada dirbkite su lengvais .md failais vietoj didelių PDF.

Išsaugokite šį scenarijų kaip scripts/docs-to-md.sh projekto šakniniame aplanke:

#!/bin/bash
# docs-to-md.sh - konvertuoja visus aplanke esančius dokumentus į Markdown naudodamas MarkItDown
# Usage: bash docs-to-md.sh ./documents

set -e

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

mkdir -p "$OUTPUT_DIR"

echo "Nuskaitomas aplankas $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 "Praleidžiama $basename (jau konvertuotas)"
    continue
  fi

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

echo "Atlikta. Rezultatai pateikti aplanke $OUTPUT_DIR"

Suteikite vykdymo teises:

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

Paleiskite:

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

Paleidus, ./reports/_md/ bus .md versijos visų dokumentų. Įkelkite juos į Claude Code naudodami @reports/_md/ ir dirbkite su glaustesniu tekstu vietoj PDF failų.

Scenarijus automatiškai praleidžia jau konvertuotus failus (jei .md failas naujesnis už šaltinio failą), todėl jį galima paleisti iš naujo be didelių sąnaudų — nereikia visko konvertuoti iš naujo.

Idempotentiškumas ir prieauginis konvertavimas

Jei norite, kad scenarijus aptiktų pakeistus PDF failus (iš naujo išsaugotus tuo pačiu pavadinimu), pridėkite turinio maišos patikrą:

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

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "Praleidžiama $basename (maiša sutampa)"
  continue
fi

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

Ši versija konvertuoja failą iš naujo tik tuo atveju, jei pasikeitė jo turinys.

Kada PDF Claude aplinkoje vis dar geresnis už Markdown?#

Trys atvejai, kai Markdown konvertavimo nepakanka:

1. Diagramų ir grafikų vaizdinė analizė

Jei Claude reikia „perskaityti“ grafiką — kainų kreivę, proceso diagramą ar architektūros schemą, — Markdown formate šios informacijos nėra. Markdown išsaugo tik paveikslų antraštes, o pats paveikslas prarandamas.

Sprendimas: įkelkite PDF failą ir aiškiai įjunkite vaizdinį režimą. Claude API ši parinktis veikia automatiškai, o AWS Bedrock reikia citations vėliavėlės.

2. Sudėtingos lentelės su sujungtais langeliais

Markdown lentelės yra plokščios. Jei PDF faile yra lentelė su sujungtais langeliais, kelių lygių antraštėmis arba įdėtinėmis lentelėmis, konverteris ją arba suplokštins, arba praras ryšius.

Sprendimas: naudokite PDF tiesiogiai, rinkitės Docling (jis geriausiai apdoroja sudėtingas lenteles) arba po konvertavimo suformatuokite lentelę rankiniu būdu.

3. Dokumentai kaip artefaktai su puslapių nuorodomis

Teisiniuose dokumentuose, sutartyse ir protokoluose svarbu cituoti, pavyzdžiui, „7 puslapis, 3 pastraipa“. Markdown formate puslapių numeriai prarandami.

Sprendimas: PDF + Files API + užklausų podėlis. Įkelkite failą vieną kartą ir paskui nurodykite jį pagal file_id; Claude matys puslapių numeraciją ir galės cituoti konkrečius puslapius.

Trumpi dokumentai

Jei PDF failas trumpesnis nei 2 puslapiai ir naudojate jį vieną kartą, konvertuoti neverta. PDF failui reikia 5 000 tokenų, o Markdown — 800, tad sutaupymas per mažas, kad būtų verta diegti MarkItDown.

Lūžio taškas — maždaug 5 ar daugiau puslapių arba 2 ar daugiau to paties dokumento panaudojimų. Mažesniems dokumentams įkelkite PDF tiesiogiai, didesnius konvertuokite.

Kokias 5 dažniausias klaidas žmonės daro naudodami PDF Claude aplinkoje?#

1. Kaskart įkeliamas tas pats PDF naujame pokalbyje

Claude Pro per 5 valandas taikomas pranešimų limitas — viena 50 puslapių ataskaita gali jį išeikvoti dar prieš užduodant antrą klausimą.

Tam galioja paprastas principas: viena užduotis — vienas pokalbis. Kai DI pradeda vartoti absurdiškai daug tokenų, vadinasi, į vieną pokalbį talpinate viską ir vis iš naujo įkeliate PDF failą. Kiekviename lange apsiribokite viena nedidele užduotimi. Vieną kartą konvertuokite dokumentą į Markdown, tada pridėkite .md failą prie kiekvieno naujo lango kartu su projektu. Konteksto lango apskritimas nepagels.

Sprendimas: vieną kartą konvertuokite jį į Markdown arba naudokite Files API su file_id ir užklausų podėliu.

2. Ekrano kopija vietoj teksto

Įprastas pavyzdys: kas nors nori parodyti Claude kodo fragmentą arba lentelę, padaro viso 1920×1080 ekrano ekrano kopiją ir stebisi, kodėl limitas pasibaigė po 5 užklausų.

1 000×1 000 pikselių ekrano kopija kainuoja ~1 300 tokenų. Tą patį tekstą nukopijavus rankiniu būdu, kainuoja 50–100 tokenų. Skirtumas — nuo 13 iki 26 kartų.

Sprendimas: glaudžiai apkarpykite ekrano kopijas, palikdami tik svarbią dalį, arba dar geriau — nukopijuokite tekstą tiesiogiai.

3. Nuskenuotas PDF be OCR

MarkItDown negali atlikti OCR. Konvertavus nuskenuotą failą, gaunamas tuščias .md failas (arba 3 eilutės triukšmo).

Sprendimas: nuskenuotiems failams naudokite PyMuPDF4LLM (su įtaisytuoju išmaniuoju OCR) arba Docling.

4. Nepaisoma 100 puslapių riba

Anthropic dokumentacijoje nurodyta 600 puslapių riba vienai užklausai, tačiau praktiškai modeliams su 200K kontekstu (Sonnet 4.x, Opus 4.x) riba yra 100 puslapių. 600 puslapių riba skirta senesniems modeliams arba specialiems planams.

Įkėlus 150 puslapių ataskaitą į Sonnet 4.6, gausite klaidą arba, dar blogiau, Claude apdoros tik pirmuosius 100 puslapių ir elgsis taip, lyg būtų perskaitęs visą dokumentą.

Sprendimas: prieš įkeldami suskaidykite ilgus PDF failus į dalis. Arba konvertuokite juos į Markdown — puslapių limito nėra, tik tokenų limitas.

5. Pakartotinėms užklausoms nenaudojamas užklausų podėlis

Jei per API dirbate su tuo pačiu dokumentu, apgaubkite jį cache_control: ephemeral. Per 5 minutes pateiktos pakartotinės užklausos kainuoja 10 % pradinės kainos. Viena užklausa kainuoja daugiau, o kitoms taikoma 90 % nuolaida.

Sprendimas: pagal numatytuosius nustatymus įjunkite užklausų podėlį viskam, ką įkeliate daugiau nei vieną kartą.

Kas toliau: konteksto inžinerija#

PDF konvertavimas į Markdown yra vienas iš būdų sutaupyti tokenų. Tačiau pats savaime jis nepadaro Claude atsakymų tikslesnių. Tikslumą užtikrina konteksto inžinerija — disciplina, apibrėžianti, ką įtraukiate į modelio kontekstą prieš užduodami klausimą.

Jei jūsų CLAUDE.md yra 800 eilučių, projekte veikia 10 nereikalingų MCP serverių ir įtraukiate 100 puslapių PDF, konvertavę į Markdown pašalinsite vieną sąnaudų šaltinį, tačiau kiti trys liks. Todėl šiuose vadovuose aptariama:

• Kur dingsta Claude Code tokenai - 9 konteksto nutekėjimo atvejai, ne vien PDF failai.
• Konteksto inžinerija 2026 m. - sistemingas konteksto valdymas.
• Planavimo režimas Claude Code aplinkoje - planavimo režimas, naudojamas prieš Claude pradedant rašyti kodą.