Neo4j LLM Graph Builder：将非结构化文本一键变成知识图谱

想象这样一个场景：你手里有一堆 PDF 文档——可能是学术论文、企业报告、产品手册——想让 AI 能够"理解"并"精准回答"关于这些文档的问题。传统的做法是把文档切成小块直接扔给大模型做 RAG（检索增强生成），但这种方式有一个致命问题：它只知道词，不知道关系。

比如问"这家公司和它的供应商之间的关系是什么？"，传统 RAG 往往答非所问。而 Neo4j LLM Graph Builder 做的事情，就是把文档变成一张"关系网"——用大模型从文本中提取实体（公司、人、产品）和关系（供应、控股、合作），存入 Neo4j 图数据库，然后用 GraphRAG（基于图的检索增强生成）来回答复杂的关系推理问题。

项目背景：Neo4j 官方出品的 GraphRAG 工具

Neo4j LLM Graph Builder 是 Neo4j Labs 官方维护的开源项目，GitHub 收获 4721 颗星，由全球最大的图数据库厂商 Neo4j 背书，定位是"将非结构化数据转化为知识图谱"的端到端解决方案。

这个项目的诞生背景很清晰：大语言模型（LLM）在处理需要"关系推理"的任务时表现不佳，而知识图谱天然擅长表达实体之间的关系。Neo4j 将两者结合，让用户上传文档后，系统自动完成：分块 → LLM 实体抽取 → 关系识别 → 存入图数据库 → 支持 GraphRAG 查询。整个过程几乎不需要用户手动干预。

项目采用前后端分离架构：后端基于 Python FastAPI，提供完整的文档处理和图谱构建 API；前端基于 React + TypeScript，提供可视化上传和图谱探索界面。同时，项目深度集成 LangChain 生态，利用 LangChain 的 llm-graph-transformer 模块实现图谱抽取，Neo4j 将该模块贡献回了 LangChain 主仓库。

图1：Neo4j LLM Graph Builder 系统架构（来源：项目文档）

核心功能：从文档到图谱的全链路

多源数据接入

系统支持极其丰富的数据输入方式，涵盖了主流的数据消费场景：本地文件（PDF、DOCX、TXT）、Google Cloud Storage（GCS）桶、Amazon S3 桶、网页 URL（通过爬虫抓取）以及维基百科文章。每种数据源都有独立的处理器类，比如 local_file.py 处理本地文件、gcs_bucket.py 对接 GCS、s3_bucket.py 对接 S3、WebBaseLoader 加载网页内容。

这种多源设计让企业用户可以把分散在各处的文档统一汇入同一个知识图谱——无论是存储在对象存储里的历史档案，还是实时抓取的新闻网页，都可以经过统一处理管线进入 Neo4j 图数据库。

文档分块与预处理

上传的文档不会整篇处理，而是先经过智能分块（create_chunks.py）。分块策略需要权衡两个维度：块太小则上下文不足，块太大则实体抽取不精确。LangChain 的 RecursiveCharacterTextSplitter 是默认分块器，用户也可以通过配置文件自定义块大小和重叠参数。

分块之后，系统使用 Tesseract OCR 提取扫描 PDF 中的文字（需要 LibreOffice 辅助转换格式），确保即使是非数字化文档也能被处理。NLTK 负责分词和词性标注，为后续实体识别打基础。

LLM 实体与关系抽取

这是项目的核心环节。系统支持多种大模型后端，通过 LangChain 的统一接口灵活切换：

• OpenAI GPT 系列（GPT-4o、GPT-4o-mini 等）
• Anthropic Claude 系列（Claude 3.5 Haiku 等）
• Google Gemini 系列（Gemini 2.5 Flash/Pro）
• Fireworks AI Qwen3-30B
• Diffbot（专门的实体抽取 API）
• Groq（高速推理平台）

LLM 负责从每个文本块中识别实体和关系类型。实体类型和关系类型可以通过 schemas 配置，用户可以预先定义自己关心的实体（如"公司"、"产品"、"人物"）和关系（如"供应"、"控股"、"竞争"），让抽取结果更符合业务需求。

存入 Neo4j 图数据库

抽取完成后，结果通过 Neo4jGraph（LangChain 的 Neo4j 集成）写入图数据库。每个实体成为图中的一个节点（Node），每种关系成为一条边（Relationship），节点和边都可以附加属性（如置信度、来源文档、时间戳）。

Neo4j Aura 提供免费云端实例，也支持自托管。graphDB_dataAccess.py 负责图数据库层面的读写操作，graph_query.py 处理查询逻辑，neighbours.py 实现基于邻居节点的图遍历查询，communities.py 则负责社区检测（用图算法找出紧密关联的实体群落）。

GraphRAG 检索与问答

图谱构建完成后，用户可以通过 Web UI 或 API 发起自然语言查询。系统将查询转化为 Cypher 图查询语言（Cypher 是 Neo4j 的查询语言，类似于 SQL），在图数据库中检索相关实体和路径，最后将检索结果作为上下文喂给 LLM 生成答案。

