这几年做知识问答类项目，最绕不开的一个问题就是：怎么让大模型回答得“有据可依”。我最近在落地一个企业知识问答系统时，把方案从传统的向量 RAG 换成了 GraphRAG + Text2Cypher 的组合——让大模型自己根据用户问题写 Cypher 查询，从知识图谱里把证据捞出来，再生成最终答案。这套流程跑通之后，多跳关系问题的回答准确率提升非常明显，而且整个链路的可解释性也强了很多。下面就把这次从数据建模、Prompt 设计、查询校验到答案生成的完整拆解记录下来，内容偏工程实践，适合已经跑通过基础 RAG、想往图增强方向进阶的开发者参考。
先说结论：Text2Cypher 这条路线，核心难点不在“让大模型写代码”，而在“让大模型在图数据库的真实 Schema 约束下写对代码”。模型本身对 Cypher 语法是有一定理解的，但语法正确和查询正确是两回事——它经常写出语义上完全跑偏的查询。这次我整理了三条关键经验：Schema 信息必须结构化注入、Few-Shot 示例必须与真实库强绑定、执行结果必须做归一化处理后再交给大模型。下面逐块拆解。
1. 项目背景与核心方案选型思路
1.1 纯向量 RAG 在多跳问题上的局限
我最早做的问答系统是标准的“文档切块—向量化—TopK 检索—拼接上下文—大模型回答”这条路线。单个事实类问题它表现得不错，比如“某产品线的负责人是谁”，只要文档里有这句话，基本能答对。但是业务方很快把问题升级了，变成“哪些供应商同时服务了 A 和 B 两个项目”“C 产品的所有上游原材料里，哪些来自同一家供应商”这类多跳问题。
这类问题的特点是：答案分散在多个文档块里，而且块与块之间没有显式关联。向量检索按相似度返回 TopK，返回的块往往只覆盖了问题里的部分实体，另外一部分关键证据被漏掉。有一次测试，我特意把答案来源控制在三份文档里，结果检索回来的内容只覆盖了其中两份，大模型在缺证据的情况下，居然顺着业务逻辑“合理推断”出了一个错误答案。这个幻觉案例直接让我决定换方案。
向量 RAG 的另一个隐性问题是“相关性不等于因果性”。两块文本语义接近，可能是因为它们都提到了同一个项目代号，但真正的关系是“甲为乙供货”，而不是“甲和乙都在某文档里出现”。向量空间里，这两种情况很难被清晰区分。知识图谱就不一样，关系是显式建模的边，模型不需要自己脑补关系，也不存在“因为字面接近所以被误判为相关”的空间。
1.2 为什么选择 Text2Cypher 作为 GraphRAG 的实现路径
GraphRAG 的落地方式不止一种。最常见的是“实体识别 + 关系映射”：先让大模型从问题里抽出实体，再到图里做实体链接，最后把链接结果转成查询或子图。这条路线的问题是中间环节太多，实体识别错一个词，后面全歪，而且每一环都要单独调优，开发和维护成本都不低。
Text2Cypher 的思路更直接：把“抽实体—链实体—查关系”这几步压缩成一步，让大模型根据问题直接输出 Cypher。省掉的中间环节越多，出错面就越小。而且 Cypher 本身是声明式查询语言，大模型对这类语言的理解比对私有中间格式的理解要好得多，因为它见过大量真实语料，对 MATCH、WHERE、RETURN 这些子句的语义把握很稳。
选这条路线还有两个实际考虑。第一是维护成本：中间环节少，后续调优只需要盯住 Prompt 和示例，不用维护一套实体链接代码。第二是可调试性：大模型生成的 Cypher 是可见的，查询结果不对可以直接看语句本身错在哪，是关系类型写错了，还是属性名写错了，一眼就能定位问题，不用在黑盒子里猜。
当然，代价也很实在。Cypher 生成是开放式的，模型可能写出语法合法但完全查不到数据的查询，也可能写出超出权限范围的危险操作。所以后面我会专门讲“查询白名单校验”和“结果兜底”，这两块是方案进入生产可用的前提，缺一个都不能上线。
1.3 整体流程与各环节职责
系统跑起来之后的流程我按顺序说明一下：用户问题进入后，先做一个轻量分类，判断是否需要走图查询；非图问题直接走普通 RAG，图问题进入 Text2Cypher 链路。链路的第一个环节是 Prompt 组装，把问题、自动生成的 Schema 摘要、动态挑选的 Few-Shot 示例拼在一起发给大模型；第二个环节是查询校验，检查语句是否只包含只读操作，是否引用了不存在的标签或关系类型，是否带 LIMIT 上限；第三个环节是执行与归一化，把查询结果转成“主语—关系—宾语”形式的证据文本；最后一个环节是答案生成，把证据文本作为上下文，要求大模型只基于证据回答，并且明确允许它说“查不到”。
这套流程里，Schema 摘要和 Few-Shot 示例是 Cypher 生成质量的胜负手。如果这两块做得粗糙，那其实根本不需要上大模型，直接用模板套查询都比它稳。所以下一章先从知识图谱建模讲起，这是整个链路的地基。
2. 知识图谱建模与 Schema 设计
2.1 节点、关系与属性的建模原则
Text2Cypher 的上限，由知识图谱的建模质量决定。模型再厉害，也不可能猜出你当初怎么设计的属性名。所以建模阶段就要想清楚几件事。
第一，标签命名全库统一。我这边统一用名词单数形式，比如 Company、Project、Product；关系类型用动词短语的现在时，比如 SUPPLIES、PARTICIPATES_IN、PRODUCES。命名统一是给大模型减少认知负担的第一步，Schema 里出现十几个风格混乱的标签，模型不懵才怪，而且一旦它猜错一个标签名，整个查询就白写了。
第二，属性命名要“见名知义”。公司名称属性叫 name，项目编码属性叫 code，时间属性用标准日期字符串。不要在图上搞一堆缩写属性，比如 cpy_nm、prj_cd 这种，模型看不懂，人也看不懂，排错的时候特别痛苦。属性名越直白，模型写 WHERE 条件时越不容易出错。
第三，边不要过度设计。有些建模规范喜欢把关系拆得很细，比如“甲 签署了 合同 属于 项目”，三个节点两条边。这种设计对精确查询友好，但对 Text2Cypher 不友好——关系路径越长，模型写错路径的概率越高。我的建议是：能一步走到的关系，就一步建模，中间节点只在确实需要独立属性时才保留。
第四，反向关系要克制。有些规范提倡每条关系都配一条反向关系方便双向查询，但对 Text2Cypher 来说，反向关系会让 Schema 描述里的关系类型数量直接翻倍，模型选错方向的概率也翻倍。我倾向于只建模正向关系，查询时按需显式指定反向场景，而不是所有关系都来一套镜像。
下面用一个简化示例说明我推荐的结构。假设要做一个供应链问答图谱，大致是这样：
(:Company {name: "甲公司", industry: "电子"}) (:Project {code: "P001", name: "旗舰项目"}) (:Product {code: "SKU-001", name: "控制模块"}) (:Company)-[:SUPPLIES {since: 2021}]->(:Project) (:Company)-[:PRODUCES]->(:Product) (:Project)-[:REQUIRES]->(:Product)三节点三类关系，覆盖了“哪些供应商参与某项目”“某产品的供应来源”“某项目采购哪些物料”这些高频问题。注意我特意没加“部门”“人员”这些节点，因为当前业务问题不涉及，加进去只会让 Schema 变长，干扰模型判断。建模时一定要克制，节点类型和关系类型宁少勿多。
2.2 Schema 摘要的自动生成与注入方式
Cypher 生成 Prompt 里，Schema 信息是必须的。问题在于怎么把 Schema 描述得既完整又精简。完整是指模型需要知道所有标签、关系类型、关键属性；精简是指不要把每个节点的几十个属性全列出来，否则 Prompt 太长，模型反而抓不住重点。
我用的做法分两步。第一步，从图数据库里查询出标签、关系类型以及每种标签的属性集合，这一步可以用数据库自带的元数据接口或者系统存储过程实现。第二步，把这些信息拼成一个紧凑的 Schema 文本，格式大致如下：
节点标签： - Company: name, industry - Project: code, name - Product: code, name 关系类型： - (Company)-[:SUPPLIES]->(Project) - (Company)-[:PRODUCES]->(Product) - (Project)-[:REQUIRES]->(Product) 查询提示： - 问题“某项目的供应商”应使用 (p:Project {code: $code})<-[:SUPPLIES]-(c:Company) - 所有标签必须使用全称，禁止缩写或变体注意最后两条“查询提示”非常重要，它们是规则性的约束，告诉模型典型问题的匹配方向，比单纯列出关系类型有效得多。模型看到关系类型列表时，只知道有哪些边，但不知道“从哪个节点出发往哪个方向查”，提示就是补上这一层。
Schema 的生成不能每次手动写，要写一个自动导出脚本。大致逻辑是：连上数据库，读取所有标签及其属性分布，读取所有关系类型，然后按固定模板拼接。属性我只取使用频率最高的前五个，避免把冷门属性也塞进去。每次查询都动态生成 Schema 还有个附带好处：库里如果新增了标签，Prompt 会自动带上，不用改一行代码。我这边是把它放在一个定时任务里，每十分钟刷新一次缓存，查询时直接读缓存。
这里有一个必须注意的细节：Schema 文本里不要把属性值样例写死。比如某公司名字叫“甲公司”，你把它写进 Schema，模型可能误以为所有查询都得匹配这个值。只保留属性名和类型，值一律用参数占位符，剩下的交给参数绑定去处理。
2.3 数据导入与索引约束的实操细节
建模做完，数据导入阶段有几个坑要先排掉。
第一个坑是重复导入。图数据库的节点没有传统关系库那种主键概念，如果不加约束，同一条数据跑两遍导入脚本，图上就会出现两个一模一样的节点。解决办法是给关键属性建唯一约束，比如公司节点的 name、项目的 code，都建唯一约束；导入时用 MERGE 而不是 CREATE，MERGE 会先查后建，配合唯一约束就能把重复问题彻底解决。
第二个坑是批量写入性能。我最早一条一条 MERGE，几万条数据导了一个多小时，人坐在那里干等。后来改成批量提交，每 500 条一个事务，时间缩短到几分钟。数据量到千万级以上的话，建议直接用专门的批量导入工具，先把 CSV 处理好再一次性入库。
第三个坑是索引。Text2Cypher 查询里最常见的匹配条件是属性等值，比如 MATCH (p:Project {code: $code})。这类查询如果没有索引就是全库扫描，数据量一上来必然超时。我给所有常用作查询入口的属性都建了索引，项目 code、公司 name 这些一个不落。执行计划也要偶尔看一眼，一旦发现某条 Cypher 的扫描行数异常，优先查索引是不是掉了。
还有一个容易被忽略的点：关系类型的命名要跟业务问题的问法对齐。业务上常问“谁负责这个项目”，关系类型如果叫 RESPONSIBLE_FOR，模型很容易写对；如果叫 IS_IN_CHARGE_OF，虽然意思一样，但和常见表述距离更远，模型写错的概率会明显高一些。命名的时候多想想“最自然的业务动词是什么”，而不是“最精确的语义是什么”。
3. Text2Cypher 核心实现
3.1 Cypher 生成 Prompt 的完整设计
Prompt 是 Text2Cypher 的心脏。我经过几轮迭代，最终固定下来一个五段式结构：角色设定、任务说明、Schema 摘要、Few-Shot 示例、输出约束。
角色设定不是废话，它确实影响输出质量。我会明确告诉模型：“你是图数据库查询专家，只输出 Cypher 语句，不输出任何解释。”这句话能省掉大量无谓的“好的，我来帮你”之类输出，也能让模型进入更聚焦的代码生成状态。
任务说明里要写明输入输出格式：输入是用户问题，输出是一条只读 Cypher 查询。要特别强调“查询必须使用 Schema 中存在的标签和关系类型，属性名必须与 Schema 一致”。Schema 摘要按上一节的方式动态拼入。Few-Shot 示例选 5 到 8 条，覆盖不同的查询模式，示例的写法是“问题 + 对应 Cypher”，中间不要掺杂别的文字。
输出约束里，除了“只输出 Cypher”之外，我还会加一条“如果信息不足，输出一条返回空结果的查询，不要编造”。这一条对抑制幻觉特别有效，模型宁可返回空，也不能虚构一个不存在的标签或者属性来凑答案。
整段 Prompt 大概长这样（省略掉动态部分）：
你是一名图数据库查询专家。你的任务是根据用户问题，编写一条 Cypher 查询语句。 要求： 1. 只输出 Cypher 语句，不包含任何解释或注释。 2. 只能使用下方 Schema 中出现的标签、关系类型和属性名。 3. 查询必须是只读操作，禁止 DELETE、MERGE、CREATE、DETACH、SET 等写操作。 4. 如果问题涉及的条件在 Schema 中不存在，输出 MATCH (n) WHERE 1=0 RETURN n，禁止编造。 5. 匹配条件中的值一律使用参数占位符 $param，不要使用字面量。 以下是 Schema 摘要： {schema_text} 以下是参考示例： {few_shot_examples} 用户问题：{question}有一个参数化的细节要特别提醒：示例里如果写死了匹配值，比如 MATCH (p:Project {code: "P001"})，模型可能会模仿这种写法，把用户问题里的实体名词直接作为字面量拼进查询。这会造成两个问题：一是查询不灵活，换个项目就查不到；二是存在注入风险。所以示例和约束里都要强调“值用 $ 参数”，示例里也尽量写 $project_code 这类占位符，而不是具体编码。
3.2 Few-Shot 示例的动态挑选
固定 Few-Shot 示例有一个毛病：不同用户问题的模式差别很大，如果示例池里全是关系查询，用户问一个聚合问题，模型就容易在示例的惯性下写歪。所以我后来把示例选择改成动态的。
做法是维护一个示例池，每条示例标注类型标签，比如“单节点”“单跳关系”“多跳”“聚合”“过滤排序”。用户问题进来之后，我先用大模型或者规则做一次轻量分类，再按类型挑选对应的示例，每种类型最多选两到三条拼进 Prompt。
实测经验是：示例数量不是越多越好。我试过塞十条以上，Prompt 长度上去了，模型的注意力被稀释，反而更容易出错。五到八条是比较舒服的区间，既覆盖主要模式，又不会让模型“过度拟合”某一条示例的写法，导致它在别的问题上也照着那条示例的思路硬套。
示例池本身要跟真实库强绑定。示例里的标签名、关系类型、属性名，必须就是当前库里的真实 Schema。有些开发者偷懒，从网上抄一段示例就塞进去，结果示例里的标签库里根本没有，模型会一本正经地跟着错。我这边的要求是：示例里的每条 Cypher，都必须在真实库上执行过一遍，确认能跑通才准入库，跑不通的直接丢弃。
示例的选择也讲究代表性。比如“哪些供应商同时服务两个项目”这种典型多跳问题，必须有一条对应的示例。我建议把历史问答日志导出来，统计问题类型分布，按分布来设计示例池，而不是拍脑袋。业务方最常问的 Top10 问题，每条都要有覆盖，剩下的小众类型再慢慢补齐。
3.3 查询校验与安全白名单
大模型生成的东西，不能直接执行。我在这块踩过一次教训：某次模型生成了一条带 DELETE 的语句，好在那是在开发环境，跑完之后数据没了，气得我第二天睡了一整天。从那以后，执行前必须过三道校验，一道都不能省。
第一道是语法校验。把生成的 Cypher 丢给图数据库的 EXPLAIN 接口，只做查询计划不实际执行。这一步能挡住大部分语法错误和不存在的标签，而且开销小、响应快。注意要检查返回信息里有没有报错，有报错就拦截，不让语句进入执行阶段。
第二道是写操作过滤。用解析或者正则，把 DELETE、MERGE、CREATE、DETACH DELETE、SET、REMOVE 这些关键词全部拉黑。最稳妥的做法是维护一个只读语句白名单前缀，只有匹配才放行，这比黑名单靠谱得多，因为黑名单永远有漏网的关键词。
第三道是结果规模控制。Text2Cypher 生成的语句如果没带 LIMIT，一个多跳查询可能返回几千行，既慢又占 token。我的办法是在执行前做一次语句改写：如果查询里有 RETURN，但同一层没有 LIMIT，就自动追加 LIMIT 50。这个改写只用于执行，不影响日志里记录的原始查询。
校验通过后，执行时还要设置超时。我统一设置 10 秒执行超时，超过就放弃并走兜底流程。图查询一旦写歪，可能在图上做全库扫描，没有超时限制的话，会把数据库拖死，甚至影响同库的其他业务查询。
三道校验的代码逻辑大概长这样：
BLOCKED_KEYWORDS = ["DELETE", "MERGE", "CREATE", "DETACH", "SET ", "REMOVE"] def validate_cypher(cypher: str) -> tuple[bool, str]: upper = cypher.upper() for kw in BLOCKED_KEYWORDS: if kw in upper: return False, f"包含被禁止的写操作关键词 {kw.strip()}" allowed_prefix = ("MATCH", "UNWIND", "WITH", "CALL") if not upper.lstrip().startswith(allowed_prefix): return False, "查询必须以只读子句开头" return True, ""注意 BLOCKED_KEYWORDS 里写的是 "SET " 带一个空格，是为了避免误伤 OFFSET、ASSET 这类包含 SET 的合法词。这种细节就是实际排坑排出来的，写正则和关键词匹配的时候一定要考虑误伤，宁可漏一个不常见的写操作，也不能把合法查询挡在门外。
3.4 查询执行与结果归一化
这一步是把 Cypher 的执行结果转换成大模型能用的证据文本，处理不好前面的功夫全白费。
图数据库返回的结果通常是行格式，每行是投影出来的列。比如查询“某项目的供应商”返回 {c.name: "甲公司"}。直接把这些原始行丢给大模型，效果很差，因为列名跟业务语义对不上，多行结果堆在一起也没有结构，模型很难从中准确提取“谁和谁是什么关系”。
我的做法是约定统一的返回格式。在 Few-Shot 示例里，我要求关系类查询统一返回列名为 entity、relation、target，聚合类查询也统一命名。这样结果转换就有固定逻辑可循：把每一行按这三列拼成“实体A — 关系 — 实体B”的文本。归一化之后，还要做去重和裁剪。结果行数多的时候，我按出现频率排序，只保留前二十条。为什么去重？多跳查询里同一家公司可能通过不同路径出现多次，不合并的话，上下文里全是重复信息，浪费 token 还干扰模型判断。
代码上就是一个简单的映射：
def normalize_rows(rows): triples = [] for row in rows: if "entity" in row and "relation" in row and "target" in row: triples.append(f"{row['entity']} — {row['relation']} — {row['target']}") # 去重并截断 seen = set() result = [] for t in triples: if t not in seen: seen.add(t) result.append(t) return result[:20]4. GraphRAG 答案生成与异常兜底
4.1 证据上下文的组装策略
Text2Cypher 执行完之后，得到的是一堆结构化结果。把它们拼成“人话”给大模型生成答案，这一步我总结了三个原则。
原则一：保留结构，不要写成纯散文。三元组格式比句子格式信息密度更高，也不容易在转换过程中丢失信息。我实测过，用“实体A — 关系 — 实体B”这样的行式文本，比把每条关系展开成一句“实体A是实体B的关系”效果更好，模型在结构化文本里找对应关系反而更准。
原则二：附上查询本身。把生成的 Cypher 和它的执行结果一起交给最终回答的模型，好处是模型能理解“这些数据是怎么来的”，在回答范围的控制上更清楚。而且出问题时，你能在日志里看到是查询错了还是回答错了，不用两头猜。
原则三：标注证据来源。如果知识图谱里有数据的来源文档 ID 或导入批次，把来源也塞进上下文里。这能让最终答案在必要的时候说出“依据来自某文档”，可解释性直接拉满。
组装出来的上下文大致长这样：
查询结果（Cypher 执行返回）： - 甲公司 — SUPPLIES — 旗舰项目 - 乙公司 — SUPPLIES — 旗舰项目 - 丙公司 — PRODUCES — 控制模块 - 控制模块 — IS_PART_OF — 旗舰项目 请基于以上证据回答问题。如果证据不足以回答，请明确说明。4.2 最终答案生成 Prompt 的注意事项
最终回答的 Prompt 比生成 Cypher 的 Prompt 要简单，但有两个坑我在项目里反复遇到。
第一个坑是“过度推理”。如果 Prompt 里只说“基于上下文回答”，模型很容易把图里的证据往外引申，加入自己的知识。比如证据里只说甲公司供应旗舰项目，模型却补充了“甲公司是行业龙头”这种图上完全没有的信息。解决办法是加一条硬性约束：“只允许使用证据中出现的实体和关系，禁止引入证据外的信息。”
第二个坑是“答非所问”。当证据里有多条关系时，模型回答时可能只挑它觉得重要的部分，忽略问题真正关心的条件。处理办法是在 Prompt 里重申用户问题，并要求“逐条对照问题中的条件，再组织答案”，让模型先核对证据再开口。
我用的最终回答 Prompt 模板：
你是企业知识问答助手。请根据给定的查询结果回答用户问题。 硬性要求： 1. 只能使用给定查询结果中的信息，禁止编造或引入外部知识。 2. 如果查询结果为空或信息不足，直接回答“根据当前知识图谱无法回答该问题”。 3. 用自然语言组织答案，必要时分点列出。 4. 回答开头不要复述查询过程。 查询结果： {evidence_text} 用户问题：{question}“查询结果为空时直接承认”这条约束是整个链路防止幻觉的最后一道闸。宁可答“不知道”，也不能瞎编，因为知识问答系统的可信度就是靠这个撑起来的。我见过太多系统为了“显得有用”强行编答案，结果被业务方一问细节就露馅，反而彻底失去信任。
4.3 空结果与多跳查询的兜底策略
Text2Cypher 链路里，空结果是最常见的失败模式。查询没报错，但返回 0 行。这种情况一般有三个原因：实体名匹配不上、关系方向搞反、属性条件不对。我建议按下面的顺序兜底。
第一步，尝试把问题里的实体名词做一次规范化再查。比如用户说“旗舰项目”，库里存的也是这个概念，但可能中间有全角空格、大小写或者简繁体差异，可以用大小写不敏感匹配或者去掉空格后再匹配。这一步成本很低，能救回不少看起来“查不到”的问题。
第二步，放宽查询条件。可以把精确匹配改成模糊匹配，把 code 精确匹配改成 name CONTAINS 关键词，把相等条件改成包含关系。这里要特别注意，放宽条件后结果可能变多，必须配合 LIMIT 使用，否则上下文会爆炸。
第三步，生成一轮“追问式”修正查询。把上一次查询的失败信息反馈给大模型，让它重新生成。我试过这个办法，对关系方向写反的情况特别有效。把空结果、原始问题、上次生成的 Cypher 一起丢回去，让模型“检查你的查询并修正”，它能自己发现方向写反了或者标签写错了。
还有一个策略我强烈建议：多跳问题拆成单跳。Text2Cypher 生成多跳查询的失败率远高于单跳，路径越长，任一步出错整条查询就废了。与其让模型一次写完三步路径，不如先查第一步拿到中间实体，再基于中间实体查第二步。这样每一步都是单跳查询，准确率会高很多。代价是多一轮 Prompt 调用，但对正确率要求高的场景非常值得。
5. 常见问题与排查技巧实录
5.1 Cypher 生成错误的三种典型模式
跑了一个多月，我把常见的 Cypher 生成错误归纳成三类，方便你排查时快速定位。
第一类是关系方向写反。模型经常把“甲供应乙”写成 (甲)<-[:SUPPLIES]-(乙)，方向反了，查询返回空。排查方法很简单：把生成的 Cypher 和用户问题打印到日志里对比，一眼就能看出来。解决办法是在 Few-Shot 里增加方向性的正反示例，明确提示“注意箭头方向与主语的对应关系”。
第二类是属性名幻觉。Schema 里明明没有某属性，模型却在 WHERE 里用了。原因通常是它从通用知识里脑补了字段。排查时看报错信息，图数据库会提示“未知属性”。解决方法是加强 Schema 约束，并确保示例池里出现的属性全部与 Schema 一致，一个都不许超纲。
第三类是标签拼写变体。比如 Schema 里是 Company，模型写出 Companies。这类问题在加上约束和 Schema 摘要后少了很多，但偶尔还会犯。靠语法校验能挡住一部分，因为 EXPLAIN 会报“未知标签”，剩余部分靠示例池里的正例慢慢纠正。
我把排查方法整理成一张速查表：
| 问题现象 | 可能原因 | 处理建议 |
|---|---|---|
| 查询返回空 | 实体名或属性值不匹配 | 用模糊匹配兜底，检查值规范化 |
| 查询返回空 | 关系方向写反 | 对比问题与 Cypher 方向，增加反例示例 |
| 报错未知标签/属性 | Schema 未更新 | 重建 Schema 摘要缓存，核对标签拼写 |
| 返回行数过多 | 缺少 LIMIT | 改写子句自动追加 LIMIT 50 |
| 回答内容与证据矛盾 | 回答 Prompt 约束弱 | 加强“只使用证据”约束，检查证据完整性 |
| 执行超时 | 缺少索引 | 检查查询入口属性是否有对应索引 |
5.2 性能问题的两个重灾区
性能问题集中在两个地方：元数据获取和 Prompt 长度。
元数据获取的重灾区是“每次都动态生成 Schema”。虽然我做了缓存，但缓存刷新时正好赶上高并发，就会有一波慢请求。后来我把刷新时间从五分钟调成三十分钟，并且用双缓冲，读请求永远打新缓存，问题就解决了。这个方案的思路很简单：Schema 信息的实时性要求没那么高，十分钟和三十分钟的差别完全可以接受。
Prompt 长度的重灾区是 Few-Shot 示例过多加上 Schema 太长。每条示例平均 150 到 300 token，八条示例加 Schema，光 Prompt 就有两千 token，模型生成时间明显变长，token 成本也上去了。我的对策是把 Schema 里的冷门属性砍掉，只留高频属性；示例池从固定八条改成动态四到六条。实测生成速度提升一倍以上，质量没有下降。
还有一个细节：图数据库连接池。我最早每次查询都新建连接，高并发时连接建立开销很大，P99 延迟上了一个台阶。改成连接池复用之后，延迟降了不少。这个不是 Text2Cypher 特有的问题，但凡是做图查询服务都会遇到，建议一开始就用连接池，别等线上报警再改。
5.3 一个完整的失败案例复盘
分享一个我印象最深的失败案例，方便大家理解排查流程的走法。
业务方问：“2023 年之后启动的项目里，哪些项目的供应商包含甲公司？”大模型生成的 Cypher 是：
MATCH (c:Company {name: "甲公司"})-[:SUPPLIES]->(p:Project) WHERE p.start_date > 2023 RETURN p.name执行报错，日志里显示“未知属性 start_date”。查 Schema，发现项目节点上没有 start_date 这个属性，只有 launch_date。模型从“启动”这个词联想出了 start_date，属于典型的属性名幻觉。
修复动作有两步：一是把 launch_date 加入 Schema 摘要的高频属性列表，让模型在生成阶段就能看到这个属性；二是给示例池加一条带时间属性过滤的查询示例，让模型看到“时间条件在 Cypher 里是这么写的”。之后同样的问题没再犯过。
这个案例的启示是：Text2Cypher 的调优是持续性的，不是一次部署完事。每次新问题报错，都要回到 Schema、示例池、校验规则这三个地方找原因。我建议把失败案例沉淀成一个回归测试集，每次改完 Prompt 都完整跑一遍，防止旧问题复发。这个测试集前期可能只有几十条，但会随着运营越来越厚，价值会越来越大。
6. 个人经验与后续扩展方向
最后说几条个人心得，都是踩坑踩出来的。
第一，Text2Cypher 的价值上限，一半在数据建模，一半在示例质量。别急着堆大模型技巧，先把图谱的标签、关系、属性命名理顺，你会发现模型犯的错直接少一半。我把建模阶段花的时间从“顺手做”改成“专门做”之后，后面调 Prompt 的时间省了不止一倍。
第二，生产环境一定要把“校验、超时、空结果兜底”这三件事做扎实，它们是系统稳定性的地基，比模型选型重要得多。模型选型只是影响单条查询的准确率，而校验和兜底决定整个系统在线上跑不跑得起来，优先级完全不同。
第三，日志要留全。每个请求的问题、生成的 Cypher、执行结果、最终回答，全部结构化落盘。排查问题时这些日志是你最快的线索，没有日志的话，出了问题只能干瞪眼。我这边是直接打到独立的查询日志表，按请求 ID 关联，出问题取一条记录就能完整复盘。
如果后续要扩展，我建议往两个方向走：一是把多跳查询自动拆分成多轮单跳查询，进一步降低失败率，这个方向我已经在验证了，效果不错；二是把 Text2Cypher 的失败样本收集起来，周期性用它们做模型微调或者构建更精准的提示词模板，长期来看能省下不少 Prompt 调用成本。
这套链路跑通之后，我最大的感受是：让大模型直接操作数据库，听起来有点吓人，但只要约束和兜底做到位，它确实能成为知识问答里最可靠的一环。图数据库把关系摆在了明面上，大模型负责把自然语言翻译成查询，两者配合得当，多跳问题就不再是 RAG 的软肋了。
