PDF:t Claude Codessa: muuntaminen, tokenit ja rakenteen säilyttäminen

Mitä PDF:lle tapahtuu Claudessa, ja miksi jokainen sivu maksaa 1 500–3 000 tokenia?#

Anthropicin virallinen dokumentaatio kuvaa prosessin kolmessa yksinkertaisessa vaiheessa:

Tämä kuulostaa loogiselta, mutta käsittelykustannukset kasvavat lineaarisesti sivumäärän mukana. Tässä on luku, joka selittää, miksi tilauksesi käyttöraja loppuu yhden PDF:n takia:

Anthropic mittasi saman 3-sivuisen PDF:n Bedrockissa kahdella tavalla nähdäkseen, kuinka paljon tokeneita se vie. Tekstitilassa (Converse Document Chat) se käytti ~1 000 tokenia. Visuaalisessa analyysissä (Claude PDF Chat) se käytti ~7 000 tokenia. Kuvien lisääminen tekee käsittelystä 7 kertaa kalliimpaa.

Sivujen kuvakaappaukset ovat vielä pahempia. 1000×1000 pikselin kuvakaappaus maksaa noin 1 300 tokenia.

Mekanismi on yksinkertainen: PDF:t ovat kalliita, koska Claude ei luota OCR-tunnistukseensa. Se käyttää sekä tekstiä että kuvaa voidakseen vertailla niitä – ja maksat molemmista kerroksista yhtä aikaa. Suurten dokumenttien kanssa voit toimia toisin: tallenna tiedosto Markdown-muodossa projektikansioosi ja sano Claudelle: ”tässä on tietoa sisältävä dokumentti – jaa se osiin.” Claude jakaa sisällön omien tiedostojensa kesken ja jatkaa työskentelyä järjestetyn tekstin parissa kuluttamatta kaikkea kerralla.

Kuinka paljon PDF kuluttaa tavallisessa tehtävässä?#

Tarkat luvut (Sonnet 4.x -malli, syöte 3 $ miljoonaa tokenia kohden):

Tämä koskee vain yhtä neljän pyynnön kierrosta. Sen jälkeen käyttöön tulee promptien välimuisti (oletuksena 5 minuutin TTL, laajennetulla tasolla enintään 1 tunti ja enintään 90 % alennus toistuvista kutsuista aikaikkunan sisällä) – säästöt kasvavat.

Aina kun lataat saman PDF:n uuteen keskusteluun, Claude lukee sen uudelleen; välimuisti ei siirry keskustelusta toiseen.

Jos muunnat saman 15-sivuisen PDF:n kerran Markdowniksi ja tuot sen sitten kuhunkin neljään uuteen keskusteluun .md-tiedostona, esimerkki käyttää 15 × 300 × 4 = 18 000 syötetokenia 135 000:n sijaan. Muunnetun sivun 300 tokenia ja PDF-sivun 2 250 tokenia ovat laskelman oletuksia, eivät jokaiselle PDF:lle mitattuja vakioita. Laske oman asiakirjasi tokenit ja varmista muunnoksen laatu ennen säästön arviointia.

Tämä laskelma on vielä merkityksellisempi Claude Pro -tilauksella. Yksi 100-sivuinen raportti voi kuluttaa koko 5 tunnin käyttörajan. Markdown-muunnoksen jälkeen samaan budjettiin mahtuu yli 10 tällaista dokumenttia.

Mitkä ovat Anthropicin PDF-tiedostojen API-rajoitukset vuonna 2026?#

Anthropicin dokumentaatiossa rajat luetellaan heti alussa (tilanne 31. toukokuuta 2026):

Claude.ai-kuluttajasovelluksessa on eri rajat: enintään 500 Mt tiedostoa kohti ja enintään 20 tiedostoa keskustelussa. Visuaalinen analyysi toimii kuitenkin vain enintään 100-sivuisissa PDF-tiedostoissa – tätä pidemmissä Claude näkee vain tekstin, ei kaavioita tai kuvia.

PDF:n voi lähettää API:n kautta kolmella tavalla:

1. URL-osoitteella - "source": {"type": "url", "url": "..."} - yksinkertaisin tapa, kun dokumentti on verkossa.
2. Base64-muodossa - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - paikallisille tiedostoille.
3. Files API:n kautta - "source": {"type": "file", "file_id": "file_abc123"} - toistuviin pyyntöihin; vaatii beta-otsakkeen anthropic-beta: files-api-2025-04-14.

