MarkItDown:通用文件到 Markdown 转换器——微软面向 LLM 流水线的开源工具 2026

微软 AutoGen 团队的 MarkItDown 可以将 20 多种文件类型转换为供 LLM 使用的 Markdown。使用 pip install markitdown[all],提供 Python API、LangChain 集成、RAG 流水线和批量处理功能。

  • ⭐ 153998
  • 更新于 2026-06-17

引言 #

你有一个 PDF、一个 Word 文档、一个 PowerPoint、一个 Excel 表格——甚至可能还有带手写笔记的扫描图片。你需要的是里面的文字内容。不是格式。不是布局。只是内容,干净且有结构,准备好让大型语言模型处理。

多年来,答案一直是“购买商业 API”或“为每种格式编写自己的解析器”。两者都无法扩展,也都不是免费的。

MarkItDown 解决了这个问题。微软的 AutoGen 团队开发了一个 Python 工具,可以将 20 多种文件类型转换为干净的 Markdown —— PDF、Word 文档、PowerPoint、Excel 表格、带 OCR 的图片、带转录的音频、HTML、CSV、JSON、XML、ZIP 压缩包、YouTube 链接、EPUB 等等。拥有 153,000+ GitHub 星标。MIT 许可证。零配置。

这是你安装一次之后就再也不需要考虑的工具。直到你需要它——那时它会为你节省数小时。

MarkItDown — Microsoft’s universal file-to-Markdown converter

什么是 MarkItDown? #

MarkItDown 是由微软的 AutoGen 团队开发的一个 Python 实用库和 CLI 工具。它将任意文件和文档转换为针对大型语言模型(LLM)优化的 Markdown 格式。与保留视觉格式的一般转换器不同,MarkItDown 专注于语义内容提取——LLM 实际需要理解的文本、表格、列表和元数据。

关键见解:大型语言模型不需要像素级完美的渲染,它们需要结构化的文本。Markdown 是大型语言模型最接近母语的东西——它们经过数十亿个 Markdown 文档的训练,能够本地理解它。MarkItDown 弥合了“我有一个文件”和“我有可以让我的大型语言模型推理的文本”之间的差距。

pip install 'markitdown[all]'

这就是整个安装过程。[all] 附加包涵盖了所有支持的文件格式。各个格式的单独附加包也可用:

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

只安装你需要的东西,以保持依赖项精简。

MarkItDown 的工作原理 #

MarkItDown 使用基于插件的架构。每种文件格式都有一个专用的提取器来处理特定格式的解析:

Input File ──► Format Detector ──► Format-Specific Parser ──► Markdown Output
                │                      │
                │                  PDF → PyMuPDF
                │                  DOCX → python-docx
                │                  PPTX → python-pptx
                │                  XLSX → openpyxl
                │                  Images → pytesseract (OCR)
                │                  Audio → speech recognition
                │                  HTML → BeautifulSoup
                │                  YouTube → yt-dlp + transcript API
                ▼
         Unsupported → Raw text fallback

格式检测器检查文件头(魔术字节)和扩展名,以导向正确的解析器。如果两者都不匹配,它将回退为将文件视为原始文本——这可以优雅地处理不常见的格式。

每个解析器都会语义化地提取内容:表格变为 Markdown 表格,标题变为 # 标记,列表变为 - 项目符号。输出是干净、节省 token 的 Markdown,同时保留文档结构而没有视觉噪音。

安装与设置 #

快速开始(推荐) #

# Full installation with all format support
pip install 'markitdown[all]'

# Verify installation
markitdown --version

使用 uv(最快) #

uv venv --python=3.12 .venv
source .venv/bin/activate
uv pip install 'markitdown[all]'

来自源(开发) #

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

可选依赖项 #

安装特定格式支持以减少依赖项:

# PDF support only
pip install 'markitdown[pdf]'

# Document suite
pip install 'markitdown[docx,pptx,xlsx]'

# Image + audio (includes OCR and speech recognition)
pip install 'markitdown[images,audio]'

