企业官网建设流程全解析

先聊点实在的：AI Agent 这个赛道现在看着热闹，但真正把 Agent 落地到业务里的人都知道，最大的瓶颈根本不在模型选哪个，而在“知识怎么组织”。如果 Agent 只是靠向量检索去“猜”答案，那它本质上就是个高级搜索引擎，谈不上理解和推理。这也是我最近几个月一直在折腾 GraphRAG + Neo4j 组合的原因——把知识变成图，让 Agent 顺着关系去推理，而不是靠文本相似度去蒙。这篇文章会把我从零搭建这套系统的完整过程、踩过的坑、以及最后怎么把并发扛下来的经验一次性讲清楚，适合正在做 Agent 落地、或者在 RAG 效果上卡住的朋友参考。

1. 为什么 AI Agent 要搭上 GraphRAG 和 Neo4j

1.1 传统 RAG 的短板：向量检索不是万能的

先泼一盆冷水：很多人做的 RAG，本质上是把文档切块、向量化、塞进向量库，然后查询时做相似度匹配。这套流程在“问答型”场景下够用，但一旦涉及到多跳推理、关系判断、全局性问题，效果立刻崩塌。

举个例子。你问“张三和李四共同参与过哪些项目，这些项目里又涉及哪些供应商”，传统 RAG 的做法是把每个 chunk 拿去算相似度，然后把最像的几个片段拼在一起丢给 LLM。问题是，张三和李四的信息可能散落在几十个文档里，每个 chunk 本身只包含局部信息，向量检索根本拼不出完整的路径关系。我实测过，这种问题用朴素 RAG 回答，正确率大概只有三到四成，而且经常出现幻觉——因为 LLM 拿到一堆不完整的片段，只能靠“脑补”把关系串起来。

更深层的问题在于：向量相似度跟“语义关系”不是一回事。两个句子字面很像，可能讲的是完全不同的实体；而两个实体关系紧密的句子，向量距离反而很远。这就是 RAG 的天花板——它擅长找“相似的内容”，但不擅长找“相关的关系”。

1.2 GraphRAG 的解题思路：从“相似”到“关系”

GraphRAG 的思路很直接：与其让 Agent 在文本的海洋里捞碎片，不如先把文本里的实体和关系抽出来，建成一张知识图谱。查询的时候，Agent 直接在图里沿着边做多跳遍历，逻辑链条清清楚楚。

我这里说的 GraphRAG 不是 Microsoft 那个完整方案，而是更广义的一种架构模式：知识图谱作为检索的中间层，LLM 负责把自然语言转化为图查询，再把图查询的结果作为上下文喂给生成模型。关键区别是，图谱把“知识”从非结构化的文本里解放了出来，变成了结构化的三元组——实体、关系、实体。

回到刚才那个问题。如果知识图谱里已经建好了“张三—参与—项目A”“李四—参与—项目A”“项目A—涉及—供应商X”这些边，那查询就变成了一个明确的图遍历任务：先找到张三和李四共同的邻居节点，再往外扩一跳找供应商。这个结果是确定的、可解释的，不再依赖语料碎片和概率匹配。

这恰恰是 AI Agent 最需要的能力。Agent 要做的不是“给你一段相关文字”，而是“根据已知事实推理出答案”。GraphRAG 提供的结构化知识，让 Agent 的每一步推理都有据可依。

1.3 Neo4j 凭什么成为 GraphRAG 的主角

图数据库不止 Neo4j 一家，但做 GraphRAG，Neo4j 目前是最顺手的选择。原因有几个。

第一，Cypher 查询语言表达能力极强。我可以用一行 Cypher 写出“找共同邻居再扩展一跳”这种多跳逻辑，换成 SQL 或者编程语言遍历，代码量至少多十倍。

第二，Neo4j 的 APOC 插件和 GDS 图算法库非常成熟。做实体消歧、社区检测、路径分析，都有现成函数直接调用，不用自己造轮子。

