markitdown:强大的文件转 Markdown 工具

1. markitdown简介

markitdown是由微软团队开发的 Python 包和命令行工具,它专注于将多种文件格式转换为 Markdown。与其他类似工具(如 textract)相比,markitdown更注重保留重要的文档结构和内容,如标题、列表、表格、链接等。虽然其输出通常对人类也有一定的可读性,但主要设计目的是供文本分析工具使用,而非用于高保真度的人类可读文档转换。

目前,markitdown支持多种文件格式,包括但不限于:

  • PDF
  • 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地址

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值