graphrag-ts

项目简介

graphrag-ts 是一个基于 TypeScript 和 PostgreSQL 实现的 GraphRAG 参考实现，专为 Markdown 文档知识库设计。它将非结构化文本抽取为实体、关系和声明，通过图算法构建社区层级，并结合向量检索、关键词匹配和图拓扑信号实现混合召回，最终生成有据可查的答案。与微软官方 GraphRAG 强依赖 Python 生态不同，该项目完全基于 Bun + TypeScript，对已有 PostgreSQL 和 Prisma 技术栈的团队接入成本极低。

核心功能

• Markdown 感知构建管道：自动切片 Markdown 文件，提取实体、边和声明，生成知识图谱
• Leiden 社区检测：在 PostgreSQL 环境中调用 WASM 版 igraph 做层级社区划分，生成社区摘要
• 三路混合召回：结合向量相似度、关键词匹配和图邻居扩散三种检索路径，用 RRF 算法融合结果
• 证据驱动的答案生成：从检索到的证据集出发，由 LLM 生成有据可查的回答
• 多跳推理支持：支持跨文档多跳关系查询，如「张三的上级和李四负责的项目有什么合作」
• 全局总结能力：通过社区摘要层的 Map-Reduce，回答文档集层面的宏观问题
• Prisma + PostgreSQL 持久化：直接复用团队已有的 Postgres + pgvector 环境
• 命名空间感知构建：支持多租户或多文档集隔离部署

技术实现

项目分为构建阶段和检索阶段两大部分。

构建阶段（src/build/）：Markdown 文件进入系统后，首先按语义和句边界做切片；接着用 LLM 抽取实体、关系边和声明；然后通过 WASM 编译的 igraph 库执行 Leiden 社区检测算法，将实体划分为层级社区并生成每个社区的摘要；最后所有数据持久化到 PostgreSQL（实体表、边表、声明表、社区表），pgvector 用于后续向量检索。

检索阶段（src/retrieval/）：用户查询进来后，先做意图解析；接着并发执行三路检索——向量相似度召回、关键词 BM25 匹配、以及从初始实体出发沿图拓扑扩散的邻居扩展；三路结果通过 RRF 算法做倒数排名融合，同时叠加实体重叠率和社区层级打分，选出最紧凑的证据子图；最后将证据集提交给 LLM 生成带引用的答案。

整个链路完全在 TypeScript/Bun 生态下运行，切片的 LLM Judge 模型和 Embedding 模型均通过环境变量接入，支持 OpenAI 风格接口的任意提供商。

快速上手

第一步：安装依赖 pnpm install，需要 pnpm 10+、Bun 1.1+、PostgreSQL（启用 pgvector 扩展）、聊天模型和 Embedding 模型。

第二步：复制 .env.example 为 .env 填写数据库连接串和模型 Key，执行 pnpm run db:generate 生成 Prisma Client，再执行 pnpm run db:push 推送表结构。

第三步：将要处理的 Markdown 文档放入 corpus 目录，调用构建管道生成实体图谱和社区摘要。

第四步：导入 injectGraphRAG 将 GraphRAG 服务注入应用，通过 retrieval() 方法传入自然语言问题，获取带证据引用的答案。

第五步：执行 bun run examples/demo.ts 可快速体验完整流程（需提前配置好模型 Key）。

适用人群

• 已有 TypeScript/Node.js 技术栈的 AI 应用开发团队
• 希望基于自有 Markdown 文档构建知识库问答系统的企业和个人
• 对 GraphRAG 感兴趣、想深入理解其原理的算法工程师和研究人员
• 需要在 PostgreSQL 已有环境下扩展知识库能力的数据平台团队

开源地址

GitHub：https://github.com/sadofriod/graphrag-ts npm 包：@ashes_born/graph-rag-ts 博客详解：https://blog.ashesborn.cloud/category/AI