Como Converter PDF para Markdown em Python

Por que Markdown, e por que é mais difícil do que parece

LLMs lidam excepcionalmente bem com Markdown: títulos marcam os limites das seções, tabelas de pipe mantêm os dados tabulares alinhados e listas continuam listas. Alimentar o modelo com texto bruto extraído de PDF perde tudo isso — e enviar o binário do PDF não é opção para a maioria dos pipelines. Por isso praticamente todo stack de RAG sério converte os documentos para Markdown antes do chunking e do embedding.

A parte difícil é que PDFs não contêm estrutura — contêm caracteres posicionados em coordenadas x/y. Um conversor precisa fazer engenharia reversa: quais linhas são títulos (pelo tamanho da fonte), quais palavras formam uma tabela (pelo alinhamento) e qual é a ordem de leitura (pela análise de layout). As bibliotecas variam enormemente em quão bem fazem isso — e é por isso que a escolha importa.

Uma segunda complicação: PDFs digitalizados não contêm texto nenhum, apenas imagens das páginas. Só algumas das opções abaixo lidam com eles, via OCR.

Opção 1: PyMuPDF4LLM — rápida e leve

O PyMuPDF4LLM é uma camada fina sobre o PyMuPDF (fitz) feita sob medida para pipelines de LLM: pip install pymupdf4llm, depois md = pymupdf4llm.to_markdown("doc.pdf") — uma linha, e é muito rápido, processando a maioria dos documentos em bem menos de um segundo.

Ele detecta títulos pelo tamanho das fontes, renderiza tabelas como tabelas de pipe e pode emitir chunks por página com metadados para ingestão direta no LlamaIndex ou no LangChain. Para PDFs nascidos digitais com layouts simples — relatórios, documentação, artigos sem formatação exótica — é um excelente padrão.

Limites: sem OCR, então páginas digitalizadas voltam vazias. Layouts complexos com várias colunas e tabelas intrincadas podem sair embaralhados, porque as heurísticas por trás priorizam velocidade em vez de análise profunda de layout. Nota de licença: o PyMuPDF é AGPL — tranquilo para ferramentas internas, mas confirme com o jurídico antes de embarcá-lo em um produto comercial.

Opção 2: Marker — a melhor qualidade, mas exige GPU

O Marker usa um pipeline de modelos de deep learning para detecção de layout, ordem de leitura e estrutura de tabelas, e produz o Markdown mais fiel entre as opções open source — dá conta de artigos acadêmicos em várias colunas, tabelas complexas e até equações.

O custo é infraestrutura: pesos de modelo de vários gigabytes, uma GPU para velocidade razoável (funciona em CPU, mas é lento — muitas vezes dezenas de segundos por documento) e uma árvore de dependências pesada que dá trabalho de verdade para implantar em produção ou em ambientes serverless.

Escolha o Marker quando a qualidade da saída em documentos difíceis for a prioridade máxima e você tiver o hardware — converter em massa um corpus acadêmico em uma máquina com GPU é o cenário ideal dele. Para um serviço leve ou uma função serverless, o peso operacional costuma descartá-lo.

Opção 3: MarkItDown — o conversor multiformato da Microsoft

O MarkItDown é a biblioteca open source da Microsoft que converte tudo para Markdown: pip install markitdown, depois MarkItDown().convert("doc.pdf").text_content. A força dele é a abrangência — a mesma API converte PDF, DOCX, PPTX, XLSX, HTML e mais, e foi por isso que viralizou na preparação de dados para LLM.

Para PDFs especificamente, a extração é mais simples que a das opções dedicadas: ele se apoia em extração básica de texto, então a detecção de títulos e a fidelidade das tabelas ficam atrás do PyMuPDF4LLM e do Marker, e PDFs digitalizados exigem configuração extra de OCR.

Escolha o MarkItDown quando precisar de uma única dependência cobrindo muitos tipos de arquivo com qualidade moderada — um script interno de ingestão que precisa aceitar "o que quer que as pessoas enviem" — e não da melhor saída possível de PDF.

Opção 4: uma API hospedada — sem dependência nenhuma

A quarta opção é não rodar a conversão localmente: envie o PDF via POST para uma API de parsing e receba o Markdown de volta. Com o ParseJet: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": open("doc.pdf", "rb")}) — o campo "text" da resposta JSON é o Markdown.

Esse caminho já vem com OCR para páginas digitalizadas, não tem pesos de modelo nem bibliotecas nativas para instalar e funciona de forma idêntica em uma função serverless, um contêiner ou um notebook. Também elimina a questão da AGPL por completo. O trade-off é uma ida e volta pela rede e um custo por documento depois do plano gratuito (300 créditos/mês grátis; um PDF custa 3 créditos).

Escolha a API quando quiser o pipeline rodando hoje, quando seus PDFs incluírem digitalizações, ou quando for implantar em algum lugar onde dependências pesadas doem — Lambda, Cloud Run, Vercel.

Qual você deve usar?

PDFs nascidos digitais, layouts simples a moderados, velocidade importa: PyMuPDF4LLM. É a melhor relação esforço-qualidade em Python puro.

Documentos difíceis (artigos em várias colunas, tabelas complexas) e uma GPU disponível: Marker. Nada open source supera a qualidade da saída dele.

Muitos tipos de arquivo diferentes por uma única biblioteca, qualidade moderada serve: MarkItDown.

PDFs digitalizados no meio, deploy serverless, ou zero apetite por gerenciar dependências: a API hospedada. Uma chamada HTTP, OCR incluído, mesmo schema de saída para todo documento.

Exemplo completo: pasta de PDFs para arquivos Markdown

Qualquer que seja o caminho escolhido, o formato do pipeline é o mesmo — iterar, converter, gravar. Aqui está com a API (troque a chamada interna por pymupdf4llm.to_markdown() para rodar localmente):

import httpx; from pathlib import Path — depois, para cada pdf em 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").

Para ingestão em RAG, divida o Markdown em chunks por títulos, e não por contagens fixas de caracteres — chunks que respeitam títulos mantêm as seções inteiras e recuperam dramaticamente melhor. Essa fidelidade estrutural é exatamente o motivo de ter valido a pena fazer a conversão com cuidado.