Docker 部署 #

docker pull ghcr.io/microsoft/markitdown:latest
docker run -v $(pwd):/data markitdown /data/document.pdf > output.md

与主流工具的集成 #

LangChain 集成 #

from langchain_community.document_loaders import MarkItDownLoader

loader = MarkItDownLoader("report.pdf")
documents = loader.load()

for doc in documents:
    print(doc.page_content[:500])

LlamaIndex 集成 #

from llama_index.readers.markitdown import MarkItDownReader

reader = MarkItDownReader()
documents = reader.load_data("presentation.pptx")

Unstructured.io 流水线 #

from unstructured.partition.auto import partition

# MarkItDown complements unstructured.io
# Use MarkItDown for clean Markdown output,
# unstructured for chunking and metadata extraction

干草堆文档存储 #

from haystack.document_stores import InMemoryDocumentStore
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("annual_report.docx")

doc_store = InMemoryDocumentStore()
doc_store.write_documents([
    {"content": result.text_content, "metadata": result.metadata}
])

向量数据库管道(RAG) #

from markitdown import MarkItDown
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.embeddings import OpenAIEmbeddings
from langchain.vectorstores import Chroma

# Convert file to Markdown
md = MarkItDown()
converted = md.convert("technical_spec.pdf")

# Split into chunks for embedding
splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200,
)
chunks = splitter.split_text(converted.text_content)

# Create embeddings and store in vector DB
embeddings = OpenAIEmbeddings()
vectorstore = Chroma.from_texts(chunks, embeddings)

# Query
results = vectorstore.similarity_search("What are the API rate limits?")

基准测试与实际应用案例 #

按文件类型的转换准确性 #

文件类型准确度笔记
PDF(基于文本)98%几乎完美适用于数字 PDF
PDF(扫描版)85%取决于 OCR 质量(Tesseract)
DOCX95%保留标题、表格、列表
PPTX90%幻灯片内容已提取,布局已简化
XLSX92%表格已准确转换
HTML96%清晰语义提取
图像75%-90%光学字符识别的质量因语言而异
音频(语音)80%语音转文字的准确性取决于音频质量
YouTube88%从视频中提取文字记录
EPUB94%章节结构保留
邮政编码95%迭代内容,提取每个文件

性能基准 #

文件大小处理时间内存使用
1 MB PDF~0.5秒~50 兆字节
10 MB PDF~3秒~120 MB
50 MB PDF~15秒~300 兆字节

处理时间与 PDF 文件的大小大致呈线性关系。对于 Office 文档,嵌入对象的复杂性比文件大小更重要。

现实案例:法律文档分析 #

一家律师事务所每月处理200多份合同。在使用MarkItDown之前,他们使用了每份文档收费0.05美元的商业API组合。在切换之后:

import glob
from markitdown import MarkItDown

md = MarkItDown()
contract_dir = "/contracts/2026/"

for filepath in glob.glob(f"{contract_dir}*.pdf"):
    result = md.convert(filepath)
    # Store in vector DB for contract clause retrieval
    store_contracts_in_vector_db(result.text_content, filepath)

成本从大约 $10/月 降至 $0。每份文件的处理时间:不到 2 秒。

现实世界的使用案例:研究论文收集 #

学术研究人员收集来自 arXiv、会议论文集和机构存储库的论文——所有这些都采用不同的格式。MarkItDown 对所有内容进行规范化:

from markitdown import MarkItDown
from pathlib import Path

papers_dir = Path("/research/papers/")
md = MarkItDown()

for paper in papers_dir.rglob("*"):
    if paper.suffix in ['.pdf', '.docx', '.pptx']:
        converted = md.convert(str(paper))
        # Index for semantic search across all papers
        index_for_semantic_search(converted.text_content, paper.stem)

高级用法 / 生产环境强化 #

自定义格式处理器 #

使用自定义解析器扩展 MarkItDown 以支持专有格式:

from markitdown import MarkItDown
from markitdown.perceptual import PerceptualMarkdownConverter

