Convertire un PDF in Markdown per risparmiare token LLM: la guida a MarkItDown

Trascini un PDF di 20 pagine dentro Claude, fai una domanda e la risposta arriva senza problemi. Quello che non vedi è il conto. Prima ancora che la tua domanda venga letta, quel documento può inghiottire decine di migliaia di token. Fallo qualche volta al giorno su scala di un intero team e finisci per pagare soldi veri per riversare PDF grezzi dentro un modello che si sarebbe accontentato benissimo di testo pulito.

Esiste una soluzione gratuita, ed è stata lì alla portata di tutti fin dall'inizio. Converti prima il file in Markdown. Questa guida spiega con precisione perché i PDF costano così tanto, quanto risparmi e come fare la conversione con un solo comando usando MarkItDown, il convertitore open source di Microsoft.

Perché un PDF costa così tanti token

Ecco la parte che nessuno ti racconta. Quando passi un PDF a un LLM, non viene letto come lo leggi tu. Secondo la documentazione PDF ufficiale di Anthropic, il sistema fa due cose per ogni singola pagina:

1. Estrae il testo dalla pagina.
2. Converte l'intera pagina in immagine, poi invia quell'immagine insieme al testo.

È questo secondo passaggio il pozzo di token silenzioso. Il modello non legge soltanto delle parole, guarda anche una foto di ogni pagina per poter capire grafici, tabelle e impaginazione. Paghi entrambe le cose.

I numeri di Anthropic rendono il costo concreto. Il solo testo estratto si aggira tra i 1.500 e i 3.000 token a pagina a seconda della densità. A questo si aggiunge il costo di un'immagine per ogni pagina. Un dato eloquente, dall'integrazione con Amazon Bedrock: la modalità PDF visivo completa usa circa 7.000 token per un PDF di 3 pagine, mentre la semplice estrazione del testo delle stesse tre pagine usa circa 1.000 token. È un fattore 7, e dipende interamente dalle immagini pagina per pagina.

Riporta tutto questo a un documento reale. Un report denso di 20 pagine può collocarsi ovunque tra i 40.000 e i 70.000 token una volta che ogni pagina è stata trasformata in immagine. Non hai ancora chiesto niente. Hai semplicemente aperto il file.

Il blocco rosso-arancio è puro sovraccarico: un'immagine per ogni pagina, che la pagina contenga o meno qualcosa di visivo che valga la pena vedere.

La soluzione: dai in pasto Markdown pulito al suo posto

La maggior parte dei documenti non ha bisogno di essere vista. Un contratto, una specifica tecnica, un paper di ricerca, una presentazione piena di elenchi puntati: tutto questo è testo travestito da impaginazione. Se togli l'impaginazione e tieni la struttura, il modello non perde nulla di ciò che gli serviva davvero.

È esattamente quello che ti offre il Markdown. È vicino al testo puro quanto può esserlo un formato, eppure codifica ancora la struttura che conta: titoli, elenchi, tabelle, link, blocchi di codice, grassetto ed enfasi. Gli LLM mainstream sono addestrati su enormi quantità di Markdown, quindi lo interpretano in modo nativo e senza alcuno sforzo. Microsoft, che sviluppa MarkItDown, lo dice senza giri di parole: il Markdown è "estremamente vicino al testo puro, con un markup o una formattazione minimi, ma offre comunque un modo per rappresentare la struttura importante di un documento".

Converti il tuo PDF in Markdown e elimini del tutto le immagini pagina per pagina. Niente più pagine trasformate in immagine, niente sovraccarico di visione, solo il testo strutturato che il modello avrebbe letto comunque. È da qui che arriva il risparmio.

Ecco MarkItDown, il convertitore gratuito di Microsoft

MarkItDown è un'utility Python leggera di Microsoft, rilasciata sotto la permissiva licenza MIT e uno degli strumenti per sviluppatori più stellati di GitHub, con oltre 135.000 stelle. Il suo unico compito è trasformare i file disordinati del mondo reale in Markdown pulito che un LLM può leggere a basso costo.

