企业官网建设流程全解析

markitdown 图像处理完全指南：AI 描述 + 元数据，把图片一键变 Markdown

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown

第一次用 markitdown 做图像处理时，我直接踩了个坑：把一堆 .jpg 丢进去，转换结果是一段空字符串。不报错，就是空白。原因很简单：这些图片本身没带 EXIF 信息，而我又没配置大模型。markitdown 的图片处理只从两条通道取信息——本地元数据、AI 描述——两条通道都没接上，自然无米下锅。这篇笔记把 markitdown 的图像转 Markdown 机制讲清楚：两条通道各需要什么、怎么选，以及怎么一次跑通。

一、它到底能帮你做什么：先划清边界

一句话定位：markitdown 把图片当作"带信息的文件"而不是"像素文件"——它提取的是结构化元数据和文字描述，不碰像素本身。

能做：

• 单独转换.jpg/.jpeg/.png为 Markdown
• 读取 EXIF 元数据：尺寸、标题、作者、拍摄时间、GPS 坐标等
• 调多模态大模型，生成图片的自然语言描述
• 配合 markitdown-ocr 插件，识别 PDF / DOCX / PPTX / XLSX里嵌的图（扫描件的全文 OCR 也走这条路）

不能做：

• 不做像素级分析：没有目标检测、图像分割，"图里有几个人"这种得靠描述文本自己判断
• 只认 jpg/jpeg/png，webp、bmp、gif 不会被图片转换器接收
• AI 通道必须有网络：它调的是 OpenAI 兼容接口，离线跑不了
• 不处理"图片以外的容器"：比如一张 TIF 里的图，它管不了

实现代码集中在 packages/markitdown/src/markitdown/converters/，其中_image_converter.py就是入口，逻辑很短，值得直接读一遍。

二、两条提取路径：元数据 vs AI 描述

markitdown 对一张图做转换时，两条路径是默认都跑的：元数据跑本地，AI 描述跑网络，谁有结果谁拼进输出。

怎么选，看你要的是哪类信息：

• 要事实（谁拍的、什么时候、在哪、多大）→ 元数据路径就够了，零成本
• 要语义（图里是什么、适合当 alt 文本、能被 grep 到）→ 必须走 AI 描述
• 两边都想要 → 什么都不用选，默认行为就是同时输出

细节上，exiftool 的路径查找顺序是：构造参数 →EXIFTOOL_PATH环境变量 → 系统 PATH 自动探测，这套逻辑在 packages/markitdown/src/markitdown/_markitdown.py 里。AI 路径默认提示词是 "Write a detailed caption for this image."，你可以用llm_prompt换成自己的中文指令，比如"以学术插图标注标准描述此图"。

三、最小可运行示例

先把依赖装好（markitdown+openai），然后跑这段：

from markitdown import MarkItDown from openai import OpenAI md = MarkItDown( llm_client=OpenAI(), # 需要环境变量 OPENAI_API_KEY llm_model="gpt-4o", ) result = md.convert("test_llm.jpg") print(result.text_content)

仓库里自带了一张测试图 packages/markitdown/tests/test_files/test_llm.jpg，红圆加蓝方块，图里还埋了一行文字。用它验证配置是最快的手段：

预期输出分两段：前面是元数据行（如果你装了 exiftool），后面是描述段。模型输出会有差异，但要点是图里那行字、红圆和蓝方块都得被提到：

ImageSize: 1692x948 # Description: 图片左侧是一个红色圆形，右上方是一个蓝色正方形， 上方文字要求描述中提及字符串 "5bda1dd6"。

仓库的单元测试（packages/markitdown/tests/test_module_misc.py）正是拿"描述里必须出现5bda1dd6"来断言的——你也可以用这个思路给自己的接入写个冒烟测试。

四、三个落地场景

1. 图片库批量加"可检索的注脚"产品截图、设计稿这类图基本不带 EXIF，元数据路径帮不上忙，但 AI 描述可以。写个循环把文件夹里的图转成同名 .md，每段描述就是一句"这张图讲什么"，整个图库从此能被grep命中。截图多的技术文档团队，这是最直接的收益。

2. 归档与无障碍：让老照片带上身份相机直出的照片 EXIF 齐全，Artist、DateTimeOriginal、GPSPosition免费拿到；再让 LLM 补一段场景描述，等于给每张图生成了 alt 文本。做无障碍网页、写回忆录式归档时，这一步省得你手写几千条描述。

3. 扫描件文档找回文字（OCR 插件）上面的路径只认"裸图"。如果文字是被嵌在文档里的扫描件，要用 markitdown-ocr 插件——它复用同一套llm_client/llm_model参数，支持 PDF 整页 OCR 兜底：

md = MarkItDown( enable_plugins=True, llm_client=OpenAI(), llm_model="gpt-4o", ) print(md.convert("发票扫描件.pdf").text_content)

插件源码在 packages/markitdown-ocr/src/markitdown_ocr/，测试数据里就有扫描发票、扫描会议纪要这些真实样例，想先看效果可以从那里挑。

五、踩坑速查

六、选型与边界

该用它：

• 手头是独立 jpg/png，想要"元数据 + 一句话描述"的 Markdown 产出，不想自己拼 OpenAI 请求
• 文档里嵌了扫描图，想低成本把它们变成可检索文本（走 OCR 插件）
• 已经用 OpenAI 兼容客户端做别的事，顺手把图片转换挂进同一条流水线

别用它：

• 要像素级能力（检测、分割、超分）——它不碰图像本身，找专业 CV 库
• 纯离线环境：AI 通道必须联网，元数据通道又依赖 exiftool 二进制，两头都卡
• 图片大量嵌在 webp/非支持容器里，预处理成本可能比直接上 OCR 框架更高
• 对描述措辞有强合规要求：默认提示词很泛，务必传llm_prompt并用小样本验收后再放量

markitdown 的图像处理本质是两件事的拼装：本地 exiftool 给事实，多模态 LLM 给语义，缺一条就空一条。给你的建议就一个：别在真实业务图上调，先拿仓库自带的 test_llm.jpg 把两条通道各跑通一次，输出里同时出现元数据行和# Description:段，这套配置才算真正接好了。

【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址: https://gitcode.com/GitHub_Trending/ma/markitdown