SentGraph-RAG

KO | EN

gitlite — search

#hacktoberfest #react #typescript #llm #rust #macos #awesome #cli #kubernetes #vue #pytorch #security #ios #open-source

(★ 9)

No description available.

SentGraph-RAG 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# SentGraph: Hierarchical Sentence Graph for Multi-hop RAG

SentGraph 是一个基于分层句子图的多跳 RAG（检索增强生成）系统，通过模拟人类阅读的逻辑结构（基于 RST 修辞结构理论），构建跨文档的层级图，解决多跳问答中证据链断裂和噪声过多的问题。

## 功能特性

- **分层句子图构建**：基于 RST 理论构建三层图结构（Topic → Core → Supplementary）
- **智能实体提取**：使用 spaCy NER 模型自动提取话题实体（支持英文和中文）
- **RST 句子分类**：基于修辞结构理论自动识别核心句子和补充句子
- **语义相似度筛选**：路径扩展时基于查询相似度过滤无关节点，提高检索质量
- **查询相关性排序**：基于查询与节点的语义相似度排序证据链，优先展示最相关证据
- **多跳检索**：使用 Neo4j 图数据库进行路径扩展和证据链检索
- **多文档格式支持**：支持文本文件（.txt）和 PDF 文件（.pdf）
- **多提供商支持**：支持 OpenAI、Anthropic、DashScope（阿里云）和本地 LLM
- **灵活的 Embedding**：支持本地模型（sentence-transformers）和 DashScope 在线服务
- **CLI 和 REST API**：提供命令行工具和 Web API 接口

## 安装

### 环境要求

- Python 3.9+
- Neo4j 数据库（5.0+）

### 安装步骤

1. 克隆项目：

```bash
git clone <repository-url>
cd SentGraph
```

2. 创建虚拟环境：

```bash
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate
```

3. 安装依赖：

```bash
pip install -r requirements.txt
```

4. 安装 spaCy 模型（可选，用于 NER 功能）：

```bash
# 英文模型（推荐）
python -m spacy download en_core_web_sm

# 中文模型（可选）
python -m spacy download zh_core_web_sm
```

**注意**：如果不安装 spaCy 模型，系统会自动使用降级方法（基于正则表达式）进行实体提取。

5. 配置环境变量：

复制 `.env.example` 为 `.env` 并填写配置：

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

编辑 `.env` 文件，配置以下内容：

```env
# DashScope 配置（推荐）
DASHSCOPE_API_KEY=sk-xxx
DASHSCOPE_LLM_MODEL=qwen-plus
DASHSCOPE_EMBEDDING_MODEL=text-embedding-v2
LLM_PROVIDER=dashscope
EMBEDDING_PROVIDER=dashscope

# Neo4j 配置
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j
```

**注意**：完整的配置示例和详细说明请参考 `docs/ENV_CONFIG_EXAMPLE.md`。

6. 启动 Neo4j 数据库：

确保 Neo4j 数据库正在运行。可以使用 Docker：

```bash
docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your_password \
  neo4j:5
```

## 使用方法

### CLI 使用

#### 构建图并索引

支持文本文件（.txt）和 PDF 文件（.pdf）：

```bash
# 文本文件
python -m cli.main build -d document1.txt -d document2.txt -o index.faiss

# PDF 文件
python -m cli.main build -d paper1.pdf -d paper2.pdf -o index.faiss

# 混合格式
python -m cli.main build -d doc1.txt -d paper.pdf -o index.faiss

# 清空现有图后重新构建
python -m cli.main build -d document1.txt --clear-graph -o index.faiss
```

#### 查询

```bash
# 基本查询
python -m cli.main query -q "你的问题" -i index.faiss

# 自定义检索参数
python -m cli.main query -q "你的问题" -i index.faiss --top-k 20 --max-depth 3
```

#### 启动 API 服务

```bash
python -m cli.main serve --host 0.0.0.0 --port 8000
```

### REST API 使用

#### 启动服务

```bash
python -m cli.main serve
```

#### 构建图

支持两种方式：
1. 直接提供文本内容（`documents`）
2. 提供文件路径（`document_files`，支持 .txt 和 .pdf）

```bash
# 方式1: 直接提供文本
curl -X POST "http://localhost:8000/api/v1/build" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": ["文档1内容", "文档2内容"],
    "document_ids": ["doc1", "doc2"],
    "output_index": "index.faiss"
  }'

# 方式2: 提供文件路径（支持 PDF）
curl -X POST "http://localhost:8000/api/v1/build" \
  -H "Content-Type: application/json" \
  -d '{
    "document_files": ["/path/to/doc1.txt", "/path/to/paper.pdf"],
    "output_index": "index.faiss"
  }'
```

