文档知识图谱结构化抽取

功能概述

从 docx/pdf 文档中抽取层次化知识节点，标注节点类型和语义关系，输出可直接导入知识图谱系统的结构化文件。

核心能力：

• 抽出至少 6 级层次化知识节点（支持最高7级）
• 标注节点类型（分类/知识点）
• 识别语义关系（前置/后置/关联）
• 输出 CSV 和 Excel 格式文件

技术架构：

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   文档解析    │───→│  LLM 语义抽取 │───→│   格式验证    │───→│  Excel 生成  │
│   (脚本)     │    │   (LLM)      │    │   (脚本)     │    │   (脚本)     │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
      │                    │                   │                   │
      ▼                    ▼                   ▼                   ▼
  提取纯文本          语义理解+推理        验证格式约束         生成标准输出
  解析模板           生成节点+关系        修复格式错误

输入参数

使用步骤

步骤 1: 解析模板规则

MANDATORY - 阅读整个文件: 使用脚本解析模板，获取格式约束：

python scripts/extract_knowledge_graph.py --template template-knowledge-graph.xlsx --dry-run

MANDATORY - 读取完整文件: 阅读 references/output-format.md 了解列结构约束。

步骤 2: LLM 语义化知识抽取（核心步骤）

此步骤由 LLM 执行语义理解和知识抽取。

2.1 读取 Prompt 模板

MANDATORY - 读取完整文件: 阅读 references/extraction-prompt.md 获取完整 Prompt 模板。

2.2 执行 LLM 抽取

使用 references/extraction-prompt.md (~391 lines) 中的完整 Prompt 模板进行知识抽取。该模板包含所有抽取规则、字段说明和示例。

2.3 LLM 抽取检查清单

抽取完成后，LLM 应自检：

• 节点顺序：父节点在子节点之前，按深度优先顺序
• 节点类型正确：Level 1-3="分类"，Level 4-7="知识点"
• 知识分类约束：分类节点category为空，知识点节点填写分类值
• 教学目标完整性：知识点的教学目标描述具体可衡量
• 排除教学管理信息：未抽取课程性质、教学学时、评价标准等
• 每个知识点名称简洁准确（不超过30字）
• 层级正确反映知识的从属关系
• 前置关系符合学习逻辑
• 已过滤非知识内容

步骤 2.4: 质量校验与修正（重要）

MANDATORY - Agent自检并自动修正

MANDATORY - READ ENTIRE FILE: 阅读 references/quality-check-prompt.md (~146 lines) 获取校验方法与修正指导。

抽取完成后，Agent必须执行质量校验。发现问题后，Agent直接修正JSON文件，无需用户干预。

校验清单与修正规则

执行流程

1. Read 工具读取生成的 JSON 文件
2. 遍历所有节点，逐一检查上述11项
3. 发现问题 → 立即使用 Edit 工具修正
4. 修正完成后重新校验（循环直到全部通过）
5. 输出校验报告，确认所有项✅

如需查看校验示例，阅读 references/quality-check-prompt.md 中的"校验示例"部分。

校验通过标准

所有校验项必须全部通过：

调用脚本校验（可选）

如需脚本辅助校验，可运行：

python scripts/extract_knowledge_graph.py \
  --json knowledge_nodes.json \
  --template template-knowledge-graph.xlsx \
  --output output.xlsx \
  --validate-only

脚本输出详细问题清单，Agent据此逐一修正。

步骤 3: 关系推理（可选增强）

MANDATORY - READ ENTIRE FILE: 阅读 references/relation-prompt.md (~167 lines) 进行关系推理。模板包含前置关系和关联关系的完整识别规则。

前置关系识别规则：

关联关系识别规则：

步骤 4: 格式验证与 Excel 生成

将 LLM 输出的 JSON 数据传入脚本，生成 Excel 文件：

python scripts/extract_knowledge_graph.py \
  --json knowledge_nodes.json \
  --template template-knowledge-graph.xlsx \
  --output output.xlsx

脚本自动验证：

• 节点类型正确（A列为"分类"或"知识点"）
• 每行只有一个节点名称 (B-H列)
• 分类节点M列为空
• 分隔符为英文分号
• 树状结构完整性

步骤 5: 输出结果

1. output.xlsx - 结构化抽取结果的 Excel 文件
2. output.csv - CSV 格式备份（可直接导入知识图谱工具）
3. 抽取统计 - 节点数量、层级分布、节点类型分布、关系类型等

列名固定约束

Excel 第二行的列名是固定不变的，由脚本生成时硬编码写入。列名对应关系如下：

重要：请勿修改任何列名。下游系统（超星泛雅等）依赖这些列名进行数据导入。列名不匹配会导致导入失败。

