Come convertire PDF in Markdown con Python

Perché Markdown, e perché è più difficile di quanto sembri

Gli LLM gestiscono il Markdown in modo eccellente: le intestazioni segnano i confini delle sezioni, le tabelle a pipe tengono allineati i dati tabellari e gli elenchi restano elenchi. Dare a un modello il testo grezzo estratto da un PDF perde tutto questo — e dargli il binario del PDF non è un'opzione per la maggior parte delle pipeline. Per questo quasi ogni stack RAG serio converte i documenti in Markdown prima di chunking ed embedding.

La parte difficile è che i PDF non contengono struttura — contengono caratteri posizionati a coordinate x/y. Un convertitore deve dedurre quali righe sono intestazioni (dalla dimensione del font), quali parole formano una tabella (dall'allineamento) e qual è l'ordine di lettura (dall'analisi del layout). Le librerie differiscono enormemente in quanto bene lo fanno, ed è per questo che la scelta conta.

Una seconda complicazione: i PDF scansionati non contengono testo, solo immagini di pagine. Solo alcune delle opzioni qui sotto le gestiscono, tramite OCR.

Opzione 1: PyMuPDF4LLM — veloce e leggera

PyMuPDF4LLM è un livello sottile sopra PyMuPDF (fitz) costruito apposta per le pipeline LLM: pip install pymupdf4llm, poi md = pymupdf4llm.to_markdown("doc.pdf") — una riga, ed è velocissima: la maggior parte dei documenti viene elaborata in ben meno di un secondo.

Rileva le intestazioni dalle dimensioni dei font, rende le tabelle come tabelle a pipe e può emettere chunk per pagina con metadati, pronti per l'ingestione diretta in LlamaIndex o LangChain. Per PDF nati digitali con layout semplici — report, documentazione, paper senza formattazione esotica — è un default eccellente.

Limiti: niente OCR, quindi le pagine scansionate tornano vuote. Layout multi-colonna complessi e tabelle intricate possono uscire rimescolati, perché le euristiche sottostanti privilegiano la velocità rispetto a un'analisi profonda del layout. Nota di licenza: PyMuPDF è AGPL — va bene per strumenti interni, ma consulta il tuo team legale prima di includerla in un prodotto commerciale.

Opzione 2: Marker — la qualità più alta, serve una GPU

Marker usa una pipeline di modelli deep learning per il rilevamento del layout, l'ordine di lettura e la struttura delle tabelle, e produce il Markdown più fedele di qualsiasi opzione open source — gestisce paper accademici multi-colonna, tabelle complesse e persino le equazioni.

Il costo è l'infrastruttura: pesi dei modelli da diversi gigabyte, una GPU per una velocità ragionevole (la CPU funziona ma è lenta — spesso decine di secondi per documento) e un albero di dipendenze pesante che richiede un vero sforzo per il deploy in produzione o in ambienti serverless.

Scegli Marker quando la qualità dell'output su documenti difficili è la priorità assoluta e hai l'hardware — la conversione in massa di un corpus accademico su una macchina con GPU è il suo terreno ideale. Per un servizio leggero o una funzione serverless, il peso operativo di solito la esclude.

Opzione 3: MarkItDown — il convertitore universale di Microsoft

MarkItDown è la libreria open source di Microsoft che converte tutto in Markdown: pip install markitdown, poi MarkItDown().convert("doc.pdf").text_content. Il suo punto di forza è l'ampiezza — la stessa API converte PDF, DOCX, PPTX, XLSX, HTML e altro, ed è per questo che è diventata virale per la preparazione dei dati per gli LLM.

Per i PDF in particolare, la sua estrazione è più semplice di quella delle opzioni dedicate: si appoggia all'estrazione di testo di base, quindi il rilevamento delle intestazioni e la fedeltà delle tabelle sono inferiori a PyMuPDF4LLM e Marker, e i PDF scansionati richiedono una configurazione OCR aggiuntiva.

Scegli MarkItDown quando ti serve una sola dipendenza che copra molti tipi di file a qualità moderata — uno script di ingestione interno che deve accettare "qualsiasi cosa la gente carichi" — piuttosto che il miglior output PDF possibile.

Opzione 4: un'API hosted — zero dipendenze

La quarta opzione è non eseguire la conversione in locale: invii il PDF con POST a un'API di parsing e ricevi il Markdown. Con ParseJet: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": open("doc.pdf", "rb")}) — il campo "text" della risposta JSON è il Markdown.

Questa strada ha l'OCR per le pagine scansionate già integrato, nessun peso di modelli né librerie native da installare, e funziona identica in una funzione serverless, in un container o in un notebook. Aggira anche del tutto la questione AGPL. Il compromesso è un round trip di rete e un costo per documento oltre il piano gratuito (300 crediti/mese gratis; un PDF costa 3 crediti).

Scegli l'API quando vuoi la pipeline funzionante oggi stesso, quando tra i tuoi PDF ci sono scansioni, o quando fai il deploy dove le dipendenze pesanti fanno male — Lambda, Cloud Run, Vercel.

Quale scegliere?

PDF nati digitali, layout da semplici a moderati, la velocità conta: PyMuPDF4LLM. È il miglior rapporto sforzo-qualità in puro Python.

Documenti difficili (paper multi-colonna, tabelle complesse) e hai una GPU: Marker. Nessuna alternativa open source batte la qualità del suo output.

Tanti tipi di file diversi con una sola libreria, e una qualità moderata va bene: MarkItDown.

PDF scansionati nel mix, deploy serverless o zero voglia di gestire dipendenze: l'API hosted. Una chiamata HTTP, OCR incluso, stesso schema di output per ogni documento.

Esempio completo: da una cartella di PDF a file Markdown

Qualunque strada tu scelga, la forma della pipeline è la stessa — itera, converti, scrivi. Eccola con l'API (sostituisci la chiamata interna con pymupdf4llm.to_markdown() per eseguirla in locale):

import httpx; from pathlib import Path — poi per ogni pdf in Path("pdfs/").glob("*.pdf"): resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": pdf.read_bytes()}); Path("md/", pdf.stem + ".md").write_text(resp.json()["text"], encoding="utf-8").

Per l'ingestione RAG, suddividi il Markdown per intestazioni anziché per conteggi fissi di caratteri — i chunk consapevoli delle intestazioni mantengono intatte le sezioni e il retrieval migliora drasticamente. Quella fedeltà strutturale è esattamente il motivo per cui valeva la pena fare la conversione con cura.