# scigraph

**Repository Path**: cxcy666_admin/scigraph

## Basic Information

- **Project Name**: scigraph
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SciGraph

SciGraph 是一个基于 LangChain、LangGraph 和 Neo4j 的科研知识图谱自动构建项目。

目标是让大模型从科研论文中抽取高质量知识，并持续扩展同一张 Neo4j 科研知识图谱，而不是每篇论文单独生成一张孤立图。

## 当前闭环

当前已经实现的最小可运行闭环如下：

```text
论文文本
-> 抽取实体、关系和证据
-> 检索已有 Neo4j 图谱上下文
-> 与已有图谱实体对齐，避免重复构建节点
-> 进行三轮质量评估与修复
-> 生成参数化 Cypher
-> 使用 MERGE 写入 Neo4j
-> 写入后验证
```

## 核心设计

系统不会让大模型直接操作数据库。

大模型先生成一个 `Knowledge Patch`，也就是准备写入图谱的变更集。这个变更集包含：

- 论文元数据
- 待创建或复用的实体
- 待创建或更新的关系
- 每条知识对应的原文证据
- 质量评估报告
- 风险标记
- 修复次数

只有通过评估和 Cypher 安全检查后，系统才会调用 Neo4j 写入工具。

## 三轮质量评估

入库前会经过三类评估：

| 评估阶段 | 目标 | 不通过时的处理 |
| --- | --- | --- |
| 事实一致性评估 | 判断实体和关系是否有原文证据支持 | 删除无证据知识，降低置信度，补充证据 |
| 图谱一致性评估 | 判断是否和已有 Neo4j 图谱重复或冲突 | 复用已有节点，合并别名，标记人工复核 |
| 科研价值评估 | 判断知识是否有助于论文关系发现和科研推理 | 丢弃低价值知识或进入待审核状态 |

如果评估失败但可以修复，系统会进入 `Repair Agent`，最多修复 3 次。

## 环境配置

在项目根目录创建或更新 `.env` 文件：

```env
DASHSCOPE_MODEL=your-model
DASHSCOPE_API_KEY=your-key
DASHSCOPE_BASE_URL=your-openai-compatible-base-url

NEO4J_URI=bolt://192.168.217.128:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j
```

注意：不要提交 `.env`，里面包含 API Key 和 Neo4j 密码。

## 安装依赖

```powershell
uv sync
```

如果本地环境还没有安装 Neo4j 驱动，可以执行：

```powershell
uv add neo4j
```

## 交互式终端

推荐使用交互式终端。进入项目目录后执行：

```powershell
uv run scigraph
```

如果已经把项目安装到当前 Python 环境，也可以直接执行：

```powershell
scigraph
```

进入后会看到类似下面的提示符：

```text
›
```

这个终端不是只能输入固定命令的工具，而是一个类似 Codex 的科研知识图谱超级智能体。它会围绕“论文读取、知识抽取、已有图谱检索、质量评估、Cypher 生成、Neo4j 写入验证”自主规划下一步。

普通问答和解释性回答会流式输出；涉及“打开文件、运行抽取、写入 Neo4j”等操作时，系统会先生成结构化动作计划，然后按步骤执行。

当前会话会维护短期会话记忆，包括最近几轮用户输入、助手回答、当前已加载论文的路径和文本内容片段。因此在打开文件后，可以直接问：

```text
这个文章主要讲了什么
文本里面内容是什么
根据这篇文章抽取知识图谱
```

系统会基于当前已读入的文本回答，而不是要求你重复粘贴。

常见操作会优先走本地快速通道，不会每次都调用大模型：

- 直接输入 `.txt` / `.md` 路径：立即读取文件
- 询问 Neo4j 连接状态：立即执行本地连接检测
- 问“文章主要讲了什么”：基于当前已加载文本回答
- 说“先预览一下”：执行 dry-run
- 说“写入 Neo4j”：执行写入流程

长任务执行时可以按 `Ctrl+C` 取消，终端会回到提示符，不会退出整个程序。

