EdgeQuake

高性能图RAG框架，基于Rust
将文档转化为智能知识图谱，实现卓越的检索与生成能力

v0.10.1 — 加强了Sigma图查看器的性能，为密集PDF文件设定了更安全的嵌入限制，并实现了curl | sh和GHCR安装流程的完全绿色通过。完整详情请参阅CHANGELOG。

---

为什么选择EdgeQuake？

传统的RAG系统仅依靠向量相似度来检索文档片段。这种方法适用于简单的查询，但在多跳推理（“X如何通过Z与Y相关？”）、主题性问题（“主要主题有哪些？”）以及关系型查询方面表现不佳。核心问题在于：向量能够捕捉语义相似性，却会丢失概念之间的结构化关系。

EdgeQuake通过在Rust中实现LightRAG算法解决了这一难题：文档不仅会被分块并嵌入向量空间，还会被分解为一个由实体和关系构成的知识图谱。在查询时，系统会同时遍历向量空间和图结构，将向量搜索的速度与图遍历的推理能力相结合。

EdgeQuake的独特之处

• 知识图谱：由LLM驱动的实体提取和关系映射，能够创建对文档的结构化理解——而不仅仅是关键词匹配。
• 6种查询模式：从快速的朴素向量搜索到基于图遍历的混合查询，每种模式都针对不同类型的提问进行了优化。
• Rust性能：采用异步优先的Tokio架构，结合零拷贝操作，可处理数千个并发请求。
• PDF LLM视觉管道 ✅ 0.4.0新增：多模态LLM（GPT-4o、Claude、Gemini）可以将PDF页面作为图像进行读取——开箱即用即可处理扫描文档、复杂表格和多栏布局。
• 生产就绪：支持OpenAPI 3.0 REST API、SSE流式传输、健康检查以及多租户工作空间隔离。
• 现代化前端：使用React 19，配合交互式的Sigma.js图可视化工具。

性能基准测试

指标	EdgeQuake	传统RAG	改进幅度
实体提取	~2-3倍更多	基线	3倍
查询延迟（混合模式）	< 200ms	~1000ms	快5倍
文档处理	25秒（1万 tokens）	~60秒	快2.4倍
并发用户数	1000+	~100	高10倍
每文档内存占用	2MB	~8MB	更优4倍

v0.4.0 — PDF现已生产就绪：PDF处理管道内置了pdfium（无需配置），并提供可选的LLM视觉模式。文本模式提取适用于所有标准PDF；启用use_vision_llm = true（或发送X-Use-Vision: true）即可将页面路由至具备视觉能力的LLM，以处理扫描文档和复杂布局。

v0.4.0更新：PDF处理现可通过edgequake-pdf2md v0.4.1中的内置pdfium实现生产就绪。无需额外设置任何库，只需上传PDF即可！

---

功能特性

🚀 高性能

• 异步优先：基于Tokio的运行时，实现最大并发能力。
• 零拷贝：利用Rust的所有权机制高效管理内存。
• 并行处理：多线程实体提取与向量嵌入。
• 快速存储：使用PostgreSQL AGE存储图数据，pgvector存储向量嵌入。
• SQL预过滤：元数据过滤条件（租户、工作空间、文档）会被推送到SQL WHERE子句中，结合GIN + B-tree索引，可在大规模场景下减少高达90%的无效向量扫描。