Files API on tärkein säästötapa, kun työskentelet saman PDF:n kanssa eri keskusteluissa. Lataa tiedosto kerran, hanki file_id ja käytä sitä kaikissa vuorovaikutuksissa. Kun käytössä on cache_control: ephemeral, toistuvat kutsut maksavat 10 % normaalihinnasta.

Anthropic neuvoo virallisesti myös käytön minimoimisessa:

Menetelmä 1: Miten MarkItDown otetaan käyttöön 5 minuutissa?#

MarkItDown on Microsoftin virallinen projekti, jota ylläpitää AutoGen-tiimi. GitHubissa sillä on 134 tuhatta tähteä ja 9,2 tuhatta forkia (toukokuun 2026 lopussa). README kuvaa sen tarkoituksen suoraan:

Tuetut tiedostomuodot:

• Dokumentit: PDF, DOCX, PPTX, XLSX
• Verkko: HTML, JSON, XML, CSV
• Media: ääni transkriptiolla, kuvat EXIF-tiedoilla ja OCR:llä, YouTube-videot (tekstitysten kautta)
• Arkistot: ZIP, EPub
• Muut: kaikki Outlook MSG -tiedostojen liitteet

Asennus

Vaatimus: Python 3.10+ (yleensä jo asennettuna macOS:ssä; Windowsissa se on asennettava erikseen).

pip install 'markitdown[all]'

Jos et tarvitse kaikkia tiedostomuotoja, voit asentaa vain valitut:

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

Yhden tiedoston muuntaminen

Yksinkertaisin tapaus:

markitdown document.pdf > document.md

Sen jälkeen document.md ilmestyy nykyiseen kansioon. Tuo se Claude Codeen komennolla @document.md tai sijoita se projektin viereen.

Python-rajapinta

Jos haluat integroida sen skriptiisi:

from markitdown import MarkItDown

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

# Voit tallentaa sen saman tien:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

Mitä MarkItDown EI osaa

• Skannattujen PDF-tiedostojen OCR - se ei palauta mitään. Skannaukset vaativat PyMuPDF4LLM:n tai Doclingin.
• Monimutkaiset, usean palstan asettelut - lukujärjestys voi mennä sekaisin.
• PDF-tiedostoihin upotetut URL-osoitteet - niitä ei säilytetä.

Yksinkertaisille PDF-tiedostoille (raportit, artikkelit, dokumentaatio) MarkItDown on paras valinta: monipuolinen työkalu, joka asentuu minuutissa eikä vaadi Python-osaamista. Sen toimintaa kyrillisellä tekstillä ja skannauksilla kuvaavat mittaukset analyysissä, jossa käsitellään PDF:n muuntamista tekstiksi tekoälyä varten.

Menetelmä 2: Mitä PyMuPDF4LLM tarjoaa, ja milloin se on parempi?#

MarkItDown tarjoaa laajan tiedostomuototuen; PyMuPDF4LLM tarjoaa syvällistä PDF-käsittelyä.

Versio 31. toukokuuta 2026 on 1.27.2.3 (julkaistu 24. huhtikuuta 2026).

Mitä sisältyy

• Monipalstaiset sivut oikeassa lukujärjestyksessä
• Taulukot muunnetaan GitHub-flavored Markdowniksi
• Ylä- ja alatunnisteet poistetaan automaattisesti
• Kuvat poimitaan erilliseen kansioon suhteellisten linkkien kanssa
• Älykäs OCR: käytetään vain lukukelvottomilla alueilla, mikä säästää ~50 % käsittelyajasta
• Natiivi C-moottori, GPU:ta ei tarvita

Asennus

pip install pymupdf4llm

Käyttö

import pymupdf4llm

# Peruskäyttö - suoraan Markdown-muotoon:
md_text = pymupdf4llm.to_markdown("document.pdf")

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

Yhdellä rivillä, kuten luvattiin:

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

Milloin kannattaa valita PyMuPDF4LLM MarkItDownin sijaan?

• Kun PDF sisältää paljon säilytettäviä linkkejä (MarkItDown kadottaa ne).
• Kun dokumentti on skannattu ja tarvitset OCR:ää.
• Kun käsittelet tuhansia tiedostoja paikallisesti ja tarvitset nopeutta – natiivi C-moottori on Python-kääreitä nopeampi.
• Kun tarvitset PDF:n kuvat erilliseen kansioon jatkokäsittelyä varten.

Lisenssin yksityiskohdat (tärkeää yrityksille)

PyMuPDF4LLM:llä on kaksoislisenssi: AGPL v3 TAI Artifex Commercial.