输出格式核心约束

核心原则（必须遵守）：

• 每行只能填写一个节点名称（树状结构，仅一个单元格有值）
• 分类节点 M列必须留空（知识点分类仅适用于知识点节点）
• 任意两节点之间只能存在一种关系（前置、后置或关联）
• 分隔符使用英文分号 ;（不使用中文分号 ；）

详细格式规则：开始填充前，MANDATORY - READ ENTIRE FILE： references/output-format.md (~289 lines)

Do NOT load：如果只是理解流程概念，不需要加载详细格式规则。只有实际生成输出时才需要加载。

关键 Anti-Patterns（重要）

绝对禁止做这些 — 会导致导入失败：

1. NEVER 分类节点填写知识分类

❌ 错误: A列="分类", M列="概念性"
✅ 正确: A列="分类", M列=""  # 分类节点M列必须留空

Why: 模板规则明确：分类节点不支持填写知识点分类。

2. NEVER 一行填写多个节点名称

❌ 错误: ['一级节点', '二级节点', '三级节点', '', '', '', '', '']
✅ 正确: ['一级节点', '', '', '', '', '', '', '']  # 每行只有一个节点名称

Why: 导入系统使用树结构。每行表示 ONE 节点。位置表示层级。

3. NEVER 使用中文分号分隔关系

❌ 错误: 知识节点A；知识节点B；知识节点C
✅ 正确: 知识节点A;知识节点B;知识节点C

Why: 解析器期待 ASCII 分号 (;, U+003B)，不是中文分号 (；, U+FF1B)。

4. NEVER 填写多个知识分类

❌ 错误: M列 = "事实性;概念性"
✅ 正确: M列 = "事实性"  # 单选值

Why: 知识分类字段是单选。多个值会导致导入失败。

5. NEVER 不完整的层级路径

❌ 错误: 
  行1: [B列: 模块] 
  行2: [D列: 章节]  # 跳过了C列

✅ 正确:
  行1: [B列: 模块]
  行2: [C列: 单元]
  行3: [D列: 主题]

Why: 每个知识节点必须有完整的父链。跳跃层级会破坏树结构。

6. NEVER 遗漏关联关系

❌ 错误: K列全部为空
✅ 正确: K列包含语义相关的知识点（同类、对比、相似原理）

Why: 关联关系是知识图谱的重要组成部分，缺失会降低图谱质量。

7. NEVER 修改Excel列名

❌ 错误: 修改Excel输出的第二行列名
✅ 正确: 保持脚本生成的标准列名不变

Why: 列名是硬编码的，用于下游系统导入。列名不匹配会导致导入失败。

8. NEVER 使用缩写名称作为关系引用

❌ 错误: "pre_requisites": ["半身裙结构图的绘制"]  # 实际节点名缺少"与工业样板的制作"
✅ 正确: "pre_requisites": ["半身裙结构图的绘制与工业样板的制作"]  # 与name完全一致

Why: 关系引用（I列前置节点、K列关联节点）按节点 name 字段精确匹配。名称不一致会被视为引用不存在的节点，导致关系丢失。

抽取决策框架

LLM 抽取时应遵循的决策逻辑：

1. 边界判断

问题: 这个节点能独立存在吗？

2. 层级定位

问自己三个问题：

Q1: 上级 - 这个节点属于哪个模块/章节？
Q2: 下级 - 这个节点包含哪些具体内容？  
Q3: 平级 - 还有哪些同类节点？

3. 节点类型判断

根据层级自动判断节点类型：

4. 关系识别

前置关系 (I列)：

• 基础概念 → 高级概念 (电阻 → 欧姆定律)
• 工具使用 → 应用操作 (万用表 → 测量电流)
• 理论知识 → 实践技能 (电路原理 → 电路安装)

关联关系 (K列)：

• 同一主题下的并列节点 (电阻 ↔ 电容 ↔ 电感)
• 相似或对比概念 (直流电路 ↔ 交流电路)
• 不同章节但逻辑相关的节点

参考文件加载指引

references 目录（工作流程参考）

examples 目录（示例模板与文档）

⚠️ 注意：

• references 文件是 Agent workflow 的组成部分，Agent 需要读取它们来了解如何执行对应任务
• examples 文件仅用于演示和测试，实际抽取任务时应使用用户提供的文档

兼容性

• 可导入平台：超星泛雅和学银在线平台
• 源文档格式：docx、pdf
• 模版格式：xlsx

验证规则与提示信息

脚本在处理过程中会输出以下验证提示：

故障排除

脚本执行失败

LLM 抽取质量问题

输出文件问题