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? #
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) |
| DOCX | 95% | 保留标题、表格、列表 |
| PPTX | 90% | 幻灯片内容已提取,布局已简化 |
| XLSX | 92% | 表格已准确转换 |
| HTML | 96% | 清晰语义提取 |
| 图像 | 75%-90% | 光学字符识别的质量因语言而异 |
| 音频(语音) | 80% | 语音转文字的准确性取决于音频质量 |
| YouTube | 88% | 从视频中提取文字记录 |
| EPUB | 94% | 章节结构保留 |
| 邮政编码 | 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.io | Adobe PDF 提取 | AWS Textract |
|---|---|---|---|---|
| 开源 | ✅ 麻省理工学院 | ✅ Apache 2.0 | ❌ 商业 | ❌ 商业 |
| 免费层 | ✅ 无限 | ✅ 限制(每月1千请求) | ❌ 每页 $0.01 | ❌ 每页 $0.001 |
| 支持的格式 | 二十 | 三十 | 仅限 PDF | 文件与表格 |
| OCR 支持 | ✅(泰瑟拉克特) | ✅(EasyOCR) | ✅ | ✅ |
| 大型语言模型优化 | ✅ 母语 | ⚠️ 通用 | ❌ | ❌ |
| 安装 | pip install | pip install + server | 软件开发工具包 | SDK + API |
| 离线支持 | ✅ 完全 | 部分 | ❌ | ❌ |
| Python API | ✅ | ✅ | ✅ | ✅ |
| 批处理 | ✅ 内置 | ✅ 内置 | ❌ | ✅ |
| 延迟(平均) | ~0.5秒/文件 | ~1.2秒/文件 | 不适用 | ~2秒/文件 |
| 令牌效率 | 高 | 中等 | 不适用 | 不适用 |
MarkItDown 在简单性、成本(免费/无限制)和针对大型语言模型的优化方面占优势。Unstructured.io 在格式数量和企业功能方面占优势。对于大多数大型语言模型管道的用例,MarkItDown 已足够且显著更简单。
限制 / 诚实评估 #
MarkItDown 在它擅长的领域表现出色——但它确实有一些限制:
扫描的 PDF 依赖于 Tesseract 的质量。 手写文本、扫描质量差以及非拉丁字符的文档可能会产生不准确的 OCR。对于重要文件,请核对 OCR 输出。
复杂布局会失去结构。 跨多列的表格、浮动图像和 PDF 中的嵌套布局可能无法完美转换。输出是“对大型语言模型足够好”,而非“像素完美”。
不支持实时协作。 这是一个批处理工具,而不是协作文档编辑器。
可选依赖可能很大。
[all]附加包包括 Tesseract、LibreOffice 以及其他系统依赖。对于生产部署,只安装你需要的部分。YouTube 字幕可用性。 并非所有 YouTube 视频都有字幕/文字记录。没有字幕的视频将悄无声息地失败。
大文件的内存使用情况。 处理100MB以上的PDF可能会消耗大量内存。对于大文件,请使用流式模式。
这些并不是致命缺点——它们是权衡。对于90%的使用场景来说,MarkItDown 的简洁性和成本(免费)胜过这些限制。

常见问题 #
问: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.futures 或 multiprocessing 来并行处理数千个文件。该工具是为批处理工作流设计的——每次转换都是独立且无状态的。
问: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 优化 的指南。
来源及进一步阅读:
- 官方文档:https://github.com/microsoft/markitdown
- GitHub 仓库: https://github.com/microsoft/markitdown
- AutoGen 团队: https://github.com/microsoft/autogen
- LangChain MarkItDown 加载器:https://python.langchain.com/docs/integrations/document_loaders/markitdown
联盟披露:本文包含联盟链接。如果您通过我们的链接注册,我们可能会获得佣金,而您无需额外支付费用。
- 为您的大型语言模型管道提供云托管服务:DigitalOcean
- 替代托管:HTStack
- 交易工具:币安, OKX
- 网络爬虫代理:WebShare
💬 留言讨论