Non è solo uno strumento per PDF. Converte una lunga lista di formati:

• Documenti PDF
• Word (.docx)
• Excel (.xlsx, .xls)
• PowerPoint (.pptx)
• Immagini, con metadati EXIF e OCR per il testo presente nell'immagine
• Audio, con metadati e trascrizione del parlato
• Pagine HTML
• Dati CSV, JSON e XML
• Archivi ZIP (ne percorre il contenuto)
• URL di YouTube (ne recupera la trascrizione)
• E-book EPub
• Messaggi di Outlook (.msg)

Un solo strumento, un solo formato di output, per quasi tutto ciò che altrimenti avresti dato a un modello sotto forma di pesante file binario.

Installare MarkItDown in 30 secondi

È un normale pacchetto Python. Per ottenere tutto, installa l'extra all:

pip install 'markitdown[all]'

Se ti interessano solo alcuni formati e vuoi un'installazione più snella, chiedi soltanto quegli extra:

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

Tra le opzioni disponibili ci sono [all], [pdf], [docx], [pptx], [xlsx], [xls], [outlook], [audio-transcription] e [youtube-transcription], fra le altre.

Convertire un PDF in Markdown dalla riga di comando

La strada più veloce è la CLI. Puntala su un file e manda l'output dove preferisci:

markitdown report.pdf -o report.md

Oppure usa una semplice redirezione, che fa la stessa cosa:

markitdown report.pdf > report.md

Puoi anche inviare un file direttamente in pipe:

cat report.pdf | markitdown

È tutto qui il flusso di lavoro. Ora hai un report.md che puoi dare a qualsiasi modello, depositare in un repository o incollare in una chat, e costa una frazione dell'originale.

File pesante in entrata, Markdown pronto per l'agente in uscita, un solo comando in mezzo.

