SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场markitdown

markitdown

办公与效率

查看项目

更新于 10-16 06:05

技能介绍

MarkItDown 是微软开发的 Python 工具，用于把各种文件格式转换为 Markdown。其定位是文档转换工具，尤其面向把文档转成适合 LLM 使用的文本格式，因为 Markdown 对 token 更高效，也更容易被现代语言模型理解。

主要能力

根据资料，MarkItDown 的核心能力包括：将文档转换为干净、结构化的 Markdown；输出为对 LLM 处理更省 token 的格式；支持 15 种以上文件格式；可选 AI 增强图片描述；支持对图片和扫描文档进行 OCR；支持音频文件的语音转写。

支持的格式与说明

PDF：可进行全文提取。 DOCX：Microsoft Word，保留表格和格式。 PPTX：PowerPoint 幻灯片，含备注。 XLSX：Excel 电子表格，可转换表格和数据。 图片：JPEG、PNG、GIF、WebP，含 EXIF 元数据与 OCR。 音频：WAV、MP3，含元数据与转写。 HTML：网页，可干净转换。 CSV：逗号分隔值，转换为表格格式。 JSON：JSON 数据，转换为结构化表示。 XML：XML 文档，转换为结构化格式。 ZIP：归档文件，迭代其内容。 EPUB：电子书，进行全文提取。 YouTube：视频 URL，可获取转写内容。

安装方式

安装全部功能： pip install 'markitdown[all]'

或从源码安装： git clone https://github.com/microsoft/markitdown.git cd markitdown pip install -e 'packages/markitdown[all]'

使用方式（命令行）

基本转换： markitdown document.pdf > output.md

指定输出文件： markitdown document.pdf -o output.md

管道输入内容： cat document.pdf | markitdown > output.md

启用插件： markitdown --list-plugins markitdown --use-plugins document.pdf -o output.md

使用方式（Python API）

基本用法： from markitdown import MarkItDown md = MarkItDown() result = md.convert("document.pdf") print(result.text_content)

从流转换： with open("document.pdf", "rb") as f: result = md.convert_stream(f, file_extension=".pdf") print(result.text_content)

高级功能

  1. AI 增强图片描述：可通过 OpenRouter 使用 LLM 为 PPTX 和图片文件生成详细图片描述。示例中初始化 OpenAI 兼容客户端，base_url 为 https://openrouter.ai/api/v1，并向 MarkItDown 传入 llm_client、llm_model 与 llm_prompt。资料推荐 llm_model 使用 anthropic/claude-sonnet-4.5（面向科学视觉场景）。

  2. Azure Document Intelligence：用于增强 PDF 转换。命令行示例：markitdown document.pdf -o output.md -d -e "<document_intelligence_endpoint>"；Python 示例通过 MarkItDown(docintel_endpoint="<document_intelligence_endpoint>") 实现。

  3. 插件系统：支持第三方插件扩展功能。可列出已安装插件（markitdown --list-plugins）并启用插件（markitdown --use-plugins file.pdf -o output.md）。可在 GitHub 用话题标签 #markitdown-plugin 查找插件。

可选依赖

可按需安装特定格式支持： 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 视频转写）。

常见使用场景（资料示例）

将科学论文转换为 Markdown，可从 PDF 论文转换并写入 .md 文件。 从 Excel 提取数据用于分析，结果会以 Markdown 表格形式呈现。 批量处理多个文档，例如遍历目录下所有 PDF 并输出到 Markdown 输出目录。 带 AI 描述地转换 PowerPoint，示例使用 OpenRouter 访问多个 AI 模型并为幻灯片图片生成详细描述。 批量转换不同格式，对 document.pdf、spreadsheet.xlsx、presentation.pptx、notes.docx 等做转换并处理异常。 提取 YouTube 视频转写，直接传入视频 URL 获取转写文本。

Docker 用法

构建镜像： docker build -t markitdown:latest .

运行转换： docker run --rm -i markitdown:latest < ~/document.pdf > output.md

资料给出的最佳实践

选择合适的转换方法：简单文档使用基本 MarkItDown()；复杂 PDF 使用 Azure Document Intelligence；视觉内容启用 AI 图片描述；扫描文档确保安装 OCR 依赖。 优雅处理错误：捕获 FileNotFoundError 以及一般异常并输出错误信息。 高效处理大文件：对大文件使用流式转换 with open("large_file.pdf", "rb") as f: result = md.convert_stream(f, file_extension=".pdf")。 优化 token 效率：Markdown 输出本身已较省 token，可进一步去除多余空白、合并相似章节、在不需要时剥离元数据；示例中用正则把连续 3 个以上换行压缩为两个换行并 strip。

与科学工作流集成（资料示例）

转换文献用于综述：遍历 literature/pdfs 下的论文，转换为 Markdown 并在输出中附加来源信息；也可使用 AI 增强转换，并传入 llm_prompt 为“Describe scientific figures with technical precision”。 提取表格用于分析：将 .xlsx 转换后，Markdown 表格可被解析或直接使用。

故障排查

常见问题：缺少依赖时安装对应功能包，例如 pip install 'markitdown[pdf]'；二进制文件错误时确保以二进制模式打开文件（注意 "rb"）；OCR 不工作时安装 tesseract（macOS：brew install tesseract；Ubuntu：sudo apt-get install tesseract-ocr）。

性能考量：大型 PDF 可能耗时较长；图片 OCR 为 CPU 密集型；音频转写需要额外计算资源；AI 图片描述需要 API 调用，可能产生费用。

资料还提到下一步可参考 references/api_reference.md、references/file_formats.md，以及 scripts/batch_convert.py、scripts/convert_with_ai.py。资源包括 MarkItDown GitHub（https://github.com/microsoft/markitdown）、PyPI（https://pypi.org/project/markitdown/）、OpenRouter（https://openrouter.ai）、OpenRouter API Keys（https://openrouter.ai/keys）、OpenRouter Models（https://openrouter.ai/models）、MCP Server：markitdown-mcp（用于 Claude Desktop 集成）、插件开发参考 packages/markitdown-sample-plugin。

关于科学示意图的说明

资料中包含一段关于可视化增强的内容：在创建文档时，若文档尚无示意图，可使用 scientific-schematics 技能生成 AI 驱动的出版级示意图，用自然语言描述所需图，Nano Banana Pro 会自动生成、审阅并优化示意图；对新文档，默认建议生成科学示意图来可视化关键概念、工作流、架构或关系。生成命令示例：python scripts/generate_schematic.py "your diagram description" -o figures/output.png。该部分更多属于该技能包中的相关说明，是否可直接使用取决于环境中是否提供对应技能与脚本，资料未进一步说明其安装与依赖。