1. markitdown简介
markitdown是由微软团队开发的 Python 包和命令行工具,它专注于将多种文件格式转换为 Markdown。与其他类似工具(如 textract)相比,markitdown更注重保留重要的文档结构和内容,如标题、列表、表格、链接等。虽然其输出通常对人类也有一定的可读性,但主要设计目的是供文本分析工具使用,而非用于高保真度的人类可读文档转换。
目前,markitdown支持多种文件格式,包括但不限于:
- PowerPoint
- Word
- Excel
- 图像(包含 EXIF 元数据和 OCR)
- 音频(包含 EXIF 元数据和语音转录)
- HTML
- 基于文本的格式(如 CSV、JSON、XML)
- ZIP 文件(递归处理内部文件)
- Youtube 链接
- EPUBs
2. 为什么选择 Markdown
Markdown 是一种轻量级标记语言,它非常接近纯文本,只有少量的标记和格式,但能够有效地表示重要的文档结构。主流的大语言模型,如 OpenAI 的 GPT - 4o,原生支持 Markdown,并且常常在响应中自动使用 Markdown 格式。这表明它们在大量的 Markdown 文本上进行了训练,对 Markdown 有很好的理解。此外,Markdown 约定在处理时具有较高的令牌效率。
3. 安装
markitdown可以通过多种方式安装,以下是两种常见的安装方法:
3.1 通过 PyPI 安装
使用 pip
安装所有可选依赖:
pip install 'markitdown[all]'
3.2 从源代码安装
git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'
4. 使用方法
4.1 命令行使用
4.1.1 基本转换
将 PDF 文件转换为 Markdown 并输出到文件:
markitdown path-to-file.pdf > document.md
或者使用 -o
选项指定输出文件:
markitdown path-to-file.pdf -o document.md
4.1.2 管道输入
可以通过管道将文件内容传递给 markitdown:
cat path-to-file.pdf | markitdown
4.2 可选依赖
markitdown具有可选依赖,用于激活不同的文件格式支持。可以根据需要单独安装这些依赖,以获得更精细的控制。例如,安装 PDF、DOCX 和 PPTX 文件的依赖:
pip install 'markitdown[pdf, docx, pptx]'
目前可用的可选依赖如下:
[all]
:安装所有可选依赖[pptx]
:安装 PowerPoint 文件的依赖[docx]
:安装 Word 文件的依赖[xlsx]
:安装 Excel 文件的依赖[xls]
:安装旧版 Excel 文件的依赖[pdf]
:安装 PDF 文件的依赖[outlook]
:安装 Outlook 邮件的依赖[az-doc-intel]
:安装 Azure Document Intelligence 的依赖[audio-transcription]
:安装音频转录(wav 和 mp3 文件)的依赖[youtube-transcription]
:安装获取 YouTube 视频转录的依赖
4.3 插件使用
markitdown支持第三方插件,插件默认是禁用的。
4.3.1 列出已安装的插件
markitdown --list-plugins
4.3.2 启用插件
markitdown --use-plugins path-to-file.pdf
要查找可用的插件,可以在 GitHub 上搜索 #markitdown-plugin
标签。开发插件的详细信息可以参考 packages/markitdown-sample-plugin
。
4.4 Azure Document Intelligence 使用
要使用 Microsoft Document Intelligence 进行转换,可以使用以下命令:
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
更多关于设置 Azure Document Intelligence 资源的信息可以参考 这里。
4.5 Python API 使用
4.5.1 基本使用
from markitdown import MarkItDown
# 禁用插件
md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.text_content)
4.5.2 使用 Document Intelligence 进行转换
from markitdown import MarkItDown
# 指定 Document Intelligence 端点
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)
4.5.3 使用大语言模型生成图像描述
from markitdown import MarkItDown
from openai import OpenAI
# 创建 OpenAI 客户端
client = OpenAI()
# 指定 LLM 客户端和模型
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)
4.6 Docker 使用
可以使用 Docker 来运行 MarkItDown:
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
5. 功能模块详解
5.1 内置转换器
markitdown提供了多种内置转换器,用于处理不同类型的文件。这些转换器在 markitdown
类的 enable_builtins
方法中注册。以下是部分内置转换器的示例代码:
# markitdown/packages/markitdown/src/markitdown/_markitdown.py
def enable_builtins(self, **kwargs) -> None:
if not self._builtins_enabled:
# 注册转换器
self.register_converter(
PlainTextConverter(), priority=PRIORITY_GENERIC_FILE_FORMAT
)
self.register_converter(
ZipConverter(markitdown=self), priority=PRIORITY_GENERIC_FILE_FORMAT
)
self.register_converter(
HtmlConverter(), priority=PRIORITY_GENERIC_FILE_FORMAT
)
# 其他转换器...
self._builtins_enabled = True
else:
warn("Built-in converters are already enabled.", RuntimeWarning)
5.2 插件系统
markitdown的插件系统允许开发者扩展其功能。插件通过 entry_points
机制加载,开发者可以创建自定义的 DocumentConverter
并在插件中注册。以下是一个简单的插件示例:
# markitdown/packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py
from markitdown import MarkItDown, DocumentConverter, DocumentConverterResult, StreamInfo
class RtfConverter(DocumentConverter):
def __init__(
self, priority: float = DocumentConverter.PRIORITY_SPECIFIC_FILE_FORMAT
):
super().__init__(priority=priority)
def accepts(
self,
file_stream: BinaryIO,
stream_info: StreamInfo,
**kwargs: Any,
) -> bool:
mimetype = (stream_info.mimetype or "").lower()
extension = (stream_info.extension or "").lower()
if extension in ACCEPTED_FILE_EXTENSIONS:
return True
for prefix in ACCEPTED_MIME_TYPE_PREFIXES:
if mimetype.startswith(prefix):
return True
return False
def register_converters(markitdown: MarkItDown, **kwargs):
markitdown.register_converter(RtfConverter())
在 pyproject.toml
中配置插件的入口点:
[project.entry-points."markitdown.plugin"]
sample_plugin = "markitdown_sample_plugin"
5.3 MCP 服务器
markitdown提供了一个 MCP(Model Context Protocol)服务器,用于与 LLM 应用(如 Claude Desktop)集成。markitdown-mcp
包提供了一个轻量级的 STDIO 和 SSE MCP 服务器,暴露了一个工具 convert_to_markdown(uri)
,其中 uri
可以是任何 http:
、https:
、file:
或 data:
URI。
5.3.1 运行 MCP 服务器
markitdown-mcp
或者使用 SSE 模式:
markitdown-mcp --sse --host 127.0.0.1 --port 3001
5.3.2 在 Docker 中运行
docker build -t markitdown-mcp:latest .
docker run -it --rm markitdown-mcp:latest
markitdown是一个功能强大且灵活的工具,它为将各种文件格式转换为 Markdown 提供了便捷的解决方案。通过其丰富的内置转换器、插件系统和 MCP 服务器,markitdown能够满足不同场景下的需求。无论是使用命令行工具、Python API 还是 Docker,都可以轻松地将文件转换为适合文本分析的 Markdown 格式。
markitdown github地址