第三，生态跟 LLM 工具链对齐得很好。LangChain 里有 Neo4jGraph 组件，LlamaIndex 也有对应集成，甚至可以直接用自然语言转 Cypher（text2cypher）的方式做检索，接入 Agent 工具非常顺滑。

当然，Neo4j 也有它的毛病，比如默认配置下写入并发不够强、内存吃紧时性能下滑厉害，这些后面我会讲怎么解决。但在“把图和 LLM 结合起来”这件事上，它目前确实是最好的选择之一。

2. 环境准备：Neo4j 安装与配置全流程

2.1 版本与安装方式怎么选

我在热词里看到“neo4j 3.5 哪里可以下载”这类问题，先给个建议：不要用 3.5。那是 2019 年的老版本，驱动协议和查询语法都比较旧，跟 LangChain 这类新工具链的兼容性很差，而且社区版老版本的安全漏洞也不会再修补了。直接用 5.x 系列的社区版，功能完整、驱动统一、文档齐全。

安装方式我实测比较过，三种常见路径：

• Desktop 版：适合本地开发，自带可视化界面和示例数据库，但对服务器部署不友好，而且新版 Desktop 开始做 License 限制了。
• Docker 版：最推荐的方式。一条命令拉镜像、起容器，版本切换和环境隔离都非常干净，后续要扩容也就改个 docker-compose。
• 压缩包直装：适合内网离线环境，但要手动配 JDK、手动起服务，遇到问题排查成本高。

我自己的选择是 Docker 单机部署生产环境，本地调试用 Desktop 或者直接连 Docker 里的实例。

如果你机器上有 Docker，拉起 Neo4j 5.x 社区版只需要一条命令：

docker run -d \ --name neo4j-graphrag \ -p 7474:7474 -p 7687:7687 \ -e NEO4J_AUTH=neo4j/yourpassword \ -e NEO4J_server_memory_heap_max__size=2G \ -e NEO4J_server_memory_pagecache_size=1G \ -v neo4j_data:/data \ neo4j:5.20.0-community

端口说明一下：7474 是浏览器管理界面的 HTTP 端口，7687 是 Bolt 协议端口，应用连数据库走的是 7687。页面端口基本只用来人肉排查问题。

2.2 安装后的关键配置（内存与连接数）

Neo4j 装好后第一件事不是导数据，而是改配置。默认配置拿来做演示还行，一旦并发上来，你会被各种 OutOfMemory 和连接超时折磨疯。

我生产环境的几个关键参数：

NEO4J_server_memory_heap_max__size=4G # JVM 堆内存上限 NEO4J_server_memory_pagecache_size=2G # 页面缓存，走 OS 内存映射 NEO4J_dbms_connector_bolt_max__connection__pool__size=500 # Bolt 连接池上限 NEO4J_dbms_transaction_timeout=60s # 事务超时

堆内存和页面缓存的分配比例，我的经验是：如果服务器内存 16G，堆内存给 4G、页缓存给 2G 是比较稳的起步值。堆内存管的是查询中间结果和事务状态，页缓存管的是图数据的磁盘映射，两者缺一不可，但也不能贪多——给 OS 留至少 4G 余量，否则系统本身会先崩。

注意：修改 Neo4j 内存参数时，不要超过容器可用内存的 50%。Docker 容器里 JVM 默认只认容器配额，但你同时开了页缓存，两者叠加容易直接 OOM。

2.3 第一批 Cypher 命令：先跑通再说

配置完以后，我强烈建议先用几个基础 Cypher 语句验证安装是否正常，也顺便感受一下图查询的语法。打开浏览器访问http://localhost:7474，用刚才设置的账号密码登录，然后敲：

// 建两个节点 CREATE (p:Person {name: '张三', age: 30}); CREATE (c:Company {name: '某某科技'}); // 建关系 MATCH (p:Person {name: '张三'}), (c:Company {name: '某某科技'}) CREATE (p)-[:WORKS_AT {since: 2021}]->(c); // 查询验证 MATCH (p:Person {name: '张三'})-[:WORKS_AT]->(c:Company) RETURN p.name, c.name;

