convez.ai
PluginDados & AnalyticsIntermediário
microsoft

MarkItDown

microsoft/markitdown

Converte arquivos para Markdown preservando estrutura, otimizado para LLMs

Ver no GitHub
ExcelentePluginScore · de 0 a 100

Utilitário Python leve para converter diversos formatos de arquivo (PDF, Word, Excel, PowerPoint, imagens, áudio, HTML, etc.) em Markdown. Preserva estrutura importante do documento (títulos, listas, tabelas, links) mantendo a saída otimizada para consumo por LLMs e pipelines de análise textual.

Instalação

$npx convez-ai microsoft/markitdown

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
196 mil
Forks
15 mil
Acompanhando
596
Saúde
62%
Último commit
há 1 semana
Versão
v0.1.9
Issues abertas
813
Contribuidores
80

Casos de uso

  • Preparar documentos para análise com modelos de linguagem
  • Extrair conteúdo estruturado de PDFs, Word, Excel e PowerPoint
  • Processar lotes de arquivos em pipelines de dados e IA
  • Integrar OCR e transcrição de áudio em workflows automatizados

Veredito

MarkItDown é uma solução prática e versátil para converter documentos em Markdown com foco real em LLMs. Ideal para quem precisa integrar extração de documentos em pipelines de IA, mas exige atenção com segurança em ambientes com inputs não confiáveis.

README em português

MarkItDown

PyPI PyPI - Downloads Built by AutoGen Team

[!IMPORTANT] MarkItDown realiza I/O com as permissões do processo atual. Assim como open() ou requests.get(), ele acessa recursos aos quais o próprio processo tem acesso. Limpe suas entradas em ambientes não confiáveis e chame a função mais restrita convert_* necessária para seu caso de uso (por exemplo, convert_stream() ou convert_local()). Consulte a seção Security Considerations da documentação para obter mais informações.

MarkItDown é uma ferramenta leve em Python para converter diversos arquivos em Markdown para uso com LLMs e pipelines relacionados de análise de texto. Para esse fim, ela é mais comparável ao textract, mas com foco na preservação da estrutura e do conteúdo importantes dos documentos como Markdown (incluindo: títulos, listas, tabelas, links, etc.). Embora a saída seja frequentemente razoavelmente apresentável e amigável para humanos, ela é destinada a ser consumida por ferramentas de análise de texto — e pode não ser a melhor opção para conversões de alta fidelidade destinadas ao consumo humano.

MarkItDown atualmente suporta a conversão de:

  • PDF
  • PowerPoint
  • Word
  • Excel
  • Imagens (metadados EXIF e OCR)
  • Áudio (metadados EXIF e transcrição da fala)
  • HTML
  • Formatos baseados em texto (CSV, JSON, XML)
  • Arquivos ZIP (itera sobre o conteúdo)
  • URLs do Youtube
  • EPubs
  • ... e mais!

Por que Markdown?

Markdown é extremamente próximo de texto puro, com marcação ou formatação mínima, mas ainda fornece uma maneira de representar a estrutura importante dos documentos. LLMs principais, como GPT-4o da OpenAI, nativamente "falam" Markdown e frequentemente incorporam Markdown em suas respostas sem solicitação explícita. Isso sugere que eles foram treinados com vastas quantidades de texto formatado em Markdown e o entendem bem. Como benefício adicional, as convenções do Markdown também são altamente eficientes em tokens.

Pré-requisitos

MarkItDown requer Python 3.10 ou superior. Recomenda-se usar um ambiente virtual para evitar conflitos de dependências.

Com a instalação padrão do Python, você pode criar e ativar um ambiente virtual usando os seguintes comandos:

python -m venv .venv
source .venv/bin/activate

Se estiver usando uv, você pode criar um ambiente virtual com:

uv venv --python=3.12 .venv
source .venv/bin/activate
# NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment

Se você está usando Anaconda, você pode criar um ambiente virtual com:

conda create -n markitdown python=3.12
conda activate markitdown

Instalação

Para instalar o MarkItDown, use pip: pip install 'markitdown[all]'. Alternativamente, você pode instalá-lo a partir do código fonte:

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

Uso

Linha de Comando

markitdown path-to-file.pdf > document.md

Ou use -o para especificar o arquivo de saída:

markitdown path-to-file.pdf -o document.md

Você também pode encaminhar conteúdo por pipe (stdin):

cat path-to-file.pdf | markitdown

Dependências Opcionais

MarkItDown possui dependências opcionais para ativar vários formatos de arquivo. Mais cedo neste documento, instalamos todas as dependências opcionais com a opção [all]. No entanto, você também pode instalá-las individualmente para mais controle. Por exemplo:

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

