# 国土空间规划法规知识图谱构建与分析系统

基于大语言模型的国土空间规划法规知识图谱构建与原理提取研究项目。

## 项目简介

本项目实现了论文《基于大模型的国土空间规划法规知识图谱构建与原理提取研究》中提出的方法论，包括：

- 法规文本预处理（HanLP）
- 基于大模型的知识抽取（NER、RE、评估、分类）
- 知识图谱构建（基于GraphRAG思路）
- 法理结构提取
- 法规逻辑推理与演化规律识别

## 技术栈

- Python 3.12+
- uv: 虚拟环境管理和包管理
- HanLP: 中文NLP处理
- LLM APIs: OpenAI, Anthropic, Qwen, Doubao, GLM
- NetworkX/iGraph: 图处理
- PyYAML: 配置文件

## 快速开始

### 1. 环境设置

使用uv创建虚拟环境并安装依赖：

```bash
# 进入项目目录
cd dofile

# 初始化uv项目并安装依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate  # Windows

# 如果uv未安装，先安装uv：
# Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Linux/Mac: curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. 配置环境变量

复制 `.env.example` 到 `.env` 并填入API密钥：

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入所需的API密钥：
- OPENAI_API_KEY
- ANTHROPIC_API_KEY
- DASHSCOPE_API_KEY (Qwen)
- VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY (Doubao)
- ZHIPUAI_API_KEY (GLM)
- SILICONFLOW_API_KEY (硅基流动，已在示例中配置)
- SILICONFLOW_API_BASE (可选，默认为 https://api.siliconflow.cn/v1)

### 3. 运行项目

```bash
# 方式1: 完整流程（推荐）
# 从文档解析到知识图谱构建
uv run python scripts/complete_pipeline.py --data-dir ../data/1法律 --output-dir ./output --max-docs 5

# 方式2: 分步骤执行
# 步骤1: 实体识别
uv run python scripts/extract.py --input ../data/1法律/3-中华人民共和国城乡规划法.docx --output ./output/entities.json

# 步骤2: 构建知识图谱
uv run python scripts/build_kg.py --data-dir ../data/1法律 --output ./output/kg.json --max-docs 5

# 步骤3: 查询知识图谱
uv run python scripts/query_kg.py --kg ./output/kg.json --query "城乡规划" --mode global
uv run python scripts/query_kg.py --kg ./output/kg.json --query "城市更新" --mode local
uv run python scripts/query_kg.py --kg ./output/kg.json --query "土地管理" --mode drift
```

### 4. 运行测试

```bash
# 基础功能测试
uv run python tests/test_basic.py

# 测试硅基流动API配置
uv run python tests/test_siliconflow.py

# 测试文档解析
uv run python tests/test_documents.py

# 测试模型可用性
uv run python tests/test_model.py

# 测试指定模型
uv run python tests/test_my_models.py

# 快速测试（小规模知识图谱构建）
uv run python tests/test_quick.py
```

### 5. 使用硅基流动API

硅基流动已经配置完成，您可以通过以下方式使用：

```python
from src.utils.llm_client import LLMClient, LLMProvider
from src.utils.config import load_config

config = load_config()
client = LLMClient(
    provider=LLMProvider.SILICONFLOW,
    model="Qwen/Qwen2.5-72B-Instruct",  # 请根据实际可用模型修改
    config=config
)

messages = [{"role": "user", "content": "你好"}]
response = client.chat(messages)
```

更多使用示例请参考：
- `examples/use_siliconflow.py` - 硅基流动使用示例
- `ENV_SETUP.md` - 环境变量配置说明

## 项目结构

```
dofile/
├── src/              # 源代码
│   ├── preprocessing/    # 文本预处理
│   ├── ontology/        # 本体模型定义
│   ├── prompts/         # Prompt模板
│   ├── extraction/      # 知识抽取
│   ├── kg_builder/      # 知识图谱构建
│   ├── analysis/        # 分析和推理
│   ├── query/           # 查询系统
│   └── utils/           # 工具函数
├── scripts/          # 执行脚本
├── config/           # 配置文件
└── tests/            # 测试文件
```

## 项目状态

### 已完成模块

✅ **项目基础结构**
- uv项目配置（pyproject.toml）
- 项目文档（README.md）
- 目录结构

✅ **文本预处理模块**
- HanLP文本处理器（分词、依存句法、句法成分分析）
- 法规文档解析器（.docx文件解析）

✅ **本体模型定义**
- 实体类型定义（9种类型）
- 关系类型定义（8种类型）
- 三维本体结构（法规层级—要素类型—关联关系）
- 四要素架构（目标—原则—要素—管控）

✅ **Prompt模板系统**
- 统一Prompt模板框架（五个模块）
- NER Prompt构建器
- RE Prompt构建器

✅ **LLM客户端封装**
- 多提供商支持（OpenAI, Anthropic, Qwen, Doubao, GLM）
- 统一API接口
- 重试机制

✅ **知识抽取模块框架**
- NER提取器（两阶段对话）
- RE提取器（多模型并行）
- 三元组评估器（LLM-as-a-Judge）
- 实体关系分类器（RAG-based）

✅ **知识图谱构建框架**
- 图谱索引器（参考GraphRAG）
- 图谱结构管理（NetworkX）

✅ **分析和推理模块框架**
- 法理结构提取器
- 逻辑推理器
- 演化规律分析器

✅ **查询系统框架**
- 全局搜索（参考GraphRAG）
- 局部搜索
- DRIFT搜索

### 待完善模块

⚠️ **部分优化空间**：
- 三元组评估的性能优化（批量评估）
- RAG-based分类的向量数据库优化（使用专业向量数据库）
- 大规模图谱的社区检测优化
- 演化规律分析的时间序列处理完善
- 可视化工具开发
- 性能监控和日志分析

### 开发指南

各模块的详细文档：
- `src/preprocessing/`: 文本预处理
- `src/ontology/`: 本体模型定义
- `src/prompts/`: Prompt模板系统
- `src/extraction/`: 知识抽取
- `src/kg_builder/`: 知识图谱构建
- `src/analysis/`: 分析和推理
- `src/query/`: 查询系统

## 许可证

[待定]