当前已实现的直接输入格式是 UTF-8 纯文本文件，例如论文摘要、正文片段、从 Markdown 导出的纯文本。PDF、HTML、BibTeX、RIS、Word、DOI/arXiv 自动拉取属于下一步扩展。

### Codex 风格体验边界

这个终端会维护两层状态：

- 当前会话状态：本轮真正读入的论文文本、研究问题、上次运行结果。
- 全局记忆：跨会话保存的历史论文路径、历史问题、历史运行摘要。

自然语言决策由大模型完成。终端本地只负责三类确定性边界：读取本地文件路径、接收长文本粘贴、执行少量快捷命令。像“你好”“怎么使用啊”“这篇文章讲什么”“开始预览”“写入 Neo4j”这类输入，都会先进入大模型 Planner，由它根据当前会话状态决定是回答、设置研究问题、运行预览还是写入数据库。

回答“这篇文章讲什么”“文本里面内容是什么”时，只认当前会话状态。如果当前会话已经读取文件，系统必须基于已读入文本回答，不能再要求你重新粘贴；如果当前会话没有文本，系统会明确让你提供路径或文本。

全局记忆不会被静默当成当前论文。只有你明确说“继续上次”“沿用之前的问题”“恢复上次论文”时，系统才会尝试从 `.scigraph/memory.json` 找到历史路径并重新打开。

### 典型自然语言用法

```text
你好
你是谁，能做什么
examples\graphrag_sample.txt
这篇文章主要讲了什么
围绕多跳问答方法之间的关系先预览一下，不要入库
看看评估结果
把 Cypher 给我看一下
确认没问题，写入 Neo4j
```

如果模型 API 暂时超时，终端不会把已读取文件忘掉，也不会说“无法访问本地文件”。对于文章摘要类问题，会先给出基于本地已读文本的预览；对于知识图谱构建任务，会显示当前失败阶段并回到提示符。

### 全局记忆

终端会在项目目录下维护 `.scigraph/memory.json` 作为全局记忆。它会跨会话保存：

- 上次打开的论文路径
- 上次设置的科研问题
- 最近处理过的论文
- 最近保存过的输出文件
- 上次运行的实体数、关系数、评估数、Cypher 数和错误摘要
- 用户偏好

再次进入 `uv run scigraph` 时，系统不会把历史记忆自动当成当前论文。历史记忆只是参考，只有你明确要求继续时才会恢复，例如：

```text
继续上次那个论文，先看评估结果
沿用之前的问题，再跑一次预览
```

也可以输入：

```text
memory
```

查看当前全局记忆。

如果只想清空当前会话：

```text
reset
```

如果要连历史全局记忆一起清空：

```text
forget
```

示例：

```text
帮我打开 examples\graphrag_sample.txt，围绕多跳问答方法之间的关系先预览一下，不要写入数据库
```

系统会自动规划为：

```text
1. 打开论文文本
2. 设置科研问题
3. 执行 Dry Run
4. 输出实体、关系、评估和 Cypher 摘要
```

继续对话也可以：

```text
看看刚才的评估结果
把生成的 cypher 给我看一下
把刚才的结果保存到 examples\dry_run_output.json
确认没问题，现在写入 Neo4j
```

保留快捷命令是为了调试和脚本化使用：

```text
open examples\graphrag_sample.txt
question 寻找多跳问答方法之间的关系
run
patch
eval
cypher
save examples\dry_run_output.json
write
exit
```

快捷命令说明：

| 命令 | 作用 |
| --- | --- |
| `open <文件路径>` | 选择一篇 UTF-8 文本论文 |
| `question <科研问题>` | 设置本轮抽取关注的问题 |
| `run` | Dry Run，只抽取、评估、生成 Cypher，不写 Neo4j |
| `write` | 执行完整流程并写入 Neo4j |
| `status` | 查看当前论文、问题和上次运行结果 |
| `patch` | 查看上次生成的 Knowledge Patch |
| `eval` | 查看三轮评估结果 |
| `cypher` | 查看生成的 Cypher |
| `memory` | 查看全局记忆 |
| `save <文件路径>` | 保存上次运行结果为 JSON |
| `reset` | 清空当前会话状态 |
| `help` | 查看帮助 |
| `exit` | 退出 |