能看到结果集返回就说明环境通了。如果你对 Cypher 完全陌生，别慌，后面第 4 章我会讲到怎么让 LLM 帮你写 Cypher，但前提是你自己得能看懂基础语法，否则错了都不知道错在哪。

3. 知识建模与图谱构建：把非结构化数据变成图

3.1 本体设计：实体、关系、属性怎么定

GraphRAG 项目里，图的质量决定了检索质量。而图的质量首先来自本体设计——也就是你想清楚：这个领域里有哪些实体类型、哪些关系类型、每个实体有什么关键属性。

我从实际项目中总结出来的经验是：本体设计不要一步到位，先用最小可用集合跑通，再根据查询需求迭代扩展。

我接手过一个企业知识库项目，最初的文档里有人员、项目、合同、供应商、客户五类核心实体，关系也相对清晰：人员—参与—项目、合同—关联—项目、供应商—供应—合同。第一版我只建了这三类节点和三条关系，跑通之后再发现需要“客户购买了哪些产品”这样的查询，就再补 Product 节点和 PURCHASED 关系。

这里有个很重要的技巧：关系永远用动词命名，不要用名词。很多新手会犯的错是建了一个叫“关系”的关系，或者把关系都混成 RELATED_TO，这样图谱看起来是建了，实际上查询时根本没法区分语义。比如 WORKS_AT、PARTICIPATES_IN、SUPPLIES 这种动词型关系名，后面的 Cypher 查询会好写得多。

属性方面，我的原则是：能放关系的就不放节点，能放节点的不放文本。每个节点至少要有一个唯一标识属性（比如 id 或者 name+type 联合唯一），这是后面用 MERGE 去重的关键。

3.2 用 LLM 自动抽取实体与关系

建图最耗时的一步就是把非结构化文档变成三元组。人工标注在少量数据上可行，但一旦文档量上百，就必须让 LLM 来抽。

我目前的抽取流程是这样的：先把文档按一定规则做粗切分（按段落或章节），然后把每段文本塞给 LLM，要求它抽取这段里面出现的实体和关系，输出格式化的 JSON。

一个可以直接参考的 Prompt 骨架：

你是知识图谱抽取引擎。请从以下文本中抽取实体和关系。 实体类型包括：Person、Company、Project、Contract、Product。 关系类型包括：WORKS_AT、PARTICIPATES_IN、SIGNED、SUPPLIES、PURCHASES。 要求： 1. 仅输出 JSON，格式为 {"entities": [{"type": "...", "name": "...", "id": "..."}], "relations": [{"source": "实体id", "target": "实体id", "type": "关系类型", "props": {}}]} 2. 不要输出任何解释性文字。 3. 如果同名实体出现多次，使用同一个 id。 文本内容： {chunk_text}

这一步的难点不是 Prompt 本身，而是 JSON 输出的稳定性。模型偶尔会输出多余的注释、截断的 JSON 或者错误的实体 id 引用。我踩了几次坑之后，现在的做法是两层保险：第一次让模型直接输出 JSON，解析失败后把原始输出扔回给模型，要求“修正为合法 JSON”，这样一次失败的损失也不大。

还有一个常见的坑是：LLM 抽取出来的实体名称可能会有细微差异，比如“张三”和“张 三”、“某某科技”和“某某科技有限公司”。这些问题会在数据入库时引发重复实体，后面 3.3 的 MERGE 部分会细讲。

3.3 数据入库的批量写入与 MERGE 避坑

实体和关系抽取完之后，下一步就是写入 Neo4j。这里有一个核心语法点：创建节点和关系时用什么命令。

很多教程会用 CREATE 命令，但它在重复运行时会创建重复数据。正确做法是用 MERGE——先根据唯一标识查找节点，存在就更新属性，不存在才新建。

