技能使用指南

markitdown（MarkItDown 文件转Markdown工具）Skill 到底是什么？

MarkItDown 文件转Markdown工具 Skill 支持 PDF、Word、PPT、Excel、图片 OCR、音频转录、YouTube 等 15+ 格式一键转成 LLM 友好 Markdown。本文详解一键安装步骤、命令行与 Python API 用法、竞品对比与真实应用场景，帮你快速搭建文档预处理流水线，建议收藏备用。

MarkItDown（文件转Markdown工具）Skillmarkitdown
22 个章节 约 19 分钟阅读 AI 智能生成

MarkItDown（文件转Markdown工具）Skill：把 PDF、Word、PPT、Excel 一键转成 LLM 友好的 Markdown

  • 一个工具覆盖 15+ 种格式：PDF、DOCX、PPTX、XLSX、图片（OCR）、音频（转录）、HTML、CSV、JSON、XML、ZIP、EPUB，甚至 YouTube 视频链接，都能统一转成结构化 Markdown。
  • 专为 LLM 场景设计：输出的是令牌效率高、结构清晰的 Markdown，而不是排版复杂、噪声很多的富文本，可直接放入 RAG 知识库或作为大模型上下文。
  • 安装与调用都很轻：一条 pip install 'markitdown[all]' 即可装齐能力，命令行和 Python API 两种用法，几行代码就能接入现有流程。
  • 可选 AI 增强：接入 LLM 客户端后，可为 PPTX 和图片生成详细描述；接入 Azure 文档智能后，可处理复杂 PDF。
  • 开源 MIT 协议：源自 Microsoft 的开源项目，插件系统可扩展，适合长期集成到工程流水线中。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 MarkItDown（文件转Markdown工具）Skill
技能英文名 markitdown
技能 ID 13033
来源 Microsoft 开源项目 MarkItDown（MIT 协议）
依赖工具 Read、Write、Edit、Bash

它解决什么问题？

开发者、科研人员和数据工作者经常遇到同一种困境：资料散落在各种格式中。论文是 PDF，会议材料是 PPTX，统计表是 XLSX，会议录音是 MP3，归档资料是 ZIP，网络课程在 YouTube 上。要把这些内容交给大模型使用，就得先人工复制粘贴、清洗格式、重排表格，这个过程既枯燥又容易丢失结构信息。

MarkItDown 解决的正是「格式碎片化 → 统一文本」这一环节：它把各种文件和办公文档转换成 Markdown，而 Markdown 具有令牌效率高、现代语言模型容易理解的特点，因此特别适合作为喂给 LLM 的文本格式。

一键安装的思路与步骤

安装前提：需要 Python 环境（能使用 pip）。如果要处理扫描件 OCR，还需系统安装 tesseract；如果要做音频/YouTube 转录、AI 图像描述等高级功能，还需要相应的可选依赖或第三方 API 密钥。

方式一：通过 pip 一键装齐全部功能

pip install 'markitdown[all]'

方式二：从源码安装（便于二次开发）

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

方式三：只装需要的格式（体积更小、依赖更少）

pip install 'markitdown[pdf, docx, pptx]'

可选依赖包括 [pptx]、[docx]、[xlsx]、[xls]、[pdf]、[outlook]、[az-doc-intel]、[audio-transcription]、[youtube-transcription] 等。

在 AI 技能平台中启用：本技能以「技能 ID 13033」或英文名 markitdown 的形式提供，在支持 AI 技能的平台中按技能名或 ID 检索启用即可，具体入口与授权方式以官方说明为准。

验证是否生效：最直接的方式是列出插件或转换一个文件——

markitdown --list-plugins
markitdown 你的文件.pdf -o output.md

如果能正常输出 output.md 且内容结构完整，就说明安装成功。

该技能的主要功能和特点

  • 多格式统一入口：PDF（完整文本提取）、DOCX（保留表格和格式）、PPTX（带备注的幻灯片）、XLSX（表格和数据）、图片（EXIF 元数据 + OCR）、音频（元数据 + 转录）、HTML、CSV、JSON、XML、ZIP（迭代内容）、EPUB、YouTube 网址。
  • 令牌效率优先的输出：相比直接导出纯文本或 HTML，Markdown 用极少的符号表达标题层级、列表和表格，显著降低上下文长度，同时保留语义结构。
  • 可选 AI 增强图像描述：通过兼容 OpenAI API 的客户端（如 OpenRouter）接入视觉模型，为 PPTX 和图片生成详细说明，特别适合含图表的技术文档。
  • Azure 文档智能增强：面对排版复杂、多栏、含扫描页的 PDF，可接入 Microsoft 文档智能服务做增强转换，命令行只需追加 -d -e <endpoint>。
  • OCR 与语音转录：图片和扫描件走 OCR 通路，WAV/MP3 音频可提取元数据并转录成文字，YouTube 链接可直接取回视频转录。
  • 插件系统：支持第三方插件扩展格式与能力，通过 --use-plugins 启用，GitHub 上以 #markitdown-plugin 标签可以找到生态插件。
  • 多种使用形态：命令行、Python API、管道输入（cat file.pdf | markitdown > output.md）、流式转换、Docker 镜像，能灵活嵌入脚本、服务或 CI 流程。
  • 配套可视化能力：技能文档中还建议配合 scientific-schematics 技能，用自然语言描述即可生成出版质量的示意图（python scripts/generate_schematic.py "图表描述" -o figures/output.png），用于补充文档中的工作流图、架构图、数据流图等。