## Dry Run

Dry Run 不会写入 Neo4j，但仍会尽量连接 Neo4j 检索已有节点，用来判断候选实体应该复用、合并、新建还是进入人工复核。这样你在确认写库之前就能看到去重结果。

Dry Run 会输出完整流水线结果，包括：

- 抽取出的实体和关系
- 每条知识的 evidence
- 三轮评估结果
- 生成的参数化 Cypher
- 写入计划摘要

运行示例：

```powershell
python -m scigraph_kg.cli --paper examples\graphrag_sample.txt --question "寻找多跳问答方法之间的关系"
```

也可以把结果保存为 JSON：

```powershell
python -m scigraph_kg.cli --paper examples\graphrag_sample.txt --question "寻找多跳问答方法之间的关系" --output examples\dry_run_output.json
```

## 写入 Neo4j

确认 `.env` 中的 Neo4j 连接信息正确后，执行：

```powershell
python -m scigraph_kg.cli --paper examples\graphrag_sample.txt --question "寻找多跳问答方法之间的关系" --write
```

写入时系统会：

1. 创建 Neo4j 唯一约束
2. 检索已有 Paper / Method / Dataset / Metric / Task 等节点
3. 复用已有节点，避免重复创建
4. 使用 `MERGE` 写入新节点和新关系
5. 给关系追加 evidence 和 source paper
6. 写入后查询验证

## 图谱 Schema

当前支持的节点类型：

- `Paper`：论文
- `Method`：方法
- `Dataset`：数据集
- `Metric`：评价指标
- `Task`：科研任务
- `Author`：作者
- `Institution`：机构
- `Finding`：科研发现

当前支持的关系类型：

- `PROPOSES`：论文提出方法
- `USES`：方法使用某个组件、指标或资源
- `EVALUATES_ON`：方法在数据集上评估
- `MEASURES_WITH`：使用指标衡量结果
- `IMPROVES_OVER`：方法优于另一个方法
- `CITES`：论文引用论文
- `EXTENDS`：方法扩展已有方法
- `SOLVES`：方法解决任务
- `REPORTS`：论文报告发现
- `AFFILIATED_WITH`：作者隶属于机构
- `MENTIONS`：论文提到某实体

## 去重策略

系统不会简单使用 `CREATE` 写入节点，而是使用稳定 ID 和 `MERGE`。

论文节点优先使用：

- DOI
- arXiv ID
- 标题 hash

科研实体节点使用：

- 类型
- canonical name
- aliases
- 已有图谱检索结果

如果 Neo4j 中已有高置信匹配节点，系统会复用该节点 ID，而不是重复创建新节点。

## 示例输出

对 `examples/graphrag_sample.txt` 进行 Dry Run 后，系统会抽取类似知识：

```text
GraphRAG - SOLVES -> Multi-hop Question Answering
GraphRAG - EVALUATES_ON -> HotpotQA
GraphRAG - USES -> F1
GraphRAG - IMPROVES_OVER -> BM25
```

每条关系都会绑定论文原文 evidence 和置信度。

## 主要代码位置

- `scigraph_kg/models.py`：Knowledge Patch、实体、关系、评估结果等数据结构
- `scigraph_kg/workflow.py`：LangGraph 智能体编排流程
- `scigraph_kg/neo4j_store.py`：Neo4j 检索、去重、写入和验证工具
- `scigraph_kg/prompts.py`：抽取、评估、修复提示词
- `scigraph_kg/cli.py`：命令行入口
- `examples/graphrag_sample.txt`：示例论文文本

## 下一步可扩展方向

- 增加 PDF 解析能力
- 增加引用关系抽取
- 增加 Neo4j 全文索引和向量索引
- 增加人工审核队列
- 增加批量论文导入
- 增加基于知识图谱的科研问题推理 Agent