> 导读：在技术科普「Coding Agent」系列中，由 NebulaGraph GenAI Team @PsiACE 为大家带来多期 Coding Agent 实践经验，并分享 NebulaGraph GenAI 的最新工作。
> 
> 本期，@PsiACE 分享的是如何用 Python 实现一个能自举的 Coding Agent，并给出了避坑指南，希望给大家的 Coding Agent 带来启发。

Bub 的第一个 milestone：自动修类型注解。由 Moonshot K2 驱动。

> Bub: Successfully fixed the first mypy issue by adding the missing return type annotation -> Noneto the \_\_init\_\_method in src/bub/cli/render.py, reducing the error count from 24 to 23.

# **01** 为什么要自己造 Agent？

Coding Agent 现在已经是个红海赛道，市面上有不少优秀的产品，还有许多团队在 PPT 中绘制宏伟蓝图。

然而，Coding Agent 的“token 大力出奇迹”现象也很明显——动辄几十万 token 的消耗，真正有价值的部分却少之又少。

**这让我很好奇：如果自己动手造一个 Coding Agent，能不能找到更高效、更实用的解决方案？**

于是，我开始折腾一个叫 Bub 的 CLI 助手。它的目标很简单：做一个命令行下的实用助手，同时具备有限的自举能力。自举这个概念在编译器、操作系统领域早已不算新鲜，很多 Coding Agent 也喜欢宣传“AI 工程师贡献了多少代码”。

我希望 Bub 能迈出自己的第一步，解决它自身代码中的第一个实际问题。

# 02 最小可用：先跑起来再说

我的经验是，能跑起来的最小闭环最重要，别一上来就追求“完美架构”或者花太多时间做数据小偷。

Bub 的分层很简单：

-   **Agent**：主循环，负责 LLM 交互、工具调用、上下文管理。
    
-   **Tool**：每个工具一个类，参数用 Pydantic 校验。
    
-   **ToolRegistry**：注册所有工具，方便扩展。
    
-   **CLI**：Typer + Rich，命令行入口，支持展开中间状态。
    

Agent 的本质其实就是一个 while 循环。每次循环，Agent 会根据当前上下文判断是否需要调用工具，如果需要就调用，然后把工具的返回结果写回上下文。

## 主循环核心代码

```
class Agent:
    def chat(self, message: str) -> str:
        self.conversation_history.append(Message(role="user", content=message))
        while True:
            # Construct context: historical messages + tool list
            ...
            response = litellm.completion(...)
            assistant_message = str(response.choices[0].message.content)
            self.conversation_history.append(Message(role="assistant", content=assistant_message))
            tool_calls = self.tool_executor.extract_tool_calls(assistant_message)
            if tool_calls:
                for tool_call in tool_calls:
                    result = self.tool_executor.execute_tool(tool_call.name, **tool_call.parameters)
                    observation = f"Observation: {result.format_result()}"
                    self.conversation_history.append(Message(role="user", content=observation))
                continue
            else:
                return assistant_message
```

## **踩过的坑**

-   没有捕获，LLM 输出格式一变就死循环
    
-   工具参数没校验，LLM 乱传参数直接崩
    
-   Observation 反馈太长或缺乏有效信息，LLM 理解困难
    

# **03** 工具定义：扩展 LLM 的能力

工具是 LLM 和外部世界的桥梁，定义得好，模型才能真正“动手”。我的做法是：

-   工具参数全部用 Pydantic 校验，类型不对直接拒绝。
    
-   命令行工具有黑名单（比如 `rm`、`del`），遇到危险命令直接报错。
    
-   工具执行结果结构化返回，别让 LLM 猜。
    
-   操作命令行工具时，stdout 和 stderr 都很重要，不能只给 exit code.
    
-   工具之间要有明确边界，避免混淆。
    

```
class RunCommandTool(Tool):
    DANGEROUS_COMMANDS = {"rm", "del"}
    def _validate_command(self, base_cmd: str) -> Optional[str]:
        if base_cmd in self.DANGEROUS_COMMANDS:
            return f"Dangerous command blocked: {base_cmd}"
    def execute(self, context: Context) -> ToolResult:
        # Validate command, execute and return results
```

# **04** Prompt：让 LLM 按套路出牌

组织良好的提示词能显著提升 LLM 的输出质量。对于 Coding Agent 来说尤其重要，因为 LLM 的输出格式很容易失控。

我的经验

-   Prompt 里要列出所有工具和参数 schema。
    
-   多给几个调用示例，覆盖常见用法。
    
-   Observation 反馈要简洁，别堆无用信息。
    

## **Bub 的 ReAct Prompt 结构**

```
You are an AI assistant with access to tools. When you need to use a tool, follow this format:
Thought: ...
Action: run_command
Action Input: {"command": "ls"}
Observation: <output>
...
Final Answer: <your answer>
```

ReAct 的好处是简单直接，容易落地，虽然 token 消耗大，但能快速试错、跨模型迁移。

# **05** Milestone：自动修类型注解

定义好 Agent Loop、工具和 Prompt 后，Bub 的第一个 milestone 就是自动修复了一个 mypy 报错。

比如：

```
-    def __init__(self):
-        self.console = Console()
-        self._show_debug = False
+    def __init__(self) -> None:
+        self.console: Console = Console()
+        self._show_debug: bool = False
```

## 实际的 Agent Loop

-   只让 agent 改类型注解、格式化、重命名，别让它碰复杂逻辑。
    
-   先用命令行工具执行 `mypy`，拿到报错信息。
    
-   让 agent 生成修复建议，再用 file edit 工具应用到代码。
    
-   修完自动再跑一次 mypy，确保没新问题。
    

## **踩过的坑**

-   模型对代码上下文理解有限，经常修错。
    
-   不验证，bug 越修越多。
    

# **06** 进阶玩法与工程自查

随着功能扩展，踩的坑也越来越多。我的一些经验：

-   工具扩展时，建议单一职责，参数 schema 明确。
    
-   长对话要截断或摘要，别让 LLM 超窗。
    
-   生产环境建议沙箱/虚拟机，命令行工具默认禁危险命令。
    
-   LLM 输出格式不稳时要有 fallback 兜底。
    

# **07** 总结

Bub 还在早期，但已经能帮我自动修 bug、跑命令、读写文件。我希望这只是一个开始，然后得到更多有意思的反馈。

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/coding-agent-2/Bub.webp)