和普通工具比强在哪？ 普通「复制粘贴 + 手动排版」无法处理批量与结构化；通用格式转换器往往面向人类阅读而非模型消费；而 MarkItDown 从设计之初就把「LLM 友好」作为第一目标，同时保留表格结构和元数据，并允许按需叠加 AI 描述能力。

如何使用该技能？

步骤 1：命令行快速转换

# 基本转换，输出到标准输出
markitdown document.pdf > output.md

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

# 管道方式
cat document.pdf | markitdown > output.md

输入：一个本地文件路径或标准输入流；输出：一段 Markdown 文本，可直接保存为 .md 文件。

步骤 2：用 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)

步骤 3：批量处理整个目录

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()
pdf_dir = Path("papers/")
output_dir = Path("markdown_output/")
output_dir.mkdir(exist_ok=True)

for pdf_file in pdf_dir.glob("*.pdf"):
    result = md.convert(str(pdf_file))
    (output_dir / f"{pdf_file.stem}.md").write_text(result.text_content)
    print(f"已转换：{pdf_file.name}")

建议在循环里加 try/except，为单个文件的失败提供兜底处理，避免整批任务中断。

步骤 4：开启 AI 增强图像描述（可选）

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI(
    api_key="your-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",
    llm_prompt="详细描述此幻灯片图像，关注关键视觉元素和数据"
)

result = md.convert("presentation.pptx")
print(result.text_content)

适合含大量图表、示意图的 PPT 和技术文档；注意该通路会产生 API 调用，可能带来成本。

步骤 5：处理复杂 PDF

markitdown document.pdf -o output.md -d -e "<document_intelligence_endpoint>"

或在 Python 中传入 docintel_endpoint 参数。多栏排版、扫描页较多的 PDF 建议走这条增强路径。

步骤 6：提取 YouTube 转录与分析表格

# YouTube 视频转转录
result = MarkItDown().convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

# Excel 转 Markdown 表格，结果可直接解析
result = MarkItDown().convert("data.xlsx")
print(result.text_content)

步骤 7：Docker 化运行

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

适合在不希望污染本地 Python 环境的 CI 或服务器场景中批量跑转换任务。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
markitdown（本技能） 面向 LLM 的文件转 Markdown 工具 15+ 格式转换、OCR、音频转录、YouTube 转录、AI 图像描述、Azure 文档智能、插件扩展 一条 pip install 'markitdown[all]' 命令；命令行与 Python API 均可用 RAG 知识库建设、文档批处理、喂给大模型的资料预处理 优势：输出令牌效率高、结构保留好、支持 AI 增强、MIT 开源；不足：部分能力依赖额外依赖包或第三方 API，OCR/转录对 CPU 与时间消耗较高
Pandoc 通用文档格式转换器 在 Markdown、HTML、LaTeX、DOCX、EPUB 等格式之间互转 需单独安装二进制，参数体系较复杂，学习曲线偏陡 排版级文档互转、出版与写作流程 优势：格式覆盖广、转换控制精细；不足：不针对 LLM 优化，PDF 与图片/音频输入支持有限，缺乏 OCR 与转录能力
Unstructured 面向 RAG 的文档预处理库 文档分区、元素级切分、多格式解析 依赖较多，配置成本较高 复杂文档切分、企业级 RAG 预处理 优势：切分粒度细、元素语义丰富；不足：上手与部署成本偏高，输出并非以 Markdown 为中心，轻量场景容易过度设计
手工复制粘贴 / 办公软件另存 零工具方案 人工整理文本 无需安装 一次性、少量文档 优势：零成本、可控；不足：完全不可批量，格式与表格结构易丢失，耗时且无法复现

选型建议：如果目标是把资料整齐地喂给大模型、且希望一次覆盖文档、图片、音频和网页，本技能是性价比最高的方案；如果要做精细的格式互转或排版级控制，Pandoc 更合适；如果需要对文档做元素级切分后再入库，可考虑 Unstructured；零散文档则手工处理即可。

该技能的典型应用场景与实际体验情况

场景一：科研人员批量整理文献

角色与痛点：研究人员手头常有几十上百篇 PDF 论文，想用大模型做综述或问答，但逐篇复制摘要和表格极耗时。

使用方式：用目录遍历脚本批量转换 literature/pdfs 下的全部 PDF 到 literature/markdown，并在输出文件头部拼接来源信息，形成可检索的本地文献库。

实际体验：上手难度低，基本安装后直接跑通；结构化 PDF 的正文、章节层级和表格大多能保留。注意事项是扫描版论文需要先装好 tesseract 才能走 OCR，超大 PDF 转换耗时明显，建议分批处理。

