企业官网建设流程全解析

DB-GPT Graph RAG 深度解析：知识图谱索引、四类图构建与图检索原理

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

本文聚焦 DB-GPT 的 Graph RAG（图谱检索）模式：在知识空间启用KnowledgeGraph索引方法后，系统如何构建由 LLM 三元组图、文档-段落图、Markdown 标题图、代码图谱组成的“图家族”，以及GraphRetriever如何通过关键词、向量相似度和 Text2GQL 三种方式定位图谱节点并沿边扩展子图。读完本文，你将掌握 Graph RAG 的建图与检索全流程、全部关键配置参数（含默认值）、图数据库（TuGraph/Neo4j）的配置方式，以及代码图谱中 tree-sitter AST 解析的实现细节与已知边界。

一、Graph RAG 是什么

Graph RAG 是 DB-GPT 中基于知识图谱索引的检索模式。当一个知识空间（knowledge space）启用了KnowledgeGraph索引方法，DB-GPT 就不再仅仅依赖向量或关键词检索，而是构建一族相互关联的图（a family of graphs），检索时通过**图遍历（graph traversal）**而不是（或辅以）向量/关键词搜索来召回知识。

从 docs/design 中的索引原理文档可以看到，DB-GPT 持久化的索引方法有三种：VectorStore（向量）、FullText（关键词/BM25）、KnowledgeGraph（知识图谱），三者可按知识空间自由组合。其中知识图谱索引是内部最复杂的一种——它不是一张图，而是共享同一条构建路径的多张图。这正是 DB-GPT Graph RAG 与传统 GraphRAG 实现（如微软版本以社区检测+全局摘要为主）的关键差异：DB-GPT 把图谱扩展为“三元组图 + 文档结构图 + 代码图”的复合体系，使答案可以精确回溯到来源 chunk。

二、启用 KnowledgeGraph 后构建的四种图

这四种图共享同一条构建路径，统一写入所配置的图数据库（graph store）。下面逐一说清每种图的语义。

2.1 LLM 三元组图（语义层）

每个 chunk 被送入 LLM，配合抽取提示词要求其输出(subject, predicate, object)三元组，返回的三元组以entity -edge- entity形式 upsert 进图存储。这是经典的“从文本构建知识图谱”路径，能捕获纯关键词/向量检索无法表达的事实与关系。例如：

chunk 文本："Anthropic's prompt cache reuses the KV matrix to cut cost" │ LLM 三元组抽取 ▼ (Anthropic) ──has──▶ (Prompt Cache) (Prompt Cache) ──reuses──▶ (KV matrix) (Prompt Cache) ──cuts──▶ (cost)

检索时，一个实体命中会扩展其邻居节点，且每条边都记录了自己来自哪个 chunk（通过_chunk_id边属性），因此答案仍可按来源引用。

2.2 文档-段落图（结构骨架）

独立于三元组之外，图存储中还会构建结构骨架：document -include- chunk、chunk -include- chunk（嵌套时的父/子关系）以及chunk -next- chunk（阅读顺序）。这使检索可以从一个实体跳到包含它的 chunk，再跳到所属文档和相邻 chunk。若启用了社区摘要（community summary）变体，还会执行社区检测并让 LLM 对每个社区做摘要。

2.3 Markdown 标题图