相比传统向量检索 RAG，GraphRAG 的优势在于：它能理解实体之间的多跳关系（A→B→C 的关系链），能够回答"谁是谁的供应商的供应商"这类需要多步推理的问题。

技术架构：FastAPI + React + Neo4j 的三角组合

后端采用 FastAPI 框架，选择它的理由很充分：异步原生支持（文档处理是 I/O 密集型任务）、自动 OpenAPI 文档生成、Pydantic 数据验证、以及与 LangChain 生态的天然亲和性。

backend/src/main.py 是入口文件，负责路由分发。核心模块按职责分离：

• create_chunks.py：文档分块
• chunkid_entities.py：块与实体的映射
• make_relationships.py：关系构建
• diffbot_transformer.py：第三方实体抽取
• communities.py：图社区发现
• neighbours.py：图遍历
• ragas_eval.py：用 RAGAs 框架做质量评估
• document_sources/：多数据源接入

前端基于 React + TypeScript + Vite 构建，使用 Tailwind CSS 做样式，通过 Neo4j Needle 组件库实现图谱可视化。项目使用 yarn 作为包管理器。Vite 构建时支持通过环境变量注入后端地址，数据源类型等配置。

部署层面，docker-compose.yml 定义了两个核心服务：backend（Python FastAPI）和 frontend（Node React），它们通过 Docker 网络通信。backend 服务还会挂载本地 GCP 凭证（~/.config/gcloud），以便访问 Google Cloud Storage。整个服务通过 Gunicorn + UvicornWorker 运行，提供生产级的并发处理能力。

LangChain 是贯穿整个项目的 AI 框架：从文档加载（WikipediaLoader、WebBaseLoader）到文本分割、从 LLM 调用（多 Provider 适配）到图谱写入（Neo4jGraph），LangChain 提供了统一的抽象层。

部署体验：30 分钟从零到图谱

项目提供了完整的 Docker Compose 配置，对于有 Docker 环境的用户来说，部署非常顺畅：

git clone https://github.com/neo4j-labs/llm-graph-builder
cd llm-graph-builder
docker-compose up -d

但有几个关键前提需要准备：

1. LLM API Key（必需）：项目不自带大模型，必须配置至少一个 LLM Provider 的 API Key。OpenAI 是默认选项，设置 OPENAI_API_KEY 环境变量即可。也可以配置 Google（Gemini）、Anthropic（Claude）等，切换 Provider 只需改配置文件，不需要改代码。

2. Neo4j 数据库（必需）：可以用 Neo4j Aura 的免费云实例（NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD），也可以本地部署 Neo4j。docker-compose 默认连接 bolt://localhost:7687，本地开发无需额外配置。

3. 其他可选依赖：GCS 访问需要 Google Cloud 凭证 JSON 文件；S3 访问需要 AWS 凭据；若处理扫描 PDF，需要 Tesseract OCR（Docker 镜像已内置）。

硬件方面，不需要 GPU——所有 LLM 调用都是通过 API 进行的，不在本地跑模型。内存需求约 4GB，磁盘 2GB（主要用于存储下载的模型权重和文档。backend Dockerfile 中内置了 sentence-transformers/all-MiniLM-L6-v2 模型的本地缓存，用于生成向量嵌入）。

部署难度评为中等：docker-compose 本身是一键的，但环境变量配置（LLM API Key、Neo4j 连接信息）需要用户有一定配置能力。没有 Docker 的用户需要手动安装 Python 3.12+、Node.js 20+、Neo4j 等依赖，略繁琐。

行业意义：GraphRAG 时代的图数据库价值重估

Neo4j LLM Graph Builder 的出现，折射出一个更大的行业趋势：RAG 技术正在从"向量检索"向"图结构检索"演进。

传统向量 RAG 的本质是"找相似的文本块"，但它无法理解语义层面的关系。当企业知识库中充斥着"关于 A 公司的各种信息分散在 50 份文档里"这种情况时，向量检索只能逐一召回这些碎片，而 GraphRAG 可以把 A 公司作为图谱中的一个节点，通过关系路径快速定位所有相关内容。

从增长曲线来看，项目的 GitHub Stars 在 2025 年保持稳定上升趋势。作为 Neo4j 官方 Labs 项目，它获得了企业的信任背书。同时，LangChain 官方将 Neo4j 的 llm-graph-transformer 纳入主仓库，意味着这套方案成为了 GraphRAG 领域的标准实践之一。

GraphRAG 也并非没有挑战：LLM 抽取实体的准确性受模型能力影响较大；构建大型知识图谱时的成本控制需要精心设计；图谱的更新（增量入库）也比向量数据库更复杂。但这些问题随着 LLM 能力的持续提升和更多开源工具的出现，正在逐步得到改善。

对于想深入了解 GraphRAG 的开发者，这个项目提供了极好的实践起点——你可以直接用官方提供的在线演示（https://llm-graph-builder.neo4jlabs.com/）体验，也可以 Clone 代码本地运行，从图数据库配置到 LLM 接入全流程走一遍，真正理解"把文本变成关系网"背后的工程逻辑。