pptx-wzq · PPT 多模态教学知识库自动化构建

作者：吴振谦 · wuzhenqian@nbu.edu.cn · QQ：38328063 本项目帮助高校教师把教学 PPT 自动转化为图文并茂、可检索、可复用、可再加工的多模态教学知识库。 当前版本：3.4.2（PyPI：https://pypi.org/project/pptx-wzq/ · GitHub：https://github.com/wuzhenqian6611/pptx-wzq）

开发原因：高校教师在课程建设与教材建设中，长期面临「课件里的大量图片、公式、文本散落各处，难以整理为规范、可复用、图文并茂的教学资源」的痛点——手工整理一份课程的图文知识库往往要耗费数周。本工具把 PPT 自动转化为图文并茂的多模态教学知识库，让教师从机械整理中解放出来。

目录

• 一、它能做什么
• 二、安装与环境要求
• 三、快速开始
• 四、右键菜单（Windows 一键操作）
• 五、命令一览
• 六、输入 PPTX 预处理要求
• 七、工作流程（8 环节）
• 八、输出文档体系与内部格式
• 九、技术架构
• 十、图块识别规则（16 条）
• 十一、生命周期与可靠性
• 十二、常见问题
• 十三、版本演进
• 十四、文档与许可

一、它能做什么

输入一份教学 PPT（.pptx），自动完成 8 环节流水线：图块提取 → 文本提取 → 公式提取 → 图块 AI 解读 → 相关性过滤 → 教材文案（整篇自主分章分节）→ JSON 组装 → 输出。

核心能力：

• 图块（可视逻辑块）优先：以「组合即图块」为第一原则，作者用 PPT 组合工具绘制的逻辑图/示意图整体保留（原生 XML 段），而非拆散成碎片。
• 源语言级解构：grpSp 组合保留原生 XML 段（p:/a:/r: 前缀）；Visio/vsdx 剥离原生文件；公式转 LaTeX——信息不降维。
• 模型按块路由：有 XML 的块 → DeepSeek 读 XML（组内公式转 LaTeX）；纯像素图块 → qwen VLM 兜底；DeepSeek 空响应自动降级；blocks_json 步骤 qwen 视觉兜底按需触发（仅 caption 未解读的块读渲染图，避免重复解读）。
• 公式双通道：组合内公式既保留为组合块内容（XML 段），又进 formulas.md（语义存档）；OLE 预览图（公式/Visio 快照）判定后不污染图块体系。
• 运行过程全透明：所有模型调用（DeepSeek/qwen）的输入输出摘要实时打印（[DeepSeek]/[qwen] 前缀），用户可随时看到每一步在想什么、输出了什么。
• 教材级文案：整个 PPT 视为一部完整教材，DeepSeek 自主划分若干章（# 第X章 章名）、每章若干节（## 第X节 节名，一节可含多页），每页内容首行标注所属章节；500 字为限（原文 ≤500 字扩写到不少于 500 字；>500 字直出整理，不改原意、不增字数）。
• 生命周期自管：全流程成功即清理过程文件；中断保留断点、二次运行自动接续。

二、安装与环境要求

系统要求

安装

pip install pptx-wzq            # 核心
pip install "pptx-wzq[ocr]"     # 含本地公式 OCR（pix2tex，可选）

安装后自带完整文档（使用手册 + 技术分析）：

from pptx_wzq import docs
print(docs.__path__)   # 查看 docs/ 目录（含 html/pdf/md）

Windows 右键菜单（可选，推荐）

装包后无需手动操作：包内 .pth 钩子在任意 Python 进程启动时自动注册右键菜单 （幂等；非 Windows 自动跳过；也可手动 pptx-wzq-menu install 立即注册）。注册后：

相关命令：

pptx-wzq-menu install     # 手动注册右键菜单（HKCU，无需管理员）
pptx-wzq-menu uninstall   # 卸载右键菜单
pptx-wzq-menu status      # 查看已注册命令

排障：右键流程每步写入 %TEMP%\pptx_wzq_launcher.log（目标/确认结果/子进程返回码）， 异常时据此定位。若右键菜单不出现，先重启"Windows 资源管理器"刷新菜单缓存。

权重来源与许可：图片过滤内置的 YOLO 模型权重 yolov5su.pt 来自 ultralytics（YOLO 官方），采用 AGPL-3.0 许可证随包分发；商用或闭源使用请自行评估其开源条款。

三、快速开始

# 一条命令跑完 8 环节（推荐）
pptx-paser "C:\课件\战略管理.pptx" -o "C:\输出\战略管理知识库"

# 跳过相关性与文案（省 Token）
pptx-paser "C:\课件\战略管理.pptx" -o out --skip related,author

# 断点续传（中断后重跑同命令自动接续）
pptx-paser "C:\课件\战略管理.pptx" -o out

四、右键菜单（Windows 一键操作）

详见上文「二、安装与环境要求 → Windows 右键菜单」。一句话：pip install -U pptx-wzq 后 下一次任意 Python 启动即自动注册；手动方式 pptx-wzq-menu install。

