markitdown

文档转 Markdown

概述

使用 Microsoft 的 MarkItDown 工具，将各种文档格式转换为整洁的 Markdown。针对大模型处理、内容提取和文档分析工作流进行了优化。

支持的格式：PDF、Word（.docx）、PowerPoint（.pptx）、Excel（.xlsx/.xls）、图像（支持 OCR/大模型）、HTML、音频（支持转录）、CSV、JSON、XML、ZIP 压缩包、EPub

快速入门

基本用法

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

命令行

# Convert single file
markitdown document.pdf > output.md
markitdown document.pdf -o output.md

# Pipe input
cat document.pdf | markitdown

🔒 安全注意事项

在生产环境中使用前：

• ✅ 验证文件类型（检查 MIME 类型，而非扩展名）
• ✅ 限制文件大小（防止 DoS）
• ✅ 清理文件路径（防止路径遍历）
• ✅ 保护 API 密钥（切勿硬编码）
• ✅ 考虑数据隐私（外部服务）

实现详情请参阅 patterns.md。

API 密钥安全

❌ 切勿：

• 在代码中硬编码密钥
• 将 .env 文件提交到 git
• 记录环境变量

✅ 始终：

• 使用环境变量：export OPENAI_API_KEY="sk-..." # pragma: allowlist secret
• 使用密钥管理服务（AWS Secrets Manager、Azure Key Vault）
• 定期轮换密钥

常见模式

PDF 文档

# Basic PDF conversion
md = MarkItDown()
result = md.convert("report.pdf")

# With Azure Document Intelligence (better quality)
md = MarkItDown(docintel_endpoint="<your-endpoint>")
result = md.convert("report.pdf")

Office 文档

# Word documents - preserves structure
result = md.convert("document.docx")

# Excel - converts tables to markdown tables
result = md.convert("spreadsheet.xlsx")

# PowerPoint - extracts slide content
result = md.convert("presentation.pptx")

带描述的图像

# ✅ SECURE: Using environment variables for API keys
import os
from openai import OpenAI

api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise RuntimeError("OPENAI_API_KEY not set")

client = OpenAI(api_key=api_key)
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("diagram.jpg")  # Gets AI-generated description

批量处理

from pathlib import Path

md = MarkItDown()
documents = Path(".").glob("*.pdf")

for doc in documents:
    result = md.convert(str(doc))
    output_path = doc.with_suffix(".md")
    output_path.write_text(result.text_content)

安装

# Full installation (all features)
pip install 'markitdown[all]'

# Selective features
pip install 'markitdown[pdf, docx, pptx]'

要求：Python 3.10 或更高版本

主要功能

• 结构保留：保留标题、列表、表格和链接
• 插件系统：通过自定义转换器扩展
• Docker 支持：容器化部署
• MCP 集成：面向大模型应用的 Model Context Protocol 服务

何时阅读配套文件

• reference.md — 在需要以下内容时阅读：

  • 完整的 API 参考和所有配置选项
  • Azure Document Intelligence 集成详情
  • 插件开发指南
  • Docker 和 MCP 服务设置
  • 故障排查和错误处理

• examples.md — 在需要以下内容时阅读：

  • 特定文件类型的可运行示例
  • 批量处理工作流
  • 错误处理模式
  • 与现有管道集成

• patterns.md — 在需要以下内容时阅读：

  • 生产部署模式
  • 性能优化策略
  • 安全注意事项
  • 应避免的反模式

快速参考

文件类型	用途	命令
PDF	报告、论文	md.convert("file.pdf")
Word	文档	md.convert("file.docx")
Excel	数据表格	md.convert("file.xlsx")
PowerPoint	演示文稿	md.convert("file.pptx")
图像	带 OCR 的图表	md = MarkItDown(llm_client=client); md.convert("img.jpg")
HTML	网页	md.convert("page.html")
ZIP	压缩包	md.convert("archive.zip") - 处理其中的内容

⚠️ 应避免的常见错误

反模式 1：硬编码 API 密钥

# ❌ NEVER DO THIS
md = MarkItDown(llm_client=OpenAI(api_key="sk-hardcoded-key"))

# ✅ ALWAYS DO THIS
api_key = os.getenv("OPENAI_API_KEY")
md = MarkItDown(llm_client=OpenAI(api_key=api_key))

反模式 2：未验证文件路径

# ❌ Vulnerable to path traversal
user_input = "../../../etc/passwd"
md.convert(user_input)

# ✅ Validate and sanitize
from pathlib import Path
safe_path = Path(user_input).resolve()
if not safe_path.is_relative_to(allowed_dir):
    raise ValueError("Invalid path")
md.convert(str(safe_path))

反模式 3：忽略文件大小限制

# ❌ Can cause DoS
md.convert("huge_file.pdf")  # No size check

# ✅ Check size first
max_size = 50 * 1024 * 1024  # 50MB
if Path("file.pdf").stat().st_size > max_size:
    raise ValueError("File too large")

常见问题

导入错误：确保 Python >= 3.10 且已安装 markitdown
缺少依赖项：使用 pip install 'markitdown[all]' 安装
图像描述无法生成：需要大模型客户端（OpenAI 或兼容服务）

详细的故障排查信息请参阅 reference.md。