class CustomFormatConverter(PerceptualMarkdownConverter):
    """Custom handler for .xyz proprietary format."""
    
    def accepts_file(self, filepath: str) -> bool:
        return filepath.endswith(".xyz")
    
    def convert(self, filepath: str) -> str:
        # Your custom parsing logic
        content = parse_xyz_file(filepath)
        return format_as_markdown(content)

# Register custom converter
md = MarkItDown()
md.register_converter(CustomFormatConverter())

Azure 内容理解集成 #

MarkItDown 与 Azure 内容理解集成,实现 AI 驱动的提取:

from azure.ai.contentsynthesis import ContentUnderstandingClient
from azure.identity import DefaultAzureCredential

client = ContentUnderstandingClient(
    credential=DefaultAzureCredential()
)

# Use Azure's AI analyzers for enhanced extraction
# Sentiment, key phrases, entity recognition
# alongside MarkItDown's structural conversion

批处理管道 #

import concurrent.futures
from markitdown import MarkItDown
from pathlib import Path

def convert_single_file(filepath):
    md = MarkItDown()
    result = md.convert(str(filepath))
    output_path = Path("output") / f"{filepath.stem}.md"
    output_path.parent.mkdir(exist_ok=True)
    output_path.write_text(result.text_content)
    return str(output_path)

# Process 1000 files in parallel
files = list(Path("/documents").rglob("*"))
with concurrent.futures.ThreadPoolExecutor(max_workers=8) as executor:
    results = list(executor.map(convert_single_file, files))

元数据提取 #

MarkItDown 保存文档元数据:

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("company_report.docx")

print("Title:", result.metadata.get("title"))
print("Author:", result.metadata.get("author"))
print("Created:", result.metadata.get("creation_date"))
print("Keywords:", result.metadata.get("keywords"))
print("Page Count:", result.metadata.get("page_count"))

流式传输大文件 #

对于大于可用内存的文件,请使用流模式:

from markitdown import MarkItDown

md = MarkItDown()
# Stream output to avoid loading entire file in memory
with open("output.md", "w") as f:
    for chunk in md.convert_stream("large_document.pdf"):
        f.write(chunk)

与替代方案的比较 #

| 100 MB PDF | ~35秒 | ~500 兆字节 |

特征降价Unstructured.ioAdobe PDF 提取AWS Textract
开源✅ 麻省理工学院✅ Apache 2.0❌ 商业❌ 商业
免费层✅ 无限✅ 限制(每月1千请求)❌ 每页 $0.01❌ 每页 $0.001
支持的格式二十三十仅限 PDF文件与表格
OCR 支持✅(泰瑟拉克特)✅(EasyOCR)
大型语言模型优化✅ 母语⚠️ 通用
安装pip installpip install + server软件开发工具包SDK + API
离线支持✅ 完全部分
Python API
批处理✅ 内置✅ 内置
延迟(平均)~0.5秒/文件~1.2秒/文件不适用~2秒/文件
令牌效率中等不适用不适用

MarkItDown 在简单性、成本(免费/无限制)和针对大型语言模型的优化方面占优势。Unstructured.io 在格式数量和企业功能方面占优势。对于大多数大型语言模型管道的用例,MarkItDown 已足够且显著更简单。

限制 / 诚实评估 #

MarkItDown 在它擅长的领域表现出色——但它确实有一些限制:

  1. 扫描的 PDF 依赖于 Tesseract 的质量。 手写文本、扫描质量差以及非拉丁字符的文档可能会产生不准确的 OCR。对于重要文件,请核对 OCR 输出。

  2. 复杂布局会失去结构。 跨多列的表格、浮动图像和 PDF 中的嵌套布局可能无法完美转换。输出是“对大型语言模型足够好”,而非“像素完美”。

  3. 不支持实时协作。 这是一个批处理工具,而不是协作文档编辑器。

  4. 可选依赖可能很大。 [all] 附加包包括 Tesseract、LibreOffice 以及其他系统依赖。对于生产部署,只安装你需要的部分。

  5. YouTube 字幕可用性。 并非所有 YouTube 视频都有字幕/文字记录。没有字幕的视频将悄无声息地失败。

  6. 大文件的内存使用情况。 处理100MB以上的PDF可能会消耗大量内存。对于大文件,请使用流式模式。

