MarkItDown 进阶三板斧OCR、音频转写与 Azure 云提取的正确打开方式【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown把 PDF、Word、PPT 丢给大模型得到一堆截断的乱码——这是许多 RAG 与 LLM 数据管线工程师的日常痛点。微软开源的 MarkItDown核心入口之所以能长期霸榜正在于它把任意文件 → 结构化 Markdown这件事做得足够干净保留标题层级、表格、列表让 GPT-4o、Claude 这类天然说 Markdown的模型直接消费。但多数教程止步于pip install markitdown[all]和一行markitdown file.pdf。真正决定管线质量上限的是三条进阶链路LLM Vision 驱动的 OCR 插件、本地音频转写链路、以及Azure Document Intelligence / Content Understanding 云提取。本文结合仓库源码逐一拆解它们的安装、调用与取舍给出可直接落地的组合策略。第一板斧markitdown-ocr 插件让扫描件与图片开口说话内置的 PdfConverter 系基于 pdfminer/pdfplumber 的文本层提取遇到扫描版 PDF、PPT 里的截图、Word 里的图片只能输出空壳。官方生态给出的答案是一个独立插件包markitdown-ocr——它不引入任何新的 ML 库或二进制依赖复用 MarkItDown 本就支持的llm_client/llm_model模式把视觉大模型变成 OCR 引擎。安装与启用pip install markitdown-ocr pip install openai # 或任意 OpenAI 兼容 SDKCLI 方式markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4oPython 方式插件 READMEfrom markitdown import MarkItDown from openai import OpenAI md MarkItDown( enable_pluginsTrue, llm_clientOpenAI(), llm_modelgpt-4o, ) result md.convert(document_with_images.pdf) print(result.markdown)插件机制优先级劫持而非源码入侵插件之所以能零侵入替换内置转换器靠的是两套机制。其一pyproject.toml 声明了markitdown.plugin入口点MarkItDown.enable_plugins 会扫描该 entry point 组并调用插件的register_converters()。其二注册逻辑 将四个 OCR 增强转换器PDF/DOCX/PPTX/XLSX以priority -1.0注册——低于内置转换器的 0.0而转换器按优先级从小到大排序后依次尝试因此插件版总是先被命中。PRIORITY_OCR_ENHANCED -1.0 markitdown.register_converter( PdfConverterWithOCR(ocr_serviceocr_service), priorityPRIORITY_OCR_ENHANCED )OCR 服务base64 图片直送视觉模型LLMVisionOCRService 的实现直白且可移植把图片流编码为data:{mime};base64,...组装成 OpenAI 风格的多模态消息调用client.chat.completions.create()默认提示词要求只返回文本、保持版面顺序。这意味着任何兼容 OpenAI 协议的客户端都能接入——仓库测试里甚至用 AzureOpenAI 演示插件 README。三类文件的差异化处理PDFPdfConverterWithOCR 先用 pdfplumber 按page.images/XObject 提取内嵌图片再把文本行与图片按 Y 坐标合并排序、交错输出保住阅读顺序当整页提取不到文本典型扫描件时自动降级为300 DPI 整页渲染后全页 OCR若 pdfplumber 打不开损坏 PDF还会用 PyMuPDF 兜底渲染。DOCX/PPTX/XLSX三个增强类分别继承内核转换器只重写_image_to_htmlhook如 DocxConverterWithOCR把 OCR 结果转义为 HTML 片段后回注到原生 HTML 管线再统一经 Markdown 渲染——原生样式、数学公式、表格结构全部保留。相同图片按 SHA-256 缓存一次识别、多处复用省 token。所有 OCR 文本以*[Image OCR]...\n[End OCR]*包裹输出方便下游按标记切分。仓库的 OCR 测试套件 还覆盖了服务签名兼容新老调用方式与错误不重试等边界。仓库自带了一批真实扫描件 fixture例如 MEDRPT-2024-PAT-3847_medical_report_scan.pdf对应的 预期输出 展示了扫描病历转 Markdown 后的形态——调试插件时可直接用这些文件做回归验证。第二板斧本地音频转写的完整调用链MarkItDown 对音频的处理是元数据 转写双轨制实现在 AudioConverter 中。依赖与格式支持音频能力是可选的 extraspip install markitdown[audio-transcription]依赖为pydubSpeechRecognitionpyproject.toml。接受.wav、.mp3、.m4a、.mp4四种扩展名及对应 MIME。转换流程分三步EXIF 元数据若本机装了exiftool输出 Title、Artist、Album、SampleRate 等字段格式归一wav/aiff/flac 直接使用mp3/mp4 经pydub.AudioSegment解码后转成 wav 内存流_transcribe_audio.py语音识别SpeechRecognition的recognize_google对音频整体识别默认语言en-US。语言与输出控制语言通过转换 kwargs 注入from markitdown import MarkItDown md MarkItDown() result md.convert(meeting.wav, languagezh-CN) print(result.markdown)输出结构为元数据键值对 ### Audio Transcript:标题下的转写文本。值得注意的实现细节音频转写依赖缺失时AudioConverter 用except MissingDependencyException: pass静默跳过转写、只保留元数据——因此排查音频没转写出来时第一件事就是确认 extras 是否装齐而不是怀疑代码。视频呢内置转换器没有任何视频支持唯一的例外是 YouTubeConverter它抓取 YouTube 页面的 meta 信息与youtube_transcript_api字幕输出 Video Metadata Transcript。本地视频文件的转写要么交给下面要说的 Azure Content Understanding要么自己挂第三方转写服务。第三板斧Azure 云提取高精度与多模态的天花板当本地解析达不到精度要求复杂表格、扫描件、手写体或需要音视频与结构化字段时Azure 是官方明示的两条云路径。模式一Document Intelligence文档高精度 OCRDocumentIntelligenceConverter 走prebuilt-layout模型关键在直接请求 Markdown 格式输出output_content_formatCONTENT_FORMAT代码中因 SDK 枚举 bug 暂以常量 markdown 代替并在返回后正则剔除!--...--注释。pip install markitdown[az-doc-intel] export MARKITDOWN_DOCINTEL_ENDPOINTyour_endpoint markitdown scan.pdf -o scan.md -d认证逻辑源码优先取AZURE_API_KEY环境变量否则回退DefaultAzureCredential。_analysis_features()里有一个容易被忽略的差异对 PDF/JPEG/PNG/BMP/TIFF 会额外开启FORMULAS、OCR_HIGH_RESOLUTION、STYLE_FONT三个分析特性而 DOCX/PPTX/XLSX/HTML 因服务端不支持而返回空列表——也就是说 Office 文件走 Doc Intelligence 只是换了排版引擎OCR 增强特性专属于文档类格式。Python 侧接入同样简单根 READMEfrom markitdown import MarkItDown md MarkItDown(docintel_endpointdocument_intelligence_endpoint) result md.convert(test.pdf) print(result.markdown)模式二Content Understanding多模态 结构化字段ContentUnderstandingConverter 是更重的一招一个cu_endpoint同时覆盖文档、图片、音频、视频四大模态按扩展名/MIME 自动路由到prebuilt-documentSearch/prebuilt-image同为 documentSearch/prebuilt-videoSearch/prebuilt-audioSearch并支持cu_analyzer_id指定自定义分析器做领域字段抽取。pip install markitdown[az-content-understanding] markitdown report.pdf --use-cu --cu-endpoint content_understanding_endpointPython 侧零配置即可按文件类型自动选分析器from markitdown import MarkItDown md MarkItDown(cu_endpointcontent_understanding_endpoint) print(md.convert(report.pdf).markdown) # → documentSearch print(md.convert(meeting.mp4).markdown) # → videoSearch print(md.convert(call.wav).markdown) # → audioSearchCU 的两大差异化能力一是音频/视频是云端的唯一高质量选项内置无视频、音频仅基础转写二是结果经 SDK 的to_llm_input()序列化为YAML front matter 承载结构化字段发票金额、日期、合同条款这是 Doc Intelligence 集成所不提供的。能力边界与组合策略把三条链路放进一张表取舍一目了然对比可参考根 README的 Capability 表能力维度内置转换器markitdown-ocr 插件Doc IntelligenceContent Understanding文档转换本地离线格式专属本地 LLM Vision云端布局提取云端多模态提取扫描件/嵌入图片不支持支持LLM 逐图/整页支持OCR 特性支持音频/视频基础音频、无视频不支持不支持音频/视频分析器结构化字段无无集成未暴露YAML front matter成本仅本地算力LLM API 按 token 计费Azure 按调用计费Azure 按调用计费据此给出可落地的选型建议默认路径纯文本、结构良好的 Office 文档用内置转换器零成本零延迟图片密度高或扫描件上markitdown-ocr插件注意它是按 token 计费的 LLM 调用——用--use-plugins全局开启前先评估文档图片量必要时按文件类型做路由避免把纯文本文档也送进视觉模型单文档追求极致精度选 Doc Intelligence-d一条命令即可适合质检、财务等对版面保真敏感的场景多模态混合语料库会议录音 视频 报表直接上 CU一个 endpoint 通吃cu_file_types参数可精确圈定哪些格式走云、哪些留在本地把计费面收紧根 README 有示例监控手段任何链路都别忘了安全边界——根 README 的安全说明强调 MarkItDown 会以当前进程权限执行 I/O在不可信环境中务必使用最窄的convert_local()/convert_stream()并对输入做白名单校验。三板斧各有其位本地 OCR 解决看得见但读不出音频转写补上听得见但记不下Azure 云提取兜住精度不够、模态太杂。按文档画像组合使用才能让 Markdown 管线既省成本、又顶得住生产级质量要求。【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 13:53:12 · 阅读 1.2k MarkItDown 进阶三板斧：OCR、音频转写与 Azure 云提取的正确打开方式
MarkItDown 进阶三板斧OCR、音频转写与 Azure 云提取的正确打开方式【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown把 PDF、Word、PPT 丢给大模型得到一堆截断的乱码——这是许多 RAG 与 LLM 数据管线工程师的日常痛点。微软开源的 MarkItDown核心入口之所以能长期霸榜正在于它把任意文件 → 结构化 Markdown这件事做得足够干净保留标题层级、表格、列表让 GPT-4o、Claude 这类天然说 Markdown的模型直接消费。但多数教程止步于pip install markitdown[all]和一行markitdown file.pdf。真正决定管线质量上限的是三条进阶链路LLM Vision 驱动的 OCR 插件、本地音频转写链路、以及Azure Document Intelligence / Content Understanding 云提取。本文结合仓库源码逐一拆解它们的安装、调用与取舍给出可直接落地的组合策略。第一板斧markitdown-ocr 插件让扫描件与图片开口说话内置的 PdfConverter 系基于 pdfminer/pdfplumber 的文本层提取遇到扫描版 PDF、PPT 里的截图、Word 里的图片只能输出空壳。官方生态给出的答案是一个独立插件包markitdown-ocr——它不引入任何新的 ML 库或二进制依赖复用 MarkItDown 本就支持的llm_client/llm_model模式把视觉大模型变成 OCR 引擎。安装与启用pip install markitdown-ocr pip install openai # 或任意 OpenAI 兼容 SDKCLI 方式markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4oPython 方式插件 READMEfrom markitdown import MarkItDown from openai import OpenAI md MarkItDown( enable_pluginsTrue, llm_clientOpenAI(), llm_modelgpt-4o, ) result md.convert(document_with_images.pdf) print(result.markdown)插件机制优先级劫持而非源码入侵插件之所以能零侵入替换内置转换器靠的是两套机制。其一pyproject.toml 声明了markitdown.plugin入口点MarkItDown.enable_plugins 会扫描该 entry point 组并调用插件的register_converters()。其二注册逻辑 将四个 OCR 增强转换器PDF/DOCX/PPTX/XLSX以priority -1.0注册——低于内置转换器的 0.0而转换器按优先级从小到大排序后依次尝试因此插件版总是先被命中。PRIORITY_OCR_ENHANCED -1.0 markitdown.register_converter( PdfConverterWithOCR(ocr_serviceocr_service), priorityPRIORITY_OCR_ENHANCED )OCR 服务base64 图片直送视觉模型LLMVisionOCRService 的实现直白且可移植把图片流编码为data:{mime};base64,...组装成 OpenAI 风格的多模态消息调用client.chat.completions.create()默认提示词要求只返回文本、保持版面顺序。这意味着任何兼容 OpenAI 协议的客户端都能接入——仓库测试里甚至用 AzureOpenAI 演示插件 README。三类文件的差异化处理PDFPdfConverterWithOCR 先用 pdfplumber 按page.images/XObject 提取内嵌图片再把文本行与图片按 Y 坐标合并排序、交错输出保住阅读顺序当整页提取不到文本典型扫描件时自动降级为300 DPI 整页渲染后全页 OCR若 pdfplumber 打不开损坏 PDF还会用 PyMuPDF 兜底渲染。DOCX/PPTX/XLSX三个增强类分别继承内核转换器只重写_image_to_htmlhook如 DocxConverterWithOCR把 OCR 结果转义为 HTML 片段后回注到原生 HTML 管线再统一经 Markdown 渲染——原生样式、数学公式、表格结构全部保留。相同图片按 SHA-256 缓存一次识别、多处复用省 token。所有 OCR 文本以*[Image OCR]...\n[End OCR]*包裹输出方便下游按标记切分。仓库的 OCR 测试套件 还覆盖了服务签名兼容新老调用方式与错误不重试等边界。仓库自带了一批真实扫描件 fixture例如 MEDRPT-2024-PAT-3847_medical_report_scan.pdf对应的 预期输出 展示了扫描病历转 Markdown 后的形态——调试插件时可直接用这些文件做回归验证。第二板斧本地音频转写的完整调用链MarkItDown 对音频的处理是元数据 转写双轨制实现在 AudioConverter 中。依赖与格式支持音频能力是可选的 extraspip install markitdown[audio-transcription]依赖为pydubSpeechRecognitionpyproject.toml。接受.wav、.mp3、.m4a、.mp4四种扩展名及对应 MIME。转换流程分三步EXIF 元数据若本机装了exiftool输出 Title、Artist、Album、SampleRate 等字段格式归一wav/aiff/flac 直接使用mp3/mp4 经pydub.AudioSegment解码后转成 wav 内存流_transcribe_audio.py语音识别SpeechRecognition的recognize_google对音频整体识别默认语言en-US。语言与输出控制语言通过转换 kwargs 注入from markitdown import MarkItDown md MarkItDown() result md.convert(meeting.wav, languagezh-CN) print(result.markdown)输出结构为元数据键值对 ### Audio Transcript:标题下的转写文本。值得注意的实现细节音频转写依赖缺失时AudioConverter 用except MissingDependencyException: pass静默跳过转写、只保留元数据——因此排查音频没转写出来时第一件事就是确认 extras 是否装齐而不是怀疑代码。视频呢内置转换器没有任何视频支持唯一的例外是 YouTubeConverter它抓取 YouTube 页面的 meta 信息与youtube_transcript_api字幕输出 Video Metadata Transcript。本地视频文件的转写要么交给下面要说的 Azure Content Understanding要么自己挂第三方转写服务。第三板斧Azure 云提取高精度与多模态的天花板当本地解析达不到精度要求复杂表格、扫描件、手写体或需要音视频与结构化字段时Azure 是官方明示的两条云路径。模式一Document Intelligence文档高精度 OCRDocumentIntelligenceConverter 走prebuilt-layout模型关键在直接请求 Markdown 格式输出output_content_formatCONTENT_FORMAT代码中因 SDK 枚举 bug 暂以常量 markdown 代替并在返回后正则剔除!--...--注释。pip install markitdown[az-doc-intel] export MARKITDOWN_DOCINTEL_ENDPOINTyour_endpoint markitdown scan.pdf -o scan.md -d认证逻辑源码优先取AZURE_API_KEY环境变量否则回退DefaultAzureCredential。_analysis_features()里有一个容易被忽略的差异对 PDF/JPEG/PNG/BMP/TIFF 会额外开启FORMULAS、OCR_HIGH_RESOLUTION、STYLE_FONT三个分析特性而 DOCX/PPTX/XLSX/HTML 因服务端不支持而返回空列表——也就是说 Office 文件走 Doc Intelligence 只是换了排版引擎OCR 增强特性专属于文档类格式。Python 侧接入同样简单根 READMEfrom markitdown import MarkItDown md MarkItDown(docintel_endpointdocument_intelligence_endpoint) result md.convert(test.pdf) print(result.markdown)模式二Content Understanding多模态 结构化字段ContentUnderstandingConverter 是更重的一招一个cu_endpoint同时覆盖文档、图片、音频、视频四大模态按扩展名/MIME 自动路由到prebuilt-documentSearch/prebuilt-image同为 documentSearch/prebuilt-videoSearch/prebuilt-audioSearch并支持cu_analyzer_id指定自定义分析器做领域字段抽取。pip install markitdown[az-content-understanding] markitdown report.pdf --use-cu --cu-endpoint content_understanding_endpointPython 侧零配置即可按文件类型自动选分析器from markitdown import MarkItDown md MarkItDown(cu_endpointcontent_understanding_endpoint) print(md.convert(report.pdf).markdown) # → documentSearch print(md.convert(meeting.mp4).markdown) # → videoSearch print(md.convert(call.wav).markdown) # → audioSearchCU 的两大差异化能力一是音频/视频是云端的唯一高质量选项内置无视频、音频仅基础转写二是结果经 SDK 的to_llm_input()序列化为YAML front matter 承载结构化字段发票金额、日期、合同条款这是 Doc Intelligence 集成所不提供的。能力边界与组合策略把三条链路放进一张表取舍一目了然对比可参考根 README的 Capability 表能力维度内置转换器markitdown-ocr 插件Doc IntelligenceContent Understanding文档转换本地离线格式专属本地 LLM Vision云端布局提取云端多模态提取扫描件/嵌入图片不支持支持LLM 逐图/整页支持OCR 特性支持音频/视频基础音频、无视频不支持不支持音频/视频分析器结构化字段无无集成未暴露YAML front matter成本仅本地算力LLM API 按 token 计费Azure 按调用计费Azure 按调用计费据此给出可落地的选型建议默认路径纯文本、结构良好的 Office 文档用内置转换器零成本零延迟图片密度高或扫描件上markitdown-ocr插件注意它是按 token 计费的 LLM 调用——用--use-plugins全局开启前先评估文档图片量必要时按文件类型做路由避免把纯文本文档也送进视觉模型单文档追求极致精度选 Doc Intelligence-d一条命令即可适合质检、财务等对版面保真敏感的场景多模态混合语料库会议录音 视频 报表直接上 CU一个 endpoint 通吃cu_file_types参数可精确圈定哪些格式走云、哪些留在本地把计费面收紧根 README 有示例监控手段任何链路都别忘了安全边界——根 README 的安全说明强调 MarkItDown 会以当前进程权限执行 I/O在不可信环境中务必使用最窄的convert_local()/convert_stream()并对输入做白名单校验。三板斧各有其位本地 OCR 解决看得见但读不出音频转写补上听得见但记不下Azure 云提取兜住精度不够、模态太杂。按文档画像组合使用才能让 Markdown 管线既省成本、又顶得住生产级质量要求。【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考