MarkItDown
部署 MarkItDown：构建资源受控的文档转换工作进程
围绕本地输入、格式依赖、资源限制与结果保存设计转换工作进程，明确哪些能力来自上游库、哪些需要应用实现。
你将学会
- 上传、队列和结果交付由外围应用负责。
- 运行时、extras 和选项应作为一个环境固定。
- 内容检查通过后再发布完整结果。
开始前需要
- 具备基础 Python 与命令行知识
- 准备一份内容可核验且不含敏感信息的文档
使用本章清单解释并验证文档导入流程中的对应环节。
先看结论
- 上传、队列和结果交付由外围应用负责。
- 运行时、extras 和选项应作为一个环境固定。
- 内容检查通过后再发布完整结果。
转换库并不是任务服务
MarkItDown 提供转换函数和 CLI。要构建带队列的上传服务，还必须决定谁可以提交文件、文件保存在哪里、转换最长执行多久，以及调用方如何取回结果。本文的工作进程方案属于集成设计，不是上游自带的托管服务。
把接收上传与执行转换分开：校验允许的大小和类型，分配任务标识，再把输入放到工作进程可读取的位置。使用选定依赖转换，并在结果检查通过后发布 Markdown。这样才能区分上传失败与解析器失败。
把运行时与格式依赖一起固定
可复现的工作进程镜像应固定 Python、实际解析的 MarkItDown 版本，以及允许格式所需的 extras。如果启用了图像描述或云转换，其设置和依赖也应纳入环境定义。安装依赖并不会自动创建外部服务或提供凭据。
README 还展示了从仓库构建 Docker 镜像并通过标准输入传入文件的方式。采用前应检查所选版本的 Dockerfile。生产队列所需的容器资源上限和可写输出目录，应在外围部署系统中配置；使用 CLI 本身不会提供这些限制。
明确重试和结果发布语义
用源文件字节、转换器版本和选项共同标识一次转换。对同一个不可变任务重试时，应新增尝试记录，不能让部分输出悄悄覆盖成功结果。先暂存输出，检查后再向任务消费者开放，是更清晰的发布流程。
即使源文档不变，依赖升级也可能改变提取文本。把代表性样本纳入发布检查，并保留旧环境用于回退。回退时同时考虑输出结构与消费者的假设；仅切换容器标签，并不能撤销已经写入索引的数据。
实施步骤
- 1
定义允许的格式并选择依赖。
- 2
建立输入目录只读的隔离工作进程。
- 3
先转换小样本，检查后再发布结果。
- 4
每次环境升级前重放样本。
可复制示例
from pathlib import Path
from markitdown import MarkItDown
# 使用工作进程分配的固定路径，不接受任意用户路径。
result = MarkItDown(enable_plugins=False).convert_local("/input/example.docx")
if not result.markdown.strip():
raise ValueError("Conversion returned no usable text")
Path("/output/example.md").write_text(result.markdown, encoding="utf-8")常见问题
这个包提供上传 API 和队列吗？
不提供。这些属于外围应用，本文介绍的是一种集成设计。
转换失败后都能直接重试吗？
不能。应区分临时基础设施故障、不支持的输入和稳定复现的内容错误，并保留尝试记录。