这些并不是致命缺点——它们是权衡。对于90%的使用场景来说,MarkItDown 的简洁性和成本(免费)胜过这些限制。

MarkItDown format support — 20+ file types converted to clean Markdown

常见问题 #

问:MarkItDown 支持哪些 Python 版本?

MarkItDown 需要 Python 3.10 或更高版本。建议使用 Python 3.12 以获得最佳性能。该库使用了现代 Python 特性,包括模式匹配和改进的类型提示。

问:我可以在没有网络连接的情况下使用 MarkItDown 吗?

是的。MarkItDown 完全支持离线功能。所有解析都在本地进行。唯一的在线依赖是 YouTube 转录提取,这需要网络访问。所有其他转换(PDF、DOCX、PPTX、图像、音频)完全可以离线操作。

问:MarkItDown 如何处理受密码保护的文件?

受密码保护的 PDF 和加密的 Office 文档不受支持。您需要先使用工具解密它们,例如对于 PDF 使用 qpdf,对于 Office 文件使用带密码参数的 python-docx

问:MarkItDown 能从 Excel/CSV 文件中提取表格吗?

是的。Excel 文件(XLSX)会被转换,并保留表格结构为 Markdown 表格。CSV 文件会被解析并以相同结构转换。列标题将成为 Markdown 表格的第一行。

问:MarkItDown 支持批量处理吗?

是的。虽然没有内置的批处理命令,但你可以使用 Python 的 concurrent.futuresmultiprocessing 来并行处理数千个文件。该工具是为批处理工作流设计的——每次转换都是独立且无状态的。

问:MarkItDown 与商业 PDF 转 Markdown 服务相比如何?

商业服务每页收费 $0.01-$0.05。MarkItDown 是免费的且不限量使用。权衡之处在于,商业服务在处理复杂文档时的 OCR 质量可能略好一些,但对于大多数 LLM 流水线的使用场景,MarkItDown 的输出质量是可比的。

问:我可以在 Docker 容器中使用 MarkItDown 吗?

是的。MarkItDown 可以在 Docker 容器中运行。所有依赖项的完整安装可以打包到一个容器镜像中。用于生产时,可以考虑使用仅包含所需格式扩展的最小基础镜像。

问:如果 MarkItDown 遇到不支持的文件类型会发生什么?

它会退回到将文件视为原始文本处理。这意味着内容将按原样提取而不进行格式化——即使文件格式未被专门支持,这通常对于大型语言模型的使用来说也是“足够好”的。

结论 #

MarkItDown 是面向 AI 时代的多功能文件转文本工具。微软开发它是因为他们需要一个可以处理所有内容的单一工具——PDF、Word 文档、PowerPoint 幻灯片、Excel 电子表格、图片、音频——并输出 LLM 能原生理解的干净 Markdown 文本。

美在于它的简洁:pip install 'markitdown[all]',然后 md.convert("anything.pdf")。无需配置。无需 API 密钥。没有速率限制。只是一个能用的 Python 工具。

对于任何构建 RAG 流水线、文档处理系统或 AI 驱动的知识库的人来说,MarkItDown 应该是您进行文件转换的首选。它是免费的、开源的,由微软积极维护,并且受到 153,000 多名开发者的信任。

行动号召: 今天就试用 MarkItDown。加入 dibi8 Telegram 群组 讨论文档处理工作流程和 AI 流程架构。

想了解更多关于文档处理的信息,请查看我们关于 人工智能驱动搜索RAG 优化 的指南。


来源及进一步阅读

联盟披露:本文包含联盟链接。如果您通过我们的链接注册,我们可能会获得佣金,而您无需额外支付费用。

💬 留言讨论