场景二：数据团队把 Excel 报表变成可分析文本

角色与痛点：分析师希望让模型理解季度报表，但表格直接贴进对话框会丢失行列关系。

使用方式：md.convert("data.xlsx")，输出即为 Markdown 表格格式，可直接阅读或二次解析。

实际体验：中小型表格转换效果干净，行列关系清晰；超宽表或大量合并单元格的工作表建议先在 Excel 侧做结构简化，再做转换，效果更稳定。

场景三：技术团队制作带图解的产品文档

角色与痛点：文档需要架构图、流程图，人工画图周期长，风格还不统一。

使用方式：先用 MarkItDown 把旧版 PPTX/DOCX 转成 Markdown 作为内容底稿，再配合技能推荐的 scientific-schematics 能力，用一句自然语言描述生成示意图；含关键图表的 PPT 还可启用 AI 图像描述，把视觉信息转成文字说明写入 Markdown。

实际体验：整个转换加配图流程可以在脚本中自动化，视觉描述质量与所选模型和提示词强相关，需要调试一两次提示词；启用 AI 描述会产生 API 调用成本，建议只对关键页面开启。

场景四：学习与内容运营提取音视频资料

角色与痛点：培训录音、线上课程、YouTube 讲座内容难以检索和复用。

使用方式：音频（WAV/MP3）走转录通路，YouTube 链接直接 convert 取回转录，再整理成笔记或知识条目。

实际体验：转录通路需要额外依赖与算力，长音频处理时间较长；建议先切片再批量转换，并对输出做一次人工校对，以修正专有名词识别偏差。

该技能能为用户带来的价值

  • 效率提升：把「打开文件 → 复制 → 清洗格式 → 重排表格」的重复劳动压缩成一条命令或几行代码，批量目录转换可一次性完成数十上百个文件的处理，且结果可复现、可版本管理。
  • 门槛降低：不需要了解每种文件格式的解析细节，也不需要为大模型单独设计文本清洗流程，安装后即可用统一接口处理 PDF、Office 文档、图片、音频和网页。
  • 成本优化：Markdown 天然令牌效率高，同样的内容占用更少上下文，长期看能显著降低调用大模型的费用，也让知识库检索更精准。
  • 格式无关的工程化能力：命令行、Python API、流式接口与 Docker 四种形态，使其能嵌入脚本、定时任务、服务端接口或 CI 流水线，成为文档处理链路上的标准前置环节。
  • 可扩展的长期价值：MIT 开源协议 + 插件系统 + 可选 AI 增强与 Azure 文档智能，意味着能力可以随业务复杂度逐步叠加，而不必中途更换技术栈。
  • 文档质量的附加收益：配合科学示意图生成能力，转换后的文档不仅能被机器读，也能被人读，兼顾可读性与视觉表达。

常见问题 FAQ

Q1：这个技能怎么安装？装完怎么确认能用？

最简方式是执行 pip install 'markitdown[all]' 装齐全部功能；若只需部分格式，可用 pip install 'markitdown[pdf, docx, pptx]' 这类按需安装方式。安装完成后运行 markitdown --list-plugins 或直接转换一个 PDF 到 output.md，能正常输出内容即表示生效。在 AI 技能平台中的启用入口以官方说明为准。

Q2：使用这个技能收费吗？

技能本身源自 Microsoft 的开源项目，采用 MIT 协议，可自由使用与集成。但有两类可能的额外成本需要注意：一是可选的 AI 图像描述需调用第三方模型 API（如 OpenRouter），会产生调用费用；二是 Azure 文档智能增强需要相应的服务端点，费用政策以对应服务官方说明为准。

Q3：它适合谁用？不适合谁？

适合需要把大量异构文档喂给大模型的开发者、做文献综述的科研人员、构建 RAG 知识库的数据团队，以及要从音视频中提取文字的内容运营。如果只是偶尔处理一两个文件，或者目标是精细的排版级格式互转（例如生成 LaTeX 或复杂排版 PDF），那么用轻量手工方式或专业格式转换器更划算。

Q4：扫描件和音频为什么转换失败或没有内容？

扫描件走的是 OCR 通路，需要系统已安装 tesseract（macOS 用 brew install tesseract，Ubuntu 用 sudo apt-get install tesseract-ocr）；音频与 YouTube 转录需要安装对应的可选依赖（audio-transcription、youtube-transcription）。另外用流式接口时务必以二进制模式（"rb"）打开文件，否则会报二进制文件错误。

Q5：和 Pandoc、Unstructured 这些方案怎么选？

判断标准是「下游消费者是谁」。下游是大模型或 RAG 知识库，希望一次覆盖文档、图片、音频、网页并拿到令牌高效的 Markdown，优先选本技能；需要精细控制格式互转、面对的是排版出版场景，选 Pandoc；需要对文档做元素级切分再入库，选 Unstructured。三者也可以组合：先用本技能统一转 Markdown，再做切分或排版处理。