**构建 API 响应格式**：
```json
{
  "status": "success",
  "stats": {
    "topic_nodes": 10,
    "core_nodes": 50,
    "supplementary_nodes": 100,
    "topic_to_core_edges": 50,
    "core_to_core_edges": 30,
    "core_to_supp_edges": 100,
    "topic_to_topic_edges": 5
  },
  "index_file": "index.faiss",
  "index_size": 150
}
```

#### 查询

```bash
curl -X POST "http://localhost:8000/api/v1/query" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "你的问题",
    "index_file": "index.faiss",
    "top_k": 10,
    "max_depth": 2
  }'
```

**响应格式**：
```json
{
  "question": "你的问题",
  "answer": "生成的答案",
  "evidence_count": 5,
  "evidence": [
    {
      "node_id": "core_1",
      "content": "证据内容",
      "labels": ["CoreSentence"],
      "similarity": 0.85
    }
  ],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 50
  }
}
```

#### 健康检查

```bash
curl http://localhost:8000/api/v1/health
```

**响应格式**：
```json
{
  "status": "healthy",
  "neo4j": "connected"
}
```

## 配置说明

### LLM 提供商

支持以下 LLM 提供商：

- `openai`: OpenAI GPT 系列
- `anthropic`: Anthropic Claude 系列
- `dashscope`: 阿里云通义千问系列（推荐）
- `local`: 本地模型（需自行实现）

### Embedding 提供商

支持以下 Embedding 提供商：

- `local`: 本地模型（sentence-transformers）
- `dashscope`: DashScope 在线服务（推荐）

### NER 配置

系统支持两种 NER 提供商：

- `spacy`: 使用 spaCy 模型（推荐，需要安装模型）
- `local`: 使用简单的正则表达式方法（降级方案）

配置示例：

```env
# NER 配置
NER_PROVIDER=spacy
SPACY_MODEL_EN=en_core_web_sm
SPACY_MODEL_ZH=zh_core_web_sm

# 实体类型配置（支持多种格式）
# 方式1：逗号分隔（推荐）
ENTITY_TYPES=PERSON,ORG,GPE,EVENT,WORK_OF_ART
# 方式2：JSON 数组格式
# ENTITY_TYPES=["PERSON","ORG","GPE","EVENT","WORK_OF_ART"]
# 方式3：空字符串（提取所有类型）
# ENTITY_TYPES=

MAX_ENTITIES_PER_DOCUMENT=10

# spaCy 自定义配置（可选，用于优化性能）
# 禁用不需要的组件以提高性能（推荐使用逗号分隔）
SPACY_DISABLE_COMPONENTS=parser,tagger
# 或使用 JSON 格式
# SPACY_DISABLE_COMPONENTS=["parser","tagger"]

# 启用语言列表（推荐使用逗号分隔）
SPACY_ENABLE_LANGUAGES=en,zh
# 或使用 JSON 格式
# SPACY_ENABLE_LANGUAGES=["en","zh"]

# 语言检测阈值（中文字符占比，默认 0.3）
SPACY_LANGUAGE_DETECTION_THRESHOLD=0.3

# 模型加载失败时是否降级到简单 NER 模型（默认 true）
SPACY_FALLBACK_ON_ERROR=true

# 实体长度过滤
SPACY_MIN_ENTITY_LENGTH=2
SPACY_MAX_ENTITY_LENGTH=50
```

**重要说明**：
- `ENTITY_TYPES` 为空字符串或空列表时，系统会提取所有识别到的实体类型（不进行类型过滤）
- `SPACY_DISABLE_COMPONENTS` 可以禁用不需要的组件（如 `parser`、`tagger`）以提高性能
- `SPACY_ENABLE_LANGUAGES` 指定启用的语言，未列出的语言将使用降级方法
- 更多配置说明请参考 `docs/ENV_CONFIG_EXAMPLE.md` 和 `docs/SPACY_NER_CONFIG.md`

### RST 分类配置

RST（修辞结构理论）句子分类配置：

```env
# RST 分类配置
RST_CLASSIFICATION_ENABLED=true
RST_CLASSIFICATION_CONFIDENCE_THRESHOLD=0.7
RST_CLASSIFICATION_BATCH_SIZE=8
```

- `RST_CLASSIFICATION_ENABLED`: 是否启用 RST 分类（默认 true）
- `RST_CLASSIFICATION_CONFIDENCE_THRESHOLD`: 分类置信度阈值（0.0-1.0）
- `RST_CLASSIFICATION_BATCH_SIZE`: 批量处理大小（减少 LLM 调用）

### 检索配置

检索相关配置：

```env
# 检索配置
MAX_DEPTH=2
SIMILARITY_THRESHOLD=0.7
TOP_K_ANCHORS=10
```

