Converter PDF para Markdown e economizar tokens: o guia do MarkItDown

Você joga um PDF de 20 páginas no Claude, faz uma pergunta e a resposta vem sem problema. O que você não vê é a conta. Antes mesmo de a sua pergunta ser lida, esse documento pode engolir dezenas de milhares de tokens. Faça isso algumas vezes por dia na escala de uma equipe e você estará pagando dinheiro de verdade para despejar PDFs brutos em um modelo que teria ficado igualmente satisfeito com texto limpo.

Existe uma solução gratuita, e ela está à vista o tempo todo. Converta o arquivo para Markdown primeiro. Este guia explica exatamente por que os PDFs são tão caros, quanto você economiza e como fazer a conversão em um único comando com o MarkItDown, o conversor open source da Microsoft.

Por que um PDF custa tantos tokens

Aqui está a parte que ninguém te conta. Quando você entrega um PDF a um LLM, ele não é lido do jeito que você lê. Segundo a própria documentação de PDF da Anthropic, o sistema faz duas coisas com cada página:

1. Ele extrai o texto da página.
2. Ele converte a página inteira em imagem e envia essa imagem junto com o texto.

Esse segundo passo é o ralo silencioso de tokens. O modelo não está só lendo palavras, ele também está olhando para uma foto de cada página para conseguir entender gráficos, tabelas e diagramação. Você paga pelos dois.

Os números da Anthropic deixam o custo concreto. Só o texto extraído fica em 1.500 a 3.000 tokens por página dependendo da densidade. Além disso, cada página carrega o custo de uma imagem. Um dado revelador da integração com o Amazon Bedrock: o modo PDF visual completo usa cerca de 7.000 tokens para um PDF de 3 páginas, enquanto a simples extração de texto dessas três mesmas páginas usa cerca de 1.000 tokens. É uma diferença de 7x, e ela vem inteiramente das imagens página por página.

Leve isso para um documento real. Um relatório denso de 20 páginas pode cair em qualquer ponto entre 40.000 e 70.000 tokens depois que cada página é rasterizada em imagem. Você ainda não perguntou nada. Só abriu o arquivo.

O bloco laranja-avermelhado é puro custo extra: uma imagem para cada página, haja ou não algo visual que valha a pena ver nela.

A solução: enviar Markdown limpo no lugar

A maioria dos documentos não precisa ser vista. Um contrato, uma especificação, um artigo de pesquisa, um conjunto de slides cheio de tópicos: tudo isso é texto vestido de diagramação. Se você tira a diagramação e mantém a estrutura, o modelo não perde nada de que realmente precisava.

É exatamente isso que o Markdown te dá. É quase tão próximo de texto puro quanto um formato consegue ser, mas ainda codifica a estrutura que importa: títulos, listas, tabelas, links, blocos de código, negrito e ênfase. Os LLMs populares são treinados em quantidades enormes de Markdown, então eles o interpretam de forma nativa e sem esforço. A Microsoft, que desenvolve o MarkItDown, coloca de forma simples: o Markdown é "extremamente próximo de texto puro, com marcação ou formatação mínima, mas ainda oferece uma forma de representar a estrutura importante de um documento".

Converta seu PDF para Markdown e você descarta por completo as imagens página por página. Sem páginas rasterizadas, sem custo extra de visão, apenas o texto estruturado que o modelo ia ler de qualquer jeito. É daí que vem a economia.

Conheça o MarkItDown, o conversor gratuito da Microsoft

O MarkItDown é um utilitário Python leve da Microsoft, publicado sob a licença permissiva MIT e uma das ferramentas para desenvolvedores com mais estrelas no GitHub, com mais de 135.000 estrelas. Sua única função é transformar arquivos bagunçados do mundo real em Markdown limpo que um LLM pode ler barato.

Não é só uma ferramenta para PDF. Ele converte uma longa lista de formatos:

• Documentos PDF
• Word (.docx)
• Excel (.xlsx, .xls)
• PowerPoint (.pptx)
• Imagens, com metadados EXIF e OCR para o texto dentro da imagem
• Áudio, com metadados e transcrição da fala
• Páginas HTML
• Dados CSV, JSON e XML
• Arquivos ZIP (ele percorre o conteúdo)
• URLs do YouTube (ele puxa a transcrição)
• E-books EPub
• Mensagens do Outlook (.msg)

Uma ferramenta, um formato de saída, para quase tudo que você de outra forma jogaria em um modelo como um binário pesado.

Instale o MarkItDown em 30 segundos

É um pacote Python comum. Para pegar tudo, instale o extra all:

pip install 'markitdown[all]'

Se você só se importa com alguns formatos e quer uma instalação mais enxuta, peça apenas esses extras:

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

As opções disponíveis incluem [all], [pdf], [docx], [pptx], [xlsx], [xls], [outlook], [audio-transcription] e [youtube-transcription], entre outras.

Converter um PDF para Markdown pela linha de comando

O caminho mais rápido é a CLI. Aponte para um arquivo e mande a saída para onde você quiser:

markitdown report.pdf -o report.md

Ou use um simples redirecionamento, que faz a mesma coisa:

markitdown report.pdf > report.md

Você também pode enviar um arquivo direto pelo pipe:

cat report.pdf | markitdown

Esse é todo o fluxo de trabalho. Agora você tem um report.md que pode entregar a qualquer modelo, colocar em um repositório ou colar em um chat, por uma fração do custo original.