instalará apenas as dependências para arquivos PDF, DOCX e PPTX.

No momento, estão disponíveis as seguintes dependências opcionais:

  • [all] Instala todas as dependências opcionais
  • [pptx] Instala dependências para arquivos do PowerPoint
  • [docx] Instala dependências para arquivos do Word
  • [xlsx] Instala dependências para arquivos do Excel
  • [xls] Instala dependências para versões antigas de arquivos do Excel
  • [pdf] Instala dependências para arquivos PDF
  • [outlook] Instala dependências para mensagens do Outlook
  • [az-doc-intel] Instala dependências para Azure Document Intelligence
  • [az-content-understanding] Instala dependências para Azure Content Understanding
  • [audio-transcription] Instala dependências para transcrição de áudio de arquivos wav e mp3
  • [youtube-transcription] Instala dependências para obtenção da transcrição de vídeos do Youtube

Plugins

MarkItDown também suporta plugins de terceiros. Os plugins estão desativados por padrão. Para listar os plugins instalados:

markitdown --list-plugins

Para ativar plugins, use:

markitdown --use-plugins path-to-file.pdf

Para encontrar plugins disponíveis, pesquise no GitHub pelo hashtag #markitdown-plugin. Para desenvolver um plugin, veja packages/markitdown-sample-plugin.

Plugin markitdown-ocr

O plugin markitdown-ocr adiciona suporte a OCR aos conversores de PDF, DOCX, PPTX e XLSX, extraindo texto de imagens incorporadas usando LLM Vision — o mesmo padrão llm_client / llm_model que MarkItDown já usa para descrições de imagem. Nenhuma nova biblioteca ML ou dependência binária necessária.

Instalação:

pip install markitdown-ocr
pip install openai  # or any OpenAI-compatible client

Uso:

Passar o mesmo llm_client e llm_model que você usaria para descrições de imagens:

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.text_content)

Se nenhum llm_client for fornecido, o plugin ainda carrega, mas o OCR é silenciosamente ignorado e o conversor padrão embutido é usado em vez disso.

Veja packages/markitdown-ocr/README.md para documentação detalhada.

Azure Content Understanding

Azure Content Understanding oferece conversão de maior qualidade com extração estruturada de campos (YAML front matter), suporte multi-modal (documentos, imagens, áudio e vídeo) e analisadores configuráveis.

Instalação: pip install 'markitdown[az-content-understanding]'

Quando usar o Content Understanding

O Content Understanding é ideal quando você precisa de capacidades além do que os conversores nativos ou da Document Intelligence fornecem:

  • Arquivos de áudio e vídeo — O CU (Content Understanding) é a única opção para vídeos, e a opção em nuvem de maior qualidade para áudios. Os conversores nativos não têm suporte a vídeo e oferecem apenas transcrição básica de áudio.
  • Extração estruturada de campos — Analisadores pré-fabricados ou personalizados extraem campos específicos de domínio (valores em faturas, datas de recibos, cláusulas contratuais), serializados como YAML front matter. Nem os conversores nativos nem a integração com Doc Intel expõem esses campos.
  • Extração de documentos de maior qualidade — Análise de layout e OCR baseados na nuvem para PDFs digitalizados, tabelas complexas e documentos multi-página.
  • Uma única API para todos os modais — Um único cu_endpoint lida com documentos, imagens, áudio e vídeo com roteamento automático do analisador.
CapacidadeConversores nativosAzure Document IntelligenceAzure Content Understanding
Conversão de documentoExtração offline específica por formatoExtração de layout em nuvemExtração multi-modal em nuvem
Campos estruturadosNão disponívelNão exposto nesta integraçãoYAML front matter a partir dos campos do analisador
Analisadores personalizadosNão disponíveisNão configuráveis nesta integraçãoSuportado com cu_analyzer_id
Áudio e vídeoÁudio básico, sem vídeoNão suportadoAnalisadores de áudio e vídeo
CustoApenas computação localChamadas à API da Azure cobráveisChamadas à API da Azure cobráveis

CLI:

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

API Python:

from markitdown import MarkItDown

# Zero-config — auto-selects analyzer per file type
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")   # documents → prebuilt-documentSearch
result = md.convert("meeting.mp4")  # video → prebuilt-videoSearch
result = md.convert("call.wav")     # audio → prebuilt-audioSearch
print(result.markdown)

Com um analisador personalizado (para extração de campos específicos de domínio):

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# Output includes YAML front matter with extracted fields:
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
# ...

Quando cu_analyzer_id é definido, o conversor automaticamente limita seu escopo aos tipos de arquivo compatíveis com base na modalidade do analisador. Tipos incompatíveis (por exemplo, arquivos de áudio com um analisador de documentos) são roteados automaticamente para os analisadores pré-fabricados padrão.