AGPL tarkoittaa: jos käytät kirjastoa julkisessa SaaS-palvelussa, koko palvelun lähdekoodi on julkaistava saman AGPL-lisenssin alaisena. Sisäisessä käytössä (esimerkiksi omalla kannettavallasi oleva skripti) ei ole rajoituksia.

Jos kehität kaupalliseen käyttöön paljastamatta koodia, osta lisenssi Artifexilta (artifex.com). Hintoja ei julkaista; pyydä ne myynnistä.

Jos rakennat tuotetta asiakkaille, tarkista lisenssi heti alussa. MarkItDown (MIT) ja Docling (MIT) ovat turvallisempia valintoja SaaS-palveluille.

Menetelmä 3: Miten MarkItDown MCP -palvelin yhdistetään Claude Codeen?#

MarkItDown CLI-tilassa tarkoittaa ”muunnan tiedostot käsin etukäteen”; MCP-palvelin tarkoittaa ”Claude Code päättää, milloin muunnos tehdään”.

Asennus

Tarvitset uv-pakettienhallinnan. Palvelinta ei tarvitse asentaa erikseen; uv lataa sen ensimmäisellä käynnistyskerralla.

Määritys Claude Codessa

Yksi komento yhdistää palvelimen kaikkiin projekteihisi kiinteällä versiolla:

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

markitdown-merkinnän pitäisi näyttää ”Connected”. Ensimmäinen käynnistys lataa noin seitsemänkymmentä pakettia ja kestää enintään minuutin; sen jälkeen palvelin käynnistyy sekunnissa tai kahdessa.

Kaksi muuttujaa tarvitaan seuraavista syistä. ORT_DISABLE_TELEMETRY=1 poistaa käytöstä tilastot, joita palvelimen sisäinen onnxruntime-moottori lähettää oletuksena Microsoftille Macissa ja Linuxissa. UV_PYTHON=3.12 käynnistää palvelimen Python 3.12:lla, jolle on saatavilla valmiiksi käännetyt paketit Windowsille, Linuxille ja Apple Silicon -Maceille. Intel-Maceissa ja macOS 13:ssa tai sitä vanhemmissa palvelin ei asennu Python 3.14:llä. Intelille ja 3.12:lle on yksi huomio: uv kääntää cryptography-kirjaston lähdekoodista, koska valmista Intel-pakettia ei ole ollut saatavilla kesäkuun 2026 jälkeen. Asennus kestää kauemmin ja voi epäonnistua. Jos Python 3.12 ei ole asennettuna, uv lataa sen puolestasi.

Palvelin toimii suoraan tietokoneellasi ja voi avata kaikki tiedostot, joihin sinulla on käyttöoikeus. Jos Claude Code oli auki, käynnistä se uudelleen; markitdown ilmestyy MCP-palvelinten luetteloon.

Käyttö

Sano Claude Codessa esimerkiksi:

Muunna /Users/your-user/Documents/report.pdf Markdown-muotoon ja analysoi pääkohdat.

Claude kutsuu itse convert_to_markdown(uri)-työkalua, saa Markdownin ja työskentelee sen kanssa – PDF:ää ei ladata lainkaan kontekstiin.

Tuetut URI:t

• file:// - paikalliset tiedostot
• http://, https:// - verkossa olevat dokumentit
• data: - sisäiset tiedot (Base64)

Tietoturva

Virallisesta README-tiedostosta:

Oletuksena se on sidottu localhost-osoitteeseen. Jos suoritat sen HTTP/SSE:n kautta (valinnalla --http --host 127.0.0.1 --port 3001), älä avaa porttia ulkoisesti ilman tunnistautumista vaativaa käänteistä välityspalvelinta.

Minkä menetelmän valitset tehtävääsi?#

Laajennettu vertailutaulukko:

Marker ilmoittaa vaikuttavia tarkkuuslukuja vertailutesteissä:

Marker vaatii kuitenkin GPU:n ollakseen nopea, ja se tuo mukanaan koneoppimismalleja. Useimpiin tehtäviin (tavalliset tekstipohjaiset PDF:t) PyMuPDF4LLM tai MarkItDown hoitaa työn muutamassa sekunnissa ilman GPU:ta.

Yksinkertainen valintasääntö

1. Yksi tai kaksi PDF:ää, tarvitaan nopeasti - MarkItDown CLI.
2. Kymmeniä PDF:iä, tarvitaan automaatiota - MarkItDown MCP -palvelin tai PyMuPDF4LLM-skriptissä.
3. PDF:t, joissa on säilytettäviä linkkejä ja kuvia ja joiden rakenne on tärkeä - PyMuPDF4LLM.
4. Yrityksen tuotannon RAG, jossa taulukoiden vakaus on tärkeää - Docling.
5. Tieteelliset artikkelit, joissa on kaavoja - Marker.
6. Et halua miettiä asiaa; anna Clauden muuntaa - MarkItDown MCP -palvelin.