Convertire in Python (e processare un'intera cartella)

Se stai integrando tutto questo in una pipeline, l'API Python è altrettanto breve:

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("report.pdf")
print(result.text_content)

result.text_content è la tua stringa Markdown, pronta da scrivere su disco o da dare in pasto a un modello. Per convertire un'intera cartella di documenti in una sola passata, ciclaci sopra:

from pathlib import Path
from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
for src in Path("docs").glob("*.pdf"):
    out = src.with_suffix(".md")
    out.write_text(md.convert(str(src)).text_content, encoding="utf-8")

Esegui questo una volta e una directory di PDF costosi diventa una directory di Markdown pulito e strutturato, che qualsiasi agente può leggere a ogni turno senza ripagare la tassa di visione.

Quanto risparmi davvero?

La risposta onesta: dipende dal documento, ma il guadagno è grande e costante. Ecco la forma generale per un tipico file ricco di testo.

Per un documento il cui valore sta nelle sue parole, la conversione in Markdown taglia abitualmente il costo in token di ben più della metà, e spesso dell'80% o più. Il risparmio non ha nulla di magico: semplicemente non paghi più per inviare una foto di ogni pagina quando al modello serviva solo il testo.

Il Markdown non è letteralmente gratis, ovviamente. Il testo estratto costa comunque token. Ma quel costo del testo è il minimo che avresti pagato in ogni caso. Quello che togli è la pila di immagini pagina per pagina posata sopra di esso.

Quando tenere il PDF (non strafare con l'ottimizzazione)

La conversione è la scelta giusta di default, non una regola universale. Tieni il PDF originale quando il punto è proprio l'impaginazione visiva:

• Grafici e diagrammi che vuoi davvero che il modello legga. Se il significato vive in un grafico a barre, l'immagine sta facendo un lavoro reale.
• Documenti scansionati che sono immagini di testo. MarkItDown può passarli all'OCR, ma se il riconoscimento è incerto, la visione del modello stesso può leggere la pagina in modo più affidabile.
• Tabelle o moduli visivi complessi dove posizione e allineamento portano un significato che si appiattisce in Markdown.
• Infografiche e pagine molto curate nel design dove l'impaginazione è il contenuto.

Per tutto il resto, cioè la maggior parte dei documenti, vince il Markdown.

La domanda non è mai "PDF o Markdown" in astratto. È "al modello serve vedere questa pagina, oppure soltanto leggerla?"

Oltre i PDF: Word, Excel, PowerPoint e perfino YouTube

Lo stesso comando di una riga funziona sul resto della tua pila di documenti. Un documento Word, un foglio di calcolo, una presentazione, una pagina web e perfino la trascrizione di un video di YouTube si riducono tutti in Markdown pulito allo stesso modo:

markitdown deck.pptx -o deck.md
markitdown budget.xlsx -o budget.md
markitdown https://www.youtube.com/watch?v=VIDEO_ID -o transcript.md

Se il tuo flusso di lavoro consiste nell'estrarre regolarmente contesto da file Office o dal web per passarlo a un modello, standardizzare tutto in Markdown per prima cosa è una delle abitudini meno costose e più redditizie che tu possa costruire.

Collegalo ai tuoi agenti di coding con il server MCP di MarkItDown

Se lavori con agenti di coding, le cose migliorano ancora. MarkItDown include un server MCP (Model Context Protocol) ufficiale, così il tuo agente può convertire i file da solo, nel mezzo di un'attività, senza che tu debba lanciare nulla a mano.

Installalo e avvialo su stdio:

pip install markitdown-mcp
markitdown-mcp

Il server espone un solo strumento, convert_to_markdown(uri), dove l'uri può essere qualsiasi URI http:, https:, file: o data:. Collegalo una volta al tuo agente e potrà recuperare un PDF, un foglio di calcolo o una pagina web e trasformarlo in Markdown su richiesta, pagando per tutto il tempo prezzi da token di testo invece che da visione.

È esattamente il tipo di cosa che si accumula quando fai girare più di un agente. In AgentsRoom, la cabina di comando multi-agente, configuri un server MCP una volta sola e ogni agente nella stanza lo eredita. Converti i tuoi documenti di riferimento in .md, committali nel repository, e ogni agente legge testo pulito e strutturato a ogni turno invece di ri-trasformare in immagine lo stesso PDF ancora e ancora. La stessa disciplina che mantiene snella una singola sessione mantiene sostenibile un'intera flotta, e questo conta quando fai girare agenti di coding in parallelo e ognuno di loro sta leggendo il tuo contesto condiviso.

Si sposa anche in modo naturale con il modo in cui le buone configurazioni di agenti già gestiscono il contesto. Se mantieni un file di contesto AGENTS.md, farlo puntare a riferimenti .md leggeri anziché a PDF grezzi mantiene stretta la finestra di contesto, il che, come abbiamo visto nel trucco del canarino per individuare la deriva del contesto, è metà della battaglia in qualsiasi sessione lunga.

In sintesi

Dare PDF grezzi in pasto a un LLM è una tassa che hai pagato senza accorgertene, perché ogni pagina viene silenziosamente trasformata in immagine. MarkItDown elimina quella tassa gratuitamente: un solo comando trasforma quasi qualsiasi file in Markdown pulito, abbatti fino all'80% del costo in token e il modello risponde altrettanto bene, spesso meglio, perché legge struttura invece di strizzare gli occhi su foto di pagine.

Converti prima, chiedi dopo. Sia la tua bolletta di token sia la tua finestra di contesto ti ringrazieranno.

Pronto a far girare tutto questo su un intero team di agenti invece che su un solo terminale? Scarica AgentsRoom, guarda cosa supporta ogni agente nella matrice di compatibilità dei provider e approfondisci il supporto multi-provider.