# 系统架构文档

## 整体架构

本系统采用模块化设计，参考GraphRAG的实现思路，实现法规知识图谱的构建、分析和查询。

## 核心模块说明

### 1. 文本预处理模块 (`src/preprocessing/`)

**职责**：处理法规文档，为知识抽取做准备

- `TextProcessor`: 使用HanLP进行中文文本处理
  - 分词（粗粒度/细粒度）
  - 依存句法分析
  - 句法成分分析
  - 词性标注
  - 省略检测
  - 共指消解候选提取

- `DocumentParser`: 解析Word文档
  - .docx文件解析
  - 章节结构识别
  - TextUnit切分（参考GraphRAG）

### 2. 本体模型模块 (`src/ontology/`)

**职责**：定义知识图谱的语义结构

- `EntityType`: 9种实体类型枚举
- `RelationType`: 8种关系类型枚举
- `OntologySchema`: 三维本体结构管理
  - 法规层级维度
  - 要素类型维度
  - 关联关系维度
  - 四要素架构（目标—原则—要素—管控）

### 3. Prompt模板模块 (`src/prompts/`)

**职责**：构建统一的Prompt模板系统

- `PromptTemplate`: 统一模板框架
  - 任务描述模块
  - 候选目标模块
  - 任务示例模块（少样本学习）
  - 任务强调模块
  - 二次对话模块

- `NERPromptBuilder`: NER任务Prompt构建
- `REPromptBuilder`: RE任务Prompt构建

### 4. 知识抽取模块 (`src/extraction/`)

**职责**：从文本中提取结构化知识

- `NERExtractor`: 命名实体识别
  - 使用Qwen-Max模型
  - 两阶段对话验证
  - JSON格式输出

- `REExtractor`: 关系抽取
  - 多模型并行（GPT-4o, Doubao-pro, GLM-4）
  - 二次对话验证
  - 句法信息集成
  - 上下文利用

- `TripletEvaluator`: 三元组评估
  - LLM-as-a-Judge方法
  - 成对排序
  - 五维度评分（语义准确性、一致性、事实性、准确性、可理解性）
  - 低质量三元组筛选

- `EntityRelationClassifier`: 实体关系分类
  - RAG-based分类（使用向量检索）
  - Prompt-based分类
  - 粗粒度和细粒度分类

### 5. 知识图谱构建模块 (`src/kg_builder/`)

**职责**：构建和管理知识图谱（参考GraphRAG）

- `GraphIndexer`: 图谱索引器
  - 文本切分为TextUnit
  - 实体和关系提取
  - 图构建
  - 社区检测（Leiden算法）
  - 社区摘要生成

- `KnowledgeGraph`: 图谱结构管理
  - 基于NetworkX
  - 三元组添加
  - 路径查询
  - 子图提取
  - 保存/加载

### 6. 分析和推理模块 (`src/analysis/`)

**职责**：分析法规体系和识别规律

- `LegalStructureExtractor`: 法理结构提取
  - 四要素提取（目标、原则、要素、管控）
  - 跨法规引用关系提取
  - 例外条款识别

- `LegalReasoner`: 逻辑推理
  - 路径查询（多跳关系）
  - 中心性分析
  - 子图分析

- `EvolutionAnalyzer`: 演化规律识别
  - 时间维度分析
  - 关系演化追踪
  - 网络演化分析

### 7. 查询系统模块 (`src/query/`)

**职责**：知识图谱查询和问答（参考GraphRAG）

- `GlobalSearcher`: 全局搜索
  - 利用社区摘要
  - 相关性评估
  - 综合答案生成

- `LocalSearcher`: 局部搜索
  - 实体邻居扩展
  - 深度控制
  - 子图提取

- `DriftSearcher`: DRIFT搜索
  - 结合局部和全局信息
  - 社区上下文整合
  - 综合答案生成

### 8. 工具模块 (`src/utils/`)

**职责**：提供通用工具函数

- `Config`: 配置管理
  - 环境变量加载
  - API密钥管理
  - 参数配置

- `LLMClient`: LLM客户端封装
  - 多提供商支持
  - 统一API接口
  - 异步/同步支持
  - 重试机制

- `file_utils`: 文件操作工具

## 数据流

```
法规文档(.docx)
    ↓
DocumentParser (解析)
    ↓
TextUnit列表
    ↓
TextProcessor (预处理) + NERExtractor (实体识别)
    ↓
实体列表
    ↓
REExtractor (关系抽取) + TextProcessor (句法信息)
    ↓
三元组列表
    ↓
TripletEvaluator (评估筛选)
    ↓
高质量三元组
    ↓
GraphIndexer (图构建)
    ↓
KnowledgeGraph
    ↓
社区检测 + 摘要生成
    ↓
完整知识图谱 + 社区信息
    ↓
Query系统 (查询和问答)
```

## 技术栈

- **语言**: Python 3.12+
- **包管理**: uv
- **NLP**: HanLP
- **图处理**: NetworkX, python-igraph
- **LLM**: OpenAI, Anthropic, Qwen, Doubao, GLM
- **数据处理**: pandas, numpy

## 参考实现

- GraphRAG: https://msdocs.cn/graphrag/
- 论文方法: `officefile/paper.tex`