五、命令一览

六、输入 PPTX 预处理要求

核心思想：用 PPT 自带工具给解析器打「块边界」标注。 组合的数量 = 该页图块数量的上限基准，可据此验收。预处理不是必须的（无组合也能跑），但组合能让图块提取完全确定、可回归。

七、工作流程（8 环节）

① blocks → ② text → ③ formula → ④ caption → ⑤ related → ⑥ author → ⑦ blocks_json → ⑧ 输出

模型路由（规则 11/16）：DeepSeek-V4-Flash 读 sources/ 的 XML 段（grpSp/Visio-XML/SVG-WMF，公式转 LaTeX）；qwen3.7-plus 读像素图原图——仅纯像素图块 / DeepSeek 空响应兜底。

八、输出文档体系与内部格式

结果目录结构（成功运行后）

<名>_result/
├─ sources/                          # 图块源资源（解读唯一输入源）
│  ├─ slide_07_blk_01_grp.xml        # grpSp XML 段（页注释 + 原生前缀，规则10）
│  ├─ slide_05_blk_02.vsdx            # Visio 可剥离（规则13）
│  ├─ slide_05_blk_03_ole.xml         # Visio 不可剥离 → XML（规则14）
│  ├─ slide_08_blk_04_vec.xml         # SVG/WMF 矢量 XML（规则15）
│  ├─ slide_19_blk_01.png             # 像素图块原图（qwen 解读输入，规则16）
│  └─ rldimg/                         # grpSp XML 内 r:embed 引用的资源图片
├─ images/                           # 块渲染图（PowerPoint，仅供人阅览）
├─ <名>_visual_blocks.json             # 核心结构化（pptx_multimodal_slide_v2.0）
├─ <名>_visualBlock_text_binding.json  # 图文关联（pptx_visual_block_text_binding_v1.0）
├─ <名>_textbook.md                   # 教材文案（篇→章→节→页，每页标注章节）
├─ <名>_captions.md                   # 块解读（绑定 sources/ 文件名 + 解读通道）
├─ <名>_texts.md / _text_entries.json   # 文本清单（组内文字标[图块内文本]）
├─ <名>_formulas.md                     # 非组合公式（LaTeX）
└─ <名>_related_filter.json              # 相关性过滤审计
（v2.0 起成功即清理：无 过程文件/；中断时保留断点供续传）

VisualBlock 内部格式（visual_blocks.json 的块对象）

{
  "block_id": "blk_01", "page": 7, "block_type": "战略管理概念框架",
  "bbox": {"x": 142.3, "y": 226.4, "w": 1026.2, "h": 400.2},
  "z_index_range": [12, 45], "is_single": false,
  "text": "战略哲学 商道 天道 人道 …",
  "assets": {
    "xml_source": "./sources/slide_07_blk_01_grp.xml",
    "raster_png": null,
    "rldimg": ["./sources/rldimg/slide_07_blk_01_image4.png", "…"]
  },
  "internal_structure": {"nodes": ["…"], "edges": ["…"]},
  "semantic_description": {
    "block_type": "战略管理概念框架",
    "expression_goal": "展示战略管理概念框架的核心逻辑",
    "expression_role": "将抽象概念通过战略哲学/商道/天道/人道具象化…",
    "expression_features": ["概念框架", "层次结构", "关系图"],
    "vlm_caption": "该图块以“战略哲学”为中心…",
    "teaching_use": "教学辅助图示",
    "formula_latex": "", "caption_source": "deepseek_xml"
  },
  "member_obj_ids": ["…"], "vector_resources": []
}

textbook.md 结构（v2.3 起）

# <名> 教材文案
# 第1章 战略管理概述          ← DeepSeek 自主命名
## 第1节 战略的概念与本质      ← 自主命名，一节可含多页
## 第 N 页
> 所属章节：第1章 战略管理概述 · 第1节 战略的概念与本质   ← 每页首行标注
（不少于 500 字正文…）

九、技术架构

十、图块识别规则（16 条）

识别层（1-9）——「组合即图块声明」

解构/解读层（10-16）

十一、生命周期与可靠性

• 成功即清理：全流程成功后中间产物（by_page/atomic_objects.json/manifest/各步骤工作目录）全部删除，结果目录只留交付物；删除失败打印警告而非静默。
• 中断续传：中断保留 work + state.json（步骤状态机 pending/running/partial/done/failed）；再运行跳过已完成、自动接续缺失；doc_md5 换源检测 → 全量重跑；author 支持缺失页补跑（--pages）。

十二、常见问题

十三、版本演进

十四、文档与许可

• 文档：完整「使用手册与技术分析」（HTML/PDF）随安装包分发于 src/pptx_wzq/docs/，安装后可 from pptx_wzq import docs 定位；README（本文档）为全量文字版。
• 许可证：MIT（本项目代码）；随包 YOLO 权重 yolov5su.pt 为 AGPL-3.0（见上文）。