简介本资源是一套面向人工智能开发者与知识图谱实践者的RAG系统教学材料聚焦于使用Dify平台构建融合知识图谱的检索增强生成应用解决传统RAG在复杂关系推理与结构化知识利用上的局限性。压缩包共3个文件含2个JSON格式数据集recipe_corpus_full.json与recipe_corpus.json提供带实体关系的食谱语料支持图谱构建与查询验证及1个GraphRAG.yml配置文件定义Dify工作流、图数据库连接与RAG链路参数整体大小633.23MB结构精简但具备端到端可运行基础。已有2613人学习下载适用于中高级AI工程师快速掌握图谱驱动RAG的设计逻辑与工程落地要点。读者可直接复用数据结构、配置模板与语料组织方式结合Dify低代码界面完成知识图谱注入、混合检索策略配置及生成效果调优显著降低从理论到Demo验证的时间成本。1. 用 Dify 搭建基于知识图谱的 RAG 系统为什么普通文档切块在复杂问答中集体失效某高校实验室在做智能教辅系统时发现学生问“张量分解和主成分分析PCA在降维目标上的本质差异是什么”传统 RAG 返回的片段要么只讲 PCA、要么只提张量甚至把《线性代数》教材里“矩阵乘法定义”这种无关段落当答案——不是模型不行是检索层根本没理解“张量 vs 矩阵”“降维目标 vs 计算过程”这两组语义关系。这暴露了纯向量检索的致命短板它把知识压成黑匣子向量丢失了实体、属性、关系的结构骨架。而知识图谱Knowledge Graph天然携带三元组头实体-关系-尾实体能把“张量分解是一种高阶数据降维方法 → 与 PCA 同属降维范式 → 但处理对象是多维数组而非二维矩阵”这样的推理链显式建模。本 Demo 课件材料不堆概念直击落地闭环用 Dify 作为低代码编排中枢接入 Neo4j 图数据库作语义索引底座让 RAG 不再“猜答案”而是“走推理路径”。适合已有结构化/半结构化领域资料如教材章节、技术白皮书、标准文档、且需要回答跨章节关联问题的教育、医疗、工业知识服务场景。你不需要从零写图谱构建 pipeline也不用魔改 LLM 提示词——Dify 的自定义工具 图数据库查询能力就是现成的“语义路由器”。2. 知识图谱构建从原始文本到 Neo4j 三元组的最小可行路径2.1 为什么选 Neo4j 而非纯向量库——结构化推理不可替代的三个硬需求很多团队一上来就想用 Chroma 或 Weaviate 替代图谱结果在 Demo 阶段就卡死。我踩过坑才明白当问题涉及“A 和 B 的共同上级是谁”“C 的所有下游影响有哪些”这类路径查询时向量库必须靠大模型“脑补”关系准确率暴跌。Neo4j 的 Cypher 查询引擎能直接执行MATCH (a)-[:HAS_PARENT]-(p)-[:HAS_PARENT]-(b) RETURN p这类确定性遍历。具体到本 Demo我们锁定三个不可妥协的结构化能力关系可追溯教材中“SVD 是矩阵分解的一种”必须存为(SVD)-[:IS_A]-(MatrixDecomposition)而非仅存 SVD 的向量属性可过滤当用户问“2023 年后提出的张量分解方法”节点需带year: 2023属性Cypher 可直接WHERE n.year 2023多跳推理保真回答“PCA 和 Tucker 分解的数学基础差异”需同时查(PCA)-[:BASED_ON]-(SVD)和(Tucker)-[:BASED_ON]-(HOSVD)再比对 SVD/HOSVD 差异——这是向量相似度无法完成的逻辑链。提示不要试图用向量库模拟图谱。我见过某团队用 128 维向量强行编码“父子关系”结果召回的“父节点”向量和“兄弟节点”向量余弦相似度反而更高——结构信息在降维中彻底湮灭。2.2 用 LLM 辅助抽取三元组规避人工标注的血泪成本全人工构建图谱一个 50 页的《机器学习导论》PDF 就要标注上千条三元组且一致性极差。我们的方案是用 LLM 做“初筛校验”人只做关键决策。核心是设计强约束的提示词模板强制输出标准 JSON 格式# extract_triples.py import openai from typing import List, Dict def extract_from_text(text_chunk: str) - List[Dict]: prompt f 你是一个知识图谱构建专家。请严格按以下规则处理输入文本 1. 仅识别明确陈述的实体关系忽略推测、比喻、条件句 2. 实体必须是名词性短语如主成分分析、奇异值分解禁止动词或形容词 3. 关系必须是通用语义关系IS_A, PART_OF, BASED_ON, USED_FOR, CONTRAST_WITH 4. 输出仅限 JSON 列表每个元素含字段head, relation, tail, confidence0.0-1.0 5. 若无明确三元组返回空列表 []。 文本{text_chunk} response openai.ChatCompletion.create( modelgpt-4-turbo, messages[{role: user, content: prompt}], temperature0.1, max_tokens512 ) try: return json.loads(response.choices[0].message.content) except: return [] # 示例输入文本片段 chunk 主成分分析PCA是一种线性降维方法其数学基础是奇异值分解SVD。 # 示例输出 # [ # { head: 主成分分析, relation: IS_A, tail: 线性降维方法, confidence: 0.98 }, # { head: 主成分分析, relation: BASED_ON, tail: 奇异值分解, confidence: 0.95 } # ]关键参数说明temperature0.1强制输出确定性避免 LLM “自由发挥”生成虚构关系max_tokens512限制长度防止 LLM 在长文本中遗漏结尾confidence字段后续用于过滤低置信度三元组如PCA, CONTRAST_WITH, t-SNE置信度常低于 0.7直接丢弃。2.3 Neo4j 数据导入用 cypher-shell 批量加载绕过 Web UI 的性能黑洞Dify 官方文档建议用 Neo4j Browser 导入 CSV但实测 10 万条三元组会卡死浏览器。生产级做法是用cypher-shell命令行工具流式加载# 1. 将 LLM 抽取的 JSON 转为 CSV注意head/tail 需去重并编号 python json_to_csv.py --input triples.json --output nodes.csv --type node python json_to_csv.py --input triples.json --output edges.csv --type edge # 2. 创建唯一约束加速后续 MATCH 查询 echo CREATE CONSTRAINT ON (n:Entity) ASSERT n.name IS UNIQUE; | cypher-shell -u neo4j -p password # 3. 批量导入节点--delimiter \t 支持制表符分隔比逗号更稳定 cat nodes.csv | cypher-shell -u neo4j -p password \ --formatcsv \ --delimiter\t \ -c USING PERIODIC COMMIT 10000 LOAD CSV WITH HEADERS FROM file:///nodes.csv AS row CREATE (:Entity {{name: row.name, type: row.type, source: row.source}}) # 4. 批量导入关系关键用 MERGE 避免重复创建节点 cat edges.csv | cypher-shell -u neo4j -p password \ --formatcsv \ --delimiter\t \ -c USING PERIODIC COMMIT 10000 LOAD CSV WITH HEADERS FROM file:///edges.csv AS row MATCH (h:Entity {{name: row.head}}) MATCH (t:Entity {{name: row.tail}}) MERGE (h)-[:RELATION {{type: row.relation, confidence: toFloat(row.confidence)}}]-(t)参数深挖USING PERIODIC COMMIT 10000每 1 万条提交一次事务内存占用降低 70%避免 OOMMERGE而非CREATE确保同一实体如“SVD”不会因多次出现被创建多个节点toFloat(row.confidence)将字符串 confidence 转为浮点数便于后续 Cypher 中WHERE r.confidence 0.8过滤。3. Dify 自定义工具开发让 LLM 能“看懂”图谱查询结果3.1 为什么不能直接用 Dify 的 HTTP 工具——图谱查询的三大特殊性Dify 内置的 HTTP 工具适合调用 REST API但 Neo4j 的 Cypher 查询有本质不同查询动态生成用户问“对比 A 和 B”需实时拼接MATCH (a:Entity {name:A})-[]-(r)-[]-(b:Entity {name:B}) RETURN rHTTP 工具无法注入变量结果结构复杂Cypher 返回的是图结构节点关系路径JSON 解析需专门逻辑错误容忍度低语法错一个括号整个查询失败需捕获ClientError并返回可读提示。因此必须开发 Python 自定义工具直接嵌入 Dify 的工作流。3.2 编写 Neo4jQueryTool支持自然语言转 Cypher 的轻量级适配器# tools/neo4j_query_tool.py from typing import Any, Dict, List, Optional from neo4j import GraphDatabase from langchain.tools import BaseTool class Neo4jQueryTool(BaseTool): name neo4j_query description Use this tool to query knowledge graph for entity relationships. Input must be a natural language question about connections between concepts. def __init__(self, uri: str, user: str, password: str): super().__init__() self.driver GraphDatabase.driver(uri, auth(user, password)) def _run(self, query: str) - str: # Step 1: 将自然语言问题映射为 Cypher 模板简化版实际项目需扩展 cypher_map { 谁是X的上级: MATCH (x:Entity {{name: {X}}})-[:HAS_PARENT]-(p) RETURN p.name, X和Y有什么共同点: MATCH (x:Entity {{name: {X}}})-[r]-(common), (y:Entity {{name: {Y}}})-[r]-(common) RETURN DISTINCT common.name, X的所有应用领域: MATCH (x:Entity {{name: {X}}})-[:USED_FOR]-(d) RETURN d.name } # Step 2: 提取关键词正则匹配中文括号内内容如“X的上级”中的X import re entities re.findall(r【(.*?)】, query) or re.findall(r“(.*?)”, query) or [query.split()[-1]] if len(entities) 1: return 未识别到查询实体请用【】或“”标出关键概念如【PCA】的数学基础是什么 # Step 3: 选择最匹配的模板并填充 template None for key in cypher_map: if key in query or key.replace(X, ).replace(Y, ) in query: template cypher_map[key] break if not template: return 当前不支持该类型查询请尝试【A】和【B】的共同上级、【C】的所有应用领域 # 填充实体支持单实体/双实体 filled_cypher template if {X} in template: filled_cypher filled_cypher.replace({X}, entities[0]) if {Y} in template and len(entities) 1: filled_cypher filled_cypher.replace({Y}, entities[1]) # Step 4: 执行查询并格式化结果 try: with self.driver.session() as session: result session.run(filled_cypher) records [record.data() for record in result] if not records: return f未在知识图谱中找到关于{entities[0]}的相关信息。 # 将图结构扁平化为文本关键Dify 的 LLM 需要可读文本 formatted [] for r in records: for k, v in r.items(): if isinstance(v, dict) and name in v: formatted.append(f{k}: {v[name]}) else: formatted.append(f{k}: {v}) return .join(formatted) except Exception as e: return f图谱查询失败{str(e)}。请检查实体名称是否准确。 # 在 Dify 中注册工具需在 Dify 后端配置 tool_instance Neo4jQueryTool( uribolt://localhost:7687, userneo4j, passwordyour_password )参数与边界说明re.findall(r【(.*?)】, query)强制要求用户用【】标注实体避免 LLM 自由解析导致歧义如“PCA 的基础”可能被误解析为“PCA 的基础”而非“PCA 的数学基础”filled_cypher.replace({X}, entities[0])仅支持单/双实体替换不支持三跳以上复杂查询——这是刻意为之的取舍保证首次 Demo 的稳定性formatted.append(f{k}: {v[name]})将 Neo4j 返回的{p: {name: 线性代数}}转为p: 线性代数确保 LLM 能直接理解无需额外解析 JSON。3.3 在 Dify 中配置工具避开“工具未启用”的玄学报错Dify 的工具管理界面有隐藏陷阱即使上传了 Python 文件若未在「应用设置」→「工具」中手动勾选LLM 永远不会调用它。操作路径必须严格遵循进入 Dify 控制台 → 「应用」→ 选择你的应用 → 「设置」→ 「工具」点击「添加工具」→ 选择「自定义工具」→ 「上传文件」选择neo4j_query_tool.py关键步骤上传后右侧会出现「启用」开关必须手动点击开启默认是关闭状态在「提示词编排」中于 LLM 节点前插入「工具调用」节点并选择neo4j_query工具测试时在「调试」面板输入【PCA】的数学基础是什么观察日志是否出现Calling tool: neo4j_query with input: 【PCA】的数学基础是什么。注意如果日志显示No tool found for query90% 是第 3 步未启用工具。Dify 不会给出任何提示这是新手翻车最高发点。4. RAG 流程编排Dify 中串联图谱查询与向量检索的混合策略4.1 为什么必须混合——单一策略在真实场景中的三重失效纯图谱查询的局限性在 Demo 中立刻暴露冷启动问题新概念如“2024 年新提出的 Tensor-Train 分解”尚未录入图谱查询返回空长尾覆盖不足教材中“PCA 计算步骤的 Python 代码示例”这类细节图谱通常不建模语义漂移风险用户问“怎么用 PCA 做图像压缩”图谱可能只存(PCA)-[:USED_FOR]-(DimensionalityReduction)但没存(PCA)-[:APPLIED_TO]-(ImageCompression)。因此我们采用图谱优先 向量兜底的混合 RAG先用 Neo4jQueryTool 查询结构化关系若图谱无结果返回“未找到”再触发向量检索Dify 内置的 Knowledge Retrieval将两路结果合并喂给 LLM由其判断哪部分更相关。4.2 Dify 工作流配置用条件分支实现“图谱有结果则跳过向量检索”Dify 的「条件分支」节点是混合策略的核心。配置步骤如下在工作流画布中拖入「工具调用」节点选择neo4j_query工具拖入「条件分支」节点连接工具调用节点的输出在条件分支中设置规则条件 1图谱命中{{tool_output}}contains未找到→ 走「否」分支即图谱有结果条件 2图谱未命中{{tool_output}}contains未找到→ 走「是」分支触发向量检索「否」分支连接「LLM」节点输入为图谱结果{{tool_output}}\n用户问题{{query}}「是」分支连接「知识检索」节点再连接「LLM」节点输入为向量检索结果{{knowledge_retrieval_output}}\n用户问题{{query}}。提示Dify 的条件判断是字符串匹配不是语义理解。所以必须让Neo4jQueryTool._run()在无结果时固定返回未在知识图谱中找到关于X的相关信息。不能返回找不到或空等变体否则条件分支失效。4.3 LLM 提示词优化强制模型区分“图谱事实”与“向量片段”即使混合了两路数据LLM 仍可能混淆来源。我们在系统提示词中加入强约束你是一个严谨的知识助手。请严格遵守 1. 当回答基于图谱查询结果以图谱结果开头时必须声明根据知识图谱结构化数据且不得添加任何推测 2. 当回答基于向量检索片段以向量检索结果开头时必须声明参考文档片段并标注来源页码若存在 3. 若两路结果冲突优先采信图谱结果并说明图谱数据具有更高结构化可信度 4. 禁止编造未提供的信息不确定时回答该信息未在当前知识库中体现。效果对比未加约束时LLM 可能将向量检索到的“PCA 可用于图像压缩”和图谱中的“PCA 基于 SVD”揉在一起生成“因为 PCA 基于 SVD所以能压缩图像”——这是错误因果加约束后输出变为“根据知识图谱结构化数据PCA 的数学基础是奇异值分解SVD。参考文档片段PCA 常用于图像压缩任务见教材 P45。”——来源清晰责任明确。5. 避坑指南图谱 RAG 在 Dify 中落地的 4 个高频翻车点5.1 现象Neo4j 查询始终返回空日志显示Connection refused原因Dify 容器与 Neo4j 容器不在同一 Docker 网络或 Neo4j 未开启远程访问。Dify 默认用bolt://localhost:7687但localhost指向 Dify 容器自身而非宿主机上的 Neo4j。解决若 Neo4j 运行在宿主机将 Dify 的 Neo4j URI 改为bolt://host.docker.internal:7687Docker Desktop或bolt://172.17.0.1:7687Linux Docker若 Neo4j 也在容器中用docker network create rag-net创建共享网络并在docker run时加--network rag-net检查 Neo4j 配置文件neo4j.conf确认dbms.connectors.default_listen_address0.0.0.0且dbms.connector.bolt.enabledtrue。5.2 现象LLM 频繁调用neo4j_query工具但输入是模糊问题如“讲讲机器学习”原因Dify 的工具调用决策由 LLM 控制当提示词未明确限定工具使用场景时LLM 会过度依赖工具。解决在系统提示词末尾追加“仅当用户问题明确涉及实体间关系如‘A 和 B 的区别’、‘C 的上级是什么’时才调用 neo4j_query 工具其他情况直接基于知识库回答。”在 Dify 的「工具」设置中将neo4j_query的描述改为“仅用于查询实体间的结构化关系如上下级、组成、应用领域等。不用于解释概念或提供步骤。”5.3 现象图谱查询结果正确但 LLM 回答中完全忽略该结果只复述向量检索内容原因Dify 的 LLM 输入上下文长度有限如 GPT-3.5 Turbo 为 16K当向量检索返回长文本3000 字图谱结果被截断丢弃。解决在「知识检索」节点设置中将「最大检索数量」从默认 3 降为 1「摘要长度」设为 200 字以内修改Neo4jQueryTool._run()对图谱结果做强制摘要return .join(formatted[:5])最多返回 5 条关系确保关键信息不被截断在系统提示词中强调“图谱结果优先级高于向量检索结果即使后者更长。”5.4 现象中文实体名如“主成分分析”在 Neo4j 中查询不到但英文名“PCA”可以原因Neo4j 默认对中文索引支持弱且CREATE CONSTRAINT未指定中文分词。解决在 Neo4j 中执行CALL db.index.fulltext.createNodeIndex(entityNameIndex, [Entity], [name])创建全文索引查询时改用全文搜索CALL db.index.fulltext.queryNodes(entityNameIndex, 主成分分析) YIELD node RETURN node.name在Neo4jQueryTool中将MATCH (x:Entity {name: {X}})替换为全文查询模板提升中文鲁棒性。6. 进阶技巧用图谱路径可视化验证 RAG 逻辑告别“黑匣子”调试6.1 为什么需要可视化——当 LLM 回答错误时你得知道是图谱错了、查询错了、还是 LLM 理解错了在某次 Demo 调试中用户问“SVD 和 HOSVD 的关系”LLM 回答“二者无关”。但直觉告诉我它们应该有关联。此时如果只看 Dify 日志里的tool_output只能看到p: 高阶奇异值分解这样的扁平文本无法判断是图谱里根本没存(SVD)-[:RELATED_TO]-(HOSVD)还是 Cypher 查询模板写错了查成了(SVD)-[:BASED_ON]-(HOSVD)或者 LLM 看到结果却没理解“高阶奇异值分解”就是 HOSVD答案是必须看到图谱中的真实节点和边。6.2 用 Neo4j Browser 快速绘制查询路径三步定位根因复制 Dify 日志中的实际 Cypher 语句在 Dify 调试面板找到neo4j_query工具调用的日志复制完整的 Cypher 命令如MATCH (x:Entity {name: SVD})-[]-(r)-[]-(y:Entity {name: HOSVD}) RETURN x, r, y在 Neo4j Browser 中粘贴执行点击「▶」按钮结果区会显示表格视图但关键在右上角切换为「Graph」视图观察图谱结构若 Graph 视图为空 → 图谱中不存在 SVD 或 HOSVD 节点建模漏了若只有 SVD 和 HOSVD 两个孤立节点 → 二者无边连接关系未抽取若有路径但关系类型是CONTRAST_WITH而非RELATED_TO→ LLM 提示词中的关系映射表需更新若路径正确但 LLM 仍说“无关” → 问题在 LLM 提示词需强化“CONTRAST_WITH也属于关系”的说明。6.3 构建自动化验证脚本每次更新图谱后一键跑通核心路径为避免每次修改都手动验证我写了这个轻量脚本放在 CI/CD 流程中# validate_graph_paths.py import csv from neo4j import GraphDatabase # 预定义关键路径测试集业务方提供 TEST_CASES [ (SVD, HOSVD, RELATED_TO), (PCA, SVD, BASED_ON), (TensorDecomposition, MatrixDecomposition, IS_A) ] def validate_path(driver, head, tail, relation): with driver.session() as session: # 检查是否存在指定关系的直接边 result session.run( MATCH (h:Entity {name: $head})-[r:$rel]-(t:Entity {name: $tail}) RETURN r, headhead, tailtail, relrelation ) if list(result): return True, f直接边 {head}-[{relation}]-{tail} 存在 # 检查是否存在两跳路径如 SVD - BASED_ON - PCA - USED_FOR - ImageCompression result session.run( MATCH (h:Entity {name: $head})-[]-(m)-[]-(t:Entity {name: $tail}) RETURN m.name, headhead, tailtail ) paths [record[m.name] for record in result] if paths: return True, f通过中间节点 {paths} 可达 return False, f未找到 {head} 与 {tail} 的 {relation} 关系路径 if __name__ __main__: driver GraphDatabase.driver(bolt://localhost:7687, auth(neo4j, password)) results [] for head, tail, rel in TEST_CASES: success, msg validate_path(driver, head, tail, rel) results.append([head, tail, rel, ✓ if success else ✗, msg]) # 输出为 CSV供 QA 团队查看 with open(graph_validation_report.csv, w, newline, encodingutf-8) as f: writer csv.writer(f) writer.writerow([Head, Tail, Relation, Status, Detail]) writer.writerows(results) driver.close() print(图谱路径验证完成报告已生成graph_validation_report.csv)执行效果运行后生成 CSV 报告其中一行可能是SVD,HOSVD,RELATED_TO,✗,未找到 SVD 与 HOSVD 的 RELATED_TO 关系路径这立刻指向问题要么补充三元组(SVD)-[:RELATED_TO]-(HOSVD)要么在Neo4jQueryTool的映射表中增加SVD 和 HOSVD 的关系: MATCH (s:Entity {name: SVD})-[]-(r)-[]-(h:Entity {name: HOSVD}) RETURN r.type。这套验证机制让我在某次课程材料更新后10 分钟内就定位到图谱构建脚本中一个正则表达式 bug——它把“HOSVD高阶奇异值分解”中的括号当作了特殊字符导致实体名被截断为“HOSVD”。没有可视化这个问题可能要花半天日志排查。希望帮到你。本文还有配套的精品资源点击获取