DB-GPT GraphRAG 实战基于 TuGraph 的社区摘要知识图谱构建与混合检索全解析【免费下载链接】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_app_develop.md 展开系统讲解如何用图数据库TuGraph在 DB-GPT 中落地 Graph RAG从环境安装、图数据库部署、LLM 配置、.env参数逐项解析到CommunitySummaryKnowledgeGraph连接器与EmbeddingAssembler检索管线的完整代码实战。读完本文你将掌握 DB-GPT GraphRAG 的三大检索增强能力——文档结构图、向量相似度检索与 Text2GQL 查询翻译的启用方法与源码级原理并能复现官方性能对比数据背后的实现机制。一、为什么用图数据库做 RAG传统向量数据库检索存在两个固有短板不确定性相似度分数是黑盒命中的切片之间没有显式关系可解释可解释性差回答难以追溯到实体与实体之间的具体关系。Graph RAG 的思路是把文档拆解为实体—关系三元组存入图数据库检索时不再只依赖向量近邻而是通过关键词、向量相似度或图查询语言GQL在图上探索子图再交由 LLM 基于子图摘要作答。从源码结构看DB-GPT 对Graph的定义不止一份图而是双图结构Knowledge Graph Triplets Graph Document Structure GraphTriplets Graph三元组图LLM 从文本中抽取的(实体, 关系, 实体)边Document Structure Graph文档结构图按文档层级如 Markdown 标题构建的 chunk 有向图节点是 chunk、边表示结构关系include / next并与三元组图合并。正是这套结构让 GraphRAG 在回答时可以给出原文引用缓解纯向量 RAG 的溯源困难。完整流程参考源码示例 examples/rag/graph_rag_example.py加载文档知识、写入图存储再通过搜索三元组召回与问题相关的子图。二、环境准备2.1 安装依赖首先安装dbgpt库官方推荐用uv按 extras 安装uv sync --all-packages --frozen \ --extra proxy_openai \ --extra rag \ --extra storage_chromadb \ --extra dbgpts --extra graph_rag其中proxy_openai提供 OpenAI 代理客户端storage_chromadb用于社区摘要Community Summary的向量存储graph_rag则是图检索相关依赖图存储连接、Leiden 社区发现插件上传等。2.2 部署 TuGraph 图数据库DB-GPT 首个支持的图数据库是 TuGraph要求版本 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 truebolt 协议默认端口为7687即下文.env中TUGRAPH_PORT的取值7070 为 HTTP 端口9090 为监控端口国内网络环境可用官方提供的 OSS 镜像包直接导入wget https://tugraph-web.oss-cn-beijing.aliyuncs.com/tugraph/tugraph-4.5.1/tugraph-runtime-centos7-4.5.1.tar -O tugraph-runtime-centos7-4.5.1.tar docker load -i tugraph-runtime-centos7-4.5.1.tar2.3 准备 LLM构建 Graph RAG 程序需要一个 LLM用于三元组抽取、社区摘要与最终作答DB-GPT 支持三种接入方式方式一OpenAI API将 API Key 设置为环境变量OPENAI_API_KEYfrom dbgpt.model.proxy import OpenAILLMClient llm_client OpenAILLMClient()方式二YI零一万物API准备好 YI 账号与 API Key设置为环境变量YI_API_KEY后即可通过对应的代理客户端调用。方式三DB-GPT 集群 API Server如果已部署 DB-GPT 集群与 API Server其接口兼容 OpenAI API可直接用OpenAILLMClient连接pip install openaifrom dbgpt.model.proxy import OpenAILLMClient llm_client OpenAILLMClient(api_basehttp://localhost:8100/api/v1/, api_key{your_api_key})2.4 TuGraph 连接配置.env 逐项解析在.env文件中设置以下变量DB-GPT 会读取它们来连接 TuGraph 并控制图检索行为GRAPH_STORE_TYPETuGraph TUGRAPH_HOST127.0.0.1 TUGRAPH_PORT7687 TUGRAPH_USERNAMEadmin TUGRAPH_PASSWORD73TuGraph GRAPH_COMMUNITY_SUMMARY_ENABLEDTrue # 启用图社区摘要 TRIPLET_GRAPH_ENABLEDTrue # 启用三元组图检索 DOCUMENT_GRAPH_ENABLEDTrue # 启用文档/chunk 结构图检索 KNOWLEDGE_GRAPH_CHUNK_SEARCH_TOP_SIZE5 # 单次检索的 chunk/三元组召回数 KNOWLEDGE_GRAPH_EXTRACTION_BATCH_SIZE20 # 文本三元组抽取的批大小 COMMUNITY_SUMMARY_BATCH_SIZE20 # 社区摘要并行处理的批大小这些变量在源码中有精确落点可作为行为佐证TUGRAPH_HOST/PORT/USERNAME/PASSWORD由 TuGraphStore 在构造时读取通过TuGraphConnector.from_uri_db建立 bolt 连接GRAPH_COMMUNITY_SUMMARY_ENABLED控制TuGraphStore.enable_summary社区摘要开关SIMILARITY_SEARCH_ENABLED控制enable_similarity_search相似度检索开关二者均为字符串true时才生效见 tugraph_store.py#L155-L160TRIPLET_GRAPH_ENABLED与DOCUMENT_GRAPH_ENABLED由 GraphRetriever 读取决定双图中哪一部分参与检索KNOWLEDGE_GRAPH_CHUNK_SEARCH_TOP_SIZE、KNOWLEDGE_GRAPH_EXTRACTION_BATCH_SIZE、COMMUNITY_SUMMARY_BATCH_SIZE、KNOWLEDGE_GRAPH_EMBEDDING_BATCH_SIZE均在 CommunitySummaryKnowledgeGraph 初始化时作为环境变量兜底值读取且默认值5 / 20 / 20 / 20与 community_summary.py 中注册的 AWEL 资源参数默认值一致。TuGraphStoreConfig还定义了几类图元素类型名均可自定义字段默认值含义vertex_typeentity三元组图顶点实体类型edge_typerelation三元组图边关系类型document_type/chunk_typedocument/chunk文档结构图的文档、chunk 顶点类型include_type/next_typeinclude/next包含与后继两种结构边类型plugin_names[leiden]需要上传到 TuGraph 的社区发现插件从源码结构看TuGraphStore在缺leiden插件时会通过dbgpt-tugraph-plugins包读取插件二进制并 base64 编码上传到数据库tugraph_store.py#L189-L230这是社区摘要基于 Leiden 算法能跑起来的前提。三、构建社区摘要知识图谱连接器DB-GPT 用CommunitySummaryKnowledgeGraph实现了带社区摘要的知识图谱——在抽取三元组之外还会用 Leiden 算法发现实体社区、由 LLM 为每个社区生成摘要即 GraphRAG 的全局搜索能力来源。创建连接器代码from dbgpt.model.proxy.llms.chatgpt import OpenAILLMClient from dbgpt.storage.knowledge_graph.community_summary import ( CommunitySummaryKnowledgeGraph, CommunitySummaryKnowledgeGraphConfig, ) llm_client OpenAILLMClient() model_name gpt-4o-mini def __create_community_kg_connector(): Create community knowledge graph connector. return CommunitySummaryKnowledgeGraph( configCommunitySummaryKnowledgeGraphConfig( namecommunity_graph_rag_test, embedding_fnDefaultEmbeddingFactory.openai(), llm_clientllm_client, model_namemodel_name, graph_store_typeTuGraphGraph, ), )其中embedding_fn不可缺省为None社区摘要需要向量化name会成为图名/向量库名前缀。CommunitySummaryKnowledgeGraph继承自 BuiltinKnowledgeGraph构造函数内部组装了四个核心组件见 community_summary.py#L248-L301组件作用依赖向量库GraphExtractorLLM 批量抽取三元组{name}_CHUNK_HISTORY去重缓存CommunityStoreCommunitySummarizerLeiden 社区发现与 LLM 社区摘要{name}_COMMUNITY_SUMMARYGraphEmbedder/TextEmbedder三元组与 chunk 文本的向量化相似度检索用-GraphRetriever关键词/向量/Text2GQL 混合图检索-若只做最简三元组图 RAG不带社区摘要仓库示例中使用的是BuiltinKnowledgeGraphTuGraphStoreConfig()见 graph_rag_example.py#L60-L68。3.1 写入流程的源码视角CommunitySummaryKnowledgeGraph.aload_document的写入管线与文档描述的双图结构一一对应community_summary.py#L312-L417_aload_document_graph若开启DOCUMENT_GRAPH_ENABLED为每个 chunk 计算父级依据 Markdown 标题层级 metadata 回溯写入 document/chunk 顶点及include、next结构边若开启相似度检索还会对 chunk 文本批量生成向量存入图节点_aload_triplet_graph调用GraphExtractor.batch_extract按KNOWLEDGE_GRAPH_EXTRACTION_BATCH_SIZE批量抽取三元组开启相似度检索时对整图批量 embed写入时把来源 chunk_id 挂到每条关系边上_chunk_id属性并建立chunk → include → entity边——这正是答案可引用原文的实现基础CommunityStore.build_communities按COMMUNITY_SUMMARY_BATCH_SIZE并行构建社区与摘要。四、从知识图谱检索并问答检索 API 与向量库保持一致通过EmbeddingAssemblerRetrieverStrategy.GRAPH组合官方示例完整代码如下import os from dbgpt.configs.model_config import ROOT_PATH from dbgpt.core import Chunk, HumanPromptTemplate, ModelMessage, ModelRequest from dbgpt_ext.rag import ChunkParameters from dbgpt_ext.rag.assembler import EmbeddingAssembler from dbgpt_ext.rag.knowledge import KnowledgeFactory from dbgpt.rag.retriever import RetrieverStrategy async def test_community_graph_rag(): await __run_graph_rag( knowledge_fileexamples/test_files/graphrag-mini.md, chunk_strategyCHUNK_BY_MARKDOWN_HEADER, knowledge_graph__create_community_kg_connector(), questionWhats the relationship between TuGraph and DB-GPT ?, ) async def __run_graph_rag(knowledge_file, chunk_strategy, knowledge_graph, question): file_path os.path.join(ROOT_PATH, knowledge_file).format() knowledge KnowledgeFactory.from_file_path(file_path) try: chunk_parameters ChunkParameters(chunk_strategychunk_strategy) # get embedding assembler assembler await EmbeddingAssembler.aload_from_knowledge( knowledgeknowledge, chunk_parameterschunk_parameters, index_storeknowledge_graph, retrieve_strategyRetrieverStrategy.GRAPH, ) await assembler.apersist() # get embeddings retriever retriever assembler.as_retriever(1) chunks await retriever.aretrieve_with_scores(question, score_threshold0.3) # chat print(f{await ask_chunk(chunks[0], question)}) finally: knowledge_graph.delete_vector_name(knowledge_graph.get_config().name) async def ask_chunk(chunk: Chunk, question) - str: rag_template ( Based on the following [Context] {context}, answer [Question] {question}. ) template HumanPromptTemplate.from_template(rag_template) messages template.format_messages(contextchunk.content, questionquestion) model_messages ModelMessage.from_base_messages(messages) request ModelRequest(modelmodel_name, messagesmodel_messages) response await llm_client.generate(requestrequest) if not response.success: code str(response.error_code) reason response.text raise Exception(frequest llm failed ({code}) {reason}) return response.text要点说明chunk_strategy使用CHUNK_BY_MARKDOWN_HEADER时按 Markdown 标题切分metadata 中保留Header0/1/2...层级文档结构图正是依赖这些层级构建父子关系index_storeknowledge_graphretrieve_strategyRetrieverStrategy.GRAPH把装配器指向图存储而非向量库as_retriever(1)取 top-1 结果score_threshold0.3为召回分数阈值finally中delete_vector_name会级联 drop 社区库、三元组抽取缓存与向量库community_summary.py#L529-L544保证测试可重入检索返回的chunk.content并非原文切片而是格式化好的上下文。CommunitySummaryKnowledgeGraph.asimilar_search_with_scorescommunity_summary.py#L474-L513会做三件事社区摘要检索全局搜索→GraphRetriever.retrieve获取三元组子图、文档子图与 text2gql 查询语句 → 用HYBRID_SEARCH_PT模板合并成含[Context]、[Graph Query Statement]、[Knowledge Graph]、[Original Text From RAG]四段结构的提示词其中[Original Text From RAG]即文档结构图召回的原文引用段。五、Web 界面创建 Knowledge Graph 知识库并对话在 DB-GPT Web 端可以不走代码直接体验 Graph RAG官方测试数据为中文样本文件为 examples/test_files/graphrag-test.md创建知识库新建知识库时选择Knowledge Graph类型底层即社区摘要知识图谱上传并处理文档上传graphrag-test.md等文档系统默认按 Markdown 标题自动分块并抽取三元组、构建社区。开始问答索引完成后即可基于知识图谱对话回答中会带上原文引用。5.1 性能对比基于 gpt-4o-mini官方文档给出了与 Microsoft GraphRAG 的对比数据复测前提为同一文档42631 tokens索引性能指标DB-GPTGraphRAG (microsoft)Doc Tokens4263142631Triplets Graph734 节点, 1064 边779 节点, 967 边Doc Structure Graph76 节点, 1090 边N/APrompt Tokens375768744990Completion Tokens41797227230Total Tokens417565972220Indexing Time170s210sDB-GPT 额外维护的 Doc Structure Graph 是其独有开销但总 token 消耗不到对方一半。查询性能模式系统耗时TokensGlobal SearchDB-GPT8s7432Global SearchGraphRAG (microsoft)40s63317Local SearchDB-GPT15s9230Local SearchGraphRAG (microsoft)15s11619Global Search 示例问题请总结知识库的内容并进行摘要说明。Local Search 示例问题DB-GPT社区和TuGraph社区在社区贡献社区生态开发者的这几个方面的联系和区别分别是什么Global Search 对应上文的社区摘要检索路径asimilar_search_with_scores先search_communities取回相关社区摘要作为[Context]再结合子图作答Local Search 则对应GraphRetriever的局部子图检索路径。六、v0.6.1文档结构图与原文引用DB-GPT 0.6.1 版本引入了三元组检索 文档结构检索的扩展定义Knowledge Graph Triplets Graph Document Structure Graph实现方式是将标准格式文件目前对 Markdown 支持最佳按层级与版式信息分解为有向图后存入图数据库每个节点代表文件的一个 chunk每条边代表 chunk 之间的结构关系include包含关系、next后继关系最后将文档结构图合并进三元组图。由此GraphRAG 回答时可以给出原文引用引用段即[Original Text From RAG]提示词模板中明确要求以引用块形式引用 GraphRAG 原文细节。对应源码中_aload_document_graph写入upsert_doc_include_chunk/upsert_chunk_include_chunk/upsert_chunk_next_chunk三种边community_summary.py#L351-L367检索侧由DocumentGraphRetriever承担。官方 Roadmap 表示会继续构建覆盖更完整信息的复杂图以支撑更高级的检索算法。七、进阶检索一向量相似度检索Similarity Search7.1 启用方式前提使用 TuGraph 4.5.1 及以上版本。在.env中设置SIMILARITY_SEARCH_ENABLEDTrue # 启用实体与 chunk 的向量相似度检索 KNOWLEDGE_GRAPH_EMBEDDING_BATCH_SIZE20 # 文本向量化的批大小 KNOWLEDGE_GRAPH_SIMILARITY_SEARCH_TOP_SIZE5 # 向量相似度检索的 topk KNOWLEDGE_GRAPH_SIMILARITY_SEARCH_RECALL_SCORE0.3 # 向量相似度检索的召回分数阈值同时需要在.env中配置一个 embedding 模型参考 configs/dbgpt-app-config.example.toml 中的 embedding 段## OpenAI embedding 模型 # EMBEDDING_MODELproxy_openai # proxy_openai_proxy_server_urlhttps://api.openai.com/v1 # proxy_openai_proxy_api_key{your-openai-sk} # proxy_openai_proxy_backendtext-embedding-ada-002 ## 通义 embedding 模型 # EMBEDDING_MODELproxy_tongyi # proxy_tongyi_proxy_backendtext-embedding-v1 # proxy_tongyi_proxy_api_key{your-api-key} ## 千帆 embedding 模型 # EMBEDDING_MODELproxy_qianfan # proxy_qianfan_proxy_backendbge-large-zh # proxy_qianfan_proxy_api_key{your-api-key} # proxy_qianfan_proxy_api_secret{your-secret-key}7.2 为什么有效TuGraph 提供完整的向量能力向量存储、索引、相似度搜索DB-GPT 借此在实体与 chunk 对象上新增_embedding字段存储向量检索时先做向量近邻再在图上扩展。从源码看_aload_document_graph中 chunk 文本经TextEmbedder.batch_embed生成向量写入图节点community_summary.py#L339-L349_aload_triplet_graph中整张三元组图经GraphEmbedder.batch_embed向量化community_summary.py#L392-L398检索端GraphRetriever从graph_store_adapter.graph_store.enable_similarity_search读取开关并组装VectorBasedGraphRetrievergraph_retriever.py#L67-L79。同环境同文档对比关键词模式 vs 相似度模式文档给出的例子对清北大学这类不精确词关键词模式难以抽取有效关键词相似度模式能识别出与清华大学的语义相近性从而把清华相关内容纳入结果。这意味着在查询不精确的场景下相似度检索比关键词检索能召回更相关的信息。此外与纯向量 RAG 相比开启相似度检索的 GraphRAG 能取得更相关、更丰富的答案八、进阶检索二Text2GQL 图查询翻译8.1 启用方式TEXT2GQL_SEARCH_ENABLEDTrue # 启用实体与关系的 text2gql 检索8.2 为什么有效关键词或向量检索会为 LLM 生成较大的多跳子图当用户问题其实可以用单条图查询表达时这种多跳子图既贵又噪。Text2GQL 将问题翻译为一条精确的 GQLCypher查询直接命中目标实体降低检索成本并提高子图准确度。从源码看翻译由Text2GQL/LocalText2GQL两个转换器完成graph_retriever.py#L11-L12翻译成功后查询语句会随GraphRetriever.retrieve一并返回写入最终提示词的[Graph Query Statement]段并要求 LLM 在回答开头以 markdown 代码块突出展示该 Cypher 语句。官方 Roadmap 提到后续将通过 prompt 优化与模型微调两条路线提升 Text2GQL 翻译能力使其在复杂问题下也能与关键词/向量检索抗衡。同环境对比关键词模式 vs text2gql 模式例如询问 DB-GPT 相关知识时text2gql 模式生成精确查询MATCH (n) WHERE n.id DB-GPT RETURN n LIMIT 10可以推断在问题简洁明确、可被单条图查询表达的场景下text2gql 检索以更低成本获得更精确的子图。九、验证与延伸阅读完整可运行示例examples/rag/graph_rag_example.py运行方式pytest -s examples/rag/graph_rag_example.py需先安装pytest pytest-asyncio并在.env配好 LLM 与 TuGraph 连接变量测试语料examples/test_files/graphrag-mini.md、examples/test_files/graphrag-test.md核心实现packages/dbgpt-ext/src/dbgpt_ext/storage/knowledge_graph/knowledge_graph.py基础三元组图BuiltinKnowledgeGraphpackages/dbgpt-ext/src/dbgpt_ext/storage/knowledge_graph/community_summary.py社区摘要图与混合检索提示词packages/dbgpt-ext/src/dbgpt_ext/storage/graph_store/tugraph_store.pyTuGraph 存储与插件管理packages/dbgpt-ext/src/dbgpt_ext/rag/retriever/graph_retriever/graph_retriever.py关键词/文本/向量/Text2GQL 多路图检索器。延伸阅读知识库与 RAG 机制知识库索引原理——文档如何变成可检索结构结构索引 / 知识图谱含代码图 / 向量 / 关键词索引Agentic RAG 对话原理——问题如何经 agentic 检索循环变成带引用的答案RAG 模块参考。十、小结DB-GPT 的 Graph RAG 以 TuGraph 为图底座用CommunitySummaryKnowledgeGraph把三元组图 文档结构图 社区摘要整合成可解释、可溯源的知识存储写入侧由 LLM 抽取三元组并用 Leiden 算法构建社区摘要检索侧通过GraphRetriever组合关键词、向量相似度与 Text2GQL 三路能力最终把社区摘要全局视角、子图局部关系与原文引用文档结构图合并进统一提示词交给 LLM 作答。按本文的.env配置与示例代码你可以从最简的BuiltinKnowledgeGraph起步逐步开启SIMILARITY_SEARCH_ENABLED与TEXT2GQL_SEARCH_ENABLED在真实业务文档上度量各自的召回与成本收益。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考