Bub it. [Build.it](http://Build.it)

---

### 项目地址

[https://github.com/PsiACE/bub](https://github.com/PsiACE/bub)

### References

-   [https://ampcode.com/how-to-build-an-agent](https://ampcode.com/how-to-build-an-agent)
    
-   [https://huggingface.co/blog/tiny-agents](https://huggingface.co/blog/tiny-agents)

如何用 Python 实现一个能自举的 Coding Agent，并给出了避坑指南，希望给大家的 Coding Agent 带来启发。

技术科普｜如何用 Python 实现 Coding Agent

NebulaGraph  Graph 服务、Storage 服务和 Meta 服务扩容

NebulaGraph 扩容｜丝滑扩容Graph、Storage 与 Meta 服务

> 关于作者：兰后，平安壹账通，数据产品经理。6 年金融行业咨询工作经验，具备大数据分析挖掘、 数据中台、数据治理等方面专业知识。负责为金融行业客户提供以 AI 产品和数据中台为核心的解决方案和咨询服务，协助客户开展数字化转型规划和设计工作。




两年前，为了给数据资产管理平台构建数据血缘功能，我被前老板“扔”去研究图数据库，熬了几个大夜写完调研报告，以为这事就这么过去了。

没想到，命运的齿轮再次转动。最近在为一家保险巨头做数字化转型时，客户冷不丁地问我：“能不能用图数据库搞点创新，让我们在集团内部的科技比赛里拿个奖？”

于是，我重新翻出这份“压箱底的宝藏”…...

#  一、选型调研

## （一）粗筛

结合数据库选型经验，我们先从 DB-Engines 排名中分别筛选出国内外排名第一的 NebulaGraph 和 Neo4j.

## （二）细筛

我们从优缺点、使用成本、是否适配信创、性能等方面，对 Neo4j、NebulaGraph 进行进一步选型调研。

**综合考虑信创和保险同业案例等方面，建议优先选择 NebulaGraph.**


|维度 | Neo4j | NebulaGraph|
|--- | --- | ---|
|优缺点 | 1. 优点：成熟的图数据库，功能全面，Cypher 语法友好，生态丰富（Bloom 算法库）； 2. 缺点：社区版仅支持单机，企业版扩展受限，写性能依赖主节点，开源受限 | 1. 优点：分布式架构，水平扩展，支持万亿边，性能强劲（导入/查询均为业界领先），对大数据生态兼容； 2. 缺点：生态相对年轻，上手难度略高，高级功能需企业版|
|是否开源 | 部分开源：社区版 GPL v3 开源，企业版闭源需商业授权 | 完全开源：源码全开源，企业版增强功能收费|
|信创兼容 | 不兼容，无国产平台官方认证，主要支持 x86 Linux 环境 | 已通过华为鲲鹏、飞腾、海光、兆芯等国产 CPU 和操作系统兼容认证，全面支持信创，可自行编译安装包，以确保符合特定的软硬件环境，实现最佳性能|
|保险行业案例 | 1. 国外保险公司构建理赔知识图谱检测欺诈； 2. 国内案例较少 | 1.众安保险：风控反欺诈（手机号异常热点检测） 2.泰康在线：构建客户关系图用于精准推荐。支持理赔反欺诈、客户画像、裂变营销 （主要参考了两大保险行业案例，更多用户案例请查看本文文末链接）|
|权威性能测评 | 1. 在 LDBC SNB 基准测试中表现优异 2. 小规模图查询较优 | 1. 在 10 亿边测试中，单跳查询2ms（Neo4j 需数十秒）；多跳查询延迟低于 5 秒（Neo4j 数百秒） 2. 导入性能和扩展性均优于 Neo4j|
|适用场景 | 1. 深度图分析：Cypher 语言对复杂路径表达更简洁 2. 开发测试场景：社区版免费且生态成熟 3. 事务一致性要求极高：如金融交易反欺诈 | 1. 需支持 10 亿+ 级节点规模：如全国级供应链网络 2. 信创改造强需求：国产芯片/0S全栈认证 3. 高并发实时查询：如 IoT 设备状态追踪|


### 1. 架构与扩展能力

|维度|Neo4j|NebulaGraph|
| --- | --- | --- |
|架构类型|单机/因果集群（企业版支持水平扩展）|分布式存储计算分离架构（支持 10 亿+ 节点）|
|扩展能力|垂直扩展为主，企业版支持读写分离集群|水平扩展（存储/计算节点独立扩容）|
|信创适配|需手动验证 JDK/0S 兼容性（如达梦适配）|完成鲲鹏/麒麟/统信全栈兼容认证|

### 2. 数据模型与查询能力

|维度|Neo4j|NebulaGraph|
| --- | --- | --- |
|核心模型|原生属性图，Schema 可选|属性图模型，支持多跳索引与动态 Schema|
|查询语言|Cypher，专为图设计，复杂路径表达更灵活|nGQL，类 SQL 语法，支持图遍历 + SQL 混合查询|
|事务支持|单机强一致，企业版支持分布式事务|支持 ACID，Raft 协议保障分布式事务|

### 3. 大数据生态集成

|维度|Neo4j|NebulaGraph|
| --- | --- | --- |
|Hive对接|需通过 ETL 工具（如Apache NiFi）同步数据|提供 Spark Connector 实现 Hive 联邦查询|
|实时计算|Spark Connector 需额外转换图结构|原生集成 Flink CDC，支持毫秒级数据同步|
|数据质量|依赖外部工具实现 ETL 质量校验|支持 Schema 约束与数据版本控制|

### 4. 性能与适用场景

|维度|Neo4j|NebulaGraph|
| --- | --- | --- |
|写入性能|单机批量导入优化（约10kTPS）|分布式批量导入（TPS 可达 100k+）|
|查询场景|深度递归查询（如社交传播链挖掘）|高并发多跳查询（如供应链 5 层路径分析）|
|适用场景|实时推荐系统、知识图谱构建|金融风控、工业物联网、国产化替代|

### 5. 成本与运维

|维度|Neo4j|NebulaGraph|
| --- | --- | --- |
|授权费用|社区版免费，生产环境需商业授权|Apache 2.0开源协议（无商业授权限制）|
|运维寒杂度|单机部詈简单，集群需专业DBA支持|依赖Kubernetes管理分布式集群|
|国产化成本|-|预置信创适配清单（含JDK/0S兼容脚本）|

# 二、产品简介

## （一）Neo4j（3.4 版本）

Neo4j 是由 Neo4j Inc. 开发的原生图数据库，基于 Java 实现，采用事务型存储引擎和图数据模型。社区版仅支持单机部署，企业版支持多节点集群（需多数节点参与写入）。

### 1. 架构

![](https://picx.zhimg.com/80/v2-316fbc29bb9d53ddc04eeb8c75df0944_1440w.jpg?source=ccfced1a)


### 2. 原生图存储引擎

基于节点-关系连接，支持无索引邻接访问（index-free adjacency），极大提高图遍历性能。

### 3. 产品特性

![](https://pica.zhimg.com/80/v2-1bf69230f6de2670fb3f1778661c5c10_1440w.jpg?source=ccfced1a)

### 4. 数据模型

原生图数据库，采用属性图模型（Property Graph），节点（Node）、关系（Relationship）、属性（Property）构成核心元素。

### 5. 查询语言

* 使用 Cypher，语法简洁、强语义，有 OpenCypher 项目支持。

* 可视化与工具链。

* 提供 Neo4j Bloom 可视化工具、Graph Data Science 库、Neo4j Aura 云服务支持等。

## （二）、NebulaGraph（通用）

NebulaGraph 是在 2019 年推出的图数据库产品，底层数据模型是属性图，基于C++ 语言编写。采用 Apache 2.0 开源授权，强调性能、横向扩展与国产兼容特性。

### 1. 架构

![](https://picx.zhimg.com/80/v2-355e792b3f97aafb0b9e8a71aeedbc40_1440w.jpg?source=ccfced1a)


采用存储计算分离的设计，包括三个核心组件：

* Meta Service：管理集群元数据和 schema 等。

* Storage Service：有状态节点负责持久存储，支持 RocksDB，使用 Raft 共识确保一致性。

* Graph (Query) Service：无状态节点处理查询请求，支持水平扩展。

### 2. 产品特性

![](https://picx.zhimg.com/80/v2-1024752d14db856760bdaec6c0f4416a_1440w.jpg?source=ccfced1a)


* 数据模型：采用属性图模型（Property Graph），兼容图计算和图存储分离。

* 查询语言：使用 nGQL，类 SQL/Cypher 结构，并部分兼容 OpenCypher，方便 Neo4j 用户迁移。

* 生态系统：集成 Nebula Dashboard（可视化管理）、Nebula Studio（交互查询）、Nebula Algorithm（图算法库）。

---

**参考资料**

1、DB-Engines 图数据库排名

2、Neo4j 官方使用文档

3、NebulaGraph 官方使用文档

4、LDBC-SNB 数据集：关联数据基准委员会提供的评测数据集，包含 26 亿顶点、177 亿关系

5、NebulaGraph 同花顺选型测评

**相关阅读**

[NebulaGraph 全球图数据库排名第二](https://mp.weixin.qq.com/s?__biz=MzE5ODg1MDA1NQ==&mid=2247515915&idx=1&sn=4f53647870a1c02566c17504fac516fc&scene=21#wechat_redirect)

[复杂关系场景，图数据库为何是首选？](https://mp.weixin.qq.com/s?__biz=MzE5ODg1MDA1NQ==&mid=2247515828&idx=1&sn=eb22a1dd1b4f5ca4c1cf45dd20f6a543&scene=21#wechat_redirect)

[开源版、企业版怎么选？产品对比+选型指南奉上～](https://mp.weixin.qq.com/s?__biz=MzE5ODg1MDA1NQ==&mid=2247516028&idx=1&sn=d4ee00718421cb63c480663e6f39640e&scene=21#wechat_redirect)

[同花顺知识图谱团队的图数据库选型——消息、基本、技术三面](https://mp.weixin.qq.com/s?__biz=MzE5ODg1MDA1NQ==&mid=2247515319&idx=1&sn=9a7a900627fda88aa2d98775b168fd35&scene=21#wechat_redirect)

NebulaGraph 与 Neo4j 全方位选型测评

NebulaGraph 与 Neo4j 选型对比

> 导读：NebulaGraph Java 是一款 Java 语言的客户端，可以连接、管理 NebulaGraph 图数据库，此外，NebulaGraph 还拥有完善的 Java 系列生态工具，包括 NebulaGraph 官方提供的 NebulaGraph Exchange、NebulaGraph Spark Connector、NebulaGraph Flink Connector，以及由社区小伙伴们贡献并维护的 ngbatis、 java-jdbc、java-orm 等等。 本文汇总了大家在使用 NebulaGraph 时可能会遇到的 Java （官方版）相关问题，先码再看，会有用到的那天～

![](https://picx.zhimg.com/80/v2-c98051e2c6f7b4fb385955de14d48d4b_1440w.jpg?source=ccfced1a)


# 01 Java Client

> Q：Method Name xxx not found

A：检查端口配置，基本是因为 Metad、Storaged、Graphd 端口配混。 或者是高版本的客户端（>=2.6）连接了低版本的服务端(<2.6)

> Q：IOErrorException: All servers are broken

A: 检查 Nebula Graphd 服务是否启动，检查客户端与服务端网络是否连通

💡说明：该错误信息出现的原因是，客户端无法连接配置的 graphd 地址。

> Q：get storage client error， java.util.NoSuchElementException: Unable to activate object

A：首先确认是否是虚拟化部署，如果是则需要把所有 stroaged host 和端口映射出来。

💡说明：因为 storaged client 使用的 storaged 地址是通过 metad 获取的，metad 返回给客户端的地址是容器内的地址，外部访问不了。

> Q：metad 连接不上,com.facebook.thrift.transport.TTransportException:java.net.ConnectException: Connection refused (Connection refused)

A：首先确认服务状态，其次检查网络连通性，最后是否是容器化部署，如果是，则可以只配置 meta leader 的服务地址。

💡说明: 因为 metad 服务只有 leader 才能进行读写请求， 当客户端传入多个 metad 地址，则客户端会随机挑选一个进行请求，根据响应结果返回的 leader host 再访问 metad leader, 此时 leader host 如果是容器内地址，无法访问。

有两种方式：1 是只配置 metad leader， 2 是把所有 metad host 和端口映射出来。

> Q：java.net.SocketException: Broken pipe(Write failed)

A: 检查服务是否在使用中途挂掉； 检查网络是否存在波动（针对偶发现象）

💡说明：该错误出现原因是， socket 连接在数据传输过程中管道的一端断开。

> Q：TProtocolException: The field 'code' has been assigned the invalid value -4

A: Nebula 服务端和客户端版本不兼容

💡说明：只存在于 2.6.0 版本之前

> Q：TProtocolException: Excepted protocol id xxx

A: Nebula 服务端和客户端版本不兼容

💡说明：只存在于 2.6.0 版本之前

> Q：client 执行语句时，语句中的中文内容乱码

A：该问题存在于3.7.0版本之前，可以更新client 版本到3.7.0或3.7.0以上。https://github.com/vesoft-inc/nebula-java/releases/tag/v3.7.0

> Q：3.x client 执行语句时，报错: session not found

A: session 在服务端过期失效。 业务端请重新获取 session.

# 02 NebulaGraph Exchange and NebulaGraph Connector

> Q：Exchange 导入hive 数据时，Exception in thread "main" org.apache.spark.sql.AnalysisException: Table or view not found

A: 检查 Exchange 的提交命令中是否遗漏了参数 -h；检查 hive table 和执行语句是否配置正确

> Q：Exchange导入时，ClassNotFoundException: com.vesoft.nebula.exchange.Exchange

A：

1. 如果是在 Yarn 模式下，则使用该命令 （github readme、使用文档、QA文档都有说明）。

```
$SPARK_HOME/bin/spark-submit --class com.vesoft.nebula.exchange.Exchange \
--master yarn-cluster \
--files /path/application.conf \ 
--conf spark.driver.extraClassPath=/path_for_exchange \
--conf spark.executor.extraClassPath=/path_for_exchange \
nebula-exchange-3.0.0.jar \
-c application.conf

说明：
--files: 表示将该文件上传hdfs。 这是spark参数
--conf spark.driver.extraClassPath: 配置exchange jar包所在目录。 这是spark参数
--conf spark.executor.extraClassPath：配置exchange jar包所在目录。 这是spark参数
-c：exchange程序参数
```

2. 如果非 yarn 模式 则确认当前目录下是否有 Exchange 的 jar 包以及 jar 包大小是否正常。

###

Q：Exception in thread "main" java.lang.NoSuchMethodError: com.google.common.xxx（java.lang.NoClassDefFoundError 错误也是 jar 包冲突）

A: guava 包冲突。 3.x NebulaGraph 要么替换 spark_home/jars 目录下的 guava 版本为 14.0， 要么使用最新的 Exchange 包（SNAPSHOT 版本）或者 3.6.0版本。

> Q：NoClassDefFoundError: scala/Product$class

A: scala 版本冲突。 spark2.4 支持 scala2.11 和 scala2.12； spark2.2 只支持scala 2.11； spark 3.x 只支持 scala2.12

> Q：导入数据时出现中文乱码

A：导入的 spark-submit 命令中增加配置：

```
--conf spark.driver.extraJavaOptions=-Dfile.encoding=utf-8
--conf spark.executor.extraJavaOptions=-Dfile.encoding=utf-8
```

> Q：Hive Schema version xxx does not match metastore's schema version 2.1.0 Metastore is not upgraded or corrupt

A:

* 将 Hive 环境中存储 Hive metastore 信息的 Mysql Version 信息更新为 spark 中使用的 metastore 版本： update hive.VERSION set SCHEMA_VERSION="2.1.0" where VER_ID=1

* 同时在 Hive 环境的 hive-site.xml 中增加如下配置，并重启 Hive

```
<property>
<name>hive.metastore.schema.verification</name>
<value>false</value>
</property>
```

💡说明：原因是 Hive 环境中配置的 metastore schema 版本和 spark 使用的 metastore 版本不一致。

> Q：Can not define any other configs when kafka exists

A: 当存在 kafka 配置时， kafka 配置之后不允许再配置其他数据源的导入。 因为 kafka 是流式数据，任务会一直停留等待 kafka 的数据，不会执行后面的t ag/edge 导入。所以 kafka 导入最好是一个 tag 一个配置文件。

> Q：导入 Mysql 或者其他数据库，提示找不到 driver，java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver

A： 需要把数据库的 driver 驱动放到 spark_home/jars 目录下。

根据数据库版本去下对应的驱动（mysql-connector-java-xxx.jar），如 mysql 驱动下载地址：https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.0.33/

> Q：Exchange 或者 Connector 数据导入少数据

A:

1. 首先查看导入过程是否有写入失败，根据下面日志查找：

* Exchange 的日志：

* Client-Import: batchSuccess.{tag/edge}

* Client-Import: batchFailure.{tag/edge}

* Spark connector 的日志：failed to write xxx

* Flink connector 的日志： write data failed: xxx

2. 确认导入数据是否存在重复

3. show stats 之前是否重新 submit job stats

> Q：java.util.NoSuchElementException: key not found: xxx

A： 确认 NebulaGraph 中是否有xxx这个属性存在。

> Q：IOErrorException:java.net.SocketTimeoutException: Read timed out

A：导入速度过快或者数据请求量过大导致请求超时未响应。 此时要调小 batch size、调小 spark partition 数， 同时调大配置中的 timeout.

> Q：Queries with streaming sources must be executed with writeStream.start()

A：

1. 确认使用的 Exchange 版本。Exchange 3.4.0 版本 不支持流式数据导入，因为该版本中加了一些数据统计的操作，流式数据是不能进行 count 统计的。 所以请替换成 Exchange3.5.0 版本。

2. 确认导入模式，流式数据不支持 SST 导入

> Q: vim 中的^C 分隔符八进制表示是\003, 在 exchange 中如何配

A: 要配成分隔符对应的 unicode 十六进制的字符： '\u0003' . 其他分隔符同理，搜一下 unicode 十六进制的表示。

> Q：3.x exchange 导入时 ErrorHandler 报错：Java.lang.UnsupportedOperationException: Append is not supported by ChecksumFileSystem

A: 导入过程有写入失败数据，失败语句在记录到 error.path 时报错。 原因是：error.path 配置了 hdfs 路径，但用户 hdfs 不允许 append 操作。

解决： 要么更改 hdfs 配置允许 append（不推荐）； 要么将 error.path 配置成本地文件，file:///xxx/xxx

此外，根本原因是存在写入失败的语句，要先排查为什么会写入失败。

# 03 其它

> Q：Your current spark version ${sparkVersion} is not supported by the current NebulaGraph Exchange

A：Spark 环境版本和所用的工具支持的 Spark 版本不一致。 具体版本对应关系在github readme 中有表格说明。

# 04 Ending

本文的问题汇总，部分问题来自 NebulaGraph 论坛，如果你在本文中未检索到相关问题，可以结合文档+论坛解决。

🔍论坛：https://discuss.nebula-graph.com.cn/

🔍文档：https://docs.nebula-graph.com.cn/3.8.0/



本文汇总了大家在使用 NebulaGraph 时可能会遇到的 Java （官方版）相关问题

关于 NebulaGraph Java，你可能遇到的二三事

> 导读：图数据库的核心价值在于揭示数据之间隐藏的复杂关系。NebulaGraph 支持丰富的图算法，将隐秘关系高效转化为 actionable 的洞见。
> 本期技术科普将带你了解图算法与 NebulaGraph Algorithm，看看 NebulaGraph 社区用户如何将这些图算法用于生产环境以及如何上手。



# **一、** 图数据库与图算法

## （一）什么是“图”？

想象一下你有一张**关系网**：

**1\. 点**：代表独立的实体。比如：

-   你微信里的所有好友。
    
-   城市地图上的所有十字路口。
    
-   一个项目里的所有任务。
    

2.**线**：代表这些实体之间的关系。比如：

-   微信里，你和某个好友是“好友关系”（一条线连着你俩）。
    
-   城市地图上，两个十字路口之间有一条“道路”（一条线连着两个路口）。
    
-   项目里，任务 A 必须在任务 B 开始之前完成（一条线从 A 指向 B，表示依赖）。
    

这种由“点”（图数据库中的顶点或节点）和连接它们的“线”（图数据库中的边）组成的结构，就叫做“图”。

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/nebula-graph-studio-case.webp)

（用 NebulaGraph Studio 进行某公司股权穿透）

## （二）什么是图算法？

图算法就是一套聪明的“解题思路”或“工具包”，专门用来分析这种“点”和“线”组成的关系网，计算关于这个网络的问题。

**为什么需要专门的“图算法”？**

-   **超越简单查询**：传统查询能找到直接邻居，但图算法能分析整个网络的结构和动态。
    
-   **量化关系价值**：把模糊的“关联”变成可计算的指标（如重要性、紧密度、相似度）。
    
-   **发现隐藏模式**：自动识别传统关系数据库难以查询的社群、关键枢纽、传播路径。
    

**图算法的应用**

**找最短路径：**

-   **问题**：从家（点A）导航到公司（点B），导航如何规划最快/综合成本最低的路线？
    
-   **图算法**：经典的最短路径算法（如 Dijkstra 算法），能快速计算出从 A 到 B 的所有可能路线中，总权重（通常代表路程长度、通行时间或综合成本）最小的那条路径。
    

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/dijkstra.webp)

**好友推荐：**

-   **问题**：微信/微博/Facebook 怎么知道你可能认识谁，从而给你推荐好友？
    
-   **图算法**：基于共同邻居的链路预测算法（如 Jaccard 算法）会分析你的社交网络图：关注你的直接好友（一度邻居），然后考察他们的好友（你的二度邻居）。那些与你拥有大量共同好友（即共同的一度邻居） 但尚未与你建立连接的人，就很可能被推荐给你。
    
![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/jaccard.webp)

**网页排名：**

-   **问题**：搜索引擎怎么决定当你搜索“图算法”时，哪个网页应该排在前面？
    
-   **图算法**：PageRank 算法。它的核心思想是：
    
-   被很多其他网页链接指向的网页（点），通常比较重要（票数多）。
    
-   被一个重要网页链接指向的网页，也会获得更高的重要性（重要的一票更有分量）。
    
-   算法会不断计算每个网页的“重要性得分”，得分高的排名就靠前。
    
![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/page-rank.webp)

# **二、图算法类型及应用场景**

图算法大致可分为以下几种类型：

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/%20algorithm-over-view.webp)

# **三、NebulaGraph Algorithm**

NebulaGraph Algorithm 是一款基于 GraphX 的 Spark 应用程序，通过提交 Spark 任务的形式使用完整的算法工具对 NebulaGraph 数据库中的数据执行图计算，也可以通过编程形式调用 lib 库下的算法针对 DataFrame 执行图计算。

## （一）NebulaGraph 支持的图算法

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/nebula-graph-algorithm-overview.webp)

> 上图为社区版支持的基础图算法，企业版支持更多高性能算法（如 InfoMap、APSP、DegreeWithTime、HyperANF 等）及基于 ISO-GQL 的自定义图算法。

## （二）NebulaGraph 用户这么用

**NebulaGraph 用户们如何用图算法解锁业务价值？**


### **1、中心性分析-PageRank**

-   **何时用**：当你需要找出整个网络中“影响力大”或“被广泛引用/连接”的节点时。
    
-   **场景举例**：识别社交媒体上的关键意见领袖；在金融交易网络中定位核心中转账户。
    
-   **社区用户**：[Boss 直聘](https://www.nebula-graph.com.cn/posts/NebulaGraph-use-case-BOSS-zhipin)整合链路追踪（Trace）、系统指标（Metrics）、日志（Logs）三大数据源，构建统一的全链路异常拓扑图，发现多个真子图分散出现在图结构中，每个子图都有“风暴中心”，故采用 PageRank 算法动态计算节点故障权重（Rank 值由节点出入度、链路错误数、事件进行加权计算），得出 Rank 值最高的 TopN 故障节点（即 “风景眼”），从而快速实现根因定位，平均收敛时间仅 20s.
    

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/boss-use-nebula.webp)

### **2、 社区发现-Louvain、Hanp**

-   **何时用**？需要在大规模网络中发现层次化的社区结构时。
    
-   **场景举例**：社交网络中的兴趣社群划分；电商用户群体细分（购买模式相似）；城市交通流量分区。
    
-   **社区用户**：[中国移动](https://www.nebula-graph.com.cn/posts/cmcc-financial-riskcontrol-practice)首先基于所有移动用户构建一个关系网络，采用 Louvain、Hanp 算法进行社区发现与挖掘，如个人的信用评分以及个人之间的关系，然后对这个社区进行打分，识别出这个社区是否为一个欺诈社区或者是一个低信用的社区，从而进行风险管理。
    
![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/zhongguoyidong-use-nebula.webp)

### **3、社区发现-LabelPropagation**

-   **何时用**？需要快速发现社区，或者网络结构清晰、社区边界明显时。
    
-   **场景举例**：实时推荐系统中的用户兴趣圈识别；新闻/信息传播路径上的群体划分。
    
-   **社区用户**：在[众安保险](https://www.nebula-graph.com.cn/posts/zhongan-insurance-knowledge-graph-practice)，LabelPropagation 应用于贷中环节。LabelPropagation 主要是通过一个确定的点 Y 去传播、衍生出它相关点。比如，贷中用户名单中某个用户是严重逾期人员，这个人员便是打上逾期标签的确定点 Y，结合既定的风控规则查看点 Y 关联延伸的点中哪些点出现相似逾期行为，从而判断这些点是否属于严重逾期的社群。
    

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/zhonganbaoxian-use-nebula.webp)

### **4、ConnectedComponent/StronglyConnectedComponent**

-   **何时用？** **CC** (弱连通分量)关心是否可以通过路径（忽略边方向）连通。用于发现孤岛。SCC (强连通分量)：关心是否可以通过有向路径互相到达。用于分析紧密循环依赖。
    
-   **场景举例**：分析社交网络中的孤立用户群体 (`CC`)；研究论文引用网络中的研究学派 (`SCC`)；分析系统模块间的循环依赖 (`SCC`)。
    
-   **社区用户**：[众安保险](https://www.nebula-graph.com.cn/posts/zhongan-insurance-knowledge-graph-practice)使用 ConnectedComponent 计算出用户关系图谱。当发现一个手机号被异常数量（如五六十人）标记为“家庭联系人”时，该手机号及其关联用户即构成一个潜在风险社群。处于此类异常社群是用户风险的强信号（充分不必要条件），用户也可能是因亲属涉黑产而被牵连。众安据此对社群内用户进行初步风控标记和深入核查。
    

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/zhonganbaoxian-use-nebula.webp)

# 四、NebulaGraph AI Suite

除了 NebulaGraph Algorithm, @wey 在 2023 年为社区提供了一个名为 NebulaGraph AI Suite 的项目，它是在 NebulaGraph 之上跑算法的 Python 套件，能给用户一个自然、简洁的高级 API。简单来说，用很少的代码量就可以执行图上的算法相关的任务。

在[《手把手教你用 NebulaGraph AI 全家桶跑图算法》](https://www.nebula-graph.com.cn/posts/nebulagraph-ai)中，@wey 给出了详细的上手教程。该项目完全开源，如果你有新的 idea, 欢迎共建～

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/what-is-graph-algorithm/nebula-ai-suite.png)


# 五、行动起来～

NebulaGraph Algorithm，提供了一套强大的“关系显微镜”。那些困扰你的问题（谁最重要？哪些人是一伙的？最优路径怎么走？）是否能用图算法来解决？访问 NebulaGraph 官方文档，深入了解 NebulaGraph Algorithm 的配置细节，开始你的图算法探索之旅吧！

文档🔍⬇️

[https://docs.nebula-graph.com.cn/3.8.0/graph-computing/nebula-algorithm](https://docs.nebula-graph.com.cn/3.8.0/graph-computing/nebula-algorithm)

---

[香港 nMeetUp](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247517169&idx=1&sn=ab591d3a4bb66d9e5cd65caaf59b7100&scene=21#wechat_redirect) 报名中🔥

进一步探索 NebulaGraph 在#知识图谱、#Web3、#金融风控 的最新应用

![](https://pic1.zhimg.com/80/v2-e8155a1bccebc30896ee5a5ed299fdc0_1440w.jpg?source=d16d100b)




带你了解图算法与 NebulaGraph Algorithm，看看 NebulaGraph 社区用户如何将这些图算法用于生产环境以及如何上手。


技术科普｜图算法是什么？何时用、怎么用？


> 导读：传统 RAG 遇瓶颈，复杂推理怎么办？ GraphRAG 正成为知识管理新利器。 但关键问题来了：GraphRAG 真的超越了 RAG 吗？GraphRAG 哪家强？GraphRAG 性能评估标准有哪些？面针对不同场景需求如何选择？香港理工大学等学者在 6 月 3 日发表论文，重磅推出首个大规模、领域特定基准 GraphRAG-Bench，为技术选型提供硬核依据。

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/technology-popularization/GraphRAG-Bench-banner.png)

🔍本文翻译略有删减，论文原文如下

https://arxiv.org/pdf/2506.02404

  


# 一、摘要


图检索增强生成（Graph Retrieval-Augmented Generation, GraphRAG）因其在结构化组织领域特定语料库并提升复杂推理能力的潜力，正日益受到认可。然而，当前 GraphRAG 模型的评估主要依赖传统的问答数据集。这些数据集在问题广度和评估指标上存在局限性，无法全面衡量 GraphRAG 模型所带来的推理能力提升。

为弥补这一不足，我们提出了 GraphRAG-Bench，这是一个为严格评估 GraphRAG 模型而设计的大规模、领域特定基准。

![](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/technology-popularization/overview-of-GraphRAG-Bench.jpg)

我们的基准具备三大优势：

*   **挑战性问题设计**： 包含大学水平、领域特定的问题，要求进行多跳推理，确保仅靠简单内容检索不足以解决问题。例如，部分问题涉及数学推理或编程。
    
*   **多样化任务覆盖**： 数据集涵盖广泛的推理任务类型，包括单项选择（MC）、判断正误（TF）、多项选择（MS）、开放式问答（OE）和填空（FB）。问题来源覆盖 20 本核心教材中的 16 个学科。
    
*   **全方位评估框架**： GraphRAG-Bench 提供了覆盖整个 GraphRAG 流程的全面评估，包括图构建、知识检索和答案生成。除了最终答案的正确性，它还评估推理过程的逻辑连贯性。
    

通过将九种前沿 GraphRAG 方法应用于 GraphRAG-Bench，我们量化了基于图的结构化如何提升模型推理能力。我们的分析揭示了关于图架构、检索效能和推理能力的关键见解，为业界研究提供了可操作的指导。

GraphRAG-Bench 的所有相关资源均已收集在：

https://github.com/jeremycp3/GraphRAG-Bench

  


## 二、研究背景


检索增强生成（Retrieval-Augmented Generation, RAG）已成为将大型语言模型（Large Language Models, LLMs）植根于外部知识的关键解决方案，用以缓解幻觉问题及领域知识匮乏的问题。通过从语料库中检索相关文本片段，RAG 为 LLM 注入事实性知识，以生成更可靠的输出。

然而，传统的 RAG 系统在处理复杂推理场景时仍不尽如人意。**RAG 中的扁平检索仅基于相似度匹配直接返回零碎的文本块，这限制了其对概念间复杂关系建模的能力，难以回答需要多跳推理、全局理解问题**。例如：

> “2008年雷曼兄弟破产事件对埃隆·马斯克的特斯拉公司有何影响？”

> “贸易政策变革事件的主要思想是什么？”

为应对这些局限，图检索增强生成（GraphRAG）被广泛研究，旨在以图的形式捕捉概念间的结构化知识。其中节点代表概念，边代表概念间的关系。GraphRAG 的最新进展可归纳为三个主要方向。

*   分层图构建方法，通过树形结构和社区检测来组织知识。
    
*   神经图检索方法，采用图神经网络编码器并结合专门的目标函数进行多跳推理。
    
*   动态知识集成系统，开发了与 LLM 紧密耦合的自适应图构建和遍历机制。
    

**通过将知识结构化为图，GraphRAG 不仅使 LLM 能够沿着显式关系路径进行遍历和推理，还能基于图结构推断隐含关系，从而支持更深层次的推理。**

然而，尽管前景广阔，现有的 GraphRAG 方法基准未能充分反映其在图结构上进行推理的性能。这些基准主要利用传统的问答数据集，如 HotpotQA 、2WikiMultiHopQA 和 MuSiQue ，这些数据集仅包含复杂度有限、答案简短的显式事实性问题，例如“Dambar Shah 的孙子是谁？”。

这些数据集存在三个关键局限：

*   仅包含常识性问题，这些问题可能已被 LLM 的训练语料覆盖。
    
*   通常仅需基于显式连接的单跳或浅层多跳推理，不足以探明图结构知识的独特优势。
    
*   答案形式单一： 多数答案为简短形式（名称、日期）或选择题，难以反映基于图的推理能力。
    

因此，我们提出一个研究问题：

**“GraphRAG 是否真正超越了传统 RAG，提升了模型的推理能力？”**

  


# 三、研究方法与实验设计



## （一）研究方法


### 1. 问题设计

为了在大学水平推理上评估 GraphRAG 框架，我们首先构建了一个权威教材语料库。从涵盖计算机科学 16 个不同子领域的 100 多份出版物出发，系统性地筛选出最具代表性的 20 本教材。我们定义了五种问题类型，每种针对 GraphRAG 推理能力的不同方面。最终选取出 1018 道高质量挑战性问题，覆盖了广泛的主题。

![图片](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/technology-popularization/GraphRAG-Bench-question.jpg)

### 2. 语料库收集与处理


（1）预处理阶段区分 PDF 文本页与扫描页，分别采用直接提取和 OCR，并提取教材元数据（大纲、章节页码）。

（2）内容解析阶段：

*   使用 LayoutLMv3 进行多模态布局分析，分割页面为标题、段落等语义块
    
*   用 YOLO 模型检测并隔离数学公式区域避免 OCR 错误
    
*   对扫描页指定区域应用 OCR 获取文本
    

（3）后处理阶段通过 MinerU 工具按阅读顺序重组可能混乱的解析元素（文本、公式等）。

（4） 基于元数据构建四级层级结构（书名→章→节→知识单元），形成带结构标注的教材树。

### 3. 专家撰写推理依据

现有基准通常仅提供最终答案或显式图路径。相比之下，我们的数据集提供了专家撰写的推理依据，清晰阐述了解决每个问题所需的完整逻辑推进过程。

这些推理依据超越了简单的语料聚合，是结构化的叙述，能够：(i) 分离出前提概念，(ii) 描述这些概念间的关系，以及 (iii) 指明问题求解过程中应用的推理操作。

通过追踪逻辑推理和知识交互的每一步，我们可以评估 GraphRAG 模型是否真正生成了基于上下文的解释，还是仅仅利用了表面模式。

为实现细粒度、主题特定的评估，我们数据集中的每个问题都带有两个层级标签：一个宽泛的子领域（Level 1，例如“机器学习”）和一个更细粒度的概念（Level 2，例如“无监督学习”）。这些标注支撑了我们的后验分析。对于每个主题，我们不仅衡量模型答案的准确性，还衡量其生成的推理依据与标准依据的契合度。通过这种方式，我们将评估转化为一个多维过程，要求模型既要提供正确答案，也要生成忠实可信的推理模式。


## （二）实验设计


### 1. 评估指标


*   **图构建：**   
 
   **效率 (Efficiency)：** 构建完整图所需的时间。
    
  **成本 (Cost)：** 图构建过程中消耗的 token 数量。
    
  **组织度 (Organization)：** 构建图中非孤立节点所占的比例（衡量图的连通性）。
    

*   **知识检索：**   
    

   **索引时间 (Indexing time)：** 构建用于检索的向量数据库所需的时间。
    
  **平均检索时间 (Average retrieval time)：** 每个查询进行知识检索的平均耗时。此外，我们总结每种方法使用的检索操作对象（Retrieval operators）以评估其检索机制的复杂度。
    

*   **生成：**   
    
我们认为现有的精确匹配（exact match）指标并不合适，因为正确答案无需逐词对应。因此，本文引入了一个新指标：**准确率 (Accuracy)**，定义如下：

   **OE 和 FB 问题：** 将生成输出和标准答案通过我们设计的提示词（prompt）输入一个 LLM，该 LLM 基于语义对齐和正确性打分。
    
   **MC 和 TF 问题：** 答案正确得 1 分，否则 0 分。
    
  **MS 问题：** 完全正确得 1 分；部分正确得 0.5 分；错误得 0 分。
    

*   **推理依据：**
    

  **推理得分 (R, Reasoning Score)：** 我们设计了一个提示词，将 GraphRAG 方法生成的推理依据和标准依据输入一个 LLM，该 LLM 给出一个推理得分（R）以评估它们的语义对应和推理一致性。
    
   **答案相关推理得分 (AR, Answer-related Reasoning Score)：** 我们额外开发了 AR 指标，用于判断当模型准确回答问题时，其是否能提供正确的推理。此指标旨在区分模型是仅仅猜对了答案，还是确实通过合理的逻辑推理得出了正确答案，从而更全面地理解模型性能。
    


### 2. 实验设置

评估了九种前沿 GraphRAG 方法的性能，为确保所有方法公平比较，采用相同的 GPT-4o-mini 作为默认的大型语言模型。我们没有设置最大 token 长度来限制单个方法的性能。对于需要选择 top-k 的方法，我们统一设置 k=5。在文本分块方面，块大小统一设置为 1200 个token.

  


# 四、实验结果


## （一）图构建评估


![图片](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/technology-popularization/graph-construction-process.jpg)


### 1.  Token 与时间成本

    

*   **树结构**的 Token 成本最低，因为它仅调用 LLM 生成摘要，但由于迭代聚类，耗时最长。
    
*   **段落图**的 Token 成本次优，仅调用 LLM 总结实体或关系，时间成本第二长，归因于耗时的实体链接过程。
    
*   **知识图谱** Token 消耗适中，需要 LLM 进行实体提取和三元组生成，但因三元组获取后知识图谱构建快速，达到最短耗时（DALK 最快）。
    
*   **丰富知识图谱** Token 消耗最多，因为它在标准知识图谱基础上通过LLM为实体和关系生成额外描述，导致时间成本增加。
    


### 2. 组织度


使用非孤立节点比例作为指标（树结构不适用此指标）。结果显示知识图谱表现最佳，其非孤立节点比例保持在约90%。丰富知识图谱表现次优；虽然引入了额外信息，但也不可避免地引入了更多噪声。段落图的非孤立节点比例最低，表明实体链接工具未能有效建立大多数实体对之间的边。


## （二）知识检索评估


![图片](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/technology-popularization/knowledge-retrieval-process.jpg)

*   **索引时间：** GFM-RAG 索引时间最短；它不构建传统的向量数据库存储实体，而是在图构建阶段专门存储与问题对应的实体。在使用向量数据库的方法中，KGP、RAPTOR 和 DALK 因存储信息量少而成本较低；ToG、G-Retriever 和 LightRAG 成本适中，因为存储关系本身耗时；GraphRAG 因额外存储社区报告而进一步增加索引时间。HippoRAG 索引时间最长，归因于其额外构建实体<->关系和关系<->文本块映射。
    
*   **平均检索时间：** RAPTOR 速度最快，其树结构能快速定位信息。GFM-RAG 和 HippoRAG 紧随其后，分别利用 GNN 和 PageRank 算法进行检索。G-Retriever 采用带奖励收集斯坦纳森林算法（Prize Collecting Steiner Forest），LightRAG 依赖基于关系的检索，两者都引入了额外延迟。GraphRAG 需要利用社区信息检索，导致耗时较长。KGP、ToG 和 DALK 因检索时依赖调用 LLM 而产生显著时间成本。
    


## （三）生成准确率评估


![图片](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/technology-popularization/generation-process.jpg)

*   鉴于 GPT-4o-mini 本身已具备较强的问答能力，并非所有 GraphRAG 方法都能有效提升其性能。
    
*   **性能下降：** DALK 和 G-Retriever 反而降低了 LLM 性能；它们过度依赖结构信息而牺牲了语义内容，在生成过程中引入了过多噪声，损害了 LLM 的判断准确性。
    
*   **小幅提升：** LightRAG、ToG 和 KGP 实现了小幅性能提升，表明其检索到的内容对生成任务提供了有限的帮助。
    
*   **显著提升：** 相比之下，GFM-RAG、GraphRAG 和 HippoRAG 通过有效整合图结构信息和文本块级语义显著提升了 LLM 性能：GFM-RAG 利用大规模预训练获得鲁棒的基础模型，GraphRAG 利用基于社区的信息优化检索，HippoRAG 通过 PageRank 算法提升检索效率。
    
*   **最佳方法：** 实验中表现最佳的方法是 RAPTOR，它通过迭代聚类构建树结构，这种设计与教材数据天然的分层组织结构高度契合，能够高效检索相关信息。
    
*   **超越传统 RAG：** 大多数 GraphRAG 方法优于 BM-25 和 TF-IDF 等传统 RAG 基线，突显了基于图的架构在提升生成准确率方面的效用。
    

## （四）推理能力评估


![图片](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/technology-popularization/reasoning-ability.jpg)

*   与生成任务的高准确率相比，GPT-4o-mini 在推理性能（ R 和 AR 得分）上表现出显著下降。R 得分的下降表明 LLM 常常无法进行正确推理，而是在许多情况下通过猜测或模式匹配来选择答案。AR 得分的下降表明，即使 LLM 提供了正确答案，其推理过程也可能存在缺陷；或者它们可能生成了正确推理但选择了错误答案。
    
*   **显著提升：** 所有 GraphRAG 方法都显著增强了 LLM 的推理能力：通过不同的算法设计，这些方法不仅检索到与问题语义相关的语料，还识别出知识库中具有多跳依赖性的语料，为 LLM 的推理提供了证据支持。这使得 LLM 能够基于外部信息进行推理，而非仅依赖内部知识进行猜测。
    
*   **算法性能分布：** 在算法性能分布上，与生成任务类似：HippoRAG 和 RAPTOR 仍是表现最好的，这很直观，因为检索到有用信息本身就与实现正确推理相关。
    
*   **超越传统 RAG：** 大多数 GraphRAG 方法仍然优于传统 RAG 基线（TF-IDF, BM-25）。
    


## （五）主题特定生成准确率分析


鉴于我们的数据集跨越 16 个不同主题领域，我们对 GraphRAG 对 LLM 生成准确率的影响进行了细粒度分析。总体而言，GraphRAG 在大多数领域带来了一致的提升。然而，也发现了一些有趣的发现：

![图片](https://nebula-cdn.nebula-graph.com.cn/nebula-website-5.0/share/technology-popularization/Generation-Accuracy-by-Topic..jpg)

*   **数学领域：** 所有 GraphRAG 方法都降低了 LLM 在数学题上的生成准确率。这是因为数学问题关键依赖于严格的符号操作和精确的推理链；模型必须在内部“计算”每个演绎步骤，而非依赖外部文本的关键词匹配。通过 GraphRAG 检索到的大多数文档是解释性或概念性的，其符号表示、公式布局和上下文结构常与问题要求不符，导致信息提取和转换过程中产生歧义或关键步骤丢失。
    
*   **伦理领域：** GraphRAG 和 LLM 本身在伦理题上的表现都平平。我们认为伦理问题从根本上涉及主观价值判断，其含义取决于道德权衡和社会规范的动态语境。LLM 通过统计学习捕捉的符号表示难以准确建模模糊的伦理概念，在推理上存在固有局限。
    
*   **稳健性：** 优秀的 GraphRAG 方法在大多数主题上显著提升了 LLM 的生成准确率，展现出稳健的性能，验证了其跨领域有效性。
    

  

**五、Observation**
=================

**🙋GraphRAG 能否提升所有问题类型的性能？**
-----------------------------

*   **单项选择问题准确率下降：** LLM 通过在大型语料库上的广泛训练内化了海量知识，使其在选择题任务中常能正确选择答案。然而，GraphRAG 基于检索的增强可能引入冗余或松散相关的信息，这些信息与问题语境并非精确匹配。此类检索噪声会干扰模型的决策能力，最终降低其在单项选择问题上的准确率。
    
*   **判断正误问题性能提升：** TF 问题需要对事实或逻辑陈述进行二元判断。LLM 可能对某些事实存在盲点或不完整的知识，导致错误答案。通过检索相关的事实证据，GraphRAG 帮助模型在回答前验证陈述。这些补充信息提高了模型在判断正误问题上的准确率。
    
*   **开放式问题性能提升：** 开放式问题允许广泛、详细的回答，这对于仅依赖内部知识的 LLM 来说可能具有挑战性。GraphRAG 通过提供来自外部语料库的额外上下文和事实来缓解这一挑战。检索到的信息丰富了模型的回答，提升了主题细节和表达能力，并通过将答案基于明确证据来减少幻觉。
    
*   **填空和多项选择问题的不同效果：** 填空问题需要精确的上下文理解以正确预测缺失词。GraphRAG 检索到的语料通常无法匹配确切的语境，引入噪声从而降低模型在填空问题上的表现。多项选择题需要从一组选项中选择多个正确答案，涉及对选项复杂组合的推理；如果 GraphRAG 的检索遗漏了相关答案选项或包含了无关细节，则可能混淆模型。因此，这些问题类型对检索精度要求很高；除非 GraphRAG 的检索非常精确，否则其收益可能有限。
    

**🙋GraphRAG 能否有效增强 LLM 的推理能力？**
--------------------------------

实验表明，GraphRAG 能有效增强 LLM 在各种问题类型上的推理能力，提高了在生成答案的同时生成正确推理依据的概率。

这归功于其高效的检索机制，不仅能为问题识别高度相关的语料，还能为 LLM 的推理过程提供有力的证据支持。特别是，现有基准缺乏对 GraphRAG 推理能力的系统性评估，而这在实际应用中至关重要。例如，在本文针对的大学级教育场景中，寻求专业知识的用户不仅期望正确答案，还期望清晰的推理依据以促进理解和知识获取。同样，在医疗场景中，患者需要清晰的用药依据和治疗建议，以确保决策的透明度。因此，有效的 GraphRAG 方法不仅应追求答案生成的高准确率，还应追求强大的推理和可解释性。

  

**六、结论**
========

本文提出了 GraphRAG-Bench，这是首个专为 GraphRAG 设计的领域特定基准。它包含一个跨越 16 个学科的数据集，通过多跳推理、复杂算法/编程任务、数学计算和多样化问题类型挑战现有方法，覆盖图构建、知识检索、生成和推理的全方位、多维评估，量化了结构化知识增强对 LLM 推理能力的提升。在九种前沿 GraphRAG 方法上进行的广泛实验，揭示了图集成在提升推理和生成性能方面的重要作用。


  

‍

  



GraphRAG 真的超越了 RAG 吗？GraphRAG 哪家强？GraphRAG 性能评估标准有哪些？

技术科普｜首个 GraphRAG-Bench 如何评估九大 GraphRAG 性能？

![](https://pic1.zhimg.com/80/v2-b62ebd2301b9bc3d8cc24427f0a9be49_1440w.jpg?source=d16d100b)


# **RAG 的历史**

云风作为中国程序员圈的先驱，曾在一篇文章中写道：“**无论我们想学什么，都应该从学习它的历史开始**。”这篇文章的许多观点都对我影响深远。今天，我们就从 RAG 的历史开始聊起。

![](https://pic1.zhimg.com/80/v2-6c2b68cfc55015b2189dc7f77d767958_1440w.jpg?source=d16d100b)


在传统大模型中，就是一个 model: 我问一个问题，经过该大模型，给出一个回答。那 RAG 则是我的问题会经历一个向量数据库，根据检索到的信息给出答案。向量数据库的广泛使用已经很久了，淘宝搜索、以图搜图或者谷歌、百度搜索，背后都是它在发挥关键作用。

**具体而言，RAG（Retrieval Augmented Generation）是一种结合了检索和生成的范式。它通过检索相关参考材料，然后从检索到的信息中进行上下文学习，以生成回答**。它能够通过检索相关文档来增强生成模型的能力，从而在问答系统中提供更准确和丰富的回答。

![](https://pica.zhimg.com/80/v2-aa43fe534e564dc18bf83203bd0e429a_1440w.jpg?source=d16d100b)


RAG 的历史可以追溯到 2020 年，那时还没有 GPT-3.5，人们普遍认为 GPT 只是一个玩具，因为它非常昂贵。在这个时期，Facebook 的 AI Research 团队发表了一篇论文，标志着 RAG 的诞生。这篇论文使用的是 GPT-2 模型，研究人员发现，将大型语言模型与自然语言处理相结合，可以产生非常好的效果。

![](https://picx.zhimg.com/80/v2-1a7f1dd15b1152379758a5e643b496d8_1440w.jpg?source=d16d100b)


# **GraphRAG 的历史**

2022 年 3 月，OpenAI 公布了自己的 API, 这使得大家开始思考如何利用这个 API 来实现更多的功能，这时向量数据库的潜力被重新发现。大家意识到，通过向量数据库或者在传统数据库中加入向量类型，可以实现 RAG 的功能。

例如，我有一个文档，先靠 OpenAI 或者其他大模型，转换成向量，储存在向量数据库里。这时我提出问题，大模型将其转换为向量，在向量数据库中查找最匹配的段落，组织语言后生成最终答案。通过这样的方式，有效解决大模型在专业领域知识不足的问题。

随着向量数据库的兴起，图数据库公司也开始思考如何利用自己的技术来实现类似 RAG 的功能。**NebulaGraph GenAI Team Leader 古思为提出了将图数据库与 RAG 结合的想法，并向 LlamaIndex提了第一个PR，将 KG-RAG 转变为 GraphRAG**. 这个转变意味着人们开始探索使用图模型来增强 RAG 的功能，利用图数据库的搜索强度可能比传统的向量更好，能够起到一定的 RAG 作用。

![](https://picx.zhimg.com/80/v2-9610c8e2a3d959e880909a324b4aad0c_1440w.jpg?source=d16d100b)


微软在 2024 年 4 月份发布了 GraphRAG 的第一篇论文，市场上很多项目开始从 RAG 向 GraphRAG 迁移。这一转变的原因是 RAG 存在一些问题，而 GraphRAG 在某些领域存在突出优势。

![](https://pica.zhimg.com/80/v2-f434d9c8728c4683a253fad396ebc217_1440w.jpg?source=d16d100b)


# **RAG VS GraphRAG**

刚我们已经提到，在处理查询时，RAG 会利用大型语言模型，将查询转换为向量形式，然后在向量数据库中检索相关信息，并通过上下文学习生成回答。市场上对这一过程进行了多种优化，例如 rerank, 它使用大型语言模型对检索结果进行再次排序，以提高回答的相关性。

![](https://pic1.zhimg.com/80/v2-d24e2d428156bddb99738daf4d487935_1440w.jpg?source=d16d100b)


然而，RAG 在处理细粒度检索和全局上下文搜索时存在局限性，如知识碎片化和上下文丢失问题。**例如，在《红楼梦》中搜索林黛玉「哭泣」的原因可以找到结果，但搜索她「不笑」则无法找到答案，因为书中并没有提供相关信息**。这些问题限制了 RAG 在企业级应用中的准确性和可靠性，因为企业需要的是接近 100% 的准确率，而 RAG 往往只能达到 95% 的准确率，这在商业环境中是不够的。

![](https://pic1.zhimg.com/80/v2-12f1365629de7adc1e1bb838ce63ddf5_1440w.jpg?source=d16d100b)

相比之下，**GraphRAG 不依赖于向量数据库，而是利用图数据库来存储和检索信息**。它通过大型语言模型抽取文档中的主要关系和实体，并将它们转换为图结构存储在图数据库中。**这种方法不仅提高了检索的强度，还能够更好地处理全局上下文搜索和领域知识集成的问题**。

# **GraphRAG 的能力总结**

![](https://pica.zhimg.com/80/v2-e7ec9a2bd6d33b3e52c32bb326ba4a8a_1440w.jpg?source=d16d100b)


![](https://pica.zhimg.com/80/v2-bd9b3b5ec83f57d8bc884a9f0784778f_1440w.jpg?source=d16d100b)

GraphRAG 通过图索引、文本到查询的转换以及链式探索（Chain of Exploration）来增强模型的探索能力，类似于传统 RAG 中的思考量，但增加了探索量。**这种基于图的方法可以利用图数据库找到真正的重组关系，实现更复杂的 AI 编排工具，满足市场上对高精度和高可靠性的需求**。

# **何时使用GraphRAG**

何时推荐使用 GraphRAG呢？我们可以考虑以下几种情况。

![](https://pica.zhimg.com/80/v2-5dedae1e0d6129784ba62770d85d4e7e_1440w.jpg?source=d16d100b)


首先，当**面对高度离散的数据时**。例如，企业可能拥有大量分散的文档和多年的杂乱数据库，GraphRAG 能够帮助整合这些信息，构建起企业知识图谱，从而实现更深层次的数据理解和利用。

其次，当**需要对全局信息进行理解**时。以《红楼梦》为例，如果我们想要对书中的人物关系和情节有全面的理解，GraphRAG 能够提供全局的视角，帮助我们捕捉到更细微的联系和深层次的内涵。

此外，**领域知识的集成**是 GraphRAG 的另一个重要应用场景。在职业招聘领域，GraphRAG 可以帮助匹配求职者的技能、工作经验与职位要求，从而提高招聘效率；在医学领域，GraphRAG 能够通过分析个体的特定特征来预测疾病，这对于精准医疗和个性化治疗方案的制定具有重要意义。

# **GraphRAG 企业知识管理与应用构建平台**

NebulaGraph 已经在实际项目中应用了 GraphRAG.

![](https://picx.zhimg.com/80/v2-6ed4433c5045ad70bef8305752fca795_1440w.jpg?source=d16d100b)


NebulaGraph 利用 GraphRAG 做 index, 对企业内部文档进行问答集的构建，旨在为企业提供高效、智能且易用的知识解决方案。通过引入知识级概念和 Meta Agent 概念，该平台显著降低了员工的使用门槛，使他们能够通过聊天式交互轻松构建知识应用，实现低心智负担的操作。

# **GraphRAG 的缺点**

在探讨 GraphRAG 技术时，我们不得不提到它的一个主要缺点——成本。**GraphRAG 的高成本主要源于其初始化阶段**，特别是当使用像 GPT-4 这样的先进模型来构建索引并存储在图数据库中时。

**然而这种成本在技术发展的不同阶段有所变化**。正如我们刚开始提到的，GPT-3 曾因其高昂的价格而让许多用户望而却步，然而随着 GPT-3.5 的推出，成本有所下降。 GPT-4 问世后，人们只会在发布后的一段时间内觉得过于昂贵。随着时间的推移，成本将进一步降低，更多经济实惠甚至免费的模型会陆续出现。

![](https://picx.zhimg.com/80/v2-da3ba0351bf180d08187e3eba0cacc26_1440w.jpg?source=d16d100b)


**尽管 GraphRAG 的初期投入可能较大，但这种成本在很大程度上是一次性的：贵，但只贵一次**。对于拥有大量文档和数据的企业来说，一旦构建了 GraphRAG 模型并将其存储在数据库中，这些数据和模型就成为了企业的长期资产。随着时间的推移，这些资产可以被反复利用，从而分摊了初始成本。此外，GraphRAG 带来的效率提升和知识管理优势，使得这种投资在长期看来是合理的。

因此，尽管 GraphRAG 的启动成本较高，但它为企业提供了一种强大的工具，以实现更智能的数据管理和决策支持，这在当今的数据驱动型经济中至关重要。


——————————分割线——————————————————————

🙋活动推荐

诚邀您参加【NebulaGraph x Airwallex 图数据库与风控】上海站，一场聚焦于图数据库与 GraphRAG 在风控领域创新应用的 nMeetup，[点此报名](https://9753492656408.huodongxing.com/event/3799122350000)

![](https://picx.zhimg.com/80/v2-515cae27af412c84eb52414701bd91e8_1440w.jpg?source=d16d100b)



🔍相关阅读

[首个提出 GraphRAG 的团队在做什么？](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247516100&idx=1&sn=aaacb7b5fcb68acdb4a12d1a98af4cfb&scene=21#wechat_redirect)

[首发完整版教程，MCP 集成至 LlamaIndex 的技术实践](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247515436&idx=1&sn=f4a428b25dcaecc5f4f9aa100695d15f&scene=21#wechat_redirect)

[NebulaGraph MCP Server 正式开源！探索 AI+图数据库无限可能](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247516029&idx=1&sn=144dbf68dd1cd770cf6bee531500ccad&scene=21#wechat_redirect)

[GraphRAG vs DeepSearch？GraphRAG 提出者给你答案](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247515612&idx=1&sn=e5b3f13debc62fcf53119e55ce2b6b71&scene=21#wechat_redirect)

[NebulaGraph 的 GraphRAG 进展、实践](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247514593&idx=1&sn=bed17f080e374d9cb957d14f17a01062&scene=21#wechat_redirect)

[VLDB 2024｜NebulaGraph RAG 正式官宣](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247511923&idx=1&sn=4d9a9b80cf528212b64ef96ec6a62fad&scene=21#wechat_redirect)

[基于 NebulaGraph ，构建属于你的 Graph RAG](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247511536&idx=1&sn=f73ada9ea4c97d23acaed65c60a06034&scene=21#wechat_redirect)

有哪些炙手可热的场景需要 GraphRAG 实现？

> “NebulaGraph 作为一款云原生图数据库，属于传统 Infra, 但我们逐渐意识到，AI 的发展将彻底改变数据库的应用场景和技术架构。于是，我们团队开始探索图数据库在 AI 领域的价值。”本文整理自 NebulaGraph @PsiACE 在 KCD Beijing 上的演讲， 与大家分享 NebulaGraph GenAI Team 的工作与进展。

![](https://picx.zhimg.com/80/v2-c00d5a1549bde4fe3e2a1730e391ceaa_1440w.jpg?source=d16d100b)



> 本文首发于[「NebulaGraph 技术社区」](https://mp.weixin.qq.com/s/346RoWfDa9zfKO8jmtGEgg)

# **Part 1 背景趋势**

## **01 传统 RAG 方法的痛点**

![](https://picx.zhimg.com/80/v2-3a5ff55238d81ca779830cda0714ce1b_1440w.jpg?source=d16d100b)



传统 RAG 方法在实际应用中面临诸多挑战：

* **细粒度知识检索能力不足**：举个例子，做 chunk 分块是一个很强的对信息浓度的假设，无论是用语义的方式还是固定大小来分块，一旦确定了这个分块，其实对知识被召回的数据的信息浓度做了一个很强的假设，有的时候就存在一些重要而细粒度的分散的信息没办法进行召回，质量就会有些损失。

* **全局上下文关联缺失**：索引的知识块中，核心知识点和其他知识点的关联，有些知识有局部性，例如 A 和 B 在一个块关联，B 和 C 在一个块关联，C 和 D 在一个块关联，如果某些任务依赖于全局的上下文，但任务中又只提及 A 和 D，这中间的关联在做 chunk 的 RAG 索引一般是丢失的，无法获取全局上下文的关联。

* **向量相似性与相关性错配**：传统 RAG 的索引方法追求相似，但实际上相似并不等于相关。例如，检索保温杯与保温大棚相关文章，在向量数据库中大概率会变成两个非常相似的向量，从而使得生活场景与农业场景产生错配。

* **全局性问题及推理型问题回答能力不足**：传统 RAG 在处理全局宏观性问题和需要推理的问题时，往往只能给出片面的答案，缺乏深度分析和逻辑推理。如果将树比喻成知识，整片森林（所有的树）代表全部知识，如果问这个森林是什么形状的，很明显这是一个宏观的问题，当只召回到一部分的树是无法回答这个问题的。

# **02 GraphRAG 的优势**

NebulaGraph 专注于图技术，已进行了多年的开源分布式图数据库的研发。**在 RAG 技术还未被称为 RAG，而是上下文学习方法的时候，我们就意识到以图的方式处理知识会对解决这些问题有很大帮助。因此，NebulaGraph 率先提出了 GraphRAG 的方法，并于 2023 年 8 月与 LlamaIndex 联合发布 GraphRAG**.

GraphRAG 的优势显著：

![](https://picx.zhimg.com/80/v2-29bc1580eb8ccd4f71abfa9437037cd4_1440w.jpg?source=d16d100b)



* **细粒度的切分实体和关系**：通过知识图谱技术，将多模态文本中的实体和关系进行细粒度的拆分，保留高度凝练的知识细节。例如，在讨论“苹果”时，能够准确识别是指水果还是苹果手机，并明确它们之间的关系。

* **保留事物间的关联关系**：在知识图谱中明确事物之间的关联，提升可解释性。比如，在工业排障场景中，通过图数据库可以清晰地展示故障之间的关联关系，高效地追根溯源，帮助用户快速定位问题。

* **图查询和图算法得到相关上下文**：利用图查询和图算法，将边和实体对应的节点都提取出来，精准获取相关上下文信息，使回答更全面、更符合预期。

## **03 云原生图数据库 NebulaGraph 的价值**

* **完整的 Infra 基座**

![](https://picx.zhimg.com/80/v2-cf72e141be2f5fc8d94a1945ca861edf_1440w.jpg?source=d16d100b)


在过去几个月里，GraphRAG 技术作为 RAG 下 state of art 的范式，得到了充分的关注，可以看到包括微软、Meta、Google都做了一些不错的工作。不过大多数实现仅仅是借用图的形式表示而并没有建立在图数据库之上，**但可以预想，随着数据量的增大，图数据库的价值在 GenAI 时代将会更加重要。因为它是一个完整的 Infra 基座，对各种运行环境和云厂商具有良好的兼容性，能够与 K8S 等技术深度集成，原有日志、可视化等工具也可完整接入，无需额外定制化开发和运维保障，这使得企业可以充分利用现有的技术资源去使用 GraphRAG**.

* **大规模复杂场景检验**

![](https://pica.zhimg.com/80/v2-02bc652d3f3e912c8d448a54ae2f0b6f_1440w.jpg?source=d16d100b)


某知名海外社交平台的好友推荐、广告推荐等场景，充分证明了 NebulaGraph 在高实时性、高精度需求场景下的高性能。**该社交平台的用户关系超过 100 亿，单个最大规模图谱超过 400 亿点，1000 亿边，但仅需 2 个工程师就可以维护所有与 NebulaGraph 相关的产品，有效降低运维成本**。


# **Part 2 技术路线**

## **01 GraphRAG-Agentic Workflow**

以往大家 RAG 的理解是检索增强生成，但我们对 RAG 的理解分为以下三个部分：‍

![](https://pic1.zhimg.com/80/v2-956e63775ded66938b20926a11048091_1440w.jpg?source=d16d100b)


* Retrieval（检索）：检索大量数据，补充数据实时性，将多模态数据转化为可检索形式。

* Agent（智能体）：可定义工具集，调用各种方法和生态产品。比如，在处理复杂问题时，Agent 可以调用不同的工具和算法，进行多轮推理和分析。

* Ground Truth（真实情况）：Ground Truth 的建设是通过 "专家经验 Human in Loop + 机器智能" 的协同机制，构建可复用、可进化的知识体系，实现知识与真实世界的同构映射，确保不同业务场景、不同阶段的应用均可基于相应的事实基准开展工作。

## **02 GraphRAG-ParseCraft**

为什么不是完全依赖现有工具去做这个事情，而是需要自己去研发一些组件呢？因为在整个解析的流程中可能涉及到一些预处理和后处理的工作，而且对于特定的内容需要有足够的能力来干涉解析过程，确保生成符合预期的结果。比如在我们的场景中可能会涉及的部分包括：

![](https://picx.zhimg.com/80/v2-ac8ac40e373a3c11f21dd7975cbf57ef_1440w.jpg?source=d16d100b)


* 特定领域的内容的理解和表征：比如故障树分析，这个场景拿到的是一个图片，但是图片上的事件存在关联关系，我们需要把它转换到图上面，并标识这些关键路径和事件。

* 通用场景下的关键结构的转换：比如文章的段落、目录，天生就是具有结构化、和领域化的内容，比如一个章节内大概率是围绕相关主题展开的，在解析过程中需要留存；再比如布局之间的关联，可能影响上下文，如果要精细地做一些事情，可能不得不将这些信息保存下来。

ParseCraft 注重集成性和可定制性，作为接入层，除了定制基于视觉语言模型的解决方案外，还能融合文档解析、布局识别等方案，只需实现少数几个 API ，就可以获得格式转换和可观测性的能力增强。预计今年上半年开源。例如，在处理复杂的文档和表格时，ParseCraft 可以将其转化为大模型易于理解的格式，提高处理效率。

## **03 GraphRAG-Deep Seach**

![](https://pic1.zhimg.com/80/v2-45829c20e348f6b2bf678f8c4fc25ba9_1440w.jpg?source=d16d100b)


我们目前的 GraphRAG 实现本身也是符合 Agentic 范式的，结合推理模型，如 DeepSeek R1 / Qwen QwQ 等，可以对任务进行预先规划，并驱动在 Workflow 中进行多轮探索和评估，与 Deep Search 充分兼容，能够节约开销、增强效果。

## **04 GraphRAG-All in MCP**

![](https://pica.zhimg.com/80/v2-242c370a7b4678147c90e5abe4bf3126_1440w.jpg?source=d16d100b)


我们团队积极参与 MCP 相关工作，输出 LlamaIndex 社区第一个 MCP 工具支持方案，落地 Local MCP 范式，并且进入官方 repo 进行集成。此外，我们实现内部工具集定义落地了 Local MCP 范式，在复用 MCP 相关接口标准的同时，改用函数调用的模式，为内部工具调用和后续开放 MCP 服务能力提供基础。实现函数调用与接口复用。例如，在处理复杂的图查询时，MCP 可以提供强大的支持，提高查询效率和准确性。（MCP 集成至 LlamaIndex 完整教程，[详情请查看](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247515436&idx=1&sn=f4a428b25dcaecc5f4f9aa100695d15f&scene=21#wechat_redirect)🔍）

## **05 Graph Insight-Text to GQL**

![](https://picx.zhimg.com/80/v2-4ddcb4c2a9fb3fcbacec36eac802bdc6_1440w.jpg?source=d16d100b)


早期数据库领域和大模型结合的一个重要方向就是 Text2SQL ，对于图数据库，对应的就是 Text2Cypher，当然，随着 ISO GQL 标准的确立，现在 Text2GQL 也成为了关键的一环。NebulaGraph 在这个方向上也做了一些努力，沉淀出了一套 Graph Insight 的方法。

一方面，利用基础的 Text2GQL 方法，用户可以以问答形式在已有图谱上进行简单的图查询和图计算。另一方面，通过利用内置的一些算子模版，可以将复杂的图查询转化为填空题，降低大模型编写复杂查询语句和探索图的难度。通过提示词工程和 ReAct 等方式，Agent 可以利用上下文对生成的 GQL 语句进行自校准，帮助写出更加准确和符合业务目标的 GQL 语句。

当然，用户也可以在这个基础上将过去积累的图算法作为模版封装，充分利用过去业务场景积累的经验，释放图上的价值。

## **06 Graph Insight- Agentic & CoE**

![](https://picx.zhimg.com/80/v2-21f3b3e505539c5c3040a084f6bf955c_1440w.jpg?source=d16d100b)



Graph Insight 我们聚集 Agentic 范式图探索能力与 Chain of Exploration（CoE），构建了一套高效的图知识处理与分析体系。不仅能深度挖掘图谱内的知识，还能以自然融合的方式整合多源数据 —— 将图探索作为 Agent 调用的工具，无缝对接互联网知识等外部数据源，打破单一数据边界，实现知识的跨域协同。

## **07 Graph Insight - MCP**

![](https://picx.zhimg.com/80/v2-5e25407eb4e62a78892f18a3dc947e5e_1440w.jpg?source=d16d100b)


针对热门的 MCP方向，团队构建了 NebulaGraph MCP Server（已正式开源，[详情请查看](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247516029&idx=1&sn=144dbf68dd1cd770cf6bee531500ccad&scene=21#wechat_redirect)🔍）。该服务不仅为大模型提供查询接口，支持直接调用执行图数据查询，还预封装了实用的算子模板，包括邻居发现、路径发现等核心功能，简化图数据操作流程。

# **Part 3 应用案例**

## **01 产品 - 图 AI 工具链**

![](https://pica.zhimg.com/80/v2-1aec0efb7dfa7924fbcc195e8ad50b2b_1440w.jpg?source=d16d100b)


我们面向开发者提供了一套完整的工具链，包括对向量、全文索引等能力做了支持，方便企业自行开发 AI 应用，核心功能包括图谱构建、图谱推理、模型微调等。

## **02 产品 – 图 AI 应用平台**

![](https://pica.zhimg.com/80/v2-5c31c93871d81ef222752b9f21d4d321_1440w.jpg?source=d16d100b)



面向终端用户，开箱即用，帮助用户以对话方式快速构建 AI 应用，如智能客服机器人、故障排查助手、研报生成机器人等，具有智能文档处理、零代码、零工作流、零提示词设计等特点。用户可以通过简单的对话方式，快速构建一个智能客服机器人，提高客户服务效率。

## **03 工业解决方案‍**

![](https://pic1.zhimg.com/80/v2-7d5624c96495ed72fff5e8d1b7f8ba36_1440w.jpg?source=d16d100b)



NebulaGraph 与行业头部企业协作，构建面向工业协同研发系统的 Graph + AI 解决方案，落地行业首个生成式人工智能驱动的实际应用场景，基于知识图数据库及智能问答系统进行数据交互，荣获沙丘社区 2024 最佳案例 15 强。

此外，在复杂排障知识图谱的构建和探索上，我们也积累了一定经验，充分运用大模型赋能排障系统，在一些场景下拥有超过 40 万有效节点。

## **04 金融行业解决方案**

![](https://picx.zhimg.com/80/v2-f9dc87dec0dcc73ccc7f6981aa6817f1_1440w.jpg?source=d16d100b)



利用基于大模型的知识图谱自动抽取和构建技术，和在金融领域深耕积累的经验洞见，NebulaGraph 和合作伙伴共同构建和发布基于 GraphRAG 和 Agentic Workflow 的行业解决方案，共同推动 Graph + AI 技术在金融风控等领域的发展。

# **结语**

NebulaGraph 在 GenAI 领域的探索和实践，不仅解决了传统 RAG 方法的痛点，还通过云原生图数据库的价值，为各行业提供了强大的技术支持。未来，NebulaGraph 将继续深化技术路线，拓展应用领域，推动 GenAI 技术的不断发展和创新。







————————————分割线————————————————

🙋活动推荐

诚邀您参加【NebulaGraph x Airwallex 图数据库与风控】上海站，一场聚焦于图数据库与 GraphRAG 在风控领域创新应用的 nMeetup，[点此报名～](https://9753492656408.huodongxing.com/event/3799122350000)

🔍相关阅读

[首发完整版教程，MCP 集成至 LlamaIndex 的技术实践](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247515436&idx=1&sn=f4a428b25dcaecc5f4f9aa100695d15f&scene=21#wechat_redirect)

[NebulaGraph MCP Server 正式开源！探索 AI+图数据库无限可能](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247516029&idx=1&sn=144dbf68dd1cd770cf6bee531500ccad&scene=21#wechat_redirect)

[GraphRAG vs DeepSearch？GraphRAG 提出者给你答案](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247515612&idx=1&sn=e5b3f13debc62fcf53119e55ce2b6b71&scene=21#wechat_redirect)

[NebulaGraph 的 GraphRAG 进展、实践](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247514593&idx=1&sn=bed17f080e374d9cb957d14f17a01062&scene=21#wechat_redirect)

[VLDB 2024｜NebulaGraph RAG 正式官宣](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247511923&idx=1&sn=4d9a9b80cf528212b64ef96ec6a62fad&scene=21#wechat_redirect)

[基于 NebulaGraph ，构建属于你的 Graph RAG](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247511536&idx=1&sn=f73ada9ea4c97d23acaed65c60a06034&scene=21#wechat_redirect)

NebulaGraph GenAI Team 在 GraphRAG 上的工作与进展

首个提出 GraphRAG 的团队在做什么？

![图片](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/MCP/dac249151143b177336ead527966a939472621355.jpg)

> 本文首发于 NebulaGraph 技术社区 [https://mp.weixin.qq.com/s/YhtDxiPIVRR3VQAoVQxYjw](https://mp.weixin.qq.com/s/YhtDxiPIVRR3VQAoVQxYjw)

# ▌一、背景


过去几周，Model Context Protocol (MCP) 在技术社区中引发了广泛的讨论和关注。借此机会，我参与了几个相关的开源项目，包括为 **LlamaIndex 官方仓库贡献了 McpToolSpec 实现**，以及和 Xuanwo、FrostMing 合作开发了一版 **Model Context Protocol Server for Apache OpenDAL™**。

MCP 是目前唯一一个在生态上具有优势的标准。在这一背景下，我们**基于 NebulaGraph 3.x 实现了一个简单的 NebulaGraph MCP Server，作为 NebulaGraph X MCP 生态中的第一个基础组件，供大家探索 AI 与图数据库结合的可能性**，希望能够看到更多在这个模式下的有趣工作。


# ▌二、Model Context Protocol (MCP)


MCP 是由 Anthropic 团队推出的一项开放协议，旨在为 AI 系统提供统一的、高效的方式访问多种数据资源。通过采用客户端-服务器架构，MCP 将数据访问标准化，解决了传统 AI 系统在不同数据源之间的碎片化问题。

**MCP 核心特点**

1.  **标准化的通信方式**：通过 MCP，AI 助手能够有效地访问各种数据源，比如本地数据、远程服务和企业工具。
    
2.  **开放性与生态优势**：目前 MCP 社区中已有近 1000 个 MCP Server 实现，覆盖搜索、天气、数据库等多个领域，支持工具的快速接入。
    
3.  **灵活的架构**：通过定义客户端和服务端的交互协议，MCP 为开发者提供了构建可扩展、可复用系统的基础。
    

虽然目前在安全性和可靠性上仍有一些挑战，但随着协议规范的完善和成熟开发模式的引入，这些问题将逐步得到解决。


# ▌三、NebulaGraph MCP Server 功能


由于最近一段时间一直围绕 GraphRAG 和 Agentic Workflow 做一些工作，利用大模型和智能体进行图上数据的洞见和挖掘是一个非常重要的议题。为此，我快速开发了 NebulaGraph MCP Server，以支持 NebulaGraph 3.x 作为工具接入 MCP 生态，供语言模型（如 Claude、GPT 等）调用和使用。

目前 **NebulaGraph MCP Server 基于 FastMCP 实现，遵循 MCP 的核心规范，旨在提供高效、轻量的图数据库连接服务**。通过将 NebulaGraph 的功能暴露为标准化的工具接口，该 Server 能够让大模型轻松调用 NebulaGraph 数据，实现简单的图探索任务。

 **多种传输方式**：
    
-   支持 stdio 和 SSE 两种传输模式，满足不同开发和部署场景的需求。
    
  **基础图探索能力**：
    
-   图空间（Graph Space）列出：允许模型查询可用的图空间。
    
-   模式（Schema）查询：支持查询指定图空间的模式定义。
    
-   查询执行（Query Execution）：支持通过 MCP Server 执行 NebulaGraph 查询。
    
   **内置算子模板**：
    
-   实现了路径搜索和邻居发现等常用操作的模板，方便语言模型按需调用这些工具，快速获取图数据的初步洞察（Insight）。
    

为了展示它的效果，我基于 LlamaIndex 中的 McpToolSpec 和 ReActAgent 构建了一个简单的示例，下面是对应的截图：
![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/MCP/3799122350000_wechat)


# ▌四、结语


**NebulaGraph MCP Server 是对 MCP 生态的一个初步尝试，旨在为语言模型和图数据库的结合提供一个起点**。随着协议的逐步成熟和生态的扩展，我们期待它能够在更多真实场景中发挥价值。如果您对这一方向感兴趣，欢迎一起探索、尝试！

**🔍相关阅读**：[首发完整版教程，MCP 集成至 LlamaIndex 的技术实践](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247515436&idx=1&sn=f4a428b25dcaecc5f4f9aa100695d15f&scene=21#wechat_redirect)‍‍

基于 NebulaGraph 3.x 实现了一个简单的 NebulaGraph MCP Server，作为 NebulaGraph X MCP 生态中的第一个基础组件，供大家探索 AI 与图数据库结合的可能性

NebulaGraph MCP Server 正式开源！探索 AI+图数据库无限可能


# ******▌********一、背景**


GraphRAG 是检索增强生成（RAG）技术的高级技术之一，旨在解决传统 RAG 的局限性。上周，[NebulaGraph 团队分享了关于 GraphRAG Indexing 模型蒸馏训练的工作](https://x.com/wey_gu/status/1892828461322162223) ，收获了诸多积极反馈。最近也收到些试图将 GraphRAG 和 DeepSearch 放在对立面混淆视听的信息。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/640-2.webp)

本文应朋友们建议整理而成，将分享 NebulaGraph 团队在 GraphRAG 领域的探索与实践历程，涵盖自 2023 年 6 月以来在 **GraphRAG** 基础研究上的进展，以及对**高级 RAG** 和 **Fusion GraphRAG** 的理解与实践。


# ******▌********二、RAG 与 GraphRAG 的缘起**



## RAG：检索增强生成


过去两年来，生成式 AI 和大语言模型的飞速发展堪称人类技术史上的重要里程碑。它们赋予计算机前所未有的上下文学习和推理能力，使得许多专属人类的复杂任务得以自动化甚至超越。然而，如何高效利用这些模型完成具体任务，成为技术落地的关键。

**RAG（Retrieval Augmented Generation，检索增强生成）作为一种基础范式应运而生。其核心在于通过“检索”（Retrieval）增强“生成”（Generation）：**

* 生成：将任务描述和领域知识（即提示词）输入大语言模型，生成相应的回答。

* 检索增强：利用检索技术为模型提供高度相关的上下文知识，从而提升生成质量。

在 RAG 中，检索环节至关重要。根据应用场景的不同，RAG 可分为两类：

* 面向公共检索系统：如 Google 或学术搜索引擎，依赖大模型调用外部 API，适用于通用知识获取。市面上的代表性产品包括 Perplexity Search 和 DeepSeek。
* 面向私有领域知识：如企业内部的研发文档或研究报告，需结合智能文档处理（IDP）、知识索引（Index）和知识管理系统。此类场景对检索技术的精准性和深度提出了更高要求。


###  朴素的 RAG

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/1.gif)


对于非结构化或半结构化知识，朴素 RAG 的典型流程包括：

* 将文档分割成块（Chunk）。

* 通过向量化嵌入（Embedding）构建语义索引，或结合 BM25 全文索引实现检索。

* 在任务执行时，基于任务需求直接检索或通过检索重写（如 HyDE）优化结果。

然而，这种方法在知识组织上的局限性使其难以满足企业级需求，具体挑战将在下文详述。

### RAG 的挑战


朴素 RAG 在实际应用中面临以下难题：

* 大海捞针：分块假设知识分布均匀，但某些关键信息可能被稀释在无关内容中，导致召回失败。

* 穿针引线：线性分割破坏了知识间的关联，难以还原全局上下文。

* 宏观问题：基于分片和关键词的索引无法有效应对全局性问题，如“哪些话题最具创新性”。

* 文档理解不足：缺乏智能文档处理时，公式、表格等复杂信息无法被正确解析和索引，影响回答质量。



# 高级 RAG



做好 RAG 并非一蹴而就，而是一个持续探索的过程。本质上，我们需要将对应用特点、RAG 技术特性以及知识本身的深刻理解，融入到 RAG 流水线的设计之中。

下图展示了一个近期发布的高级 RAG 总结性工作的简化图例：一个高级 RAG

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/2.webp)


**可见，在现代高级的 RAG 方法中，数据持久化层包含 "Graph DB"（即图数据库，一种以图结构——“节点”和“边”为中心的数据库），而图数据库也正是本文主题 GraphRAG 的重要基础设施。**

现代图数据库能够以高效、可扩展的方式驱动多租户、超大数据规模、高并发场景下复杂关联关系（图数据）的持久化、查询、访问和计算。它是高级 RAG 系统、智能体记忆系统（Agent Memory）的重要骨干基础设施，如下图所示。面向关联关系的图状结构，与我们梳理知识的脑图、甚至大脑中的神经元结构都非常相似。这种并非偶然的结构相似性，正是高级 RAG 知识索引解决朴素 RAG 方法挑战的关键。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/3.gif)


常见的高级 RAG 方法，在特别的索引结构上，包括树状索引（Tree-RAG）、分层检索（Raptor）和图状索引（GraphRAG），其中 GraphRAG 是我们文章的重点。


## ****高级 RAG****


**GraphRAG 这个方法最初是我们在 2023 年 8、9 月份开始，在 LlamaIndex 社区上持续做的一些工作和两次公开的 Webinar 上提出，并给出了开源的实现和可复现的效果比较试验。（** **[Graph RAG: 知识图谱结合 LLM 的检索增强](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247508410&idx=1&sn=a0432b3bbeac4e60a43c320f88201e81&scene=21#wechat_redirect)）**

在最初的 GraphRAG 参考实践中，我们给出了索引期基于大模型的同构图谱抽取的实现和查询区基于实体、关系语义的捞取与可配置的子图查询的知识召回，并比较了基于 Text-to-Query 方法的一些效果比较与结合方案的实现。现在，为了区隔之后 Graph-based RAG 方法的演进，我们把最初的 GraphRAG 叫做 **SubGraph RAG** 。

在当时的 VLDB workshop 上([VLDB 2024｜NebulaGraph RAG 正式官宣](https://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247511923&idx=1&sn=4d9a9b80cf528212b64ef96ec6a62fad&scene=21#wechat_redirect))，我们分享过的两个观点是

* 在与知识打交道的过程中，只用分片处理的方法、绕过 Graph（Knowledge Graph）一定是不够的，这也是我们做 GraphRAG 探索的初衷

* 这个 GraphRAG 的方法仅仅是一个开始，我们在不断探索更多在 Graph 之上的探索、推理的策略

随后，我们和 Researcher: Diego 一起讨论，**做了图索引之上 Chain of Exploration 的工作** ，并在 PyCon China 2024 上第一次给出了做了 Chain of Exploration 的分享。

之后，我们看到了非常多的 GraphRAG 相关工作被发表，比如 MIT 材料科学的两篇 利用我们的工作的 MechGPT、海马体 RAG 利用 pagerank 权重的工作 HippoRAG、LinkedIn 的利用 半结构化数据图建模的 RAG工作都非常有启发性。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/4.webp)


当然，最让我们兴奋的工作是微软的 GraphRAG: From Local to Global 工作，**他** **们充分探索了基于大模型抽取的知识图谱索引之上利用社区发现算法得到分级聚集结构下的全局性摘要**，这些摘要是没有偏见的保有原始知识中天然聚集性质、重要性质的脉络知识，在回答带有宏观全局性的问题中效果非常好。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/5.webp)


我们从这些后续的工作中受益匪浅，在与我们的客户 Graph based RAG 落地工作中，不断打磨、探索、累积了很多各个环节的优化、方法、策略。

最终形成了我们称为 **Fusion GraphRAG** 的方案。


# ******▌********三、Fusion GraphRAG**


Fusion GraphRAG 是我们团队在 GraphRAG 基础上的创新实践。它融合了高级 RAG 技术，通过图状结构存储文档层级、章节关系及特殊元素（如公式、表格），实现高效、灵活的检索。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/6.gif)


**Fusion GraphRAG 的本质在于 Sota 的高级 RAG 方法融合、充分连接的元知识索引、充分打磨调优的 GraphRAG**（可选索引）。

* Fusion GraphRAG 通过在一个联通图谱内的“元知识”索引，清晰地揭示海量知识文档的内在关联，呈现从文件夹、文档、章节到段落、图表、公式的完整脉络，此为知识图谱的“元知识频谱”。

* 在此基础上，用户可选择不同粒度的知识抽取方法（非必须），构建图谱结构的图索引，形成“增强图频谱”。

* 进一步，用户可以对图索引和元知识层进行诸如图摘要、权重分配、时序/状语信息补充等增强操作，以提升知识检索和利用的效率。


# *▌*四、Fusion GraphRAG 实现私域 Deep Research


**Fusion GraphRAG 融合了先进的 IDP 技术与 RAG 索引方法，并将提取的多模态知识有机地关联为图状结构，从而精确映射真实世界知识的内在逻辑。** 依托高性能、支持图语义与向量检索的现代图数据库作为持久化底层，Fusion GraphRAG 能在这一统一图谱上实现面向元知识层次与图谱增强的高级检索。

例如：

* 多层级知识检索：通过我们提出的 “Chain of Exploration” 检索器——一个能自主在图谱中探索并查找任务相关知识的智能 Agent，Fusion GraphRAG 可以在同时包含文件夹、文件层级以及章节（附摘要）结构信息的图谱上，既完成传统基于 Chunk 的检索任务，又能支持基于分层结构实现的脑图式 RAG 检索。（注：此方法不依赖昂贵的图谱抽取技术，后续将探讨如何进一步降低抽取成本。）
* 全局与局部深度分析：通过引入图抽取与图社区摘要等增强手段，“Chain of Exploration” 能够在图谱上按需执行全局搜索以解决宏观问题，同时进行针对多个知识点的精准局部检索，甚至对涉及复杂关联的深度问题（如关键知识间路径查找）进行分析。

* 多 Agent 协同：利用 Fusion GraphRAG 构建多 Agent 系统，可以将一整套算法与行为准则封装为一个专用的 Fusion GraphRAG Agent，此 Agent 可作为另一 RAG Agent 的召回计划生成器，在少而精的专业知识（know-how）构建的 Fusion Graph Index 指引下，自动规划出基于海量知识库的复杂查询方案。这为构建私有领域的自主学习 Deep Research/Action Agent 提供了有力支撑。

* 私有知识库内的深度研究：在 Fusion GraphRAG 之上，我们可以轻松实现针对私有知识库的 Deep Researcher。依托天然的知识连接与索引，再结合针对 “Chain of Exploration” Agent 的优化提示工程，以及类似 DeepSeek R1 的推理模型，就能实现类似 Deep Researcher 的 RAG 召回效果，为深度研究提供强大动力。


# ******▌********五、回到 GraphRAG 的时间线**


在我们的视角下，GraphRAG 正在不断演进，下面简要梳理这一发展历程：

* GraphRAG - 2023-08NebulaGraph 在 LlamaIndex 社区首次提出并实现了基本的 GraphRAG 模型。

* GraphRAG with Community Summary - 2024-04微软在论文中提出了基于社区发现算法实现全局摘要的 GraphRAG 方法，为图谱检索提供了新的思路。

* Fusion GraphRAG

  * 融合了文档层级、章节层级、以及文中各类特殊元素（如公式、表格、图表）的多频谱混合图状索引；

  * 支持可选的知识抽取与知识增强（包括社区摘要、时序增强等），构建混合层级结构查询、全局图召回、知识频谱图谱召回以及（可选） Chain of Exploration 检索；

  * 同时支持将公共知识图谱、现有知识图谱以及图状数据中的 Chain of Exploration 召回方法进行融合。

### **图抽取**

需要指出的是，在大模型时代，对原始知识进行类似知识图谱的抽取并非 Fusion GraphRAG 的必选项，因为并非所有 RAG 任务都需要细粒度的“知识预习”。图抽取的代价较高，目前多数公开方案成本也不低。

> 注：LazyGraphRAG 的相关工作同样值得关注，它提供了另一种优化思路。

> 附：Fusion GraphRAG 的索引及增强流程示意图

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/7.webp)


### **让图抽取成为默认策略**

高质量的 GraphRAG 索引虽然效果显著，但成本昂贵。我们的终极目标是让图抽取的成本降低到与 Embedding 类似的水平，实现大规模普及。

实际上，AI 技术社区（包括我们自身）已经在朝这一方向不断努力：利用 NER 模型、更小型（例如 Phi 系列）的 LLM 进行 SFT、小规模 LLM 的 few shot 方案、尽可能的可编程方法，甚至融合 NER 与 LLM 的多种方案，都是当前探索的方向。最近，我们也看到了一些令人振奋的曙光！

本质上，我们探索的基于 LLM 的抽取方法都采用了不同形式的 CoT（思维链）策略。近期，DeepSeek-MATH 论文中首次提出的 GRPO 方法在 DeepSeek R0 中用于冷启动获取 Think-aloud（思考过程）的深度 CoT 能力表现非常出色。同时，我们注意到基于 Qwen2.5（小尺寸 0.5b 模型）进行 GRPO 训练，在需要强推理能力的任务（例如数学问题）上，通过大约 200 步训练就能获得令人满意的效果。

结合这些观察，我们开展了如下探索：
* 数据收集与预处理：利用 DeepSeek R1，在挑选的最新原始知识数据（晚于模型 cut-off date）的基础上进行抽取任务，并开启 `<think>` 模式，收集高质量的 CoT 与图抽取的 Ground Truth，筛选掉质量不合格或思考过程过长的样本，作为训练数据。

* 奖励机制设计：基于开源社区中针对数学问题推理训练的 GRPO 奖励函数，我们设计了奖励高质量推理过程和高质量抽取结果的奖励函数。这两项奖励均依托高质量、低成本的指令大模型进行评估打分。

在一块 A100 显卡上经过约 200 步训练后，我们初步评估结果显示：基于 Qwen2.5-3b 的小尺寸抽取模型在引入 GRPO 训练后，其性能已经超越了 GPT-4o-mini。以下是各模型的对比结果：

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/8.webp)


正如当初推出首个 GraphRAG 开源实现时一样，这项工作仅仅是个起点。它证明了图抽取技术成本正在不断降低，未来我们有望大胆应用于更多场景，实现大规模的知识 GraphRAG。与此同时，这个方法也为特定领域范式数据抽取质量的提升提供了经济可行的方案。

> 训练数据、合成过程以及训练流程均已开源https://github.com/wey-gu/grpo-graph-extraction

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/9.webp)


### **RAG 应用落地的挑战**

众所周知，**RAG 更多的是一种技术和功能，而非一个完整的产品** 。在企业级应用中，产品形态本身所面临的挑战，往往远超技术或原理上的难题。

举个例子，Excel 电子表格软件凭借其公式计算和数据可视化功能，为会计和企业数据处理领域带来了颠覆性的变革。理论上，只需学习 Excel 中的各类公式和图表功能，就能获得大量实战经验，成为专业的数据分析师。但实际上，我们观察到，大多数企业员工仅仅熟悉 Excel 的基本操作，而许多昂贵且高级的 SaaS 产品，其功能实际上也不过是 Excel 部分能力的延伸。

如果基于 RAG 能力构建的企业产品，只是一个具备强大应用编排和知识库索引能力的“无代码”平台，那么这样的平台很可能只能在企业内部的少部分用户或团队中落地。大部分宝贵的领域知识仍停留在个人或小圈子中，无法以智能高效的方式被全面激活和利用。

为了解决这一问题，我们基于 FusionGraphRAG 与 Agentic RAG 技术，打造了一个全新的高级知识库与低门槛应用平台 —— NebulaGraph AI 应用平台（内部命名为 “Catalyst”，即催化剂）。该平台的核心设计理念包括：

* 无需构建复杂 Workflow：用户不需要自行搭建工作流。
* 无需编写繁琐 Prompt：用户无需学习复杂的指令语法。
* 简化知识定义：用户只需将对私有知识的理解转化为对不同“知识篮子”的定义。
* 智能对话交互：用户通过与我们的“元智能体”交流，传达解决问题的方法。

这种设计大幅降低了使用门槛，使得企业内部的知识能够被更高效、更智能地激活与应用，真正实现“插上翅膀”的飞跃。

### **AI 应用平台**

在这个平台中，企业用户可以将成百上千个文档轻松归入各自的知识“篮子”，并为每个篮子选择适合的“预学习”——即索引模式：
![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/10.webp)


**知识探索**用户可以随时在各个知识篮子中进行探索，快速定位所需信息，直观理解知识集合内的知识分布、深浅、特种。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/11.webp)


**智能应用生成**用户无需亲手编写复杂的 prompt，只需通过对话的方式与平台互动，即可生成各种类型的智能应用、迭代沉淀应用的 prompt。例如：

* 平台内置了生成智能体应用的“元智能体”，让对话即成为开发工具。

* “帮我构建一个投研报告生成助手”

* “我要做一个 xx 申报助手”

* “基于我所有的周报知识，构建一个 yy 领域回答助手，我想放到钉钉签名上，免得别人来烦我关于 yy 的问题” ……

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/12.webp)


**问答搜索应用**平台支持构建问答型搜索应用，帮助用户快速获得精确答案。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/3.4/13.webp)


**知识溯源**同时，针对问答应用，基于连接的知识溯源，追踪答案的来源，确保信息透明可靠。


# ******▌********六、总结**


GraphRAG 的发展代表了 RAG 技术从基础检索向高级知识管理的演进。通过解决传统 RAG 在知识稀释、关联丢失和宏观问题上的挑战，GraphRAG 为企业级应用提供了更高效、灵活的解决方案。我们团队开发的 **Fusion GraphRAG 融合了智能文档处理（IDP）、多层次知识索引和图状结构，将知识的内在关联映射到检索过程中，显著提升了复杂任务的处理能力。**

在实践中，我们通过优化图抽取成本（R1 知识蒸馏、 GRPO 方法、 Qwen2.5-3B 规模上的工作，并开源出来。），让 GraphRAG 技术更具经济可行性，使其能够广泛应用于企业知识管理和智能应用平台。

未来，我们相信 GraphRAG 将成为高级 RAG 和智能体记忆（Agent Memory）的核心基础设施，推动深层研究和智能决策的进一步发展。NebulaGraph AI 应用平台的推出，正是这一愿景的初步实现。

最后，对于 GraphRAG，这是 Sherman 和我们 NebulaGraph GenAI team 每一位同学共同相信的观点：

* **狭义的 “GraphRAG”、甚至 “SubGraph RAG”，在特定场景仍然有优势，我们可以按需应用这个技术组合**

* **Deep Research, Deep Search 的形态与 Graph-based RAG 方法，尤其是 Fusion GraphRAG 可以形成很好的互补**

* **Graph Infra 是高级 RAG/Agent Memory 中不可绕过的结构与方法（Graph is inevitable in Advanced RAG），是以向量为基础的 RAG 的重要演进与互补。**



分享 NebulaGraph 团队在 GraphRAG 领域的探索与实践历程，涵盖自 2023 年 6 月以来在 **GraphRAG** 基础研究上的进展，以及对高级 RAG 和 Fusion GraphRAG  的理解与实践。

GraphRAG vs DeepSearch？GraphRAG 提出者给你答案

# ****▌一、前言****

本文主要介绍了如何将 **MCP**（Model Context Protocol，模型上下文协议）工具转换为可以直接使用的 **LlamaIndex** 工具，使 **LlamaIndex** 用户能像使用 **Claude**, **Cursor** 等现代 AI 应用一样无缝集成这些服务。

![图片](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/%E5%B0%81%E9%9D%A2.png)

# ****▌二、技术背景****


## ****2.1 什么是 MCP 协议 ？****


**MCP**（模型上下文协议，[https://modelcontextprotocol.io](https://modelcontextprotocol.io)）是面向 AI 应用交互的服务构建协议。开发者可通过该协议构建具备数据资源（resources）、功能工具（tools）和提示模板（prompts）的服务端点。例如，我们可以定义获取 IP 详细信息的 `fetch_ipinfo` 工具：

```
@mcp.tool()
async def fetch_ipinfo(ip: str | None = None, **kwargs) -> IPDetails:
    """获取指定IP的详细信息
    
    参数:
        ip(str or None): 目标 IP 地址，格式如 192.168.1.1
        **kwargs: 传递给 IPInfo 处理器的附加参数
    
    返回:
        IPDetails: 包含城市、时区等信息的结构化数据
    """
    handler = ipinfo.getHandler(
        access_token=os.environ.get("IPINFO_API_TOKEN"),
        headers={"user-agent": "basic-mcp-server"},
        **kwargs,
    )
    details = handler.getDetails(ip_address=ip)
    return IPDetails(**details.all)
```


## ****2.2 **LlamaIndex 框架特征******


LlamaIndex（[https://github.com/run-llama/llama_index）是构建知识索引系统的核心框架，](https://github.com/run-llama/llama_index%EF%BC%89%E6%98%AF%E6%9E%84%E5%BB%BA%E7%9F%A5%E8%AF%86%E7%B4%A2%E5%BC%95%E7%B3%BB%E7%BB%9F%E7%9A%84%E6%A0%B8%E5%BF%83%E6%A1%86%E6%9E%B6%EF%BC%8C)**其核心价值在于将外部信息结构化地接入大语言模型，实现高效的信息检索、智能问答和对话生成**。当需要集成动态数据源时，将 MCP 工具转换为 LlamaIndex 工具成为关键技术需求。

在 **LlamaIndex** 中，**NebulaGraph** 已经有两种方法实现 **GraphRAG**：

`KnowledgeGraphIndex` 用来对任何私有数据从零构建知识图谱（基于 LLM 或者其他语言模型），再 4 行代码进行 Graph RAG：

```
graph_store = NebulaGraphStore(
    space_name=space_name,
    edge_types=edge_types,
    rel_prop_names=rel_prop_names,
    tags=tags,
)
storage_context = StorageContext.from_defaults(graph_store=graph_store)
# Build KG
kg_index = KnowledgeGraphIndex.from_documents(
    documents,
    storage_context=storage_context,
    max_triplets_per_chunk=10,
    space_name=space_name,
    edge_types=edge_types,
    rel_prop_names=rel_prop_names,
    tags=tags,
)
kg_query_engine = kg_index.as_query_engine()

```

 
`KnowledgeGraphRAGQueryEngine` 则可以在任何已经存在的知识图谱上进行 GraphRAG:

```
graph_store = NebulaGraphStore(
    space_name=space_name,
    edge_types=edge_types,
    rel_prop_names=rel_prop_names,
    tags=tags,
)
storage_context = StorageContext.from_defaults(graph_store=graph_store)
graph_rag_query_engine = KnowledgeGraphRAGQueryEngine(
    storage_context=storage_context,
)
```


# ▌三、为什么需要将 MCP 集成至 LlamaIndex


在实际 AI 应用开发中，集成 MCP 工具主要解决以下需求：

-   **功能复用**：利用现有 MCP 生态（项目列表见https://github.com/AlexMili/Awesome-MCP）快速扩展系统能力
    
-   **流程统一**：建立标准化工具调用范式，简化大模型对外部 API 的调用复杂度
    
-   **自动化管理**：通过自动转换机制实现 MCP 工具到 `LlamaIndex FunctionTool` 对象的映射，便于 Agent 自动调度
    

该集成方案可以有效降低开发成本，同时发挥 LlamaIndex 在上下文管理和对话生成方面的优势。

# ****▌四、技术实现方案****

实现流程包含三个关键阶段：

-   **MCP 服务通信**：通过 MCPClient 类建立服务连接，支持工具发现（list\_tools）和调用执行（call\_tool）
    
-   **适配器构建**：定义 MCPToolAdapter 类，将 MCP 工具元数据转换为 LlamaIndex 的 FunctionTool 对象
    
-   **智能代理集成**：在 LlamaIndex Agent 中加载转换后的工具，实现自动化调用
    

# ********▌五、核心代码解析********

**协议转换适配器**

```
from llama_index.core.tools import FunctionTool
from pydantic import create_model, BaseModel

class MCPToolAdapter:
    def __init__(self, client):
        self.client = client

    async def list_tools(self):
        tools = await self.client.list_tools()
        return [
            FunctionTool.from_defaults(
                fn=self._create_tool_fn(tool.name),
                name=tool.name,
                description=tool.description,
                fn_schema=self._create_pydantic_model(tool.schema),
            ) for tool in tools
        ]
    
    def _create_pydantic_model(self, json_schema):
        # 实现JSON Schema到Pydantic模型的动态转换
        ...
```


**类型系统映射**

```
JSON_TYPE_MAPPING = {
    "string": str,
    "number": float,
    "integer": int,
    "boolean": bool,
    "object": dict,
    "array": list
}

def create_dynamic_model(schema):
    fields = {}
    for name, prop in schema["properties"].items():
        py_type = JSON_TYPE_MAPPING[prop["type"]]
        if name in schema.get("required", []):
            fields[name] = (py_type, Field(...))
        else:
            fields[name] = (Optional[py_type], Field(None))
    return create_model("DynamicModel", **fields)
```


**服务调用封装**

```
   async def fetch_ipinfo_wrapper(**kwargs):
    return await mcp_client.call_tool("fetch_ipinfo", kwargs)
```


**关键技术创新点**

-   **动态模式转换**：实现 JSON Schema 到 Pydantic 模型的运行时转换，保证参数校验的严格性
    
-   **异步调用管道**：基于 Python asyncio 构建非阻塞式服务调用，提升工具执行效率
    
-   **协议抽象层**：通过适配器模式解耦 MCP 协议与 LlamaIndex 框架，保证系统扩展性
    

> 将 MCP 工具的输入参数转换为 Pydantic 模型的原因在于：MCP 工具使用 JSON Schema 格式定义输入参数（在工具对象的 `inputSchema` 中，类型为 `Dict[str, Any]` ），而 `create_model_from_json_schema` 函数将其转换为 Pydantic 模型，该模型用作 LlamaIndex 中 FunctionTool 的 `fn_schema`。

# ******▌六、**LlamaIndex 中的 MCP 工具********

********调用实践********

以下代码来自 `llamaindex_mcp_example.py`，完整展示了 MCPToolAdapter 与 LlamaIndex 的集成方式：


```
import os
from llama_index.core.llms import ChatMessage
from llama_index.core.agent import ReActAgent, ReActChatFormatter
from llama_index.core.agent.react.prompts import REACT_CHAT_SYSTEM_HEADER
from llama_index.llms.azure_openai import AzureOpenAI

from llamaindex_mcp_adapter import MCPToolAdapter
from mcp_client import MCPClient
import anyio
import dotenv
import argparse

dotenv.load_dotenv()

# 系统级指令模板
SYSTEM_PROMPT = """\
您是一个智能法律助手

在回答用户问题前，必须通过IP信息确认用户所在司法管辖区
操作规则：
- 当涉及地理位置、时区等问题时，自动调用fetch_ipinfo工具
- 法律咨询类问题需结合IP所在国家/地区法律体系
"""

async def get_agent(adapter: MCPToolAdapter):
    """智能代理初始化函数"""
    tools = await adapter.list_tools()  # 获取MCP工具列表
    
    # 配置Azure OpenAI大语言模型
    llm = AzureOpenAI(
        model=os.environ.get("AZURE_OPENAI_MODEL", "gpt-4"),
        max_tokens=int(os.environ.get("AZURE_OPENAI_MAX_TOKENS", 4096)),
        azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
        api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
        api_version=os.environ.get("AZURE_OPENAI_API_VERSION"),
        engine=os.environ.get("AZURE_OPENAI_ENGINE")
    )
    
    # 构建ReAct智能代理
    agent = ReActAgent.from_tools(
        llm=llm,
        tools=list(tools),
        react_chat_formatter=ReActChatFormatter(
            system_header=SYSTEM_PROMPT + "\n" + REACT_CHAT_SYSTEM_HEADER,
        ),
        max_iterations=20,  # 限制最大推理步数
        verbose=True        # 启用详细日志
    )
    return agent

async def handle_user_message(message_content: str, agent: ReActAgent):
    """消息处理流水线"""
    user_message = ChatMessage.from_str(role="user", content=message_content)
    response = await agent.achat(message=user_message.content)
    print(f"[智能代理响应] {response.response}")

if __name__ == "__main__":
    async def main():
        # 命令行参数解析
        parser = argparse.ArgumentParser()
        parser.add_argument("--client_type", 
                          choices=["sse", "stdio"], 
                          default="stdio",
                          help="连接模式：sse(Server-Sent Events)或stdio(标准输入输出)")
        args = parser.parse_args()

        # MCP客户端初始化
        if args.client_type == "sse":
            client = MCPClient("http://0.0.0.0:8000/sse")  # SSE长连接模式
        else:
            client = MCPClient(                            # 子进程模式
                "./venv/bin/python", 
                ["mcp_server.py", "--server_type", "stdio"]
            )
        
        # 工具适配器初始化
        adapter = MCPToolAdapter(client)
        agent = await get_agent(adapter)

        # 执行测试用例
        await handle_user_message("我的IP所在城市是哪里？", agent)
        await handle_user_message("持有大麻在我国是否合法？", agent)

    anyio.run(main)  # 启动异步运行时
```


**关键实现解析**

-   工具获取机制：
    
-   通过 `adapter.list_tools()` 动态加载 MCP 服务端注册的工具列表
    
-   自动将每个 MCP 工具转换为 LlamaIndex 的 `FunctionTool` 对象
    
-   智能代理配置：
    
-   使用 Azure OpenAI 作为底层大语言模型引擎
    
-   集成 `ReAct` 推理框架，支持多步工具调用
    
-   设置 20 步的最大推理深度防止无限循环
    
-   消息处理流程：
    
-   将用户输入封装为标准化 ChatMessage
    
-   通过 `agent.achat()` 触发自动化工具调用链
    

# ******▌七、运行 Demo******


## ****7.1 标准输入输出模式****



```
python llamaindex_mcp_example.py --client_type stdio
```

执行输出示例

[DEBUG] 检测到ListToolsRequest协议请求
[工具调用] 步骤ID: ede14770-91c9-428b... | 输入: 我的IP所在城市是哪里？
[推理日志] 当前用户语言：中文，需调用工具获取数据
[动作触发] fetch_ipinfo | 参数: {}
[网络请求] 调用MCP工具耗时128ms
[观察结果] {"ip": "183.193.123.192", "city": "上海", "country": "CN"...}
[最终响应] 您的IP所在城市为上海

[法律咨询] 步骤ID: e728f5d0-6c0e-454a... | 输入: 持有大麻是否合法？
[推理日志] 已确认用户所在国家：中国
[知识库检索] 加载中国刑法第357条
[最终响应] 根据中国法律，持有大麻属违法行为，最高可判处有期徒刑


## ****7.2 SSE 服务模式****



```
# 终端1：启动SSE服务端
python mcp_server.py --server_type sse

# 终端2：运行客户端
python llamaindex_mcp_example.py --client_type sse
```


# ****▌八、技术方案总结****

通过以下三步实现深度集成：

**协议通信层**：

-   基于 `MCPClient` 实现服务发现与工具调用
    
-   支持 SSE/STDIO 双模连接，适应不同部署场景
    

**类型转换层**：

-   动态将 JSON Schema 转换为 Pydantic 模型
    
-   实现参数自动校验与类型提示
    


```
def create_dynamic_model(schema):
    # 自动生成带字段描述的Pydantic模型
    fields = {
        name: (map_type(prop), Field(..., description=prop["description"]))
        for name, prop in schema["properties"].items()
    }
    return create_model("DynamicModel", **fields)
```

**智能代理层**：

-   集成 ReAct 推理框架实现自动化工具调度
    
-   通过系统提示词约束工具使用规范
    


```
SYSTEM_PROMPT = """\
法律咨询必须遵循以下规则：
1. 首次响应前必须调用fetch_ipinfo确认用户辖区
2. 引用法律条文需标注具体条款编号
3. 不得对未覆盖地区提供法律建议"""
```


通过持续扩展 MCP 生态，开发者可快速构建具备专业领域能力的智能代理系统。欢迎访问 MCP 开发者社区获取更多工具资源。

查看源代码：[https://github.com/psiace/psiace/tree/main/demo/llamaindex-mcp-adapter](https://github.com/psiace/psiace/tree/main/demo/llamaindex-mcp-adapter)



本文主要介绍了如何将 MCP（Model Context Protocol，模型上下文协议）工具转换为可以直接使用的 LlamaIndex 工具，使 LlamaIndex 用户能像使用 Claude, Cursor 等现代 AI 应用一样无缝集成这些服务。

首发完整版教程，MCP 集成至 LlamaIndex 的技术实践


# ****一、前言****


“**东风夜放花千树，更吹落，星如雨**” —— 南宋词人辛弃疾笔下描绘的元宵盛景，穿越 800 年时空依然让我们心驰神往。这个起源于汉代太一神祭祀的古老节日，在历史长河中不断焕发新生：东汉时期与佛教燃灯习俗融合，唐代发展为全民狂欢的"上元节"，宋代市井中诞生猜灯谜等民俗...元宵节作为中华民族历史悠久、内涵丰富的重要传统节日，其意义早已超越了“节日”的单一范畴，而成为家庭团圆、祈福迎祥的象征。

![图片](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/%E5%85%83%E5%AE%B5%E8%8A%82/%E5%85%83%E5%AE%B5%E8%8A%82/4a5759cb1a25147e9fbef14c84254206.png)

在漫长的历史演进中不断融合和创新，形成了历史、传说、民俗、美食、诗词等多重文化。这些文化要素构成了一幅多层次、跨领域、互联互通的文化全景图。我们如何用现代科技来传承和弘扬这一古老节日的文化内涵？本文将带你走进元宵节的文化世界，通过 **NebulaGraph** 和 **DeepSeek** 构建直观易懂的**元宵节知识图谱**。


# ****二、元宵节的多重文化维度****


在构建元宵知识图谱之前，我们必须对元宵节文化进行系统性拆解，将其内涵细分为多个独立但又相互关联的知识域。从知识图谱建模的角度来看，每一个知识域都可以视为一个节点类别（Tag），而这些类别之间的关系则由边（Edge）来表示。下面我们详细介绍元宵节的四大文化维度。


```
-- 插入类别节点
INSERT VERTEX `Category` (name) VALUES "元宵节传说";
INSERT VERTEX `Category` (name) VALUES "关于元宵的诗";
INSERT VERTEX `Category` (name) VALUES "民俗活动";
INSERT VERTEX `Category` (name) VALUES "美食文化";
```



## **2.1 历史传说**


元宵节中流传着大量的传说和民间故事，这些传说不仅为节日增添了神秘色彩，同时也反映了古人对自然、神祇以及命运的理解。在图谱建模时，每一个传说故事都可以构建为一个节点，其属性包括传说名称、来源文献、相关朝代和地域。通过定义“传说关联”边，将不同传说故事与历史传承、民俗活动相互链接，形成完整的文化脉络。




```
# 历史传说（含时空维度）
CREATE TAG `HistoricalLegend` (
    name string NOT NULL,          # 传说名称
    era string,                    # 所属朝代
    region string DEFAULT "中国",  # 地域分布
    description string,            # 详细描述
    source string                  # 文献来源
) COMMENT = "历史传说实体";

```




## **2.2 民俗风情**


元宵节作为民间传统节日，其民俗活动丰富多彩，涵盖了赏花灯、猜灯谜、踩高跷、扭秧歌等多个方面。每一种民俗活动都深深植根于地方文化，并具有鲜明的地域特色。在知识图谱中，民俗活动作为一个独立的知识领域，其节点属性包括活动名称、起始年份、流行指数、地域分布及文化意义等，通过“民俗关联”边将其与历史、传说等领域关联起来。


```
# 民俗活动（带时空特征）
CREATE TAG `FolkActivity` (
    name string NOT NULL,          # 活动名称
    start_year int,                # 起始年份
    popularity double,             # 流行度指数
    spatial_scope string,          # 地域分布
    cultural_significance string   # 文化意义
) COMMENT = "民俗活动实体";

```


## **2.3 美食文化**


元宵节的美食是传统节日中不可或缺的一部分，每种食品都蕴含着独特的文化象征意义：

-   元宵/汤圆：象征团圆与和谐，寓意家庭和睦、生活甜蜜。
    
-   年糕：寓意年年高升、步步高升，是对美好未来的期盼。
    

在知识图谱中，美食文化节点需包含食品名称、热量、原料成分（以字符串形式存储多个原料）、及象征意义等属性。通过“美食关联”边，可以将美食与民俗活动、历史传承等关联起来，形成完整的文化生态链。


```
# 美食文化（含营养成分）
CREATE TAG `FoodCulture` (
    name string NOT NULL,          # 食物名称
    calories double,               # 热量(kcal)
    ingredients string,      # 原料成分
    symbolic_meaning string        # 象征意义
) COMMENT = "美食文化实体";
```



## **2.4 诗词雅韵**


元宵节在文人墨客笔下同样是一座灵感的宝库。历代文人以元宵为题，创作了大量优美诗词，这些诗词不仅反映了当时的社会风貌，更承载了深厚的情感与审美：经典作品：如辛弃疾的《青玉案·元夕》、欧阳修的《生查子·元夕》等，均成为千古绝唱。在知识图谱中，诗词作品节点包括标题、作者、创作朝代、韵律模式、情感分析值和完整内容等，通过“诗词关联”边将诗词与民俗活动、历史传承、传说故事等多维信息建立联系。


```
# 诗词作品（带文学特征）
CREATE TAG `Poetry` (
    title string NOT NULL,         # 诗词标题
    author string,                 # 作者
    dynasty string,                # 创作朝代
    rhyme_scheme string,           # 押韵模式
    sentiment_analysis double,     # 情感分析值
    content string                 # 完整内容
) COMMENT = "诗词作品实体";
```



# ****三、NebulaGraph + DeepSeek****


****构建元宵节知识图谱****


## **3.1 数据建模**


在构建元宵知识图谱过程中，我们首先需要对各个文化维度进行数据建模。基于前文介绍的四大维度，我们已经将数据分为以下四大节点类别：

HistoricalLegend（历史传说）属性：名称、朝代、地域、描述、文献来源。

FolkActivity（民俗活动）属性：活动名称、起始年份、流行指数、地域分布、文化意义。

FoodCulture（美食文化）属性：食品名称、热量、原料成分（字符串存储）、象征意义。

Poetry（诗词作品）属性：标题、作者、朝代、韵律模式、情感分析值、完整内容。

接下来，我们需要定义边类型来表达不同领域之间的关联：


```
# 定义多维关联边类型
# ================================================
# 时空关联边（带权重）
CREATE EDGE `HistoricalContinuity` (
    start_year int,                # 起始年份
    end_year int,                  # 终止年份
    influence_factor double        # 影响力系数
) COMMENT = "历史延续性关联";

# 文化传播边（带地理编码）
CREATE EDGE `CulturalDiffusion` (
    from_region string,            # 发源地
    to_region string,              # 传播地
    diffusion_path string          # 传播路径
) COMMENT = "文化传播路径";

# 语义关联边（带置信度）
CREATE EDGE `SemanticLink` (
    relation_type string,          # 关系类型
    confidence double,             # 置信度
    source string                  # 知识来源
) COMMENT = "语义关系关联";

# 创建边类型：RelatedTo
CREATE EDGE RelatedTo (
    description string,  # 关系描述
) COMMENT = "历史传说与民俗活动之间的关联关系";

# 创建边类型：AssociatedWith
CREATE EDGE AssociatedWith (
    description string,  # 关系描述
) COMMENT = "民俗活动与美食文化之间的关联关系";

# 创建边类型：WrittenFor
CREATE EDGE WrittenFor (
    description string,  # 关系描述
) COMMENT = "民俗活动与诗词作品之间的关联关系";
```


经过数轮和 DeepSeek 的沟通，得到了以下数据：

![图片](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/%E5%85%83%E5%AE%B5%E8%8A%82/%E5%85%83%E5%AE%B5%E8%8A%82/1.png)

## **3.2 通过 DeepSeek 做元宵节文化知识抽取**


在构建元宵知识图谱过程中，需要大量非结构化的元宵节文化文本转换为结构化数据，再通过图谱表达各实体与关系。以下介绍如何利用 DeepSeek 对元宵节文化文本进行知识抽取，并将抽取结果以 nGQL 语句导入 NebulaGraph。这里给出两种方法：



### 方法一：直接与 DeepSeek 对话



构建提问策略 根据元宵节文化知识的需求，设计几个关键问题，例如：

-   “元宵节的起源和历史背景是什么？”
    
-   “元宵节有哪些传统民俗活动？”
    
-   “元宵节的代表美食有哪些？它们分别象征什么？”
    
-   “请解析《青玉案·元夕》中描绘的元宵盛景。”
    

通过 DeepSeek 的在线接口或对话系统，直接输入上述问题。DeepSeek 会返回结构化或半结构化的回答，其中可能包含实体及其属性、关系等信息。例如，返回的数据可能类似于：

实体：元宵节 属性：起源 → “汉代祭祀太一神”、历史记载 → “《史记》记载…”

实体：赏花灯 属性：地域 → “华北,江南”、文化意义 → “象征光明与希望”

实体：元宵 属性：美食寓意 → “象征团圆与美满”

实体：青玉案·元夕 属性：作者 → “辛弃疾”、朝代 → “宋代”

同时，还会返回诸如：

("元宵节", "hasTradition", "赏花灯")

("元宵节", "hasFood", "元宵")

("赏花灯", "describedIn", "青玉案·元夕")

根据 DeepSeek 返回的结构化知识，我们整理出各个节点及关系，然后生成 nGQL 语句。例如：


```
# 建立元宵节与赏花灯的关联（例如，历史传承到民俗活动） 
INSERT EDGE RelatedTo (description) VALUES "HL001" -> "FA001":("元宵节催生了赏花灯这一民俗活动"); 
# 建立赏花灯与元宵之间的关联（民俗活动与美食文化） 
INSERT EDGE AssociatedWith (description) VALUES "FA001" -> "FC001":("赏花灯与元宵相辅相成，共同构成节日风貌"); 
# 建立赏花灯与诗词作品之间的关联 INSERT EDGE WrittenFor (description) VALUES "FA001" -> "P001":("《青玉案·元夕》描绘了赏花灯的盛景");

```




### 方法二：本地部署 DeepSeek


对于大规模数据或需要对抽取过程进行精细控制的场景(事实是总是遇到“服务器繁忙，请稍后再试”)，可以选择在本地部署 DeepSeek。此方法适合批量处理、自动化知识库构建，步骤如下：

本机部署 DeepSeek-R1

i、下载安装 Ollama；

ii、运行：ollama run deepseek-r1；

iii、下载安装 ChatBox；

iV、在ChatBox 的设置中选择 "OllamaAPI" 并选择 DeepSeek-R1 模型

准备元宵节相关的海量语料，如历史文献、民间故事、网络文章、诗词资料等，并进行文本格式化处理。

文本预处理对语料进行清洗、分词,将预处理后的文本组织成适合 DeepSeek 模型输入的格式。

批量知识抽取运行本地部署的 DeepSeek 模型，对处理后的文本数据进行批量推理。模型会自动识别出文本中的关键实体、属性及其之间的关系，并生成结构化输出。

输出数据示例（JSON 格式）：


```
{
  "entity": "元宵节",
  "attributes": {
    "起源": "汉代祭祀",
    "传统": "赏花灯,猜灯谜",
    "美食": "元宵,汤圆",
    "诗词": "青玉案·元夕"
  },
  "relations": [
    {
      "subject": "元宵节",
      "predicate": "hasOrigin",
      "object": "汉代"
    },
    {
      "subject": "元宵节",
      "predicate": "hasTradition",
      "object": "赏花灯"
    },
    {
      "subject": "元宵节",
      "predicate": "hasFood",
      "object": "元宵"
    },
    {
      "subject": "赏花灯",
      "predicate": "describedIn",
      "object": "青玉案·元夕"
    }
  ]
}
```

数据转换与 nGQL 导入，如：


```
# 插入美食文化节点：元宵 
INSERT VERTEX FoodCulture(name, calories, ingredients, symbolic_meaning) VALUES "FC001":("元宵", 450, "糯米,芝麻,白糖", "象征团圆与美满");

# 插入诗词作品节点：青玉案·元夕 
INSERT VERTEX Poetry(title, author, dynasty, rhyme_scheme, sentiment_analysis, content) VALUES "P001":("青玉案·元夕", "辛弃疾", "宋代", "xyz", 0.85, "东风夜放花千树，更吹落、星如雨..."); 

```

持续更新与调优根据实际抽取效果，不断优化 DeepSeek 模型参数和抽取策略，提升实体和关系的准确性。


## **3.3 数据导入与知识图谱构建**


将 DeepSeek 提取的数据导入到 NebulaGraph 中，可以使用以下 nGQL：


```
# 1. 插入历史传说数据
INSERT VERTEX `HistoricalLegend` (
    name, era, region, description, source
) VALUES
"HL001":("元宵节起源", "汉代", "中国", 
    "源于汉代祭祀太一神的活动，《史记·乐书》记载：'汉家常以正月上辛祠太一甘泉'", 
    "《史记》"),
"HL002":("燃灯习俗起源", "东汉", "洛阳",
    "东汉明帝时期佛教传入，敕令正月十五燃灯表佛，《僧史略》载：'西域十二月三十日...汉明帝令烧灯，表佛法大明也'",
    "《洛阳伽蓝记》"),
"HL003":("舞龙舞狮起源", "唐代", "中原",
    "舞龙舞狮起源于唐代，最初是宫廷表演，后流传至民间，象征驱邪避灾、吉祥如意",
    "《唐书》"),
"HL004":("踩高跷起源", "北宋", "北方",
    "踩高跷起源于北宋时期，最初是民间表演艺术，后成为元宵节常见活动",
    "《宋史》"),
"HL005":("扭秧歌起源", "明代", "北方",
    "扭秧歌起源于明代，最初是农民庆祝丰收的舞蹈，后成为元宵节传统活动",
    "《明史》");
# ================================================

# 2. 插入民俗活动数据
INSERT VERTEX `FolkActivity` (
    name, start_year, popularity, spatial_scope, cultural_significance
) VALUES
"FA001":("赏花灯", 180, 0.95, ARRAY["华北","江南"], "象征光明与希望，促进社区凝聚力"),
"FA002":("猜灯谜", 960, 0.88, ARRAY["全国"], "智力活动与传统文化的结合体现"),
"FA003":("舞龙舞狮", 618, 0.92, ARRAY["中原","华南"], "寓意驱邪避灾、吉祥如意"),
"FA004":("踩高跷", 1046, 0.85, ARRAY["北方"], "传统表演艺术，增加节日欢乐气氛"),
"FA005":("扭秧歌", 1368, 0.90, ARRAY["北方"], "传统舞蹈，表达喜庆和丰收的喜悦");
# ================================================

# 3. 插入美食文化数据
INSERT VERTEX FoodCulture(name, calories, ingredients, symbolic_meaning)
VALUES
    "FC001":("元宵", 450, "糯米,芝麻,白糖", "象征团圆与美满"),
    "FC002":("汤圆", 350, "糯米,红豆,椰蓉", "寓意家庭和睦、生活甜蜜"),
    "FC003":("年糕", 320, "糯米,红枣,花生", "象征年年高升，生活步步高"),
    "FC004":("炸元宵", 500, "糯米,豆沙,植物油", "外酥里嫩，寓意生活红火"),
    "FC005":("饺子", 280, "面粉,猪肉,白菜", "象征团圆和财富");
# ================================================

# 4. 插入诗词作品数据
INSERT VERTEX `Poetry` (
    title, author, dynasty, rhyme_scheme, sentiment_analysis, content
) VALUES
"P001":("青玉案·元夕", "辛弃疾", "宋代", "xyz", 0.85, "东风夜放花千树，更吹落、星如雨。宝马雕车香满路。凤箫声动，玉壶光转，一夜鱼龙舞。蛾儿雪柳黄金缕，笑语盈盈暗香去。众里寻他千百度，蓦然回首，那人却在、灯火阑珊处。"),
"P002":("生查子·元夕", "欧阳修", "宋代", "abd", 0.78, "去年元夜时，花市灯如昼。月上柳梢头，人约黄昏后。今年元夜时，月与灯依旧。不见去年人，泪湿春衫袖。"),
"P003":("正月十五夜", "苏味道", "唐代", "abc", 0.80, "火树银花合，星桥铁锁开。暗尘随马去，明月逐人来。游伎皆秾李，行歌尽落梅。金吾不禁夜，玉漏莫相催。"),
"P004":("十五夜观灯", "卢照邻", "唐代", "aabb", 0.82, "锦里开芳宴，兰缸艳早年。缛彩遥分地，繁光远缀天。接汉疑星落，依楼似月悬。别有千金笑，来映九枝前。"),
"P005":("元夕无月", "丘逢甲", "清代", "aabb", 0.75, "三年此夕月无光，明月多应在故乡。欲向海天寻月去，五更飞梦渡鲲洋。"),
"P006":("京都元夕", "元好问", "金代", "aabb", 0.80, "袨服华妆着处逢，六街灯火闹儿童。长衫我亦何为者，也在游人笑语中。"),
"P007":("鹧鸪天·元夕有所梦", "姜夔", "宋代", "aabb", 0.78, "肥水东流无尽期，当初不合种相思。梦中未比丹青见，暗里忽惊山鸟啼。春未绿，鬓先丝，人间别久不成悲。谁教岁岁红莲夜，两处沉吟各自知。"),
"P008":("清平乐·上元月蚀", "纳兰性德", "清代", "aabb", 0.85, "瑶华映阙，烘散蓂墀雪。比拟寻常清景别，第一团圆时节。影蛾忽泛初弦，分辉借与宫莲。七宝修成合璧，重轮岁岁中天。"),
"P009":("元夕二首", "王守仁", "明代", "aabb", 0.75, "故园今夕是元宵，独向蛮村坐寂寥。赖有遗经堪作伴，喜无车马过相邀。"),
"P010":("元夕影永冰灯", "唐顺之", "明代", "aabb", 0.80, "正怜火树千春妍，忽见清辉映月阑。出海鲛珠犹带水，满堂罗袖欲生寒。烛花不碍空中影，晕气疑从月里看。为语东风暂相借，来宵还得尽余欢。");

```


![图片](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/%E5%85%83%E5%AE%B5%E8%8A%82/%E5%85%83%E5%AE%B5%E8%8A%82/2.png)

在建立关联关系和创建索引后，执行到数据库中，让我们看看效果～

![图片](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/%E5%85%83%E5%AE%B5%E8%8A%82/%E5%85%83%E5%AE%B5%E8%8A%82/3.png)

![图片](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/%E5%85%83%E5%AE%B5%E8%8A%82/%E5%85%83%E5%AE%B5%E8%8A%82/4.png)

环形关系图彩蛋 🎉
祝大家元宵节团团圆圆



本文将带你走进元宵节的文化世界，通过 NebulaGraph 和 DeepSeek 构建直观易懂的元宵节知识图谱