夜雨聆风学习资料网

ARTICLE · 1360651

微软开源的万能文档转换库MarkItDown

微软开源的万能文档转换库MarkItDown

当我们借助 AI 智能体搭建专属知识库的时候,第一步往往就是把 PDF、Word 这类格式的文档,转换成文本形式的 MarkDown 文档。

微软推出的文档转换工具库 MarkItDown 正好可以实现这项能力,它很适合用来为大模型准备输入数据、开展企业知识库的数据清洗 工作,或是完成文档自动化解析,能够帮我们省去编写多套复杂解析库代码的麻烦。

早在 2024 年 12 月,微软就已经在 GitHub 上公开了 microsoft/markitdown 项目的源代码,并开启对外公测。这个项目由微软研究院 以及微软 AutoGen、AI 工具开发团队负责发起和维护。项目的首席开发者 Adam Fourney 是微软研究院的资深研究员,同时也是微软知名 AI 框架 AutoGen 的核心贡献者之一。项目开源之后,吸引了世界各地大量开发者参与共建。

项目速览

项目仓库microsoft/markitdownGitHub 开源
开源时间2024 年 12 月,同步开启对外公测
维护团队微软研究院 + AutoGen / AI 工具开发团队
首席开发者Adam Fourney(微软研究院资深研究员)

接下来,我们就来介绍 MarkItDown 的安装和使用方式。

📌 本文目录

01安装INSTALL一行命令装齐全部依赖
02使用:测试代码USAGE批量转换器类,覆盖常用格式
03测试结果RESULTPDF 与 Word 均一次转换成功
01

INSTALL

安装

pip install

安装只需要一行命令,[all] 表示把 PDF、Word、Excel、PPT 等各类格式所需的依赖一并装上。

...Command Prompt1 行

pip install "markitdown[all]"

— 安装过程:多数依赖显示 Requirement already satisfied,只补装 azure-ai-* 与 mammoth 等少数包

02

USAGE

测试代码

DocumentBatchConverter

测试代码封装成一个 DocumentBatchConverter 类:既能转换单个文件,也能递归遍历目录批量转换,并且保持原有的相对目录结构。

...20261110-markitdown_test.py120 行

# -*- Coding:UTF-8 -*-

'''====================================================

@File    : 20261110-markitdown_test.py

@IDE     : PyCharm 2024.3 Professional Edition

@Version : Python 3.14.6

@Date    : 2026/11/10 20:29

===================================================='''

import os

import logging

from typing import List, Optional

from markitdown import MarkItDown

# 配置日志规范 (PEP 8 风格)

logging.basicConfig(

level=logging.INFO,

format="%(asctime)s - %(levelname)s - %(message)s"

)

logger = logging.getLogger(__name__)

class DocumentBatchConverter:

"""

基于 Microsoft MarkItDown 的文档批处理转换器

支持格式:PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), HTML 等

"""

def __init__(self, llm_client: Optional[object] = None, llm_model: Optional[str] = None):

"""

初始化转换器

:param llm_client: 可选的大模型客户端 (如 openai.OpenAI()),用于图像分析与高级解析

:param llm_model: 模型名称 (如 'gpt-4o')

"""

try:

if llm_client and llm_model:

self.md_engine = MarkItDown(llm_client=llm_client, llm_model=llm_model)

logger.info("已成功加载集成 LLM 能力的 MarkItDown 引擎。")

else:

self.md_engine = MarkItDown()

logger.info("已成功加载标准 MarkItDown 引擎。")

exceptExceptionas e:

logger.error(f"MarkItDown 引擎初始化失败: {e}")

raise e

def convert_single_file(self, input_path: str, output_path: str) -> bool:

"""

转换单个文件为 Markdown

:param input_path: 源文件路径

:param output_path: 输出 Markdown 文件路径

:return: 转换成功返回 True,失败返回 False

"""

ifnot os.path.exists(input_path):

logger.warning(f"源文件不存在: {input_path}")

returnFalse

try:

logger.info(f"正在转换: {input_path} -> {output_path}")

result = self.md_engine.convert(input_path)

# 确保目标目录存在

output_dir = os.path.dirname(output_path)

if output_dir andnot os.path.exists(output_dir):

os.makedirs(output_dir, exist_ok=True)

withopen(output_path, "w", encoding="utf-8") as f:

f.write(result.text_content)

logger.info(f"转换成功!输出文件已写入: {output_path}")

returnTrue

exceptExceptionas err:

logger.error(f"转换文件 '{input_path}' 时发生异常: {err}", exc_info=True)

returnFalse

def batch_convert_directory(self, input_dir: str, output_dir: str,

valid_extensions: Optional[List[str]] = None) -> None:

"""

批量递归转换目录下的所有目标文档

:param input_dir: 输入文件夹路径

:param output_dir: 结果输出文件夹路径

:param valid_extensions: 过滤后缀名列表 (如 ['.pdf', '.docx', '.xlsx', '.pptx'])

"""

if valid_extensions isNone:

valid_extensions = [".pdf", ".docx", ".xlsx", ".pptx", ".html", ".xml"]

input_dir = os.path.abspath(input_dir)

output_dir = os.path.abspath(output_dir)

ifnot os.path.exists(input_dir):

logger.error(f"指定的输入目录不存在: {input_dir}")

return

logger.info(f"开始遍历目录: {input_dir}")

success_count = 0

fail_count = 0

for root, _, files in os.walk(input_dir):

for file_name in files:

ext = os.path.splitext(file_name)[1].lower()

if ext in valid_extensions:

src_file_path = os.path.join(root, file_name)

# 保持相对目录结构

rel_path = os.path.relpath(src_file_path, input_dir)

dest_file_path = os.path.join(output_dir, os.path.splitext(rel_path)[0] + ".md")

success = self.convert_single_file(src_file_path, dest_file_path)

if success:

success_count += 1

else:

fail_count += 1

logger.info(f"批处理完成。成功: {success_count} 个,失败: {fail_count} 个。")

if __name__ == "__main__":

# 使用示例

converter = DocumentBatchConverter()

# 批量转换目录

converter.batch_convert_directory(input_dir="D:/markitdown_docs", output_dir="D:/markitdown_md")

03

RESULT

测试结果

成功 2 / 失败 0

— 运行结果:一个 Word、一个 PDF 均转换成功,批处理完成 成功 2 个,失败 0 个

我分别拿了一个 PDF 文件 和一个 Word 文件 来测试,两个文件都顺利转换成了 md 文件,而且转换速度很快。

⚠ 两点需要留意

1

Python 的版本必须是 3.10 及以上。

2

MarkItDown 主要用来提取文档里的文本和内容结构,没办法百分之百还原原文档精致的视觉排版效果,比如段落缩进、特殊字体这类样式,所以它并不适合用来制作可以直接给人阅读的印刷文件。

∞

THE END

写在最后

MarkItDown 把「文档 → 文本」这一步标准化了,剩下的清洗、切分与入库,才轮到我们自己动手。

今天的分享就到这儿啦,非常感谢您对“Python SQL审天下”公众号的关注和点赞。

如果您觉得我的公众号能给您带来一丝丝的收获,请多多转发给您的朋友圈,让更多的人看到并了解。

也许您不经意间的点赞和转发,会给他人带来独特的体验和感受。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料