ReportRAG

基于 GraphRAG 的 8D 质量报告知识图谱构建系统，支持从 8D 报告中自动提取实体、关系，构建可查询的知识图谱。

系统架构

系统由三个核心模块组成，采用流水线架构处理 8D 报告：

JSON/Markdown 输入
       ↓
┌─────────────────┐
│ chunk_generator │  → 逐行格式 chunks
└─────────────────┘
       ↓
┌──────────────────┐
│ entity_extractor │  → 实体列表
└──────────────────┘
       ↓
┌────────────────────────┐
│ relationship_extractor │  → 关系列表
└────────────────────────┘
       ↓
CSV/JSON 输出

模块详解

1. chunk_generator.py

负责从原始数据生成逐行格式的内容块（chunks）。

输入: JSON 文件（{report}_content_list.json）和可选的 Markdown 文件

处理流程:

1. JSON 解析: 读取解析后的文档内容，过滤掉 header/footer/page_number 等元数据
2. Markdown 补充:
   • 提取 Markdown 中的 HTML 表格（某些表格在 JSON 中可能识别不完整）
   • 提取 Markdown 中的图片引用
3. 图片匹配: 基于关键词匹配将 Markdown 中的图片关联到文本内容
   • 提取文本中的关键词（产品型号、缺陷类型、组件）
   • 与图片上下文进行匹配
   • 按匹配度排序并去重
4. 二级标题提取:
   • 表格: 从表格内部提取（如 Customer Complain info / 客户投诉信息）
   • 表格: 从表格前导说明文字提取（如 Ø 封装厂生产现场497K产品信息）
   • 图片: 从 Markdown 标题提取（如 Failure Description & Photo、包装外观确认）
   • 同一组图片（如包装外观确认下的多张图片）共享同一个二级标题
5. caption 提取:
   • 图片: 图注文字（如 外箱；无异常）
   • 表格: 前导说明文字（如 2024total 出货V客户2.62KK...）
6. 章节检测: 基于关键词识别 D0-D8 章节
   • D0-metadata: 8d report, customer complain
   • D1-team: team, 团队, 成员
   • D2-problem: problem, 问题描述, failure description
   • D3-containment: containment, 围堵措施, sorting
   • D4-root-cause: root cause, 根本原因, 原因分析
   • D5-corrective: corrective, 纠正措施, action
   • D6-verification: verification, 效果验证, verify
   • D7-prevention: prevention, 预防措施, prevent
   • D8-closure: closure, 团队祝贺, conclusion

输出字段:

• id: 哈希生成的唯一标识
• human-readable_id: 顺序序号（1, 2, 3...）
• chunk: 内容（文本/HTML/图片路径）
• 格式: text/table/image
• Dn: D章节代码（D0-metadata, D2-problem等）
• D-title: 章节中英文标题
• chunk_type: 二级标题英文
• chunk_title: 二级标题中文
• caption: 图注/说明文字（图片的caption或表格的前导说明）
• document_id: 报告名称

二级标题提取示例:

元素类型	二级标题 (chunk_title)	caption
客户投诉表格	Customer Complain info / 客户投诉信息	-
围堵区域表格	围堵区域 Containment Action	-
出货记录表格	Ø 出货记录	2024total 出货V客户2.62KK...
失效描述图片	Failure Description & Photo	卷盘破损
包装外观图片	包装外观确认	外箱；无异常
卷盘外观图片	卷盘外观确认	确认破损卷盘双面...

2. entity_extractor.py

从 chunks 中提取结构化实体。

实体类型:

类型	提取规则	示例
REPORT	每个报告一个	8D_SFS06R013UGF卷盘破损
PRODUCT	正则匹配产品型号模式	SFS06R013UGF, OSG60R030HT3ZF
DEFECT_TYPE	关键词匹配	破损, 变形, 切伤, 超标
COMPONENT	关键词匹配	卷盘, 引脚, 散热片, 塑封体
SECTION	基于 Dn 字段生成	D1-team, D2-problem
IMAGE	格式为 image 的 chunk	images/xxx.jpg
TABLE	格式为 table 的 chunk	表格_3

产品型号正则模式:

r'SFS\w+'
r'OSG\w+'
r'SFSE\w+'
r'ORI\s+\w+'

去重策略: 使用 type:name 作为唯一键，确保同一实体只被提取一次。

3. relationship_extractor.py

基于 chunks 和 entities 构建实体间的关系网络。

关系抽取逻辑:

1. 按报告分组: 将 chunks 按 document_id 分组处理
2. 收集维度数据: 在每个报告内收集
   • 产品型号列表（PRODUCT）
   • 缺陷类型列表（DEFECT_TYPE）
   • 组件列表（COMPONENT）
3. 生成关系三元组:

关系	方向	权重	描述示例
涉及	REPORT → PRODUCT	1.0	报告涉及产品SFS06R013UGF
存在缺陷	PRODUCT → DEFECT_TYPE	1.5	产品存在破损缺陷
影响	DEFECT_TYPE → COMPONENT	1.0	破损影响卷盘
组成部分	COMPONENT → PRODUCT	0.8	卷盘是SFS06R013UGF的组成部分

权重设计: 产品-缺陷关系权重最高（1.5），反映质量问题分析的核心关注点。

项目结构

ReportRAG/
├── main.py                    # 主入口脚本
├── chunk_generator.py         # Chunk 生成模块
├── entity_extractor.py        # 实体提取模块
├── relationship_extractor.py  # 关系提取模块
├── settings.yaml              # GraphRAG 配置文件
├── .env                       # 环境变量
└── 8D_output/                 # 输入数据目录（gitignored）
    └── {report_name}/
        └── hybrid_auto/
            ├── {name}_content_list.json
            ├── {name}.md
            └── images/

使用方法

环境配置

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装依赖（系统仅需基础依赖，无 PyTorch 要求）
pip install tqdm

准备数据

将 8D 报告放入 8D_output/ 目录：

8D_output/
└── 8D_SFS06R013UGF卷盘破损/
    └── hybrid_auto/
        ├── 8D_SFS06R013UGF卷盘破损_content_list.json
        ├── 8D_SFS06R013UGF卷盘破损.md
        └── images/
            └── xxx.jpg

运行

# 处理所有报告
python main.py

# 处理单个样例
python main.py -s

# 按关键词筛选报告
python main.py -f 卷盘破损

# 指定输入输出目录
python main.py -i /path/to/input -o /path/to/output

输出格式

运行后生成以下文件：

chunk.csv

字段	类型	说明
id	string	唯一标识符（MD5哈希）
human-readable_id	int	顺序序号（1,2,3...）
chunk	string	内容（文本/HTML/图片路径）
格式	enum	text/table/image
Dn	string	D章节代码
D-title	string	章节中英文标题
chunk_type	string	二级标题英文
chunk_title	string	二级标题中文
document_id	string	报告名称

entities.csv

字段	说明
id	实体唯一ID
name	实体名称
type	实体类型（REPORT/PRODUCT/DEFECT_TYPE/COMPONENT/SECTION/IMAGE/TABLE）
description	实体描述
source_chunk_id	来源 chunk ID
source_text	来源文本片段

relationships.csv

字段	说明
id	关系唯一ID
source	源实体名称
target	目标实体名称
description	关系描述
source_chunk_id	来源 chunk ID
weight	关系权重（0.8-1.5）

同时生成对应的 .json 文件便于程序读取。

配置说明

关键词配置

系统内置以下关键词用于实体识别和章节检测：

组件关键词:

['卷盘', '引脚', '散热片', '塑封体', '铜丝', '焊盘', 
 '锡', '丝印', '粘接料', '焊线', '静电袋', '内盒', '外箱']

缺陷关键词:

['破损', '变形', '切伤', '脱落', '超标', '击穿', '疏松', 
 '异物', '生锈', '异常', '失效', '弯曲', '附着', '压痕']

可通过修改各模块中的关键词列表扩展识别能力。

GraphRAG 集成

生成后的三表可直接用于 GraphRAG 知识图谱构建：

# 使用生成的 chunk.csv, entities.csv, relationships.csv
python -m graphrag.index --root .

技术特点

1. 模块化设计: 三个核心模块职责清晰，便于独立测试和扩展
2. 逐行格式: 每个文档元素独立成行，保留完整的位置和元数据信息
3. 多模态支持: 同时处理文本、表格和图片，建立元素间关联
4. 零重型依赖: 无需 PyTorch/TensorFlow，仅依赖标准库和基础工具
5. 规则驱动: 基于正则和关键词的实体提取，结果可解释、可调试

注意事项

1. 输入 JSON 文件应为解析后的结构化数据（非原始 PDF）
2. Markdown 文件用于补充表格内容和图片匹配，是可选输入
3. 图片匹配基于关键词共现，可能存在误匹配，建议人工校验关键图片
4. 章节检测基于关键词，对于非标准格式的报告可能需要调整规则

License

LICENSE