Miten kirjoitat valmiin skriptin, joka muuntaa asiakirjakansion automaattisesti?#

Käytännön esimerkki: kuvittele, että yhdessä kansiossa on 40 asiakkaiden PDF- ja PPTX-raporttia – välitysliikkeiden tiliotteita, sopimuksia ja esityksiä. Koko kansion lataaminen suoraan Claudeen ei auta: konteksti-ikkuna täyttyy tiedoista ennen ensimmäistä vastausta. Aja koko kansio alla olevalla skriptillä kerralla ja jatka sen jälkeen kevyiden .md-tiedostojen käsittelyä raskaiden PDF:ien sijaan.

Tallenna tämä skripti projektin juureen nimellä scripts/docs-to-md.sh:

#!/bin/bash
# docs-to-md.sh - muuntaa kaikki kansion asiakirjat Markdown-muotoon MarkItDownilla
# Käyttö: bash docs-to-md.sh ./documents

set -e

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

mkdir -p "$OUTPUT_DIR"

echo "Scanning $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 "Skipping $basename (already converted)"
    continue
  fi

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

echo "Done. Results are in $OUTPUT_DIR"

Tee siitä suoritettava:

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

Suorita se:

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

Ajokerran jälkeen ./reports/_md/ sisältää kaikkien dokumenttien .md-versiot. Tuo ne Claude Codeen komennolla @reports/_md/ ja työskentele pakatun tekstin kanssa PDF:ien sijaan.

Skripti ohittaa automaattisesti jo muunnetut tiedostot (jos .md-tiedosto on lähdetiedostoa uudempi) – sen uudelleenajo on nopeaa eikä kaikkea tarvitse käsitellä uudestaan.

Idempotenssi ja inkrementaalinen muuntaminen

Jos haluat skriptin tunnistavan PDF:t, joita on muutettu (tallennettu uudelleen samalla nimellä), lisää sisältötiivisteen tarkistus:

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

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "Skipping $basename (hash matches)"
  continue
fi

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

Tämä versio muuntaa tiedoston uudelleen vain, jos sen sisältö on muuttunut.

Milloin PDF on Claudessa edelleen parempi kuin Markdown?#

Kolme tilannetta, joissa Markdown-muunnos ei riitä:

1. Kaavioiden ja graafien visuaalinen analyysi

Jos Clauden pitää ”lukea” kaaviota – hintakäyrää, prosessikaaviota tai arkkitehtuurikaaviota – tieto ei ole Markdownissa. Markdown säilyttää vain kuvatekstit; itse kuva katoaa.

Ratkaisu: lataa PDF ja ota visuaalinen tila erikseen käyttöön. Claude API:ssa lippu toimii automaattisesti; AWS Bedrockissa tarvitset citations-lipun.

2. Monimutkaiset taulukot, joissa on yhdistettyjä soluja

Markdown-taulukot ovat litteitä. Jos PDF:ssä on yhdistettyjä soluja, monitasoisia otsikoita tai sisäkkäisiä alitaulukoita, muunnin joko litistää taulukon tai kadottaa sen suhteet.

Ratkaisu: käytä PDF:ää suoraan, käytä Doclingia (se käsittelee monimutkaiset taulukot parhaiten) tai muotoile taulukko käsin muunnoksen jälkeen.

3. Dokumentit artefakteina ja sivuviittaukset

Oikeudellisissa asiakirjoissa, sopimuksissa ja pöytäkirjoissa on tärkeää voida viitata kohtaan ”sivu 7, kappale 3”. Sivunumerot katoavat Markdownissa.

Ratkaisu: PDF + Files API + promptien välimuisti. Lataa dokumentti kerran ja viittaa siihen sitten file_id-tunnisteella; Claude näkee sivunumeroinnin ja voi viitata tiettyihin sivuihin.

Lyhyet dokumentit

Jos PDF on alle 2 sivua ja käytät sitä kerran, muuntaminen ei kannata. PDF:n 5 000 tokenia verrattuna Markdownin 800 tokeniin ei tuota riittävästi säästöä MarkItDownin asennuksen perustelemiseksi.

Kannattavuusraja on noin 5+ sivua tai 2+ käyttökertaa samalle dokumentille. Tätä pienemmät tiedostot kannattaa ladata suoraan PDF:nä; tätä suuremmat kannattaa muuntaa.