对于KnowledgeGraph空间下的.md文件，构建器从已存储的 chunk 中重建文件内容，扫描^(#{1,6})\s+标题行（跳过围栏代码块内的标题），输出由contains边连接的heading顶点：file → H1 → H2 → H3。它是“结构索引”的图谱化版本——用边遍历代替内存中的树。

2.4 代码图谱（tree-sitter AST 解析）

代码图谱是 Graph RAG 中最值得深入理解的部分。它由同一个RepoGraphBuilder（与 Markdown 标题图共享构建器）负责，是GIT_REPO类型知识空间实现代码级检索的核心。实现位于 repo_graph_builder.py：

• 以 AST 解析而非正则匹配：对 Python / Java / JavaScript / TypeScript / Go / Rust / C / C++ 使用 tree-sitter，把function_definition、class_definition、method_declaration、interface_declaration、struct_item等目标 AST 节点映射到语义节点类型；没有 tree-sitter 语法的语言回退到正则def/class行扫描，仍会输出file -defines-> function|class边。
• 节点类型：repository、file，以及代码节点function/class/method/interface/impl/struct/enum/trait，每个节点携带name、file_path、start_line、end_line、language属性。
• 边类型：contains（repo→file、file→heading）与defines（file→代码节点）。
• 扫描约束（源码可见的工程细节）：RepoGraphBuilder 内置SKIP_DIRS（.git、node_modules、__pycache__、venv、dist、build、vendor、target、.next等）跳过无关目录，单文件超过MAX_FILE_SIZE = 1_000_000字节（约 1MB）的文件会被跳过，保证构建不会拖垮图数据库。

它带来的是精确的代码级问答能力，比如“apply_anthropic_cache_control定义在哪里”“列出PromptCache类的所有方法”——由顶点查找 +defines边遍历回答，而不是模糊的向量匹配。

关于边的重要边界（务必知晓）：检索层支持遍历CALLS/INHERITS/IMPLEMENTS边（用于调用链与类层级查询），但当前的RepoGraphBuilder只产出contains和defines两类边。因此，如果图谱完全由该构建器生成，调用链、继承关系类查询将返回空结果——除非这些边由其他构建器产生。设计依赖调用图谱的功能时必须注意这一点。

三、GraphRetriever 的检索流程

GraphRetriever通过四种方式匹配图节点——关键词、节点嵌入的向量相似度、自然语言转图查询（Text2GQL）、以及文档-图关联——然后沿边扩展。每条边都记住其来源 chunk，保证答案可引用。

核心实现在 graph_retriever.py，它采用策略组合架构：主类组装四个子检索器（见 graph_retriever.py#L124-L144）：

• KeywordBasedGraphRetriever：按关键词在三元组图中查节点；
• VectorBasedGraphRetriever：按节点/问题嵌入向量做相似度检索（依赖图数据库的向量能力，TuGraph 4.5.1+）；
• TextBasedGraphRetriever：先做意图翻译，再由 Text2GQL 生成图查询语句直接查图；
• DocumentGraphRetriever：在三元组命中后，用命中的实体去文档图中定位 chunk 与文档。

3.1 完整检索链路

从 GraphRetriever.retrieve 的源码可以还原出精确的决策顺序：

1. 若启用 Text2GQL 文本搜索（enable_text_search）：先走TextBasedGraphRetriever，将自然语言问题转成图查询直接检索三元组图；
2. 用KeywordExtractor（LLM 驱动）从原始问题中抽取关键词；
3. 若上一步没有命中任何子图：
   • 若启用向量相似搜索，则将问题与关键词分别嵌入，把向量集合作为subs；否则直接用关键词字符串；
   • 若启用三元组图（TRIPLET_GRAPH_ENABLED）：按上述subs类型选择向量或关键词检索器查三元组图；
   • 若启用文档图（DOCUMENT_GRAPH_ENABLED）：三元组图命中则用子图中的实体反查文档图（实体 → 所属 chunk → 文档）；三元组未命中则用subs直接查文档图。
4. 返回三元组子图(subgraph)与文档子图(subgraph_for_doc, text2gql_query)，交给上层拼装为带引用的上下文。

这个“Text2GQL 优先、关键词/向量兜底、实体反查文档”的级联设计，正是原文档所述“答案保持可引用”的底层保证：无论哪条路径命中，最终都收敛到携带_chunk_id的边和具体 chunk。

3.2 三种检索手段的适用场景与配置

（1）关键词检索（默认路径）：LLM 抽取关键词后按节点名匹配，适合精确术语、实体名明确的场景。

（2）向量相似度检索：TuGraph 提供了向量存储、索引与相似度搜索能力，DB-GPT 在 entity 与 chunk 对象中引入_embedding字段存储嵌入数据。启用后，对“清北大学”这类关键词抽取困难、但语义指向明确的模糊查询，能召回“清华大学”相关节点——相比纯关键词检索覆盖面更广，答案更丰富。

（3）Text2GQL 检索：关键词或向量检索会为 LLM 生成较大的多跳子图去总结信息，当用户问题可用单条图查询表达时（例如“DB-GPT 在知识图谱中是什么”），这种方式成本较高。Text2GQL 能生成精确的图查询语言，例如：

MATCH (n) WHERE n.id = 'DB-GPT' RETURN n LIMIT 10

在问题简洁清晰时显著降低检索成本并提高子图精确度。Text2GQL 支持两种实现：基于 LLM 的提示词方式，或本地微调模型（TEXT2GQL_MODEL_ENABLED=True+TEXT2GQL_MODEL_NAME，如qwen2.5:latest，对应 LocalText2GQL）。

3.3 文档图检索（Retrieval Of Document Structure）

DB-GPT 0.6.1 扩展了 GraphRAG 中 “Graph” 的定义：

Knowledge Graph = Triplets Graph + Document Structure Graph

文档结构图将标准格式文件（当前对 Markdown 支持最好）按层级与布局信息分解为有向图存入图数据库：每个节点代表一个 chunk，每条边代表 chunk 间的结构关系，并与三元组图合并。由此 GraphRAG 回答时能够给出原文引用。

四、图数据库与配置

四类图都写入所配置的 graph store。从源码结构看，graph_store 工厂目录提供了 TuGraph 与 Neo4j 两种适配器；应用配置中通过[rag.storage.graph]段选择类型。仓库提供了完整的 GraphRAG 配置示例 configs/dbgpt-graphrag.toml：

[rag.storage.graph] type = "tugraph" host = "127.0.0.1" port = 7687 username = "admin" password = "73@TuGraph"

4.1 准备 TuGraph

TuGraph 是 DB-GPT 首推的图数据库。按官方快速入门文档拉取并启动容器（版本要求 latest / >= 4.5.1；向量相似度检索需要 TuGraph 4.5.1 及以上，因为用到其向量能力）：

docker pull tugraph/tugraph-runtime-centos7:4.5.1 docker run -d -p 7070:7070 -p 7687:7687 -p 9090:9090 \ --name tugraph_demo tugraph/tugraph-runtime-centos7:latest \ lgraph_server -d run --enable_plugin true

其中bolt 协议默认端口为7687（上述配置中的port即指它）。

4.2 环境变量总表

以下变量在.env文件中设置，是 Graph RAG 行为的全部开关。结合 GraphRetriever 构造函数 的解析逻辑与各参数默认值：

4.3 Web 界面使用流程

1. 在知识库页面用Knowledge Graph类型创建知识库；
2. 上传文档（如 graphrag-test.md），默认按 Markdown 标题切分并自动索引；
3. 索引完成后即可查看图谱数据，然后开始基于知识图谱的对话。

DB-GPT Graph RAG 知识创建与图谱数据界面：

五、编程式构建 Graph RAG 应用

仓库提供了可直接运行的示例 examples/rag/graph_rag_example.py，它演示两种图谱连接器：BuiltinKnowledgeGraph（朴素图谱）与CommunitySummaryKnowledgeGraph（带社区摘要），并以 pytest-asyncio 方式运行：

# .env 中设置 LLM 与 TuGraph 连接（见上节环境变量总表） pip install pytest pytest-asyncio pytest -s examples/rag/graph_rag_example.py

核心 API 链路（摘自示例）：

from dbgpt.model.proxy.llms.chatgpt import OpenAILLMClient from dbgpt.rag.embedding import DefaultEmbeddingFactory from dbgpt_ext.rag.assembler import EmbeddingAssembler from dbgpt_ext.rag.knowledge import KnowledgeFactory from dbgpt_ext.rag import ChunkParameters from dbgpt_ext.storage.knowledge_graph.community_summary import ( CommunitySummaryKnowledgeGraph, ) from dbgpt.rag.retriever import RetrieverStrategy llm_client = OpenAILLMClient() model_name = "gpt-4o-mini" def create_community_kg_connector(): """创建带社区摘要的知识图谱连接器""" return CommunitySummaryKnowledgeGraph( config=TuGraphStoreConfig(), # TuGraph 连接配置 name="community_graph_rag_test", embedding_fn=DefaultEmbeddingFactory.openai(), llm_client=llm_client, llm_model=model_name, ) knowledge = KnowledgeFactory.from_file_path(file_path) assembler = await EmbeddingAssembler.aload_from_knowledge( knowledge=knowledge, chunk_parameters=ChunkParameters(chunk_strategy="CHUNK_BY_MARKDOWN_HEADER"), index_store=knowledge_graph, # 以知识图谱作为索引存储 retrieve_strategy=RetrieverStrategy.GRAPH, # 图检索策略 ) await assembler.apersist() # 构建图谱 retriever = assembler.as_retriever(1) chunks = await retriever.aretrieve_with_scores(question, score_threshold=0.3)

要点：把index_store指向知识图谱对象、retrieve_strategy设为GRAPH后，整个EmbeddingAssembler管线（切分 → 嵌入 → 建图）就切换到 Graph RAG 路径，检索接口与向量库保持一致，便于在同一业务中切换索引方式。

六、与 RAG 的定位差异及已知边界

• 定位差异：向量 RAG 把整个 chunk 平均成一个点，混合主题会模糊、精确术语（API 名、错误码）可能漏检；Graph RAG 用图谱遍历捕获关系与结构，文档结构图让答案可以精确引用到 chunk，相似度检索补上语义泛化，Text2GQL 则在“单查询可表达”的问题上降本提准。四种图 + 三条检索路径的组合，使 Graph RAG 适合实体关系密集、文档结构规范、需要代码级问答的知识库场景。
• 已知边界（来自原文档与源码的一致表述）：
  1. 检索层支持的CALLS/INHERITS/IMPLEMENTS边，当前RepoGraphBuilder不产出，纯自建图谱上的调用链/继承查询为空；
  2. 向量相似度检索依赖 TuGraph 4.5.1+ 的向量能力，并必须配置嵌入模型；
  3. 结构类图（标题图、文档结构图）的价值集中在 Markdown 等结构化文档；非 Markdown 文档没有标题层级，结构树退化为扁平列表。
• 适用前提：文中所有配置项、默认值与端口均基于当前仓库源码（packages/dbgpt-ext）与 configs/dbgpt-graphrag.toml 实测核对；升级 TuGraph 或更换 Neo4j 后请以对应适配器的行为为准。

七、延伸阅读

• 知识库索引原理：从原始文件到可检索索引的完整管线（结构/知识图谱/向量/关键词索引）；
• Agentic RAG 对话原理：图谱检索如何嵌入 Agentic 检索循环；
• Graph RAG Cookbook：编程式构建 Graph RAG 应用的完整用户手册；
• TuGraph 集成安装：图数据库后端安装指南；
• RAG 模块参考：RAG 模块整体 API 与概念。

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT