microsoft / markitdown

microsoft/markitdown

open_in_new前往仓库

用于将文件和办公文档转换为Markdown的Python工具。

项目概览

项目概述

MarkItDown 是微软开发的一个轻量级 Python 工具，用于将各种文件格式（如 PDF、Office 文档、图片、音频等）转换为 Markdown 格式，以便于大型语言模型（LLM）和文本分析管道使用。它旨在保留文档的重要结构（如标题、列表、表格、链接等），输出适合机器消费的 Markdown 文本。

核心功能

  • 支持多种文件格式转换：PDF、PowerPoint、Word、Excel、图片（EXIF 元数据和 OCR）、音频（EXIF 元数据和语音转录）、HTML、文本格式（CSV、JSON、XML）、ZIP 文件、YouTube 链接、EPUB 等。
  • 提供命令行工具和 Python API。
  • 支持可选依赖，按需安装特定格式的转换支持。
  • 支持第三方插件扩展，例如 OCR 插件。
  • 集成 Azure 内容理解（Content Understanding）和 Azure 文档智能（Document Intelligence），提供更高质量的云转换服务。
  • 支持使用 LLM 进行图像描述（如 GPT-4o）。
  • 提供 Docker 镜像，便于容器化部署。

适用与不适用场景

适用场景：

  • 需要将文档转换为 Markdown 以用于 LLM 提示或文本分析。
  • 批量转换办公文档、PDF、图片等。
  • 需要从文档中提取结构化信息（通过 Azure 内容理解）。
  • 在自动化管道中集成文档转换功能。

不适用场景：

  • 需要高保真度的文档转换供人类阅读（输出可能不够美观）。
  • 处理不受信任的输入时未进行适当的安全隔离（存在安全风险）。
  • 需要实时转换大量视频或音频（可能需要云服务）。

技术架构与依赖

  • 语言：Python 3.10+。
  • 依赖：核心依赖较少，可选依赖按需安装，如 [pdf]、[docx]、[pptx]、[xlsx]、[audio-transcription] 等。
  • 集成：支持 OpenAI 客户端、Azure 内容理解、Azure 文档智能。
  • 插件机制：支持第三方插件，通过 #markitdown-plugin 标签发现。

安装与快速开始

安装：

pip install 'markitdown[all]'

或从源码安装：

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

快速开始（命令行）：

markitdown path-to-file.pdf > document.md

或使用 -o 指定输出文件：

markitdown path-to-file.pdf -o document.md

快速开始（Python）：

from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("test.xlsx")
print(result.text_content)

典型使用方法

使用 Azure 内容理解：

from markitdown import MarkItDown
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")
print(result.markdown)

使用 LLM 进行图像描述：

from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)

使用 Docker：

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

配置与部署要点

  • 环境变量：Azure 端点等可通过参数传递，也可设置环境变量（具体变量名未在文档中明确，建议参考官方文档）。
  • 安全配置：在不受信任的环境中，应限制输入来源，使用 convert_local() 或 convert_stream() 等窄化 API。
  • 插件配置：默认禁用插件，需通过 --use-plugins 或 enable_plugins=True 启用。
  • 部署：可使用 Docker 容器化，或作为 Python 库集成到应用中。

限制、风险与许可证

  • 限制： 输出可能不适合人类阅读；部分格式（如视频）需要云服务支持；依赖可选安装，需注意依赖冲突。
  • 风险： 安全风险：执行 I/O 操作时可能访问敏感资源，需对输入进行消毒；云服务调用可能产生费用。
  • 许可证： MIT 许可证。

官方链接

信息来源和分析时间