MarkItDown
评估 MarkItDown 性能：别让提取失败消失在吞吐量里
按格式设计转换基准，核算缓冲与可选服务，并以真正可接受的文档数衡量性能和成本。
你将学会
- 同时报告验收通过数量和提取质量。
- 明确测量不可 seek 输入缓冲与并发影响。
- 外部服务成本应与本地解析分开。
开始前需要
- 具备基础 Python 与命令行知识
- 准备一份内容可核验且不含敏感信息的文档
使用本章清单解释并验证文档导入流程中的对应环节。
先看结论
- 同时报告验收通过数量和提取质量。
- 明确测量不可 seek 输入缓冲与并发影响。
- 外部服务成本应与本地解析分开。
统计仍然有用的文档
一个快速转换器如果丢掉决定性的表格，就没有快速完成你的导入任务。为样本集标注预期事实，同时报告耗时与保留事实的比例。按格式和复杂度分组，不能用短文本与大型扫描件的平均值掩盖真实工作量。
最初的报告应记录输入字节数、适用时的页数或幻灯片数、extras、插件设置、依赖版本和失败情况。把冷启动与预热进程分开测量；复用已初始化的转换器，与每个文件都启动一次 CLI，衡量的是不同成本。
在真实路径上寻找时间和内存开销
核对的 convert_stream 会先把不可 seek 的输入复制进内存，格式依赖还可能另有缓冲。除了耗时，也要测量进程峰值内存，尤其是在多个任务共用工作进程时。上传接口接收流，不足以证明解析过程使用恒定内存。
可选图像描述模型与云端文档服务会增加网络、服务等待和计费。应把这些调用与本地提取分开测量，不要把外部服务延迟算成解析器自身延迟，也不要把本地与云辅助运行当成输出语义完全相同的比较。
发布别人能够复现的测量
重复运行、说明硬件，并报告分布而不是最好的一次耗时。失败转换和被验收拒绝的输出都应计入分母。总处理及复核成本除以通过验收的文档数，是更贴近实际工作目标的运行指标。
下方计时器只测量一次本地调用，既不统计峰值内存，也不能证明输出质量。做性能结论前，应增加样本事实评估器和进程级资源采样。本文提供测量设计，不编造吞吐数据，也不虚构关键词搜索需求。
实施步骤
- 1
按格式和复杂度建立带事实标签的样本集。
- 2
记录环境、插件与转换选项。
- 3
重复测量冷启动和预热运行，保留失败记录。
- 4
先验收事实，再计算每份通过文档的成本。
可复制示例
from time import perf_counter
from markitdown import MarkItDown
converter = MarkItDown(enable_plugins=False)
start = perf_counter()
result = converter.convert_local("example.docx")
elapsed = perf_counter() - start
print({"seconds": elapsed, "characters": len(result.markdown)})常见问题
输出字符数是质量得分吗？
不是。它可以暴露空输出或异常短的结果，但不能证明正确事实得到保留。
本文有实测吞吐量吗？
没有。这里提供可复现的测量方法和计时示例，不把未执行的基准当作结果。