markitdown 实战教程：4 个任务把办公文档变成可用的 Markdown

markitdown 实战教程4 个任务把办公文档变成可用的 Markdown【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdownmarkitdown 是一个轻量 Python 工具把 PDF、PPT、Word、Excel、图片、音频、HTML、CSV、ZIP 等 20 多种格式统一转成 Markdown。它解决的真问题是Office 文件进不了模型复制粘贴丢表格和层级LLM 又读不了二进制。跑通后你手里是一份带#标题、标准表格和链接的.md文件几百页文档几分钟就能转完直接切分入知识库不用再手工整理。安装 markitdown全量与按需两种装法装之前先建虚拟环境避免依赖打架。安装命令如下按你实际处理的格式选 extraspip install markitdown[all] pip install markitdown[pdf,docx,pptx]第一行装齐 PDF、Office、音频等全部可选依赖最省事。第二行只装你真正要用的格式装得快、依赖少。可用的 extras 还有xlsx、xls、outlook、audio-transcription、youtube-transcription、az-doc-intel、az-content-understanding完整清单见 packages/markitdown/README.md。不想在本机装环境也可以走 Docker仓库根目录自带 Dockerfile构建后docker run --rm -i markitdown:latest report.pdf out.md一条命令完成转换。转第一个文件3 条命令覆盖三种输入下面三条命令分别演示文件参数、管道输入、扩展名提示三种入口markitdown presentation.pptx -o out.md cat report.pdf | markitdown cat slide.pptx | markitdown -x pptx-o指定输出文件不传就写到终端没有文件名的管道输入要靠-x给扩展名提示否则猜不出格式。转换结果里幻灯片标题变成#开头的 Markdown 标题表格保留行列结构演讲者备注追加在该页内容末尾。PDF、EPUB 也是同一套入口章节结构转成标题层级。批量转换子目录递归加失败留痕目录结构简单的批量任务shellfor循环最省事每个文件独立成败。但一旦要递归子目录、只挑特定格式、失败要单独留痕Python API 更可控from pathlib import Path from markitdown import MarkItDown from markitdown._exceptions import FileConversionException md MarkItDown() for f in Path(docs).rglob(*.*): if f.suffix in {.pptx, .docx, .xlsx, .pdf}: try: md_path Path(out) / f.with_suffix(.md).name md_path.write_text(md.convert_local(f).text_content, encodingutf-8) except FileConversionException: print(FAILED:, f)rglob递归所有子目录convert_local()只读本地路径单文件抛FileConversionException时记下路径继续跑下一份整批不中断。需要把转换能力挂给本地 agent 时装markitdown-mcp包起一个 MCP 服务它只暴露一个工具convert_to_markdown(uri)接受http、file、data等 URI。救活扫描件OCR 插件还是云端纯扫描的 PDF 用内置提取经常只剩空白或乱码。可选三条路本地 LLM 的 OCR 插件、Azure Document Intelligence、Azure Content Understanding。本地方案装markitdown-ocr插件后配置写法如下from markitdown import MarkItDown from openai import OpenAI md MarkItDown(enable_pluginsTrue, llm_clientOpenAI(), llm_modelgpt-4o) print(md.convert(scanned_invoice.pdf).text_content)插件对无文字的扫描件页自动按 300 DPI 渲染整页送视觉模型识别没有提供llm_client时插件静默跳过自动退回内置转换。插件细节看 OCR 插件说明。云端走 CLI 加-dDocument Intelligence或--use-cuContent Understandingendpoint 可一次性写进环境变量MARKITDOWN_DOCINTEL_ENDPOINT/MARKITDOWN_CU_ENDPOINT。四条路线怎么选一张表说清方案适合的文件需要什么成本内置转换器含文本层的 PDF、Office对应 extra本地免费markitdown-ocr插件扫描件、内嵌图片的 Office任意 OpenAI 兼容客户端本地 LLM 调用Document Intelligence文档、扫描件Azure 资源 endpoint按调用计费Content Understanding文档、音频、视频Azure 资源 endpoint按调用计费图片转文字llm_client 让视觉内容可读markitdown 默认对图片只输出 EXIF 元数据图里的数据一个字符都拿不到。传入llm_client后图片会被编码连同你的提示词发给视觉模型返回的描述文本直接写进 Markdown。针对图表这类结构化内容提示词可以点名要什么md MarkItDown( llm_clientOpenAI(), llm_modelgpt-4o, llm_prompt列出坐标轴含义、数据点与趋势, ) print(md.convert(chart.jpg).text_content)上面这张就是仓库里用来验证描述能力的测试图红色圆形和蓝色方形并排放置配一段要求识别形状与颜色的英文说明。llm_prompt不传时用默认提示词同一批图建议缓存结果避免重复调用视觉模型。输出空白、格式不识别怎么查五个高频问题和对应动作报不支持的格式 → 对应的 extra 没装pip install markitdown[pdf]按需补上管道流识别不出格式 → 加-x pptx给扩展名提示扫描件输出空白或乱码 → 上一节的 OCR 插件或云端二选一输出里 base64 图片数据被截断 → 加--keep-data-uris保留 data URI服务器端处理上传文件 → 改用convert_local()或convert_stream()并先校验路径别用宽泛的convert()先跑markitdown report.pdf -o report.md把手感做出来遇到扫描件再叠加 OCR 插件或云端 endpoint遇到图片内容丢失再传llm_client。【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考