MinerU 深度优化
本文档详细说明 NotebookLM2PPT 中 MinerU 深度优化功能的技术实现细节，适合技术人员参考。
🧠 核心原理
MinerU 优化功能通过解析 MinerU 生成的 JSON 文件，提取页面结构信息，对基础转换生成的 PPT 进行深度优化，提升排版质量、图片清晰度和文本准确性。
🔧 核心模块
文件: notebooklm2ppt/utils/ppt_refiner.py
主要函数:
python
def refine_ppt(tmp_image_dir, json_file, ppt_file, png_dir, png_files, final_out_ppt_file)参数说明:
tmp_image_dir: 临时图片目录json_file: MinerU 生成的 JSON 文件路径ppt_file: 基础转换生成的 PPT 文件路径png_dir: PDF 转换生成的 PNG 图片目录png_files: PNG 文件列表final_out_ppt_file: 最终输出的优化后 PPT 文件路径
📊 优化流程
1. 智能文本框筛选
问题: 基础转换可能会识别出无关的文本框
解决方案: 使用 IOU（交并比）算法评估文本框与 PDF 内容块的重叠程度
实现:
python
def compute_iou(boxA, boxB):
# 计算两个矩形的交集面积
xA = max(boxA[0], boxB[0])
yA = max(boxA[1], boxB[1])
xB = min(boxA[2], boxB[2])
yB = min(boxA[3], boxB[3])
interWidth = max(0, xB - xA)
interHeight = max(0, yB - yA)
interArea = interWidth * interHeight
boxAArea = (boxA[2] - boxA[0]) * (boxA[3] - boxA[1])
boxBArea = (boxB[2] - boxB[0]) * (boxB[3] - boxB[1])
iou = interArea / float(boxAArea + boxBArea - interArea)
return iou筛选逻辑:
- 计算每个文本框与 PDF 内容块的 IOU
- 保留 IOU > 0.01 的文本框（相关性强）
- 删除 IOU ≤ 0.01 的文本框（可能是无关元素）
2. 字体统一处理
问题: 基础转换生成的 PPT 中，文本框字体可能各不相同
解决方案: 统一所有文本框字体为"微软雅黑"
实现:
python
# 创建微软雅黑字体对象
newFont = TextFont("微软雅黑")
# 遍历文本框中的所有文本范围
for textRange in paragraph.TextRanges:
textRange.LatinFont = newFont3. 高质量图片替换
问题: 基础转换过程中图片可能被压缩或质量降低
解决方案: 从 MinerU JSON 提取原始高清图片并替换
实现:
python
def download_image(image_url, tmp_image_path):
if os.path.exists(tmp_image_path):
return # 避免重复下载
response = requests.get(image_url)
with open(tmp_image_path, 'wb') as f:
f.write(response.content)
# 替换 PPT 中的图片
image = slide.Shapes.AppendEmbedImageByPath(ShapeType.Rectangle, tmp_image_path, rect1)
image.Line.FillType = FillFormatType.none
image.ZOrderPosition = 0 # 设置图片在最底层4. 智能背景处理
问题: 需要平衡纯色区域填充和复杂背景保留
解决方案: 基于边缘多样性和颜色差异的智能判断
实现:
python
# 计算边缘多样性
def compute_edge_diversity(image_cv, left, top, right, bottom):
# 提取四条边缘并计算颜色标准差
# ...
return diversity
# 计算四点颜色差异
def compute_four_point_diff(image_cv, left, top, right, bottom):
# 获取四个角的颜色并计算差异
# ...
return np.mean(diffs)
# 智能决策
if diversity < 10 and diff < 9:
# 纯色区域，填充平均颜色
cv2.rectangle(image_cv, (l, t), (r, b), fill_color, thickness=-1)
else:
# 复杂背景，保留原背景
image_cv[t:b, l:r] = old_bg_cv[t:b, l:r]📈 完整工作流程
1. 数据准备
python
# 1. 加载 MinerU JSON
data = load_json(json_file)
pdf_info = data['pdf_info']
# 2. 根据页码筛选信息
indices = get_indices_from_png_names(png_files)
pdf_info = [pdf_info[i] for i in indices]
# 3. 计算缩放比例
pdf_w, _ = pdf_info[0]['page_size']
presentation = Presentation()
presentation.LoadFromFile(ppt_file)
ppt_H, ppt_W = presentation.SlideSize.Size.Height, presentation.SlideSize.Size.Width
ppt_scale = ppt_W / pdf_w2. 逐页处理
python
for page_index, slide in enumerate(presentation.Slides):
# 1. 智能文本框筛选和字体统一
# 2. 高质量图片替换
# 3. 智能背景处理3. 保存结果
python
presentation.SaveToFile(final_out_ppt_file, FileFormat.Pptx2019)
print(f"优化完成! 输出文件: {final_out_ppt_file}")
# 清理 PPT
clean_ppt(final_out_ppt_file, final_out_ppt_file)🔍 关键算法
IOU（交并比）算法
应用: 文本框筛选 原理: 计算两个矩形区域的重叠程度 阈值: 0.01（经过实验验证的合理阈值）
边缘多样性检测算法
应用: 背景处理 原理: 计算文本块边缘的颜色多样性 阈值: 10（边缘颜色变化小，认为是纯色区域）
四点颜色差异算法
应用: 背景处理 原理: 计算文本块四个角的颜色差异 阈值: 9（四个角颜色差异小，认为是纯色区域）
⚙️ 技术参数
| 参数 | 默认值 | 作用 | 影响 |
|---|---|---|---|
| IOU 阈值 | 0.01 | 文本框筛选 | 影响文本框保留数量 |
| 边缘多样性阈值 | 10 | 背景处理 | 影响纯色区域判断 |
| 四点差异阈值 | 9 | 背景处理 | 影响复杂背景保留 |
| 图片缓存 | 启用 | 性能优化 | 减少重复下载 |
🚀 性能优化
- 图片缓存: 已下载的图片会缓存到
tmp_image_dir，避免重复下载 - 并行处理: 支持并行处理多个页面，提升转换速度
- 内存管理: 处理完每页后及时释放临时变量，避免内存占用过高
🐛 故障排查
常见问题
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 图片下载失败 | 网络连接问题或 URL 无效 | 检查网络连接，确认 JSON 中的图片 URL |
| 文本框筛选不准确 | IOU 阈值不合适或 JSON 解析质量差 | 调整 IOU 阈值，检查 JSON 质量 |
| 背景处理效果不理想 | 阈值设置不合适 | 调整边缘多样性和四点差异阈值 |
| 优化速度慢 | 文档较大或网络速度慢 | 分批处理，确保网络连接稳定 |
调试建议
- 启用调试模式: 设置环境变量
NOTEBOOKLM2PPT_DEBUG=1 - 检查 JSON 文件: 确认 JSON 文件格式正确，包含完整的页面信息
- 验证图片 URL: 手动访问 JSON 中的图片 URL，确认可访问
- 调整阈值: 根据实际情况调整算法阈值
📚 技术依赖
- Spire.Presentation: 用于 PPT 操作和修改
- NumPy: 用于数值计算和数组操作
- OpenCV: 用于图像处理和分析
- Requests: 用于下载 MinerU 图片
- Pillow: 用于图像处理