我之前用一个真实的教训证明了这个坑：第一次灌数据用 CREATE，跑了三遍之后图谱里出现了几千个重复节点，后来不得不写清理脚本按 id 聚合删除，浪费了大半天。从那以后我所有入库脚本统一用 MERGE。

批量写入的高效姿势是使用 UNWIND 配合参数化查询：

UNWIND $batch AS item MERGE (p:Person {id: item.person_id}) SET p.name = item.person_name, p.age = item.age

在 Python 里调用时，把整个批次的数据通过参数传进去，避免逐条执行：

from neo4j import GraphDatabase driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password")) batch = [ {"person_id": "p001", "person_name": "张三", "age": 30}, {"person_id": "p002", "person_name": "李四", "age": 28}, ] with driver.session() as session: session.run( """ UNWIND $batch AS item MERGE (p:Person {id: item.person_id}) SET p.name = item.person_name, p.age = item.age """, batch=batch, )

这里 UNWIND 的作用是把 Python 侧传来的列表展平成一行一行的记录，Neo4j 会对每行执行 MERGE。一次调用处理几百上千条都不成问题，比逐条调用快一个数量级。

关于重复实体的问题，如果你的抽取环节已经做了实体 id 归一化，这里基本不会有问题；但如果还是出现了近重复节点，我建议不要急着删数据，先在 Cypher 里用模糊匹配查一下：

MATCH (p:Person) WHERE p.name CONTAINS '张' AND p.name CONTAINS '三' RETURN p.id, p.name

确认重复后，用 MERGE 把两个节点的关系迁移过去，再删除孤儿节点。这个流程我后面会单独讲，这里先记住一个原则：宁可入库前多花时间做实体归一，也不要入库后花更多时间清理。

4. GraphRAG 检索链路与 AI Agent 集成

4.1 检索链的完整设计：向量 + 图双通道

图谱建好了，怎么把它接进 AI Agent 才是重头戏。

我目前的检索链路是双通道设计：一个通道走传统向量检索，负责召回“语义上相关的碎片文本”；另一个通道走图查询，负责召回“结构上相关的实体与关系”。最终把两路结果合并去重后作为上下文丢给 LLM 生成答案。

这么设计的原因很实际：图检索擅长回答关系类、多跳类问题，但细节性的描述（比如“某份合同的违约金条款是什么”）还是得靠向量检索去找原文。两者互补，缺一个效果都会打折。

整体流程用文字描述就是这样：

1. 用户问题进来
2. 路由层判断：问题偏向“事实性问答”还是“关系推理”
3. 事实性问答走向量检索，取 top-k 相关片段
4. 关系推理走图检索，根据问题生成 Cypher 并执行，取图结构结果
5. 两路结果合并去重，按相关度排序截断
6. 拼接为上下文，等待 Agent 生成回答

这里的第 2 步“路由判断”可以直接让 LLM 做，也可以根据问题中是否包含关系动词、人名、公司名等特征做规则判断。我现在的做法是规则优先，兜底交给 LLM，因为规则判断几乎没有延迟，能省一点就省一点。

4.2 text2cypher：让 LLM 生成查询语句

图检索最关键的一环，是把自然语言问题翻译成 Cypher。

简单粗暴的实现：把 Neo4j 的 Schema 信息（节点标签、关系类型、属性名）拼进 Prompt，让 LLM 生成 Cypher，然后执行。这一步就是热词里说的 text2cypher。

一个可复用的 Prompt 模板：

你是 Neo4j 专家。根据以下图结构信息，把用户问题翻译为 Cypher 查询。 节点标签： - Person: name, age, position - Company: name, industry - Project: name, budget, status - Contract: name, amount, sign_date 关系类型： - WORKS_AT: (Person)-[]->(Company), since - PARTICIPATES_IN: (Person)-[]->(Project), role - SIGNED: (Company)-[]->(Contract), sign_date - RELATED_TO: (Project)-[]->(Contract) 用户问题：张三参与了哪些项目，这些项目关联了哪些合同？ 仅输出 Cypher 语句，不要解释。

模型往往会输出这样的 Cypher：

MATCH (p:Person {name: '张三'})-[:PARTICIPATES_IN]->(proj:Project)-[:RELATED_TO]->(c:Contract) RETURN proj.name, c.name, c.amount

这里有个大坑：LLM 对 Schema 的理解可能不准，生成出来的 Cypher 偶尔会引用不存在的属性或者关系，导致执行报错。我的处理办法是在执行前加一层轻量校验：用正则检查语句中是否包含 Schema 里定义过的标签和关系名，不包含就要求 LLM 重新生成。

还有一类问题是要注意的：LLM 生成 Cypher 时可能把用户问题里的具体值直接拼进去，比如名字带引号、特殊字符，容易导致语法错误。现在的做法是强制要求 LLM 用参数占位符，然后在执行时用参数传递。比如生成MATCH (p:Person {name: $name})...，执行时传{"name": "张三"}。

4.3 把 GraphRAG 封装成 Agent 的工具

有了图查询能力，下一步就是把检索链路封装成 Agent 可以调用的工具。结合热词里很多人问的 LangGraph + FastAPI 技术栈，我分享一下目前工程里的工具函数形态。

在 LangChain / LangGraph 里，一个工具就是一个函数加一个 docstring，Model 会根据 docstring 判断什么时候调用、传什么参数：

from langchain.tools import tool from neo4j import GraphDatabase driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password")) @tool def graph_retrieval_tool(query: str) -> str: """ 当用户询问涉及多个人物、公司、项目之间的关系、合作、 参与信息，或者需要多跳推理时，使用此工具。 输入为用户的原始问题，输出为图数据库的查询结果。 """ # 这里调 text2cypher 后端，把 query 翻译成 Cypher 并执行 cypher = text2cypher(query) with driver.session() as session: result = session.run(cypher) records = [dict(record) for record in result] return json.dumps(records, ensure_ascii=False)

docstring 的质量直接决定 Agent 什么时候会用这个工具。我一开始写的 docstring 比较模糊：“查询知识图谱”，结果模型经常在不该用图检索的时候调它，浪费了不少 token。后来改成上面这种包含“关系、合作、参与、多跳”触发词的描述后，路由准确性明显提升。

如果你用的是 LangGraph，可以根据 Agent 的意图分析结果做显式条件路由——意图为关系型问题就走 GraphRAG 分支，否则走普通 RAG 分支。这样比让模型自己乱选工具更可控。

4.4 结果融合与重排：图优先还是向量优先

图检索结果和向量检索结果如何合并，这是很多人做混合检索时问得最多的点。

我的经验是：关系推理类问题，图结果优先，向量结果只做补充；事实描述类问题，向量优先，图结果仅作辅助。实际操作中我会给两路结果打上来源标签，然后在重排阶段用 LLM 做最终筛选。

一个简化版本的重排 Prompt：

你是一个答案融合器。下面有两组检索结果： 1. 图数据库查询结果（结构化） 2. 文本片段检索结果（非结构化） 请综合两者信息，输出一个完整回答。优先使用图结果中的关系信息作为骨架， 用文本片段补充细节。如果信息冲突，明确指出冲突并选择更可靠的信息。

这个方案跑下来，多跳问题的正确率比我之前纯向量检索高了近一倍。代价是检索链路多了一次 LLM 重排调用，延迟大约增加 1 到 2 秒。对于“本来就要调用大模型生成答案”的 Agent 流程来说，这点延迟完全可以接受。

5. AI Agent 扛并发：GraphRAG + Neo4j 的性能优化

5.1 瓶颈到底在哪：先定位再优化

热词里有“ai agent 怎么扛并发”这个问题。先纠正一个误区：Agent 的并发瓶颈往往不在模型 API，而在检索层的中间件——其中就包括 Neo4j。

一个典型的 Agent 请求要经历：模型调用、工具调用、Neo4j 查询、向量库查询。如果 Neo4j 查询单次要 500ms，50 个并发请求同时进来，数据库连接池和线程池立刻被打满。我遇到过的情况是：并发一高，Neo4j 日志里全是连接超时和内存溢出，然后 Agent 整体响应时间从 5 秒退化到 30 秒以上。

所以优化之前，先自己接口分段计时，看时间到底花在哪。我用过一个笨但有效的办法：在 Agent 链路的每个环节打点，记录耗时、状态、错误码。跑一轮压测之后就能肉眼看出瓶颈在哪个环节。切记不要一上来就调参，先定位。

5.2 Neo4j 侧的调优：索引、缓存、连接池

Neo4j 侧能做的优化，我总结为三件事：索引、连接池、查询本身。

索引几乎是第一个要做的。没有索引的 MERGE 和 MATCH 是全库扫描，数据上了十万节点后性能会急剧下降。我在实体 id 上建了唯一约束（同时也建了索引），查询基数一下降了一个数量级：

CREATE CONSTRAINT person_id_unique IF NOT EXISTS FOR (p:Person) REQUIRE p.id IS UNIQUE; CREATE CONSTRAINT company_id_unique IF NOT EXISTS FOR (c:Company) REQUIRE c.id IS UNIQUE;

连接池方面，Python 驱动默认的连接池大小可能不够。Neo4j Python Driver 的max_connection_pool_size参数建议根据并发预期适当调大。注意一个误区：连接池不是开得越大越好，因为每个连接都要占用内存和文件描述符。我这边 100 并发压测时，连接池设到 200 就基本触顶了，再往上加，机器自己先撑不住。

查询本身的优化，核心原则是：能不查出节点就不查，能不展开关系就不展。Cypher 里的RETURN *是性能杀手，尤其是图关系多的时候，一个节点带几十条关系，结果集会爆炸。我现在的检索工具里所有 RETURN 都是显式列出需要的字段，比如RETURN proj.name, c.name, c.amount，绝不返回整节点。

5.3 应用侧的优化：缓存、异步、限流

Neo4j 调完之后，更大的提升空间在应用侧。

第一个必做的是缓存。GraphRAG 的查询链路里有大量的重复查询——同样的问题在同一个时间段内会被多次问及（或者相似的问法）。我做了两级缓存：第一级是短时内存缓存，key 是归一化后的问题文本，TTL 设 60 秒；第二级是 Cypher 结果缓存，针对完全相同的 Cypher 查询，TTL 100 秒。实测下来图表层的缓存命中率能到 30% 到 40%，Neo4j 的压力立刻小了一圈。

这里有个细节：问题文本归一化不要只是去掉空格，建议把全角半角统一、同义表达替换、甚至让 LLM 把问题“标准化”后再作为缓存 key。否则“张三参与了哪些项目”和“张三都参与了什么项目”会被当成两个不同的问题，缓存形同虚设。

第二个是异步化。在 FastAPI 里，把 Neo4j 查询放进后台 task 或者用async驱动做异步查询，避免阻塞事件循环。注意 Neo4j 官方的 Python Driver 是同步的，如果整个 Agent 不是基于 ASGI 的异步栈，直接用线程池跑查询就好，别硬扛。

第三个是限流。无论缓存命中率多高，总有穿透到 Neo4j 的请求。我会在应用层加一个简单的令牌桶限流，比如每秒允许进入 Neo4j 的查询数不超过 100。一旦超限，直接返回“稍后重试”而不是把数据库压垮。这一招特别有用，因为图数据库一旦被压到死锁或者 GC 风暴，恢复时间远比限流等待时间长。

5.4 一个可参考的并发架构

把上面的优化串起来，我现在的并发架构大概是这个形态：

FastAPI 接收请求，进入 Agent 编排层。编排层先查缓存，缓存命中直接返回；未命中则进入工具调用。工具层根据意图选择 GraphRAG 或向量检索，GraphRAG 内部再走 text2cypher 生成、Schema 校验、Neo4j 查询、结果格式化。所有对 Neo4j 的访问都通过统一的连接池，查询语句全部参数化，返回字段全部显式指定。

部署上，Neo4j 和应用服务分开部署，避免容器之间互相抢占 CPU 和内存。应用层做无状态水平扩展，Neo4j 单机为主，后续如果数据量再涨，再考虑集群或者分片——但那是另一个复杂度层面的事，单机先把性能榨干再说。

我实测过一组对比数据：优化前，50 并发压测，成功请求比率只有 62%，平均响应时间 18 秒；优化后（索引 + 缓存 + 限流 + 连接池调整），同样 50 并发，成功率 99%，平均响应时间 7 秒。这个结果说明大部分问题出在检索链路，而不是模型本身。

6. 常见问题与排查技巧实录

6.1 安装与启动的坑

Neo4j 安装和启动阶段的坑，我列几个高频的：

Docker 起容器后页面打不开。先看端口有没有被占用：docker ps -a看容器状态，再用docker logs neo4j-graphrag看启动日志。最常见的原因是端口冲突，7474 或者 7687 被别的服务占了。

JVM 内存报错。如果你用 Docker 部署并设了NEO4J_server_memory_heap_max__size，但容器内存限制比这个值小，JVM 会启动失败。解决方案是在docker run里加上--memory=8g之类的参数，或者在 docker-compose 里配置mem_limit。

Neo4j 3.5 的老版本下载问题。如果你是从旧教程里看到 3.5，我只能说直接用 5.x 吧，从零学没必要回到那个旧时代。如果你确实有历史数据在 3.5 里，升级时需要先导出再导入，不兼容的部分要重写，工作量不小。

6.2 Cypher 性能与语法问题

Cypher 执行慢，排查思路就一条链路：先用EXPLAIN查看执行计划，再用PROFILE查看实际运行耗时。重点看有没有NodeByLabelScan这种全表扫描的迹象，如果有，优先加索引。

语法层面的常见问题包括：变量名拼错、关系方向搞反、单引号转义出问题。这类报错日志一般都挺明确，按提示改就行。我踩过比较多的是：在文本字段里包含了单引号，生成 Cypher 时没转义直接语法错误。所以还是那句话，能用参数就用参数，能避免字符串拼接就避免。

6.3 中文实体抽取与数据质量问题

中文文本的实体抽取，模型表现通常不如英文，问题集中在几个方面：

一是分词不一致导致实体名变体。比如“阿里巴巴”和“阿里 巴巴”，或者全角半角空格混入。二是指代消解难，文档里“该公司”到底指哪家公司，LLM 经常搞错。三是模型会在实体名里夹带标点符号或者多余描述。

我的应对方案：抽取后在 Prompt 里增加一条“实体名必须为原文中的连续片段，禁止添加任何修饰词”；入库前做一次清洗，把常见标点、空格、全角转半角统一处理；再用 Neo4j 里的相似度匹配定期检查是否有近似重复实体。

6.4 连接与并发报错

并发场景下最常见的报错有两类：一类是连接超时，另一类是事务冲突。

连接超时通常是连接池耗尽或者网络问题。先看应用日志里 Neo4j 的ServiceUnavailable还是SessionExpired，前者多半是连不上，后者多半是连接被断。解决方式：启动时用driver.verify_connectivity()做健康检查，查询时给 session.run 设超时，避免无限等待。

事务冲突是我在并发写入时遇到的——多个事务同时改写同一个节点，Neo4j 会抛TransientError。这里我的经验是：写入操作尽量串行化，用一个队列把写请求排好队；读操作才并行。如果硬要并行写，就做好重试逻辑，Neo4j 的事务冲突是瞬时的，重试两三次一般能过。

最后分享一个实操结