GraphMind｜基于知识图谱的 GraphRAG 知识 Agent

GraphMind 面向 NLP 知识检索场景，将 Neo4j 结构化图查询、语义实体检索与可选 LLM 表达层组合为一个可解释的知识 Agent。每次请求都会规划受限工具、检索图谱证据并经过 Evidence Gate 校验：证据充分时返回带引用的图谱回答；图谱未覆盖时仍可提供通识补充，但会明确标注“非图谱证据、可能不准确或过时、需要核验”。

仓库内的清洗主数据包含 246 个实体、1678 条关系；展示截图所对应的扩展图谱快照可见 372 个节点、2462 条关系。实际运行规模以 /api/stats 返回的当前 Neo4j 数据为准。

核心能力

• Tool Routing：将已有图谱能力封装为 search_entity、get_neighbors、find_relation_path、multi_hop_query、semantic_search 五类工具。
• Structured Graph Retrieval：按问题意图查询节点属性、直接关系和最长 4 跳的可解释关系路径，而不是只做文本相似度检索。
• Hybrid Retrieval：融合实体名/别名匹配、轻量语义检索和 Neo4j 子图扩展，并对结果去重排序。
• Evidence Gate：定义、关系、公式、特征等问题采用不同证据条件，并把结果分为 grounded、mixed、general_knowledge 三种来源状态。
• Grounded Output：回答同时返回 [E1] 形式引用、证据分数、证据子图和规划/工具/门控轨迹，前端可直接展开查看。
• Session Memory：保留有 TTL 和长度上限的会话实体上下文，用于处理“它”“这个模型”等追问。
• Graph Exploration：Vue 3 + ECharts 支持全景图、局部多跳子图、节点搜索、类型过滤、图谱联动和图片导出。

运行链路

User Query
   ↓
Entity Linking + Intent Router + Session Context
   ↓
Bounded Agent Planner
   ├── search_entity
   ├── get_neighbors
   ├── find_relation_path
   ├── multi_hop_query
   └── semantic_search
   ↓
Evidence Fusion → Evidence Gate
   ├── sufficient → Answer + Citations + Evidence Graph + Tool Trace
   └── insufficient → 明示风险的通识回答（mixed / general_knowledge）

qa_system.py 保留了原项目的实体识别、意图识别、Cypher 模板、会话记忆和规则/LLM 双模式；graphmind_runtime.py 负责工具规划、检索编排、证据融合与门控。这样既能单独验证 Agent 层，也不会把业务查询逻辑全部重写进框架代码。

API 示例

curl -X POST http://localhost:8000/api/ask \
  -H 'Content-Type: application/json' \
  -d '{"question":"BERT 和 Transformer 是什么关系？","session_id":"demo"}'

响应除原有 answer、entities、intent、matched_nodes 外，还包含：

{
  "status": "grounded",
  "stop_reason": "evidence_sufficient",
  "evidence_score": 0.92,
  "citations": [{"id": "E1", "kind": "path", "content": "..."}],
  "evidence_graph": {"nodes": [], "links": []},
  "tool_trace": [{"stage": "plan", "summary": "..."}]
}

可通过 GET /api/tools 查看工具的输入 Schema；POST /api/ask/rule 强制使用规则回答，POST /api/ask/smart 强制使用已配置的 LLM 表达层。两条链路都会经过同一个 Evidence Gate。

来源状态含义：grounded 表示回答有直接图谱证据；mixed 表示存在相关图谱上下文，但问题所需属性或关系仍由通识补充；general_knowledge 表示没有可用图谱证据，回答整体来自通识知识。后两者不会伪造图谱引用，并会附带风险提示。

任意问题的通识补答需要配置可用的 LLM Provider；若未配置，系统只使用少量内置确定性兜底，并返回 graph_context_only 或 general_knowledge_unavailable，不会把“未能生成回答”误标成通识结论。

快速开始

要求 Python 3.10+ 与 Neo4j 5.x。

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

在 .env 中配置 NEO4J_URI、NEO4J_USER、NEO4J_PASSWORD。如需 LLM 表达层，再填写所选服务的 API Key；不配置 LLM 也可运行完整的规则检索与 Agent 证据链。

# 清洗并导入图谱
python main.py

# 启动 FastAPI（默认 http://localhost:8000）
python qa_system.py

# 另一个终端运行 Agent 单元测试
python -m pytest -q tests/test_graphmind_runtime.py

浏览器打开 http://localhost:8000 使用 GraphMind 页面，或打开 http://localhost:8000/docs 调试接口。

项目结构

graphmind_runtime.py       # Tool Registry、Planner、Evidence Fusion/Gate、引用与轨迹
qa_system.py               # FastAPI、Neo4j 查询、实体/意图路由、会话记忆、问答入口
llm_service.py             # 可选 LLM 服务与严格的证据内回答提示
index.html                 # GraphMind 聊天、证据卡片、工具轨迹、图谱可视化
kg_builder.py              # Neo4j 图谱构建
data_cleaner.py            # 实体/关系清洗与端点校验
data/                      # 原始、扩展和清洗后的 CSV 数据
tests/test_graphmind_runtime.py

效果预览

现有截图来自原始 KBQA 界面；升级后的页面会额外显示 Evidence 状态、引用卡片与 Agent 工具轨迹。更多原项目展示说明见 SHOWCASE.md。

边界说明

• 语义检索当前基于本地轻量文本向量，便于离线运行；它不是独立向量数据库或 Cross-Encoder。
• LLM 可以组织图谱事实，也可以在证据不足时提供通识补充；两类内容必须通过状态、提示语和引用字段区分，模型可用不等于图谱证据充分。
• find_relation_path、子图深度和结果数量均设有硬上限，以控制 Cypher 查询范围和返回上下文大小。
• 密钥、日志、缓存和本地运行产物不应提交；私有配置只通过环境变量或 .env 提供。