# LiveGraphRAG

> 把散落在产品文档里的答案，变成带来源、能追溯、可继续追问的知识服务。

LiveGraphRAG 是一个面向私有化软件运维支持场景的 GraphRAG 项目。它以 Nextcloud 31、32、33 的官方资料为知识底座：当用户询问配置、升级、排错或功能差异时，系统不仅给出回答，还会附上对应的原始文档片段、版本信息与引用来源。

项目围绕 RAG 与 Agentic RAG 工作流构建，既能作为知识检索服务接入业务系统，也能为智能助手提供可靠的上下文与引用。

## 它能做什么

- 根据问题检索不同版本的官方资料，避免把旧版本说明当成当前答案。
- 结合关键词、向量和图关系寻找相关信息，而不是只做简单的文本匹配。
- 返回可点击、可阅读的来源证据，让每条结论都能回到原文。
- 支持租户与版本隔离，适合模拟多环境知识库的使用方式。
- 提供受限 Agent 流程：先查证据，再组织答案，引用不通过就不输出。
- 通过 Redis 缓存、限流、异步索引与可观测性组件，模拟一套更接近真实服务的运行链路。

## 项目一览

```text
用户 / AI Client
       │
       ▼
Web / API Client
       │
       ▼
检索与问答服务
 ┌─────┼─────────┐
 ▼     ▼         ▼
PostgreSQL  Redis  Neo4j
文档与快照  缓存与任务 图关系
       │
       ▼
模型 Provider（可切换）
```

系统默认使用确定性 Provider，方便在没有模型凭证的情况下体验完整流程；需要真实模型时，可以通过环境变量显式切换。

## 快速开始

### 环境要求

- Docker 与 Docker Compose
- Python 3.12+
- GNU Make（Windows 可使用兼容环境）

### 启动服务

```bash
cp .env.example .env
make up
make migrate
make import-postgres
make demo-up
```

`.env` 只用于本地配置，不应提交任何密钥或真实环境信息。

## 体验演示页面

启动演示页面：

```bash
make demo-ui
```

然后访问 [http://127.0.0.1:8080](http://127.0.0.1:8080)。页面提供两种使用方式：

- **证据检索**：输入问题，直接查看相关文档、版本与来源卡片。
- **Agent 分析**：观看系统依次检索资料、整理信息并生成带引用回答的过程。

如需启用 DeepSeek，在本机 `.env` 中设置 `DEEPSEEK_API_KEY`，并在启动前设置：

```bash
LIVEGRAPHRAG_LLM_PROVIDER=deepseek
```

真实模型调用可能产生费用。

## 产品界面

下列截图展示本地 Compose 演示中的完整链路：选择 Nextcloud 版本并提出运维问题，检索本版本官方资料，生成带来源校验的回答，再回溯到具体文档与行号。示例为 Nextcloud 32 的 Redis 文件锁问题，页面显示的模型与来源数量均来自该次运行。

| 首页与能力概览 | 版本化运维提问 |
| --- | --- |
| ![LiveGraphRAG 首页：官方证据、版本上下文与关系推理能力概览](docs/product-screenshots/main_interface.png) | ![分析工作台：输入 Redis 文件锁问题，选择 Nextcloud 32，并显示本次总结模型](docs/product-screenshots/query.png) |

| 可验证答案与本次分析 | 官方来源证据库 |
| --- | --- |
| ![分析结果：Redis 文件锁配置建议、授权校验状态、版本上下文和五条来源](docs/product-screenshots/result.png) | ![来源证据库：五条 Nextcloud 32 官方资料，显示标题、路径和可追溯行号](docs/product-screenshots/source.png) |

## 技术组成

| 领域 | 主要组件 |
|---|---|
| 服务接口 | Python、FastAPI、SSE |
| 关系与检索 | PostgreSQL、pgvector、全文检索、Neo4j |
| 异步处理 | PostgreSQL Outbox、Redis Streams |
| 缓存与限流 | Redis、Lua Token Bucket、SingleFlight |
| 可观测性 | OpenTelemetry、Prometheus、Grafana |
| 容器化 | Docker Compose |

## 项目结构

```text
apps/           API、智能检索与 Worker 入口
livegraphrag/   领域模型、应用服务与基础设施实现
migrations/     PostgreSQL 迁移
data/           固定语料、清单与评测数据
tests/          单元、契约与集成测试
docs/           架构、实验记录与运行说明
scripts/        数据处理与本地工具脚本
```

## 延伸阅读

- [项目概览](docs/PROJECT_OVERVIEW.md)
- [数据使用说明](NOTICE_DATA.md)

## 数据说明

仓库中的资料来自公开的 Nextcloud 官方文档。示例租户、角色和使用场景均为合成数据，不包含真实用户或企业信息。