Mitkä ovat 5 yleisintä virhettä, joita ihmiset tekevät Clauden PDF-tiedostojen kanssa?#

1. Saman PDF:n lataaminen uuteen keskusteluun joka kerta

Claude Prolla on viiden tunnin viestiraja – yksi 50-sivuinen raportti voi kuluttaa sen loppuun ennen kuin ehdit esittää toista kysymystä.

Tähän on yksinkertainen periaate: yksi tehtävä – yksi keskustelu. Kun tekoäly alkaa kuluttaa kohtuuttoman paljon tokeneita, syynä on se, että yrität mahduttaa kaiken yhteen keskusteluun ja tuot PDF:n mukaan yhä uudelleen. Pidä jokaisessa ikkunassa yksi mikrotehtävä. Muunna dokumentti Markdowniksi kerran ja lisää .md-tiedosto jokaiseen uuteen ikkunaan projektin rinnalle. Konteksti-ikkunan ympyrä ei muutu keltaiseksi.

Ratkaisu: muunna se Markdowniksi kerran tai käytä Files API:a file_id-tunnisteen ja promptien välimuistin kanssa.

2. Kuvakaappaus tekstin sijaan

Tyypillinen esimerkki: joku haluaa näyttää Claudelle koodinpätkän tai taulukon, ottaa kuvakaappauksen koko 1920×1080-näytöstä ja ihmettelee, miksi käyttöraja tuli vastaan viiden pyynnön jälkeen.

1000×1000 pikselin kuvakaappaus maksaa ~1 300 tokenia. Sama käsin kopioitu teksti maksaa 50–100 tokenia. Ero on 13–26-kertainen.

Ratkaisu: rajaa kuvakaappaukset tiukasti vain tärkeään kohtaan tai, mikä vielä parempi, kopioi teksti suoraan.

3. Skannattu PDF ilman OCR:ää

MarkItDown ei osaa OCR:ää. Jos muunnat skannauksen, tuloksena on tyhjä .md-tiedosto (tai kolme riviä kohinaa).

Ratkaisu: käytä skannauksiin PyMuPDF4LLM:ää (jossa on sisäänrakennettu älykäs OCR) tai Doclingia.

4. 100 sivun rajan sivuuttaminen

Anthropicin dokumentaatiossa pyyntökohtaiseksi rajaksi annetaan 600 sivua – käytännössä 200K-kontekstia käyttävien mallien (Sonnet 4.x, Opus 4.x) raja on kuitenkin 100 sivua. 600 sivun raja on tarkoitettu vanhemmille malleille tai erityistasoille.

Jos lataat 150-sivuisen raportin Sonnet 4.6:een, saat virheen tai, mikä pahempaa, Claude käsittelee vain ensimmäiset 100 sivua ja toimii kuin olisi lukenut koko dokumentin.

Ratkaisu: jaa pitkät PDF:t osiin ennen lataamista. Tai muunna ne Markdowniksi – sivurajaa ei ole, vain tokenraja.

5. Promptien välimuistin käyttämättä jättäminen toistuvissa pyynnöissä

Jos käsittelet samaa dokumenttia API:n kautta, lisää se kenttään cache_control: ephemeral. Viiden minuutin sisällä toistetut kutsut maksavat 10 % alkuperäisestä hinnasta. Ensimmäinen pyyntö maksaa enemmän; loput saavat 90 % alennuksen.

Ratkaisu: ota promptien välimuisti oletusarvoisesti käyttöön kaikelle, jonka lataat useammin kuin kerran.

Mitä seuraavaksi: kontekstisuunnittelu#

PDF:n muuntaminen Markdowniksi on yksi tapa säästää tokeneita. Se ei yksinään tee Clauden vastauksista tarkempia. Tarkkuus syntyy kontekstisuunnittelusta – siitä, mitä mallin kontekstiin lisätään ennen kysymyksen esittämistä.

Jos CLAUDE.md-tiedostossasi on 800 riviä, projektissasi on 10 tarpeetonta MCP-palvelinta ja tuot mukaan 100-sivuisen PDF:n, Markdown-muunnos estää yhden vuodon, mutta kolme muuta jäävät jäljelle. Siksi näissä oppaissa käsitellään seuraavia aiheita:

• Mihin tokenit kuluvat Claude Codessa - 9 kontekstivuodon mallia, eivätkä vain PDF:t.
• Kontekstisuunnittelu vuonna 2026 - järjestelmällinen kontekstinhallinta.
• Plan Mode Claude Codessa - suunnittelutila ennen kuin Claude alkaa kirjoittaa koodia.