💉 知识注入 ✨ 0.8.0新增 (#131)

• 领域术语表：注入缩写定义（OEE、NLP、ML）及同义词映射，自动扩展查询词。
• 隐形引用：注入条目会丰富知识图谱，但不会显示为查询结果中的来源引用。
• 完整的CRUD API：按工作空间提供PUT、GET、PATCH、DELETE接口；通过POST /api/v1/workspaces/:id/injection/upload可进行基于文件的注入。
• 文本与文件输入：接受纯文本定义或上传.txt/.md术语表文件。
• 状态轮询：后台处理过程中会跟踪实体数量，并显示已完成、失败或处理中的状态。
• 专用UI：/knowledge页面提供列表视图、内联编辑、删除确认及实体数量显示。
• 查询扩展：在向量搜索之前，自动使用注入的同义词扩展查询。

🏷️ 自定义实体配置 ✨ 0.9.0新增 (#85)

• 领域预设：可选择6种精选预设——通用、制造、医疗、法律、科研、金融。
• 最多50种实体类型：每个工作空间可配置多达50种领域特定类型（此前上限为20种）。
• 自定义类型：可在预设之外添加任意大写下划线命名的实体类型（如BEARING_TYPE、VIBRATION_ANOMALY）。
• 工作空间级配置：实体类型在创建工作空间时设定，并存储于工作空间元数据中。
• 自动归一化：输入内容会在存储前进行修剪、转大写并去重。
• 实时UI选择器：工作空间创建对话框中包含可折叠的实体类型部分，显示芯片标签和数量徽章。
• 向后兼容：未进行自定义配置的现有工作空间将自动使用9种默认的通用类型。

知识图谱

• 实体提取：自动检测人物、组织、地点、概念、事件、技术和产品（共7种可配置类型）。
• 关系映射：由LLM驱动的关系识别，结合关键词标注。
• 多次提取：多轮提取可比单次提取多捕获15-25%的实体。
• 社区检测：通过Louvain模块度优化，将相关实体聚类，便于主题性查询。
• 图可视化：交互式的Sigma.js前端，支持缩放和拖动。

📄 PDF 处理（v0.4.0 已正式上线）

• 文本模式：基于 pdfium 的快速提取，适用于标准 PDF（默认设置，无需配置）
• 视觉模式 ✨：使用大模型将每页作为图像读取 — 支持 GPT-4o、Claude 3.5+ 和 Gemini 2.5
• 自动回退：当视觉模式失败时，会优雅地回退到文本提取（BR1010）
• 表格重建：视觉模式能够恢复文本解析器容易出错的复杂表格
• 多栏布局：大模型能够理解多栏页面的阅读顺序
• 内置 pdfium：无需设置 PDFIUM_DYNAMIC_LIB_PATH 环境变量 — 二进制文件已打包在主程序中

🔍 6 种查询模式

1. 朴素模式：简单的向量相似度匹配 — 适合关键词式查找，速度最快（约 100–300 毫秒）
2. 局部模式：以实体为中心，结合局部图谱邻域 — 适合查询特定关系（约 200–500 毫秒）
3. 全局模式：基于社区的语义搜索 — 适合主题性或高层次问题（约 300–800 毫秒）
4. 混合模式 (默认)：结合局部与全局搜索，提供平衡且全面的结果（约 400–1000 毫秒）
5. 混合模式：可自定义比例的朴素模式与图谱结果加权组合
6. 绕过模式：直接调用大模型进行查询，不经过 RAG 检索 — 适用于一般性问题

🌐 REST API

• OpenAPI 3.0：完整的 Swagger 文档位于 /swagger-ui
• 流式传输：使用 Server-Sent Events (SSE) 提供实时响应
• 版本化：路径为 /api/v1/*，并保持向后兼容
• 健康检查：提供 Kubernetes 兼容的 /health、/ready 和 /live 接口

🎯 React 19 前端

• 实时流式渲染：逐 token 显示生成内容
• 图可视化：支持缩放和拖动的交互式网络图
• 文档上传：拖放上传，并显示进度
• 配置界面：可视化 PDF 处理配置构建器

🔌 MCP（模型上下文协议）

• 代理集成：通过 MCP 向 AI 代理开放 EdgeQuake 功能
• 工具发现：代理可以编程方式查询、上传并探索知识图谱
• 互操作性：兼容 Claude、Cursor 等支持 MCP 的客户端

服务器实现细节请参见 mcp/。

---

快速入门

⚡ 选项 1 — 一条命令（Docker，约 30 秒，无需编译）

仅需 Docker 即可，零前置条件。
不需要 Rust、Node.js，也无需运行 cargo build 或 npm install。

# 下载并运行交互式安装向导
curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/quickstart.sh | sh

向导将引导您完成以下步骤：

1. 选择提供商 — 选择 OpenAI 或 Ollama（无需从环境变量中推断）
2. 选择模型 — 从精选且标明价格的列表中挑选您的大模型及嵌入模型
3. 验证 — 检查 OpenAI 的 API 密钥或 Ping Ollama 并确认模型可用性
4. 启动服务栈 — 拉取镜像、启动服务，并轮询健康状态，耗时最多 90 秒
5. 重复运行感知 — 检测当前运行或停止的容器以及现有数据卷；提供“更新并重新配置”或安全的“全新启动”选项（需输入 DELETE）。

或者直接使用 docker compose：

curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/docker-compose.quickstart.yml \
  | docker compose -f - up -d

也可以先下载 Compose 文件再启动：

curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/docker-compose.quickstart.yml \
  -o docker-compose.quickstart.yml
docker compose -f docker-compose.quickstart.yml up -d

随后打开： http://localhost:3000

服务	URL
Web UI	http://localhost:3000
API	http://localhost:8080
Swagger	http://localhost:8080/swagger-ui
健康检查	http://localhost:8080/health

无头模式 / CI 安装（无需交互式终端）：

EDGEQUAKE_LLM_PROVIDER=openai \
  OPENAI_API_KEY=sk-... \
  docker compose -f docker-compose.quickstart.yml up -d

管理命令：

docker compose -f docker-compose.quickstart.yml logs -f    # 查看日志
docker compose -f docker-compose.quickstart.yml ps         # 检查状态
docker compose -f docker-compose.quickstart.yml down       # 停止服务

指定版本： 使用 EDGEQUAKE_VERSION=0.10.1 sh quickstart.sh 可以安装特定版本。

---

🛠️ 选项 2 — 开发环境搭建（需 Rust 工具链）

前置条件

• Rust：1.78 或更高版本（安装 Rust）
• Node.js：18+ 或 Bun 1.0+（安装 Node）
• Docker：用于 PostgreSQL（安装 Docker）
• Ollama：用于本地大模型（可选，安装 Ollama）

安装步骤（5 分钟）

# 1. 克隆仓库
git clone https://github.com/raphaelmansuy/edgequake.git
cd edgequake

# 2. 安装依赖
make install

# 3. 配置前端环境
cp edgequake_webui/.env.local.example edgequake_webui/.env.local

# 4. 启动完整服务栈（PostgreSQL + 后端 + 前端）
make dev

完成！ 🎉

• 后端：http://localhost:8080
• 前端：http://localhost:3000
• Swagger UI：http://localhost:8080/swagger-ui
• 模型提供商：Ollama（本地，免费）

首次上传文档

# 上传文件（PDF、TXT、MD 等）
curl -X POST http://localhost:8080/api/v1/documents/upload \
  -F "file=@your-document.pdf"

响应：

{
  "id": "doc-123",
  "status": "已完成",
  "chunk_count": 15,
  "entity_count": 12,
  "relationship_count": 8,
  "processing_time_ms": 2500
}

首次查询

# 查询知识图谱
curl -X POST http://localhost:8080/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "主要概念是什么？",
    "mode": "混合"
  }'

响应：

{
  "answer": "主要概念包括：知识图谱、实体抽取和混合检索……",
  "sources": [
    { "chunk_id": "chunk-1", "similarity": 0.92 },
    { "chunk_id": "chunk-5", "similarity": 0.87 }
  ],
  "entities": ["KNOWLEDGE_GRAPH", "ENTITY_EXTRACTION"],
  "relationships": [
    {
      "source": "KNOWLEDGE_GRAPH",
      "target": "ENTITY_EXTRACTION",
      "type": "ENABLES"
    }
  ]
}

---

架构

┌────────────────────────────────────────────────────────────────────────────┐
│                              EdgeQuake 系统                              │
└────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  前端（React 19 + TypeScript）                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  文档        │  │    查询      │  │    图         │  │   设置       │     │
│  │   上传       │  │  接口        │  │ 可视化        │  │   配置       │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
│         │                 │                 │                 │             │
│         └─────────────────┴─────────────────┴─────────────────┘             │
│                                    │                                        │
│                                    ▼                                        │
│  ┌────────────────────────────────────────────────────────────────────┐     │
│  │                         REST API（Axum）                            │     │
│  │  /api/v1/documents  •  /api/v1/query  •  /api/v1/graph             │     │
│  │  OpenAPI 3.0 规范  •  SSE 流式传输  •  健康检查                  │     │
│  └────────────────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  后端（Rust - 11 个 Crate）                                                 │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │  edgequake-core          │  协调与管道                 │   │
│  │  edgequake-llm           │  OpenAI、Anthropic、MiniMax、Ollama 等 │   │
│  │  edgequake-storage       │  PostgreSQL AGE、内存适配器          │   │
│  │  edgequake-api           │  REST API 服务器                          │   │
│  │  edgequake-pipeline      │  文档摄取管道              │   │
│  │  edgequake-query         │  查询引擎（6 种模式）                   │   │
│  │  edgequake-pdf           │  PDF 提取（视觉 / edgeparse）            │   │
│  │  edgequake-auth          │  身份验证与授权                           │   │
│  │  edgequake-audit         │  合规性与审计日志                       │   │
│  │  edgequake-tasks         │  后台任务处理                            │   │
│  │  edgequake-rate-limiter  │  速率限制中间件                          │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                    ┌───────────────┴───────────────┐                        │
│                    ▼                               ▼                        │
│  ┌─────────────────────────────┐   ┌──────────────────────────────────┐     │
│  │   LLM 提供商             │   │   存储后端               │     │
│  │  • OpenAI（gpt-4.1-nano）    │   │  • PostgreSQL 15+（AGE + 向量） │     │
│  │  • Anthropic（Claude）       │   │  • 内存存储（开发/测试）       │     │
│  │  • MiniMax（MiniMax-M2.7）   │   │  • 图：属性图模型               │     │
│  │  • Ollama（gemma3:12b）      │   │  • 向量：pgvector 嵌入           │     │
│  │  • LM Studio、xAI、Gemini   │   │                                  │     │
│  │  通过环境变量自动检测     │   │                                  │     │
│  └─────────────────────────────┘   └──────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘

                    数据流：文档 → 分块 → 实体 → 图
                    查询流：问题 → 图遍历 → LLM → 答案

算法工作原理

EdgeQuake 在 Rust 中实现了 LightRAG 算法。其核心思想是：在索引阶段提取知识图，然后在查询时遍历该图。

索引管道（针对每份文档）：

1. 分块 — 将文档拆分为约 1200 个 token 的片段，重叠 100 个 token。
2. 提取 — 使用 LLM 将每个分块解析为 (实体, 类型, 描述) 和 (源, 目标, 关键词, 描述) 元组。
3. 提炼 — 可选的第二轮处理捕捉遗漏的实体（可将召回率提高约 18%）。
4. 归一化 — 通过大小写归一化和描述合并来去重实体（可减少约 36%-40% 的重复）。
5. 嵌入 — 为分块和实体生成向量嵌入。
6. 存储 — 写入 PostgreSQL：分块存储到 pgvector，实体/关系存储到 Apache AGE 图数据库。

查询流程（6 种模式）：

• 朴素 — 仅对分块进行向量相似度搜索（速度快，不使用图）。
• 局部 — 通过向量搜索找到相关实体，然后遍历其局部图邻域。
• 全局 — 使用 Louvain 社区检测找到主题聚类，并检索社区摘要。
• 混合 (默认) — 结合局部实体上下文与全局社区上下文。
• 混合 — 对朴素向量结果和图增强结果进行加权混合。
• 绕过 — 完全跳过检索步骤，直接将问题传递给 LLM。

完整的技术说明请参阅 LightRAG 算法深度解析。

---

文档

📚 完整文档索引

您可以在 docs/README.md 中浏览完整文档。

📦 SDKs

EdgeQuake 提供多种语言的官方 SDK：

• Python SDK (变更日志)
• TypeScript SDK (变更日志)
• Rust SDK
• 其他 SDK 支持 C#、Go、Java、Kotlin、PHP、Ruby、Swift 等语言。

SDK 和核心更新请参阅 CHANGELOG.md。

🚀 快速入门（15 分钟）

指南	描述	时间
安装指南	前提条件与设置	5 分钟
快速入门	首次数据摄取与查询	10 分钟
首次数据摄取	理解数据管道	15 分钟

📖 教程（动手实践）

教程	描述
构建你的第一个 RAG 应用	端到端教程
PDF 数据摄取	PDF 上传与配置
多租户设置	工作空间隔离
文档摄取	上传与处理工作流
从 LightRAG 迁移	Python 到 Rust 的迁移指南

🏗️ 架构（工作原理）

文档	描述
概述	系统设计与组件
数据流	文档如何在系统中流转
Crate 参考	11 个 Rust crate 的详细说明

💡 核心概念（理论）

概念	描述
Graph-RAG	为什么知识图谱能增强 RAG
实体抽取	基于 LLM 的实体识别
知识图谱	节点、边和社区
混合检索	向量检索与图检索结合

深度解析（高级）

文章	描述
LightRAG 算法	核心算法：抽取、图构建、检索
查询模式	6 种模式详解及权衡
实体归一化	去重与描述合并
提炼	多轮抽取以确保完整性
社区发现	Louvain 聚类用于全局查询
分块策略	基于 token 的分段并带重叠
嵌入模型	模型选择与维度的权衡
图存储	Apache AGE 属性图后端
向量存储	pgvector HNSW 索引与搜索
PDF 处理	视觉与 EdgeParse 抽取流水线
成本追踪	按操作监控 LLM 成本
管道进度	实时进度跟踪

📊 对比

对比	关键见解
与 LightRAG（Python）对比	性能与设计差异
与 GraphRAG 对比	微软方案对比
与传统 RAG 对比	为什么图很重要

API 参考

API	描述
REST API	HTTP 端点
扩展 API	高级 API 功能

运维（生产环境）

指南	描述
部署	生产环境部署
配置	所有配置选项
监控	可观测性设置
性能调优	优化指南

🐛 故障排除

指南	描述
常见问题	调试指南
PDF 抽取	PDF 特有的故障排除

🔗 集成

集成	描述
MCP 服务器	用于 AI 代理的模型上下文协议
OpenWebUI	具有 Ollama 模拟功能的聊天界面
LangChain	检索器与智能体集成
自定义客户端	Python、TypeScript、Rust、Go 客户端

📓 更多资源

• FAQ - 常见问题
• 食谱 - 实用技巧
• 安全 - 安全最佳实践

---

Docker 部署

EdgeQuake 在每次打标签发布时，都会通过 GitHub Container Registry (GHCR) 发布一个生产就绪的多架构 Docker 镜像。该镜像原生支持 linux/amd64（x86 服务器、Intel Mac）和 linux/arm64（Apple Silicon、AWS Graviton），无需 QEMU 模拟。

# 拉取最新版本 — 架构会自动选择
docker pull ghcr.io/raphaelmansuy/edgequake:latest

# 固定到特定版本
docker pull ghcr.io/raphaelmansuy/edgequake:0.10.1

首次发布包的可见性： 在首次通过 CI/CD 发布后，您可能需要在 GitHub → 您的个人资料 → Packages → edgequake → 包设置 → 更改可见性 中将 GHCR 包的可见性设置为 Public。一旦设为公开，docker pull 就无需身份验证即可使用。

根据您的部署环境，有以下三种部署选项可供选择：

---

选项 A — 仅 API（自备 PostgreSQL）

如果您已经拥有带有 pgvector 和 apache_age 扩展的 PostgreSQL 数据库，则这是最快的启动方式。无需 Rust 工具链，也不需要本地构建——只需拉取镜像并运行即可。

# 一行命令
docker run -d \
  --name edgequake \
  -p 8080:8080 \
  -e DATABASE_URL="postgres://user:password@your-db-host:5432/edgequake" \
  -e EDGEQUAKE_LLM_PROVIDER=openai \
  -e OPENAI_API_KEY="sk-..." \
  ghcr.io/raphaelmansuy/edgequake:latest

# 验证
curl http://localhost:8080/health

或者使用 docker compose（推荐用于持久化配置）：

cd edgequake/docker
cp .env.example .env        # 设置 DATABASE_URL 和提供商密钥
docker compose -f docker-compose.api-only.yml up -d
curl http://localhost:8080/health

---

选项 B — 使用预构建镜像的全栈部署 (最快，无需 Rust)

直接从 GHCR 拉取 EdgeQuake API、前端和 PostgreSQL 镜像。无需 Rust 工具链、Node.js 工具链或本地 Docker 构建。

cd edgequake/docker
cp .env.example .env        # 设置 EDGEQUAKE_LLM_PROVIDER 和您的 API 密钥
docker compose -f docker-compose.prebuilt.yml up -d

服务已启动：

服务	端口	镜像
edgequake API	8080	ghcr.io/raphaelmansuy/edgequake:latest
frontend	3000	ghcr.io/raphaelmansuy/edgequake-frontend:latest
postgres	5432	ghcr.io/raphaelmansuy/edgequake-postgres:latest

# 使用特定 API 版本
EDGEQUAKE_VERSION=0.10.1 docker compose -f docker-compose.prebuilt.yml up -d

# 查看日志
docker compose -f docker-compose.prebuilt.yml logs -f edgequake

# 健康检查
curl http://localhost:8080/health

# 停止
docker compose -f docker-compose.prebuilt.yml down

---

选项 C — 全栈，从源码构建（包含前端）

在本地构建包括 Next.js Web UI 在内的所有组件。需要 Docker BuildKit 和足够的磁盘空间（Rust 构建缓存约需 4 GB）。

cd edgequake/docker
docker compose up -d         # 构建 API、前端和 postgres

服务已启动：

服务	端口	描述
edgequake API	8080	REST API + 文档处理
frontend (Next.js)	3000	Web UI
postgres	5432	PostgreSQL with pgvector + Apache AGE

# 查看日志
docker compose logs -f edgequake

# 检查健康状况
curl http://localhost:8080/health

# 停止
docker compose down

---

环境变量

所有 compose 文件都从位于同一目录下的 .env 文件中读取配置。您可以复制 edgequake/docker/.env.example 文件来开始使用。

变量	默认值	描述
DATABASE_URL	(由全栈 compose 自动设置)	PostgreSQL 连接字符串
EDGEQUAKE_LLM_PROVIDER	ollama	大模型提供商：openai、anthropic、gemini、mistral、azure、vertexai、ollama
EDGEQUAKE_EMBEDDING_PROVIDER	(与 LLM 相同)	混合模式下的独立嵌入模型提供商
OPENAI_API_KEY	—	对于 openai / azure 必需
ANTHROPIC_API_KEY	—	对于 anthropic 必需
GEMINI_API_KEY	—	对于 gemini 必需
MISTRAL_API_KEY	—	对于 mistral 必需
AZURE_OPENAI_API_KEY	—	对于 azure 必需
AZURE_OPENAI_ENDPOINT	—	Azure 资源端点 URL
GOOGLE_CLOUD_PROJECT	—	对于 vertexai 必需
XAI_API_KEY	—	对于 xai 必需
OLLAMA_HOST	http://host.docker.internal:11434	Ollama 服务器地址（通过网关访问主机）
EDGEQUAKE_VERSION	latest	GHCR 镜像标签（仅适用于选项 B）
RUST_LOG	info	日志级别（debug、info、warn、error）

提示 — 主机上的 Ollama： 当 EdgeQuake 在 Docker 容器内运行而 Ollama 在您的主机上运行时，请将 OLLAMA_HOST 保持其默认值（http://host.docker.internal:11434）。在 Linux 上，compose 文件中的 extra_hosts: host.docker.internal:host-gateway 条目会自动解析此问题。

---

本地构建镜像

Dockerfile 位于 edgequake/docker/Dockerfile，采用两阶段构建（Rust 构建阶段 → Debian slim 运行时阶段）。pdfium 在编译时通过 pdfium-auto 嵌入，无需外部共享库。

# 为当前主机架构构建
docker build -f edgequake/docker/Dockerfile edgequake -t edgequake:local

# 多平台构建（需要 docker buildx）
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -f edgequake/docker/Dockerfile edgequake \
  -t edgequake:local --load

---

CI/CD — 自动化发布

当推送版本标签时，Docker 镜像会通过 GitHub Actions（.github/workflows/release-docker.yml）自动构建并发布：

# 标记一个发布版本 — 触发多架构 Docker 构建 + 发布到 ghcr.io
git tag v0.10.1 && git push origin v0.10.1

linux/amd64（使用 ubuntu-latest runner）和 linux/arm64（使用原生 ARM64 runner — 无需 QEMU）会并行构建，并合并为一个单一的多架构清单。同一个镜像标签（ghcr.io/raphaelmansuy/edgequake:0.10.1）可以在 x86 服务器、Apple Silicon Mac 和 AWS Graviton 实例上运行。

你也可以通过 GitHub Actions 上的 workflow_dispatch 输入来触发无标签的手动 Docker 构建与发布（“Actions → Release — Docker (GHCR) → Run workflow”）。

---

开发

构建与测试

# 构建后端
cd edgequake && cargo build --release

# 运行测试
cargo test

# 代码检查与格式化
cargo clippy
cargo fmt

# 构建前端
cd edgequake_webui
bun run build

Make 命令

EdgeQuake 使用统一的 Makefile 来处理所有开发任务：

# 完整开发栈
make dev              # 启动所有服务（PostgreSQL + 后端 + 前端）
make dev-bg           # 在后台启动（用于代理/自动化）
make dev-memory       # 使用内存存储启动（仅用于测试）
make stop             # 停止所有服务
make status           # 检查服务状态

# 仅后端
make backend-dev      # 使用 PostgreSQL 运行后端
make backend-memory   # 使用内存存储运行后端
make backend-bg       # 在后台运行后端
make backend-test     # 运行后端测试

# 仅前端
make frontend-dev     # 启动前端开发服务器
make frontend-build   # 构建用于生产环境的前端

# 数据库
make db-start         # 启动 PostgreSQL 容器
make db-stop          # 停止 PostgreSQL 容器
make db-wait          # 等待数据库就绪

# 质量检查
make test             # 运行所有测试
make lint             # 检查所有代码
make format           # 格式化所有代码
make clean            # 清理构建产物

代理工作流

EdgeQuake 的开发采用基于规范驱动的开发方法，使用 edgecode SOTA 编码代理。

• AGENTS.md：全面的代理指南和工作流
• specs/：所有开发规范
• OODA 循环：迭代式开发周期（观察、调整、决策、行动）

详细代理工作流文档请参阅 AGENTS.md。

---

贡献

EdgeQuake 是由 Raphaël MANSUY 创建的 edgecode SOTA 编码代理开发的。该项目遵循规范驱动的开发方法，所有更改都在实现之前先在 specs/ 目录中进行规范说明。

当前状态：edgecode 尚未公开，但很快就会发布。

目前，贡献应直接通过 Raphaël MANSUY 提交：

• GitHub Issues：报告 bug 并请求功能
• GitHub Discussions：提问和分享想法
• 直接联系：对于重大贡献，请联系 @raphaelmansuy

详细贡献指南请参阅 CONTRIBUTING.md。

---

社区与支持

行为准则

我们致力于提供一个友好且包容的环境。请阅读我们的 行为准则。

支持渠道

• GitHub Issues：Bug 报告和功能请求
• GitHub Discussions：问题解答和社区帮助
• LinkedIn：@raphaelmansuy
• Twitter/X：@raphaelmansuy

创始人

Raphaël MANSUY 🇫🇷 - 🇭🇰🇨🇳 — 香港永久居民，致力于构建智能文档检索系统和上下文图谱系统。

---

许可证

本项目采用 Apache License, Version 2.0（“许可证”）授权。您可以在以下网址获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面协议另有规定，否则根据本许可证分发的软件以“按原样”基础提供，不附带任何明示或暗示的保证或条件。具体语言的权限和限制请参阅 LICENSE 文件。

版权所有 © 2024–2026 Raphaël MANSUY

---

致谢

EdgeQuake 受以下优秀工作的启发，并在此基础上构建：

• LightRAG 研究论文（arxiv.org/abs/2410.05779）：我们感谢 LightRAG 基础算法的作者们，该算法驱动了 EdgeQuake 中核心的知识图谱提取和检索能力。他们在实体提取、关系映射和混合检索方面的创新方法对我们框架的设计起到了关键作用。

  特别感谢 LightRAG 的作者们：

  • Zirui Guo
  • Lianghao Xia
  • Yanhua Yu
  • Tu Ao
  • Chao Huang

• GraphRAG（arxiv.org/abs/2404.16130）：微软提出的“从局部到全局”的知识图谱方法，用于查询聚焦的摘要生成。

  • Shuai Wang
  • Yingqiang Ge
  • Ying Shen
  • Jianfeng Gao
  • Xiaodong Liu
  • Yelong Shen
  • Jianfeng Wang
  • Ming Zhou

• Rust 社区：感谢其出色的异步生态系统（Tokio、Axum、SQLx），这些技术使 EdgeQuake 能够实现高性能。

• React 社区：感谢 React 19 和现代前端栈，它们为我们交互式的用户界面提供了强大支持。

---

快速链接

资源	URL
📚 完整文档	docs/README.md
🚀 快速入门指南	docs/getting-started/quick-start.md
📦 SDK 概览	sdks/
🐍 Python SDK	sdks/python/README.md
🦀 Rust SDK	sdks/rust/README.md
🟦 TypeScript SDK	sdks/typescript/README.md
📜 更改日志	CHANGELOG.md
🔧 代理工作流	AGENTS.md
🤝 参与贡献	CONTRIBUTING.md
📜 行为准则	CODE_OF_CONDUCT.md
📄 许可证	LICENSE
🐛 报告问题	GitHub Issues
💬 讨论	GitHub Discussions
🌐 仓库	github.com/raphaelmansuy/edgequake

---

准备好构建智能文档检索了吗？ 立即开始！

星标历史

EdgeQuake 快速上手指南

EdgeQuake 是一个基于 Rust 构建的高性能 Graph-RAG（图检索增强生成）框架。它通过将文档转化为智能知识图谱，结合向量搜索的速度与图遍历的推理能力，显著提升了多跳推理和复杂主题查询的效果。

环境准备

方案一：零依赖运行（推荐）

仅需安装 Docker 和 Docker Compose。无需安装 Rust、Node.js 或任何编译工具。

• 适用场景：快速体验、生产部署、CI/CD 环境。

方案二：开发模式

若需修改源码或贡献代码，需准备以下环境：

• Rust: 版本 1.78 或更高 (安装链接)
• Node.js: 版本 18+ 或 Bun 1.0+ (安装链接)
• Docker: 用于运行 PostgreSQL 数据库 (安装链接)
• Ollama (可选): 用于本地运行大模型 (安装链接)

国内加速提示：

• Rust 用户建议配置 Crates.io 镜像源。
• Docker 用户建议配置国内镜像加速器（如阿里云、腾讯云等）以加快拉取速度。
• Node.js 用户建议使用 cnpm 或配置 npm 淘宝镜像。

---

安装步骤

方式 A：一键启动（Docker）

这是最快捷的方式，脚本会自动引导你选择 LLM 提供商（OpenAI 或 Ollama）并完成环境初始化。

1. 运行交互式安装向导

curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/quickstart.sh | sh

脚本将引导你完成：提供商选择、模型选择、API Key 验证及服务启动。

2. 非交互式启动（适用于 CI 或无终端环境） 如果你已准备好环境变量，可直接通过 docker compose 启动：

EDGEQUAKE_LLM_PROVIDER=openai \
OPENAI_API_KEY=sk-你的密钥 \
curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/docker-compose.quickstart.yml \
| docker compose -f - up -d

3. 访问服务 启动完成后，打开浏览器访问：

• Web 界面: http://localhost:3000
• API 接口: http://localhost:8080
• Swagger 文档: http://localhost:8080/swagger-ui

方式 B：源码开发安装

1. 克隆仓库

git clone https://github.com/raphaelmansuy/edgequake.git
cd edgequake

2. 安装依赖并配置

# 安装后端和前端依赖
make install

# 配置前端环境变量
cp edgequake_webui/.env.local.example edgequake_webui/.env.local

3. 启动全栈服务

make dev

此命令将自动启动 PostgreSQL、后端服务和前端开发服务器。默认使用 Ollama 作为提供商。

---

基本使用

1. 创建工作空间

登录 Web 界面 (http://localhost:3000)：

• 点击 "New Workspace"。
• 选择领域预设（如通用、医疗、法律等）或自定义实体类型。
• 配置 LLM 和 Embedding 模型（若在安装时未配置）。

2. 上传文档

• 支持 PDF 和 文本文件。
• PDF 处理模式：
  • 文本模式 (默认)：快速提取标准 PDF 内容。
  • 视觉模式 (Vision Mode)：针对扫描件、复杂表格或多栏布局，开启 Use Vision LLM 选项，系统将调用多模态模型（如 GPT-4o, Claude 3.5）读取页面图像。
• 拖拽文件上传，系统会自动进行实体提取、关系映射并构建知识图谱。

3. 发起查询

在对话框中输入问题，EdgeQuake 提供 6 种查询模式，默认为 Hybrid (混合模式)：

• Naive: 纯向量相似度搜索，速度最快，适合简单关键词查找。
• Local: 基于实体的局部图邻域搜索，适合查询具体实体间的关系。
• Global: 基于社区的全局语义搜索，适合宏观主题性问题（如“主要趋势是什么？”）。
• Hybrid (默认): 结合 Local 和 Global，平衡速度与深度，适合大多数复杂问题。
• Mix: 可配置权重的混合模式。
• Bypass: 跳过检索直接询问 LLM，适合通用常识问题。

示例提问：

"X 是如何通过 Z 与 Y 产生关联的？" (测试多跳推理能力) "这份文档中关于制造业的主要主题有哪些？" (测试全局主题分析)

4. 查看知识图谱

查询结果页面右侧或独立的 Knowledge 标签页展示了交互式图谱：

• 使用鼠标滚轮缩放、拖拽平移。
• 点击节点查看实体详情及关联关系。
• 可视化呈现文档中的概念网络。

5. 高级功能：知识注入 (Knowledge Injection)

在 v0.8.0+ 版本中，你可以注入领域术语表：

• 上传 .txt 或 .md 文件，定义缩写词（如 OEE, NLP）或同义词。
• 系统会自动将这些知识融入图谱，并在查询时自动扩展术语，且不会作为引用来源显示。
• 路径：Web 界面 -> /knowledge 页面进行管理。