Nota sobre custo: Cada chamada convert() para um formato roteado pelo CU é uma chamada à API da Azure cobrável. Use cu_file_types para restringir quais formatos serão roteados ao CU:

from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # only PDFs use CU
)

Mais informações sobre o Azure Content Understanding podem ser encontradas aqui.

Azure Document Intelligence

Para usar a Microsoft Document Intelligence na conversão:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

Mais informações sobre como configurar um recurso de Azure Document Intelligence podem ser encontradas aqui

API Python

Uso básico em Python:

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.text_content)

Conversão de Document Intelligence em Python:

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

Para usar Modelos de Linguagem Grande (LLMs) para descrições de imagens (atualmente apenas para arquivos pptx e imagem), forneça llm_client e llm_model:

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)

Docker

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

Contribuindo

Este projeto aceita contribuições e sugestões. A maioria das contribuições requer que você concorde com um Acordo de Licença de Contribuidor (CLA) declarando que tem o direito de, e realmente faz, conceder-nos o direito de usar sua contribuição. Para detalhes, visite https://cla.opensource.microsoft.com.

Quando você enviar uma solicitação pull (pull request), um bot CLA determinará automaticamente se você precisa fornecer um CLA e decorará a PR adequadamente (por exemplo, verificação de status, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Código Aberto da Microsoft. Para mais informações, veja a FAQ do Código de Conduta ou entre em contato com opencode@microsoft.com com quaisquer perguntas adicionais ou comentários.

Como Contribuir

Você pode ajudar analisando issues ou ajudando a revisar PRs (Pull Requests). Qualquer issue ou PR é bem-vindo, mas também marcamos alguns como 'abertos para contribuição' e 'abertos para revisão' para facilitar contribuições da comunidade. Estes são apenas sugestões e você é bem-vindo a contribuir de qualquer maneira que desejar.

TodosEspecialmente Precisa Ajuda da Comunidade
IssuesTodas as IssuesIssues abertas para contribuição
PRsTodos os PRsPRs abertas para revisão

Executando Testes e Verificações

  • Navegue até o pacote MarkItDown:

    cd packages/markitdown
    
  • Instale hatch no seu ambiente e execute os testes:

    pip install hatch  # Outras formas de instalar hatch: https://hatch.pypa.io/dev/install/
    hatch shell
    hatch test
    

    (Alternativa) Use o Devcontainer que já possui todas as dependências instaladas:

    # Reabra o projeto no Devcontainer e execute:
    hatch test
    
  • Execute verificações pre-commit antes de enviar um PR: pre-commit run --all-files

Considerações de Segurança

O MarkItDown realiza I/O com as permissões do processo atual. Como open() ou requests.get(), ele acessa recursos aos quais o próprio processo tem acesso.

Limpe seus inputs: Não passe entradas não confiáveis diretamente para o MarkItDown. Se qualquer parte da entrada puder ser controlada por um usuário ou sistema não confiável, como em aplicações hospedadas ou de lado do servidor, ela deve ser validada e restringida antes de chamar o MarkItDown. Dependendo do seu ambiente, isso pode incluir restringir caminhos de arquivos, limitar esquemas URI e destinos de rede, e bloquear acesso a endereços privados, loopback, link-local ou de serviços de metadados.

Chame apenas o método de conversão necessário: Prefira a API de conversão mais restrita que se encaixe no seu caso de uso. O método convert() do MarkItDown é intencionalmente permissivo e pode lidar com arquivos locais, URIs remotos e streams de bytes. Se sua aplicação só precisa ler arquivos locais, chame convert_local(). Se você precisar ter mais controle sobre a obtenção de URIs, chame requests.get() por conta própria e passe o objeto de resposta para convert_response(). Para controle máximo, abra um stream na entrada que deseja converter e chame convert_stream().

Contribuindo com Plugins de Terceiros

Você também pode contribuir criando e compartilhando plugins de terceiros. Veja packages/markitdown-sample-plugin para mais detalhes.

Marcas Registradas

Este projeto pode conter marcas registradas ou logotipos de projetos, produtos ou serviços. O uso autorizado das marcas registradas ou logotipos da Microsoft está sujeito a e deve seguir Guia de Marca & Identidade Visual da Microsoft. O uso de marcas registradas ou logotipos da Microsoft em versões modificadas deste projeto não pode causar confusão nem implicar patrocínio pela Microsoft. Qualquer uso de marcas registradas ou logotipos de terceiros está sujeito às políticas desses terceiros.

Ver o original no GitHub

Bom para

Relacionados