- `MAX_DEPTH`: 路径扩展最大深度（默认 2）
- `SIMILARITY_THRESHOLD`: 语义相似度阈值，用于路径扩展时的节点筛选（默认 0.7）
- `TOP_K_ANCHORS`: 初始检索锚点数量（默认 10）

**功能说明**：
- **语义相似度筛选**：路径扩展时会计算查询与邻居节点的语义相似度，只保留相似度高于阈值的节点，减少噪声
- **查询相关性排序**：证据链排序时会计算查询与每个节点的相似度，优先展示与查询最相关的证据

### 文档加载配置

文档加载器支持以下文件格式：

- `.txt`: 纯文本文件（自动检测编码：UTF-8、GBK）
- `.pdf`: PDF 文件（使用 pypdf 提取文本）

**注意**：PDF 支持需要安装 `pypdf` 包（已包含在 `requirements.txt` 中）。

### DashScope 配置

DashScope 是阿里云提供的模型服务，支持：

- **LLM 模型**：
  - `qwen-turbo`: 快速响应
  - `qwen-plus`: 平衡性能和成本（推荐）
  - `qwen-max`: 最强性能

- **Embedding 模型**：
  - `text-embedding-v1`: 第一代模型
  - `text-embedding-v2`: 第二代模型（推荐，1536 维）
  - `text-embedding-v3`: 第三代模型（最新）

### 向量索引配置

```env
# FAISS 索引类型（默认 IndexFlatIP）
FAISS_INDEX_TYPE=IndexFlatIP
```

### 日志配置

```env
# 日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
LOG_LEVEL=INFO
```

## 项目结构

```
SentGraph/
├── sentgraph/              # 核心模块
│   ├── __init__.py
│   ├── config.py           # 配置管理
│   ├── exceptions.py       # 异常类
│   ├── prompts.py          # 提示词模板
│   ├── llm_utils.py        # LLM 工具
│   ├── embedding.py        # 向量化模块
│   ├── ner.py              # NER 实体提取模块
│   ├── neo4j_client.py     # Neo4j 客户端
│   ├── document_loader.py  # 文档加载器（支持 .txt 和 .pdf）
│   ├── graph_builder.py    # 图构建
│   ├── index.py            # 向量索引
│   ├── retrieval.py        # 检索模块
│   └── generation.py       # 生成模块
├── cli/                    # 命令行接口
│   ├── __init__.py
│   └── main.py             # CLI 入口
├── api/                    # REST API
│   ├── __init__.py
│   ├── app.py              # FastAPI 应用
│   ├── routes.py           # API 路由
│   └── dependencies.py    # 依赖注入
├── tests/                  # 测试
├── docs/                   # 文档
│   ├── README.md           # 项目说明
│   ├── ENV_CONFIG_EXAMPLE.md  # 环境配置示例
│   └── SPACY_NER_CONFIG.md    # spaCy NER 配置指南
├── requirements.txt        # 生产依赖
├── requirements-dev.txt    # 开发依赖
└── pyproject.toml          # 项目配置
```

## 开发

### 代码格式化

```bash
black .
isort .
```

### 代码检查

```bash
ruff check .
mypy .
```

### 运行测试

```bash
pytest
```

## 许可证

[MIT License]

## 文档

- **README.md**（本文档）：项目概述和使用说明
- **ENV_CONFIG_EXAMPLE.md**：详细的环境配置示例和说明
- **SPACY_NER_CONFIG.md**：spaCy NER 配置详细指南
- **AGENTS.md**：AI 编码代理开发指南

## 接下来的计划

我们计划在未来的版本中实现以下功能：

### 1. 增加 Milvus 支持

- 支持使用 Milvus 作为向量数据库，替代或补充现有的 FAISS 索引
- 提供更强大的向量检索能力和更好的可扩展性
- 支持分布式部署和集群模式

### 2. 优化索引和检索链路性能

- 优化向量索引构建速度，支持增量索引更新
- 优化检索算法，减少检索延迟
- 实现缓存机制，提升重复查询的响应速度
- 优化图数据库查询性能，减少多跳检索的耗时

### 3. 支持更多文件类型

- **Office 系列**：
  - `.docx`：Microsoft Word 文档
  - `.xlsx`：Microsoft Excel 表格
  - `.pptx`：Microsoft PowerPoint 演示文稿
- **其他格式**：
  - `.md`：Markdown 文档
  - `.html`：HTML 网页
  - `.epub`：电子书格式
  - 更多格式持续添加中...

## 参考

- 论文：SentGraph: Hierarchical Sentence Graph for Multi-hop Retrieval-Augmented Question Answering
- RST 理论：Rhetorical Structure Theory

SentGraph-RAG

SentGraph-RAG 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

SentGraph-RAG

SentGraph-RAG 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README