Arquivo pesado na entrada, Markdown pronto para o agente na saída, um único comando no meio.

Converter em Python (e processar uma pasta inteira em lote)

Se você está conectando isso a um pipeline, a API Python é igualmente curta:

from markitdown import MarkItDown

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

result.text_content é a sua string Markdown, pronta para gravar em disco ou enviar a um modelo. Para converter uma pasta inteira de documentos de uma só vez, faça um loop sobre ela:

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")

Rode isso uma vez e um diretório de PDFs caros vira um diretório de Markdown limpo e estruturado, que qualquer agente pode ler a cada turno sem pagar de novo a taxa de visão.

Quanto você economiza de verdade?

A resposta honesta: depende do documento, mas o ganho é grande e consistente. Veja a ordem de grandeza para um arquivo típico, rico em texto.

Para um documento cujo valor está nas palavras, converter para Markdown corta o custo em tokens rotineiramente em bem mais da metade, e muitas vezes em 80% ou mais. A economia não tem nada de mágico: você simplesmente deixa de pagar para enviar uma foto de cada página quando o modelo só precisava do texto.

O Markdown não é literalmente de graça, claro. O texto extraído ainda custa tokens. Mas esse custo de texto é o piso que você sempre ia pagar. O que você remove é a pilha de imagens página por página assentada por cima dele.

Quando manter o PDF (não otimize demais)

Converter é o reflexo certo por padrão, não uma regra universal. Mantenha o PDF original quando a diagramação visual for justamente o ponto:

• Gráficos e curvas que você realmente precisa que o modelo leia. Se o sentido vive em um gráfico de barras, a imagem está fazendo um trabalho de verdade.
• Documentos escaneados que são imagens de texto. O MarkItDown pode passá-los pelo OCR, mas se o reconhecimento estiver instável, a própria visão do modelo pode ler a página de forma mais confiável.
• Tabelas ou formulários visuais complexos onde posição e alinhamento carregam um sentido que se achata em Markdown.
• Infográficos e páginas com design pesado onde a diagramação é o conteúdo.

Para todo o resto, que é a maioria dos documentos, o Markdown vence.

A pergunta nunca é "PDF ou Markdown" no abstrato. É "o modelo precisa ver esta página, ou só ler?"

Além dos PDFs: Word, Excel, PowerPoint e até o YouTube

O mesmo comando de uma linha funciona no resto da sua pilha de documentos. Um documento Word, uma planilha, um conjunto de slides, uma página web e até a transcrição de um vídeo do YouTube se reduzem todos a Markdown limpo da mesma forma:

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 o seu fluxo de trabalho envolve puxar contexto regularmente de arquivos do Office ou da web para entregar a um modelo, padronizar tudo para Markdown primeiro é um dos hábitos mais baratos e de maior alavancagem que você pode adquirir.

Conecte aos seus agentes de código com o servidor MCP do MarkItDown

Se você trabalha com agentes de código, isso fica ainda melhor. O MarkItDown traz um servidor MCP (Model Context Protocol) oficial, então o seu agente pode converter arquivos sozinho, no meio da tarefa, sem você rodar nada na mão.

Instale e rode sobre stdio:

pip install markitdown-mcp
markitdown-mcp

O servidor expõe uma única ferramenta, convert_to_markdown(uri), onde a uri pode ser qualquer URI http:, https:, file: ou data:. Conecte ao seu agente uma vez e ele pode puxar um PDF, uma planilha ou uma página web e transformar em Markdown sob demanda, pagando preços de tokens de texto em vez de preços de visão o tempo todo.

Esse é exatamente o tipo de coisa que se acumula quando você está rodando mais de um agente. No AgentsRoom, o cockpit multiagente, você configura um servidor MCP uma vez e cada agente da sala o herda. Converta seus documentos de referência para .md, faça o commit deles no repositório, e cada agente lê texto barato e estruturado a cada turno em vez de rasterizar o mesmo PDF de novo e de novo. A mesma disciplina que mantém uma única sessão enxuta mantém uma frota inteira acessível, o que importa quando você está rodando agentes de código em paralelo e cada um deles está lendo o seu contexto compartilhado.

Isso também combina naturalmente com a forma como bons setups de agentes já gerenciam o contexto. Se você mantém um arquivo de contexto AGENTS.md, apontá-lo para referências .md leves em vez de PDFs brutos mantém a janela de contexto enxuta, o que, como vimos no truque do canário para detectar a deriva de contexto, é metade da batalha em qualquer sessão longa.

O que fica

Alimentar um LLM com PDFs brutos é um imposto que você vem pagando sem perceber, porque cada página é discretamente transformada em imagem. O MarkItDown elimina esse imposto de graça: um comando transforma quase qualquer arquivo em Markdown limpo, você descarta até 80% do custo em tokens, e o modelo responde igualmente bem, muitas vezes melhor, porque está lendo estrutura em vez de apertar os olhos para fotos de páginas.

Converta primeiro, depois pergunte. A sua conta de tokens e a sua janela de contexto vão te agradecer.

Pronto para rodar isso numa equipe inteira de agentes em vez de um único terminal? Baixe o AgentsRoom, veja o que cada agente suporta na matriz de compatibilidade de provedores e leia mais sobre o suporte multiprovedor.