
> 作者周伟诚，来自携程风控研发团队，专注于风控系统及特征平台领域。 2021年开始深入探索图数据，并在风控场景下进行多次落地实践，取得了显著的业务增益。



**一、前言**

携程作为在线旅游代理（OTA）行业中的一家头部企业，处理着海量的在线实时交易订单。然而，随着订单数量的增加，潜在的欺诈风险也随之上升。为了更有效地识别团伙欺诈和黑产攻击，同时确保实时风控系统的高响应性，携程风控研发团队对多个图数据库进行了调研和试用，**最终选择了 NebulaGraph 数据库，并成功将其投入线上使用，从而实现业务增益 32%。**

**二、业务需求**

在某些业务场景中，风控系统需要对业务事件进行补充，以丰富其风险画像，从而更有效地识别风险和防范欺诈。

然而，常规技术手段，在识别新客的业务行为时存在一定的局限性。主要原因在于，新客的历史数据较少 ，其业务风险的背景信息往往不够完善，这增加了欺诈的可能性。统计数据显示，相较于存量用户的业务行为，新客业务行为的欺诈风险高达数倍。为应对这一挑战，携程风控团队**提出了利用图数据库构建实时动态图的设想，以丰富新客业务行为的风险画像，从而提高欺诈识别率。**

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

一笔新客的业务行为通常包含多个维度的信息 ，如下图中的U，V，W 这 3 种元素。通过这些相同的元素 ，我们可以关联出一阶邻居和二阶邻居。如下图的例子所示，通过相同的元素 V1 可以关联出当前业务事件的一阶邻居，再通过相同的元素 U3 可以关联到二阶邻居的 W2。这样，我们可以从新客业务的单一信息中关联出其多阶邻居，并综合这些关联信息，更好地识别该业务行为的风险。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/a20455a89e48ac53d5b43b26bdb1a288.png)

基于上述业务模型，我们将每个元素构建为一个节点，并使用该节点的维度作为其标签（tag）。节点的唯一标识符（vid）设置为具体的元素值。为了便于追溯，点上添加了该元素所属的业务事件号和请求时间。对于同一个业务事件中的元素，我们会创建边将这些代表元素的节点关联起来，表示它们之间存在关联关系。

在当前的业务场景中，还有个需求是保持一年内的实时关联图，对于超过一年时间的数据，将不再参与图的关联。因此，我们利用了 NebulaGraph 图数据库的一个特性，即它允许为时间戳类型的属性设置有效期（TTL）。根据业务要求，我们为所有节点的请求时间设置了一年的 TTL。一年之后，这些节点将自动过期，不再参与实时图的关联。这样可以确保当前订单的关联数据仅限于一年内的时间窗口。

**三、查询逻辑**

在实际的构建关联过程中，我们遇到了两个问题。第一个问题是查询存在热点问题。如下图所示，例如从 U1 元素开始，它关联查询到 N 个 W 元素的节点，然后每个 W 元素又各自关联到 N 个 V 元素。这样会导致关联查询的数量急剧膨胀，甚至可能导致超时和服务器宕机。

对于这样的热点问题，我们需要加以排除，因为其数据价值不高，并且会因为查询超时而降低整体的关联率，进而影响风险识别的最终结果。

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

第二个问题是，如下图所示。当某笔业务事件刚进入风控系统时，由于图数据的写入是通过消息队列推送的方式进行的，可能会出现以下情况：当该业务事件中包含的 3 个元素（U1、W1、V1）尚未被写入图数据库时，系统就要求查询 U1 的关联信息。这时，系统无法查询到 V2 和 U2 的信息。

为了解决这个问题，我们提出了一个解决方案，即将单个关联改为群组关联 。这样，即使这些元素尚未被关联写入图数据库，也能在同一笔业务事件中查找到这些元素的二阶关联邻居。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/60398af42cd61b7eadccf35690a2ce49.png)

**四、解决方案**

以下是我们的解决方案。

首先，对于第一个热点问题，我们会根据节点的标签类型（tag）查询其关联节点。如果某类关联数据（例如 U 关联 W）超过了规定的阈值，我们将其舍弃，以确保实时风控的高响应速度。
如下图所示，如果 U1 查询到的 W 元素数量超过了规定的阈值 X，我们将这些 W 节点剔除，不再参与下一阶的关联过程。然后，我们将符合要求的一阶关联结果节点进行合并和去重，作为二阶关联的起始点。接下来，使用同样的策略查询二阶邻居，最后进行数据的整理和合并。这样可以用较小的代价剔除热点干扰。

针对上一节提到的第二个问题，即同一订单中的多个元素因关联写入延迟导致无法查询的情况，我们也提出了解决方案。具体而言，我们将同一订单中的多个元素（如 U1、W1、V1）作为一个整体，并行查询它们的关联邻居，然后将各自的结果去重合并，最终返回综合结果。此方案在下图中有所体现。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/66accb5eac613c7c9fefa29ed72bb359.jpeg)

在上图所示的流程中，我们使用了一个关键的 nGQL 查询语句，如下图所示。该语句的作用是从一组起始点开始，根据它们的关联点的标签（tag）类别进行关联查询。对于超过热点阈值的某类关联数据，我们会进行过滤和剔除。
例如，在下图的例子中，起始点关联到的 W 元素数量已经超过了热点阈值，形成了一个热点，符合剔除过滤的条件。因此，W 元素将返回一个空列表，表示不再参与下一阶的关联查询过程，从而避免了热点对风控系统性能的影响。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/c6a6ce954729c5709f6c6c09ec2f9e08.jpeg)

**五、业务收益**

我们借助 NebulaGraph 在对此风控业务场景进行落地实践的过程中，构建了一个实时图特征平台的应用逻辑闭环，结构如下图所示。
当一笔业务行为事件进入风控系统时，会同时异步写入到图特征平台和大数据平台。 风控系统在对当笔事件进行风险评估时，会实时调用图特征平台进行关联信息的补充，从而提高资质评估的准确性。
大数据平台则会定期对图特征平台进行补数操作，确保图库数据的完整性和一致性。 同时提升图特征平台的健壮性，可以在较短时间内快速恢复缺失的数据。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/daf8483f25533c38066849c5a3763fe2.png)

业务上线后，我们**额外获取了 55% 的关联业务信息**，通过这些新增的特征信息，使得**该场景下的覆盖率相对提升了32%** ，获得了良好的业务增益。

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/37c11c8145d64cb79382663c6b8e17aa.png)

**六、未来规划**

图数据库是一个新兴的技术领域，因其天然的关联属性和查询优势，十分适合于风控场景，尤其是挖掘业务行为特征。携程集团在调研了多个图库之后，选定 NebulaGraph 作为主流支持的图数据库。

携程风控研发团队目前正在积极挖掘 NebulaGraph 的使用场景，后续会探索在血缘关系，欺诈团伙识别等场景的落地实践。

在此特别感谢 NebulaGraph 团队和开源社区的技术赋能，愿未来一路同行！

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/d7346a0594b23ad55764e1e5c1de8faf.jpeg)
















携程使用 NebulaGraph 实现业务增益 32%

携程 x NebulaGraph｜业务增益 32%，NebulaGraph 在携程风控场景下的落地实践

**一、简介**

NebulaGraph 是一款开源的、分布式的、易扩展的原生图数据库，能够承载包含数千亿个点和数万亿条边的超大规模数据集，并且提供毫秒级查询。

图数据库在许多业务场景中扮演着重要角色，得益于其独特的数据模型和高效的查询性能。以下是一些常见的图数据库业务应用场景：

-   知识图谱：企业和组织需要从各种数据孤岛中构建领域知识图谱，支持智能问答和语义搜索。
    
-   社交网络分析：社交网络平台需要分析用户之间的关系、兴趣、互动等信息，以提供个性化推荐、广告定向投放。
    
-   金融风控：金融机构需要监测异常交易活动、识别潜在的欺诈行为、评估信用风险。
    
-   推荐系统：电子商务、媒体平台需要根据用户的浏览历史、购买记录等信息，提供个性化的商品或内容推荐。
    

NebulaGraph Cloud 是为 NebulaGraph 设计的全托管云服务，**本文将结合亚马逊云科技的产品，详细介绍如何实现降本增效。**


**二、NebulaGraph Cloud**

**平台架构**

![image|561x499](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/9da20f7acfd239dc38ee3ecc5f3bd1be4ceac701_2_561x499.jpeg)

NebulaGraph Cloud 基于 K8S 设计和构建 ，背后有以下因素：

-   K8S 的 Opertor 模式使得集群内部发生的一切可以被自动化，降低开发成本。
    
-   K8S 提供了一系列抽象能力，用于简化计算、存储和网络资源的管理，可以帮助用户避险厂商锁定，做到 100% Cloud agnostic。
    
-   K8S 内置的扩缩容、调度框架、资源监控、服务发现等能力，可以将各种管理操作变的更容易。
    

**服务组件**

NebulaGraph Cloud 由两部分构成：

**控制平面（Control Plane）**

提供用户控制台访问，包括组织管理、用户权限控制、数据库管理、网络安全设置、监控、告警等功能，帮助用户管理他们的 NebulaGraph 集群。

**数据平面（Data Plane）**

接收控制平面下发的指令，包括资源调度、配置、版本更新、水平扩缩容、规格调整、备份和恢复、可观测性、计量等功能。

**成本优化设计**

以数据库的配置示例来说明：


```
apiVersion: apps.nebula-cloud.io/v1alpha1
kind: Database
metadata:
  name: db123456
  namespace: db123456
spec:
  provider: aws
  region: "us-east-2"
  k8sRef:
     name: "k8s-ml65nmjg"
     namespace: "k8s-ml65nmjg"
  tier: standard
  graphInstanceType: NG.C4.M32.D0
  graphNodes: 1
  StorageInstanceType: NG.C4.M32.D50
  StorageNodes: 1
  version: v3.8.2c
```


数据库实例使用 CRD Database 定义，它在数据平面的管理操作由控制器 database-controller 负责。

对于依赖的计算资源通过 CRD NodePool 定义，**NodePool 是对各个云厂商计算资源的抽象，在 Amazon EKS 中用于管理 NodeGroup。**

前文提到 NebulaGraph 是计算-存储分离的架构，所以一个数据库实例会对应两个 NodePool 对象。

```
# Graph 资源池
apiVersion: apps.nebula-cloud.io/v1alpha1
kind: NodePool
metadata:
  name: gnp-7d0b156e
  namespace: db123456
spec:
  databaseRef:
    name: db123456
    namespace: db123456
  instanceCount: 1
  instanceType: x
  k8sRef:
    name: k8s-ml65nmjg
    namespace: k8s-ml65nmjg
  labels:
    platform.nebula-cloud.io/database-name: db123456
    platform.nebula-cloud.io/graph-pool: db123456-f24a
  provider: aws
  region: us-east-2
  zoneIndex: 0
  
# Storage 资源池
apiVersion: apps.nebula-cloud.io/v1alpha1
kind: NodePool
metadata:
  name: snp-59e9cc63
  namespace: db123456
spec:
  databaseRef:
    name: db123456
    namespace: db123456
  instanceCount: 1
  instanceType: x
  k8sRef:
    name: k8s-ml65nmjg
    namespace: k8s-ml65nmjg
  labels:
    platform.nebula-cloud.io/database-name: db123456
    platform.nebula-cloud.io/Storage-pool: db123456-un6g
  provider: aws
  region: us-east-2
  zoneIndex: 0
```

**规格调整**

选择合适的实例规格对用户和服务商都是一个比预期更具挑战性的任务。用户通常不清楚他们需要多大的实例，例如，当用户的数据从100 GB 逐渐增长到 1 TB 时，他们可能不清楚这些数据在每个阶段需要多少 CPU 核心或多大内存。这就需要用户和 SA 共同努力来找出答案。

在使用全托管云服务时，我们提供实例规格调整功能，支持对 Query 节点或者 Storage 节点单独调整，以满足用户在成本控制和性能达标方面的需求。用户可以根据监控面板的历史曲线判断是否达到单节点处理瓶颈，同时云平台也会发出站内告警。

![image|690x225](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/f5f5f6a57a63973e531106af4a1391e834c63d09_2_690x225.png)


**水平扩缩容**

水平扩缩容支持对 Query 节点或者 Storage 节点单独调整。**Query 节点可视为无状态服务，在处理查询流量波动时可通过扩缩容来解决。**

Storage 节点负责存储图数据并提供读写能力，每个 Storage 节点上都分布一定数量的数据分片。每次进行扩缩容都会涉及数据迁移及数据分片再均衡，因此需要谨慎操作。

节点扩容前需要准备相应的计算资源，控制器 database-controller 会将当前期望的节点数下发给 infra-controller 触发 Amazon EKS 的 NodeGroup 扩容，这里我们**没有启用 CA 或者 Karpenter 有以下原因：**

-   扩缩容决策依赖于特定的集群条件和资源请求，如果这些条件没有得到满足，它可能不会执行预期的扩缩容操作。
    
-   跨可用区场景下无法保证指定区域的扩缩容。
    
-   基于 Pending Pod 的模式跟我们的业务系统无法紧密集成。
    
![image|690x216](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/753847db27e05d64ab3f647df0523610bdbbb87c_2_690x216.png)


**自动弹性伸缩**

通过自动扩容/缩容支持不同的工作负载是我们的一个重要目标。由于计算和存储是分离的，我们可以根据每个服务节点的利用率来增加或减少 CPU 和内存资源。

弹性伸缩服务架构如下：

![image|690x278](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/c8ff42ffa7adc0f30c46e9d1618dd8a09d92748b_2_690x278.jpeg)


每隔 10 分钟，弹性伸缩服务就会根据监控数据的历史和当前值计算数据库实例应分配的资源量，最终确定是否应增加或缩减计算资源。

**它可以驱动水平扩缩容和垂直扩缩容（调整实例规格），确保业务高峰时能提前弹出来。** 我们在此基础上将继续不断改进，通过纳入更多指标和主动预测策略来缩短扩缩容的时间。

**三、效率提升设计**

**网络安全访问**

![image|690x228](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/b49d9f8193e3bde0f05041a65507764da8955fea_2_690x228.png)


**目前我们为用户提供两种网络连接方式：网络白名单和 Privatelink 私网连接。**

为了确保网络安全并简化配置步骤，我们在数据库实例与网络负载均衡（NLB）之间引入了代理服务 ngproxy，充分利用了 NLB 提供的功能。NLB 支持在通过的每个报文上设置 PPv2 header，ngproxy通过解析报文可以知晓用户端的 endpoint ID 与在控制台设置的 ID 是否一致，不匹配则会拒绝请求。同样的原理也适用于公网访问的白名单，只有当源地址与白名单中的地址匹配时，才会被允许通过。

**备份和恢复**

**数据备份是防止数据丢失的第一道防线。** 无论是因为硬件故障、软件错误、数据损坏还是人为操作失误，备份都可以确保数据的安全。

我们为用户提供手动备份和定时备份两种方式，将备份数据上传到亚马逊云科技的对象存储Amazon S3。我们没有采用基于云存储快照的备份恢复方案，因为基于 SST 的备份恢复速度比云存储快照更快，而且不需要依赖云厂商的基础服务。需要注意的是，在进行数据备份时 DDL 和 DML 语句将会被阻塞，因此建议在业务低峰期执行备份操作。

备份数据目录结构：

```
backup_root_url/
- BACKUP_2024_08_20_16_31_43
├── BACKUP_2024_08_20_16_31_43.meta
├── data
│   └── 10.0.0.12:9779
│       └── data0
│           └── 5
│               ├── data
│               │   ├── 000009.sst
│               │   ├── 000011.sst
│               │   ├── 000013.sst
│               │   ├── CURRENT
│               │   ├── MANIFEST-000004
│               │   └── OPTIONS-000007
│               └── wal
│                   ├── 1
│                   │   ├── 0000000000000000001.wal
│                   │   └── 0000000000000000005.wal
.....
│                   ├── 30
│                   │   ├── 0000000000000000001.wal
│                   │   ├── 0000000000000000004.wal
│                   │   └── 0000000000000000005.wal
└── meta
    ├── __disk_parts__.sst
    ├── __edges__.sst
    ├── __id__.sst
    ├── __indexes__.sst
    ├── __index__.sst
    ├── __last_update_time__.sst
    ├── __local_id__.sst
    ├── __parts__.sst
    ├── __roles__.sst
    ├── __spaces__.sst
    └── __tags__.sst
- BACKUP_2024_08_20_19_02_35
```

恢复数据时采用恢复至新实例的方案，这样可以充分利用云上资源弹性扩展的优势，在指定某个时间点的备份集后快速拉起一个新的数据库实例，用户在验证新的数据库实例工作正常后可以释放掉旧实例。

**高可用性**

针对那些对服务可靠性要求极高的用户，我们提供了跨可用区容灾解决方案。

在 NebulaGraph 中 Zone 是服务节点的集合，它将多个 Storage 节点划分成可管理的逻辑区域，实现资源隔离。同时，平台服务会控制 Query 节点访问指定的 Zone 内的副本数据，从而降低跨可用区通信产生的网络延时与流量成本。

管理有状态服务跨可用区的一个主要挑战是存储卷的区域亲和性问题。为了解决这个问题，我们采取了在每个可用区放置一个 NodeGroup 的方法。这样一来，就可以避免新扩容的 Node 可能被错误地安排在不正确的可用区中，从而导致 Pod 无法被调度的情况发生。

根据过往用户案例中的经验，我们还支持在某个可用区单独扩容的方案。云原生社区类似 HPA 的方案，只解决了扩容后的数量问题，但是无法扩容到指定区域。根据每个区域承载的业务流量进行扩展，可以有效地提高服务质量。如果某个区域观察到 QPS 突然激增，数据平面的弹性伸缩服务将允许在此区域缩放 Query 节点。

![image|690x309](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/ead9f0ff2d6e68afb9a05dbdc2ec418e60590178_2_690x309.png)


**四、云上实战**

在开通订阅后开始创建数据库，接下来演示访问数据库的几种方式：

**可视化工具**

从 Database 列表选中某个实例，进入 Data->Graph 图空间管理，点击 Explorer Graph 进入可视化应用。

![image|690x198](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/ce7ed2c9cfab7106e383bd3424e40c8237588324_2_690x198.png)


点击右上角的 Console 打开控制台便可以执行 GQL 语句的查询。

![image|690x359](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/b097fa13dfc3ad0490e89138ee5c00e68c4d585f_2_690x359.png)


**网络白名单**

在数据库实例的 Overview 页面点击 Connect，选中 Public 方式。

![image|644x499](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/90dc038f3a3e9714718599fc876fdfead128eb83_2_644x499.jpeg)


在没有配置网络白名单时，数据库实例无法直接从公网访问。

```
$ ./nebula-console -addr nebula-graph-ncqqo19eh0aus73e4un6g.aws.cloud.nebula-graph.io -port 9669 -u dbaas-test@vesoft.com -p $PASSWORD -enable_ssl

Welcome!

(dbaas-test@vesoft.com@nebula) [(none)]> show spaces;
+------------------------+
| Name                   |
+------------------------+
| "genshin"              |
| "hanxiaotest"          |
| "movie_recommendation" |
| "nba"                  |
+------------------------+
Got 4 rows (time spent 602µs/222.883326ms)

Mon, 02 Sep 2024 16:52:39 CST
```


**Privatelink 私网连接**

按照 Create Private Link Endpoint 的配置步骤，确定业务所在的 VPC ID 和 Subnet ID。

运行命令创建 Endpoint：
```
aws ec2 create-vpc-endpoint --vpc-id <YOUR-VPC-ID>  --region us-east-2 --service-name com.amazonaws.vpce.us-east-2.vpce-svc-04f25889c855f891b --vpc-endpoint-type Interface --subnet-ids  <YOUR-SUBNET-IDs>
```

登录亚马逊云科技控制台查看 Endpoint 状态：

![image|690x212](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/1fe27de7e96f4deb53862da71dbcbbe02a8f6afb_2_690x212.png)


在业务 VPC 内测试访问是否正常。

![image|690x146](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/cb5260250eb6c4b416f9578ffa1d4106d5be1291_2_690x146.png)


接下来大家可以按照自己的业务需求通过官方生态工具在云上进行数据维护。

**五、总结与展望**

本文介绍了基于云原生理念在亚马逊云科技上的服务落地 NebulaGraph 全托管云服务的架构细节，**着重阐述如何通过亚马逊云科技的产品为用户带来实质利益，为用户在云端使用 NebulaGraph 提供兼具成本和弹性优势的全新解决方案。**

在确保服务质量的同时，我们将继续探索各种可能性，降低用户成本并提高易用度。我们的目标是让用户只需为其使用的资源付费，将成本概念贯彻到每一个细节中。

**目前 NebulaGraph Cloud Beta 版本试用活动正在火热进行中，** 每月最高消费控制在1美元以内，大家可以通过以[下链接注册账号](ttps://aws.amazon.com/marketplace/pp/prodview-wctboqxrwqkjy?sr=0-1&ref_=beagle&applicationId=AWSMPContessa) 或[直接访问注册账号](https://cloud.nebula-graph.io)。

欢迎对 **NebulaGraph Cloud** 感兴趣的小伙伴添加小助手 NebulaGraphbot(wechat) 解锁更多 DBaaS 相关内容。

只要1$ 解锁 NebulaGraph on AWS，通通1$

全托管 NebulaGraph 试用活动进行中！解锁成本优化与效率提升的实践指南

![image|690x387, 100%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/d709b2dd5b59dc1282c210a4a72a956bb2f72b9c.jpeg)


> **听说没人能拒绝一根棍子、一只猴子？**
> 
> **NebulaGraph 送《黑神话：悟空》啦！**

历时 6 年，承载着全球玩家的期待，《黑神话：悟空》已正式上线发售。它早已超越游戏本身，成为一段文化之旅，一次情怀共鸣，一场从儿时就开始做的英雄梦。

正如悟空在混沌世界中披荆斩棘、闯荡四方，每一个使用 NebulaGraph 的你，都是数据世界中的天命人，勇敢探索未知，发现隐藏的价值，追寻数据的英雄梦。无论是在复杂的社交网络分析中揭示隐藏的关系，还是让数据价值最大化，你的每一个使用案例都值得被分享和赞扬。

我们诚挚地邀请您参与 NebulaGraph 用户案例征文活动，畅谈您在实际应用中使用 NebulaGraph 的宝贵经验和成功案例。您的实践，不仅是我们版本迭代的动力，也是其他 NebulaGraph 用户打怪升级的通关攻略。



**【征文要求】**

-   主题：用户案例；
    
-   内容：文章结构完整、逻辑清晰、文字通顺，图文并茂；
    
-   结构：包括但不限于，公司及业务介绍、业务挑战与产品选型、NebulaGraph 的使用场景与解决方案、经验分享 or 踩坑总结；
    
-   发布：进入 NebulaGraph 论坛，在【文章】 分类下撰写文章并发布。
    

**【评奖方式】**

本次征文采用文章积分来评选得分 Top5，公式如下：‍‍

```
文章得分 = 浏览量 + 点赞（ ❤ ）数 x 2 + 评论数 x 5

```

（说明：公式优化了点赞权重过高的问题，提升了浏览量的优先级。即，你越早发文章，优势越突出）

**【征文奖品】**

Top5 皆可赢取《黑神话：悟空》标准版，此外，按名次排序，我们送出不同等级的社区周边礼包。

**【征文时间】**

即刻起至 9 月 30 日。


————————————————————————————————
**🎉我是小彩蛋**

我们欢迎新朋友加入 NebulaGraph 社区，如果您无法提供用户案例，但是《黑神话：悟空》忠实玩家，且对图数据库感兴趣，可以投稿「使用 NebulaGraph 分析《黑神话：悟空》」。

如通过 NebulaGraph 预测终极 boss、推荐最佳合作伙伴、可视化人物关系图谱、分析角色关系网络中隐藏任务触发的影响因素......我们将随机送出周边大礼包 n 份🐒

听说没人能拒绝一根棍子、一只猴子？
NebulaGraph 送《黑神话：悟空》啦！

来领《黑神话：悟空》！NebulaGraph 用户案例征集 ing

![image|690x352, 100%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/WechatIMG300.jpg)

**背景 💻**

8 月 17 日，NebulaGraph Meetup 厦门站以“图数据库+AI”为主题，汇聚行业专家与技术爱好者，共同探讨了 AI 的最新实践与 GraphRAG 的创新解决方案。厦门风光旖旎，相信现场小伙伴们亦满载而归。‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

![image|690x426, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(1).jpg)
![image|690x459, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(2).jpg)

未能到场的小伙伴们可查阅本次 nMeetup 精彩回顾及直播回放⬇️‍‍‍‍‍‍‍‍‍‍‍‍‍‍

「NebulaGraph GenAI Team @BeautyyuYanli 压轴，NebulaGraph RAG 受到不少社区朋友们关注，欢迎大家加入 NebulaGraph RAG 技术交流群，一同探索更多可能🌟」
![image|506x500, 50%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(3).jpg)


**Topic 回顾 ⏰**

**Part 1 聚焦 AI 的最新实践**。FastGPT 开发者 & 布道师王子俊深入介绍了 FastGPT 的高级编排功能，帮助大家如何构建高效的 AI 工作流；厦门巅峰科技有限公司技术负责人涂标松分享了 AI 助力客服中心录音质检的应用，为录音质检私有化部署提供了解决方案。  

![image|690x459, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(4).jpg)

![image|690x467, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(5).jpg)


**Part 2 聚焦 GQL**。NebulaGraph Committer 大叶老师 以 ISO-GQL 标准为引，分析了图数据库驱动程序现状，提倡建立统一的调用方式的标准；NebulaGraph 产品经理方扬 @MuYi ，对 ISO-GQL 作出深入解析，并介绍  GQL 在图数据库中的重要性。

![image|690x459, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(6).jpg)

![image|690x459, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(7).jpg)

大叶老师不仅是 NebulaGraph 的 Committer ，陪伴 NebulaGraph 走过多个版本的迭代，也积极承担了社区布道的重大责任。本次 nMeetup 选址大叶老师所在地——厦门，亦是我们与大叶老师的双向奔赴。借此机会，NebulaGraph 社区聘请其为「厦门城市站站长」，再次感谢大叶老师的支持～！

![image|666x500, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(8).jpg)


**Part 3 聚焦 GraphRAG**。厦门大学平潭研究院研究员杨知铮，以对话诗仙李白为例，分享了如何将 GraphRAG 引入传统文化教育，引发了现场小伙伴们的强烈共鸣和热烈讨论，纷纷表达对 GraphRAG 在传统文化教育中应用的期待。

NebulaGraph 研发 @BeautyyuYanli ，介绍了 NebulaGraph GenAI 团队在 GraphRAG 的探索与尝试。**（GraphRAG 由 NebulaGraph 和 LlamaIndex 共同推出，能够将知识图谱与大语言模型结合，为搜索引擎提供更全面的上下文理解，带来更智能的搜索结果。）**GraphRAG 推出后，NebulaGraph 构建了 GenAI Suite，帮助更多企业和开发者更加高效地探索与使用 GraphRAG。本次 nMeetup 还进行了 live demo，更加直观地让大家理解 NebulaGraph 的 GraphRAG 解决方案。‍‍‍‍

![image|690x459, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(9).jpg)

![image|690x459, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(10).jpg)

**社区结语 🎙️**  

本次 nMeetup 不仅是一次技术分享的盛会，也是一场开发者社区的聚会，相信每一位参与者都在这里有所收获，碰撞出思维的火花。未来，我们将会有更多的机会与大家见面交流，分享更多的技术心得和实战经验。期待在下一站 nMeetup 中，再次见到熟悉的面孔，结识更多新的朋友！

（留言猜猜我们下一站去哪儿？随机掉落精美周边😄）

![image|690x459, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(11).jpg)

![image|690x459, 75%](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/image%20(12).jpg)

**回放+PPT🔗**

回放地址：[https://www.bilibili.com/video/BV1X3WpeTEpx/?spm_id_from=333.999.0.0&vd_source=817871e38f2f5dbaed653bece6b00ecf](https://www.bilibili.com/video/BV1X3WpeTEpx/?spm_id_from=333.999.0.0&vd_source=817871e38f2f5dbaed653bece6b00ecf)

PPT 获取方式：关注「NebulaGraph技术社区」公众号，后台回复「厦门站」

8 月 17 日，NebulaGraph Meetup 厦门站以“图数据库+AI”为主题，汇聚行业专家与技术爱好者，共同探讨了 AI 的最新实践与 GraphRAG 的创新解决方案。厦门风光旖旎，相信现场小伙伴们亦满载而归。‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

【nMeetup 厦门站】活动精彩回顾（附ppt+回放）

各位社区小伙伴大家好，2024 年第一站 **nMeetup** 来啦！速速与我们面基😄

本次 nMeetup 由 **NebulaGraph**、**FastGPT**、**厦门创业中心**联合主办走进厦门，与社区各位小伙伴进行交流分享。本场活动将聚焦“**图数据库 + AI**”方向。

此次活动，我们邀请到了厦门大学平潭研究院研究员、DataWhale 开源社区作者杨知铮，厦门巅峰科技有限公司技术负责人、《Llama 大模型实践指南》作者之一涂标松，独立开发者、NgBatis 发起人、NebulaGraph Committer叶伟城，FastGPT maintainer、FastGPT 开发者布道师，B 站科技区万粉博主王子俊，NebulaGraph 产品总监方扬等专家和大咖，为社区的小伙伴们带来精彩的技术分享。

**活动免费！欢迎各位小伙伴报名参与！现在即可报名！**

## **🕙时间、地点**

-   时间：2024 年 8 月 17 日 13:30-17:00
    
-   地点：厦门市湖里区新丰路176-180号火炬荟智空间A区二楼路演厅
    

## **🧾议程**

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/C34B6759-1BDF-42D8-8A98-ECDDC4269C3B.png)


## **📮报名方式**

**扫描上方海报中的二维码即可报名，[或点击🔗链接直接报名](https://www.slidestalk.com/NebulaGraph/xiamen)**

## **🎁互动礼品**

线下参与本次活动，现场可获得 NebulaGraph 和 FastGPT 社区周边礼品一份。

各位社区小伙伴大家好，2024 年第一站 nMeetup 来啦！速速来面基😄

【nMeetup厦门站】图数据库 + AI 厦门站 Meetup 与你相约 8 月 17 日


自 2023 年 8 月 **NebulaGraph** 和 **LlamaIndex** 共同推出 [Graph RAG](http://mp.weixin.qq.com/s?__biz=Mzg4OTg0MzY0Mw==&mid=2247508410&idx=1&sn=a0432b3bbeac4e60a43c320f88201e81&chksm=cfe75b6ef890d278dedc9685b25459aa6bd7186ae06ea76f861f9c92964a4a0177cd1f818741&scene=21#wechat_redirect) 以来，凭借着 **LLM（大语言模型)**  和 **RAG（检索增强生成）** 的发展势头，在业界掀起了一场革命。通过本文，我们将向你介绍什么是 Graph RAG，为什么它具有革命性，以及如何构建你的Graph RAG，来利用数据的上下文与 NebulaGraph 回答复杂的多部分问题。

## 了解日益流行的 Graph RAG

Graph RAG 能够将知识图谱与大语言模型（LLM）结合使用，从而为搜索引擎提供更全面的上下文理解。由于其带来了更具成本效益、更智能且精确的搜索结果，这项技术已引起了广泛的关注。除了提供更准确的回答以建立用户信任外，Graph RAG 还克服了传统搜索增强技术的主要障碍：缺乏上下文理解和数据训练。因此，这些先进的检索增强技术有望扩展到各个行业，如医疗诊断辅助、内容创作和推荐、互动游戏以及知识图谱构建。

微软在由高级首席数据架构师 Jonathan Larson 和首席项目经理 Steven Truitt 撰写的博客文章《GraphRAG: Unlocking LLM Discovery on Narrative Private Data》中强调了 Graph RAG 的重要性。他们通过将 Graph RAG 与基线 RAG 系统进行对比，展示了 Graph RAG 的有效性，得出结论认为 Graph RAG 方法使LLM能够在图谱中找到支点，从而提供包含原始支持文本的更优答案。而基线 RAG 在处理需要跨数据集汇总信息以形成答案的查询时则显得力不从心。
**NebulaGraph 数据库已经集成了 LlamaIndex 和 LangChain 等大语言模型（LLM）框架** ；你只需专注于 LLM 编排逻辑和管道设计，无需担心复杂的实现。你可以通过简单的四个步骤进行试用，检查 Graph RAG 是否如传言般出色，然后再进一步将其集成到应用程序或其他场景中。

**注意：**

由于 LlamaIndex 的快速发展，最近的重构/重大变更导致一些 Graph RAG 教程无法运行。本文提供了更新后的 Graph RAG 教程，以便你可以无误地进行操作。

我们在上游发布之前已经探索了许多内部方法。我们相信 LlamaIndex 中Graph + RAG 的基本概念值得探索，因此我们将原始的工作坊和笔记本放在参考章节中。

**设置你的 NebulaGraph 集群**

* 通过 Google Colab 中的 NebulaGraph Lite 启动 NebulaGraph 集群
* 使用 Docker 扩展部署集群
* 实例化一个 NebulaGraphStore
## 使用 NebulaGrpah 构建你的 Graph RAG
~~~
import os
from llama_index.core import KnowledgeGraphIndex, SimpleDirectoryReader
from llama_index.core import StorageContext
from llama_index.graph_stores.nebula import NebulaGraphStore

os.environ["NEBULA_USER"] = "root"
os.environ["NEBULA_PASSWORD"] = "nebula"
os.environ["NEBULA_ADDRESS"] = "127.0.0.1:9669"


space_name = "paul_graham_essay"
edge_types, rel_prop_names = ["relationship"], ["relationship"]  # default, could be omit if create from an empty kg
tags = ["entity"]  # default, could be omit if create from an empty kg

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)
~~~
现在，随着你的 NebulaGraph 集群的设置，可以动手进行知识图谱构建部分。**请确保在 Jupyter 环境中运行以下所有步骤。**

**依赖关系**

Graph RAG 的实现需要以下依赖项：
~~~
pip install llama-index
pip install llama-index-llms-ollama
pip install llama-index-graph-stores-nebula
pip install ipython-ngql
pip install llama-index-embeddings-huggingface
~~~
**创建 LlamaIndex 知识图谱索引**

KnowledgeGraphIndex 可从非结构化文本中自动构建知识图谱，也可基于实体的查询。在创建图 RAG 查询引擎之前，你需要设置 LlamaIndex 知识图谱索引。在这个示例中，我们将演示如何通过创建文档对象来从文本数据构建知识图谱，然后再创建索引。
~~~
from llama_index.core import (
    VectorStoreIndex,
    SimpleDirectoryReader,
    KnowledgeGraphIndex,
)

graph_store.query("SHOW HOSTS")

Settings.chunk_size = 512

documents = SimpleDirectoryReader(
    "data"
).load_data()
~~~
~~~
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,
    max_knowledge_sequence=15,
)
~~~
### 创建一个朴素图 RAG 检索器

最后一步是创建 Graph RAG 检索器，在其基础上构建查询引擎，以便您可以使用自然语言问题进行查询。
~~~
from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.retrievers import KnowledgeGraphRAGRetriever

graph_rag_retriever = KnowledgeGraphRAGRetriever(
    storage_context=storage_context,
    verbose=True,
)

query_engine = RetrieverQueryEngine.from_args(
    graph_rag_retriever,
)
response = query_engine.query("What's the relationship between Bob and Alice")
~~~
现在，您已经尝试了 Graph RAG，如果您想进一步了解如何通过 GraphStore 和 VectorStore 进行检索，您可以在此处找到更多演示示例：https://www.siwei.io/tutors/GraphRAG/101.html。

[欢迎加入社区官方 Slack 群](https://join.slack.com/t/nebulagraph/shared_invite/zt-2h51ct4t0-IlXFaU01mpb3t2WgQ8qqNA)。

参考：

* https://bit.ly/graph-rag-workshop
* https://siwei.io/graph-enabled-llama-index/kg_and_vector_RAG.html
* https://siwei.io/demo-dumps/graph-rag/GraphRAG.html

通过本文，我们将向你介绍什么是 Graph RAG，为什么它具有革命性，以及如何构建你的Graph RAG，来利用数据的上下文与 NebulaGraph 回答复杂的多部分问题。

基于 NebulaGraph ，构建属于你的 Graph RAG 

![|](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/0715banner-05.jpg)
日前，金蝶征信泾渭云基于关系图谱技术和人工智能技术，推出产业图谱产品——“核企上下游名单查询”和“企业交易圈洞察”，将分别助力小微金融的获客营销和风控场景。
![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/jingweiyun0.jpg)
链上企业是一片待开发的蓝海。在真实的小微金融服务中，银行金融机构出于风险规避，偏好经营规模更大的企业。而最缺乏资金的尾部小微群体，作为中国经济的毛细血管，占比达企业总数 90%以上。

据新华信用《财税数据风控白皮书》调研分析显示，当一家企业与超过4家以上的大型企业存在稳定交易关系，其坏账率是普通客群的 51%；产业链上下游企业的平均风险比普通客群低 46%。

“我们在讨论小微金融服务时，常常会提及一个「不可能三角」理论，即同时实现「风险可控、成本可控、规模发展」三个目标。”产业图谱负责人表示，“**产业图谱有助于破解这个不可能三角。它就像一个雷达，通过关系链中的任意一家企业，可精准勾勒其产业链、关联核心企业以及其上下游企业画像，帮助银行金融机构从长尾小微群体中批量筛选优质企业、识别风险企业。**"

## 提供「核企上下游名单」查询，助力银行批量获取链上优质客户

从事产业链知识图谱研发，一方面要有大量企业授权交易数据积累，另一方面需要掌握较为扎实的算法技术。金蝶征信与百余家金融机构合作，累计服务数百万小微企业，基础大数据库已覆盖**全国 2 亿+工商司法数据库**、**4000 万+交易企业节点**，自研的“泾渭云”大数据征信云服务可以实现秒级响应千万量级计算。

在构建“产业+行业+企业”的知识图谱体系基础上，泾渭云引入**NebulaGraph** 分布式图数据库技术，提供多个产业链、行业分类和企业标签，通过对企业和上下游产业链关系紧密度的分析，批量筛选出符合银行小微金融业务要求的客户白名单，并为企业智能匹配银行供货贷、采购贷、订单贷等金融产品。据悉，“核企上下游名单”最高可识别与认定核心企业存在 6 层交易关系或股权关系的小微企业。以某商业银行为例，银行可识别到的与核心企业直接交易的优质小微企业，占到了白名单企业数的 10%

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

## 企业交易圈洞察，帮助透视隐藏的企业风险

管理学大师彼得·圣吉说：“所谓系统思考就是看见整体的修炼，看见相互关联而不是单一的事件，看见变化的形态。”在风控板块，产业图谱同样发挥着重要作用。

产业图谱的“企业交易圈洞察”服务，在获得查询企业的授权后，可根据该企业的发票购销交易关系及工商股权关联，构建企业网状产业知识图谱，评估企业之间交易的真实性、紧密性及连续性，包括关系企业是否有上市公司、企业本身是否存在失信等负面信息，构建更真实全面的小微信用画像，降低信贷投放风险。

近年来，国家提出梳理在产业链上发挥强链补链稳链作用的优质中小微企业，形成产业链图谱或链企名单，列出融资需求清单，倡导金融服务更多延伸到链上小微企业。

在普惠金融从“增量”迈向“提质”的新阶段，泾渭云推出的产业图谱系列产品，或许可为行业提供新的解题方向。目前，泾渭云针对不同业务需求为银行提供定制化解决方案。对于优质客户，提供提额方案，助力其实现更快速的发展；对于风险表现欠佳的客户，通过降额措施，帮助控制风险。

对图数据库 NebulaGraph 感兴趣？欢迎前往 **GitHub** ✨ 查看源码：**https://github.com/vesoft-inc/nebula**

泾渭云金蝶征信利用 NebulaGraph 技术，通过产业图谱助力银行挖掘企业关系链，实现批量获客和风控。

NebulaGraph 助力金蝶征信产业图谱深挖企业关系链，实现银行批量获客 

![图数据库和知识图谱](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-1.jpg)

图数据库和知识图谱是管理图结构数据（包括节点（实体）和边（关系））的两大主流方案。图数据库利用基于图的数据模型存储信息，支持通过专用的图查询语言实现对图数据的查询和遍历；知识图谱通过整合推理和派生新知识的机制，增强了图数据库的功能。这种增强的表达力不仅让你能进行更高级的数据分析，还能从图中相互连接的数据点中提取洞察力。

本文将简要介绍知识图谱，再探讨使用 llamaindex 和 NebulaGraph-lite 生成知识图谱。

## 知识图谱是什么

知识图谱是一种图形化的知识表示方法，它将相关联的概念、事物及其关系描绘成一个网络。它涵盖了现实世界中的实体，如物体、人物、地点和事件。知识图谱的核心通常依赖图数据库，图数据库专注于通过存储离散的信息片段及其之间的关联来管理数据。

知识图谱的核心组成部分包括：**实体**是现实世界中的事物或概念，包括人、地点、活动和思想总结。在图型表达中，这是一种可视化数据集之间关系的方式，实体在图中表示为节点。

实体的例子包括：
- 人物：巴拉克·奥巴马、塞雷娜·威廉姆斯
- 地点/位置：纽约市、金字塔
- 事件：第二次世界大战、2008 年经济危机
- 抽象/意识形态：民主、重力

**关系**描述了对象之间的相互作用或联系方式，且展示了它们是如何联系在一起的。在知识图谱中，关系通过边来表示，这些边连接相应的节点。而边的流动方向可以是单向，也可以是双向，这取决于实体关系的性质。

### 知识图谱的分类

知识图谱拥有以下能力：
- 有效管理和可视化异构信息：能够在统一的框架内处理不同系统的数据，实现清晰且深具洞察力的信息展示。
- 集成新的数据资源：知识图谱固有的灵活性，能很好地同新数据源融合，支持知识库的持续扩充。
- 理解并阐释任何存储信息中的关系：能够发现并展示不同信息库中实体之间的关系，从而全面理解潜在的关联关系。

图谱的主要类型：

- RDF（资源描述框架）三元组存储：专注于存储和处理基于 RDF 框架的信息，该框架通过三元组（主体、谓语、客体）来表示知识。
带标签的属性图：专门研究节点和边附带信息标签的图，提供了更为丰富和细致的数据表现。

### RDF（资源描述框架）图

RDF 图，全称资源描述框架图，是用来表示类似网络结构的网络信息的一种方式。基本上，它是一系列围绕主题、谓词和客体组成的声明。以“巴黎是法国的首都”这句话为例，在 RDF 图中，“巴黎”作为主题，“是……的首都”作为谓词，“法国”作为对象（客体）。而这三个元素共同构成了一个“三元组”，代表了一个事实。一个 RDF 图可以包含众多这样的三元组，从而构建成一个互连的信息网络。 

资源描述框架（RDF）三元组存储是一种标准化的知识表示数据模型。在这个模型中，每个元素都通过统一资源标识符（URI）被赋予一个独一无二的标识符。这种机制确保主题、谓词和客体的机器可读性。此外，RDF 三元组存储采用了一种名为 SPARQL 的标准化查询语言，该语言支持从存储中检索数据。得益于数据表示和查询的标准化，RDF 三元组存储能够与其他遵循 RDF 框架的知识图谱实现互操作。

![SPARQL](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-2.png)

上图展示了一个社交网络中的个体（圆形节点 Jack、Joe、Jane），和他们之间的友谊关系（有向连接线 knows）。此外，每个有深色边缘的节点都表示该个体有收入（有向连接线 hasIncome）。菱形节点显示了网络中可能存在的额外数据（三元组）。

RDF 图的优点：

- 互操作性：RDF 是 W3C 的标准，意味着不同的系统可以理解并交换存储在 RDF 图中的数据。这使得它非常适合跨平台和应用程序之间的数据共享。

- 标准化：由于其标准化的格式，RDF 图支持标准查询语言 SPARQL 来探索和分析图中存储的数据。

- 推理与推导：RDF 图能够利用本体（可以视为对概念的正式描述）来进行数据推理。这使系统能够推导出图中没有直接表述的新信息。

- 灵活：RDF 图能够表述多种数据类型和关系，适合模拟复杂的领域和整合不同来源的数据。

### RDF 图的缺点：

- 深度搜索复杂：在大型 RDF 图中进行深度搜索的计算成本可能很高，这可能拖慢需要探索多个连接的查询的速度。

- 结构严格：RDF 数据以“三元组”（主体、谓语、客体）的形式存储，这种结构可能不如其他图模型那样灵活，后者允许对实体或关系本身添加属性。

- 学习曲线陡峭：理解和使用 RDF 需要良好地掌握其基本概念及 SPARQL 查询语言，这对新用户来说可能是一个挑战。

### 带标签的属性图 (LPG)

带标签的属性图（LPG）是一种用于表现具有相互连接的服务及其关系的特殊图数据库模型。以下是其主要特点的详细解释：

- 节点：可表示现实中的男性或女性特征。每个节点都具有独特的描述，并可被赋予一个或多个标签以表明其类型或大小（例如，“人物”、“产品”）。

- 属性：节点可能拥有键值对，用以存储关于该实体的额外信息。这些属性允许对图中的元素进行基本描述。

- 边：表示节点之间的联系，并展示实体间的关系。边与节点类似，可以用多种方式标记（例如，“认识”、“购买”），同时也可以拥有自己的属性。

LPG 的主要特性：

- 丰富的数据结构：节点和边都能拥有属性，与其他模型如 RDF 相比，允许更密集和信息量更大的数据表现。

- 高效的存储与查询：LPG 结构通常能带来高效的存储方式和更快速的图内连接遍历，便于进行查询。

- 灵活：LPG 由于没有预定义的模式，具备很高的灵活性，允许模拟多种数据关系。

### RDF vs 属性图

![RDF vs 属性图](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-3.png)

### 属性图与 LLM 模型结合的智能问答

属性图和大型语言模型（LLM）是两个强大的工具，可以结合使用，从数据中挖掘出新线索。以下是它们如何协作的具体方式：

**数据增强：dou bao z**

- LLM 可用于生成属性图中点和边的文本描述，这样不仅可以丰富数据内容，还能帮助其他工具或用户更加容易地理解各项关系。

- LLM 还可以基于图中已有的数据生成新的点和边，这对于进行异常检测或预测欺诈行为等任务非常有用。

**查询与探索：**

- LLM 可以用来创建查询属性图的自然语言接口，允许用户以比传统的图查询语言更为直观的方式（例如自然语言）对数据进行提问。

- LLM 也能够汇总图查询结果，并为这些发现生成解释。

**推理和推断：**

LLM 可以用于执行属性图上的推理任务，这可能包括基于现有数据推断节点间新的关系，或识别图中存在的不一致。

![LLM](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-4.png)

示例演示：

以下展示了使用 Llamaindex KnowledgeGraphIndex 和 NebulaGraph Lite Reference 结合 Google Gemini LLM 和 Collab 分步实现知识图谱的过程。

### 为 Gemini 生成 API 密钥

前往 https://aistudio.google.com/app/prompts/new_chat 并生成一个新的 API 密钥。

### 加载 PDF 文档

```
! mkdir ad && cd ad
! curl https://arxiv.org/pdf/2106.07178.pdf --output AD1.pdf
! mv *.pdf ad/
! pip install -q transformers

%pip install llama_index pyvis Ipython langchain pypdf  llama-index-llms-huggingface  llama-index-embeddings-langchain llama-index-embeddings-huggingface
%pip install --upgrade --quiet llama-index-llms-gemini  google-generativeai
%pip install --upgrade --quiet llama-index-graph-stores-nebula nebulagraph-lite
```

### 导入谷歌 API 密钥

```
import os

from google.colab import userdata
GOOGLE_API_KEY = userdata.get('GOOGLE_API_KEY')
os.environ["GOOGLE_API_KEY"] = GOOGLE_API_KE

```

### 导入必要的模块和库

```
import logging
import sys

logging.basicConfig(stream=sys.stdout, level=logging.INFO)
logging.getLogger().addHandler(logging.StreamHandler(stream=sys.stdout))
from llama_index.core import (
                         ServiceContext,
                         KnowledgeGraphIndex)
from llama_index.core import SimpleDirectoryReader
from llama_index.core.storage.storage_context import StorageContext
from pyvis.network import Network

from llama_index.llms.huggingface import HuggingFaceLLM
检查支持的 Gemini 模型。本例中，我们将使用 Gemini 1.0 专业版。

import google.generativeai as genai

for m in genai.list_models():
    if "generateContent" in m.supported_generation_methods:
        print(m.name)
        print(m)

from llama_index.llms.gemini import Gemini

llm = Gemini(model="models/gemini-1.0-pro-latest")

```
### 导入 BGE 嵌入

```
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import ServiceContext


embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")

```

### 加载广告目录内容

```

documents = SimpleDirectoryReader("/content/ad").load_data()
print(len(documents))

```
###  在本地启动 Nebula 图数据库精简版的 Docker 实例

```
from nebulagraph_lite import nebulagraph_let
n = nebulagraph_let(debug=False)
n.start()

```

### 在 Nebula 存储中设置名为“nebula_ad”的命名空间和节点

```
%ngql --address 127.0.0.1 --port 9669 --user root --password nebula

# If not, create it with the following commands from NebulaGraph's console:
%ngql CREATE SPACE nebula_ad(vid_type=FIXED_STRING(256), partition_num=1, replica_factor=1)

```


```
import time

print("Waiting...")

# Delay for 10 seconds
time.sleep(10)

%ngql --address 127.0.0.1 --port 9669 --user root --password nebula
%ngql USE nebula_ad;
%ngql CREATE TAG entity(name string);
%ngql CREATE EDGE relationship(relationship string);

```
### 将文档数据加载到图数据库中

```
import os
os.environ["NEBULA_USER"] = "root"
os.environ["NEBULA_PASSWORD"] = "nebula"  # default is "nebula"
os.environ[
    "NEBULA_ADDRESS"
] = "127.0.0.1:9669"  # assumed we have NebulaGraph installed locally

space_name = "nebula_ad"
edge_types, rel_prop_names = ["relationship"], [
    "relationship"
]  # default, could be omit if create from an empty kg
tags = ["entity"]  # default, could be omit if create from an empty kg

from llama_index.core import StorageContext
from llama_index.graph_stores.nebula import NebulaGraphStore

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)

from llama_index.core import Settings

Settings.llm = llm
Settings.embed_model = embed_model
Settings.chunk_size = 512

```

### 更新图数据库中的节点数据


```

# NOTE: can take a while!
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,
    include_embeddings=True
)

```

### 检查 Nebula 存储中已插入的图数据

```

# Query some random Relationships with Cypher
%ngql USE nebula_ad;
%ngql MATCH ()-[e]->() RETURN e LIMIT 10

```

### 数据查询与输出：

![v](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-28-5.png)

### 现在开始查询索引数据

`query_engine = index.as_query_engine()`

```

from IPython.display import display, Markdown

response = query_engine.query(
    "Tell me about Anomaly?",
)
display(Markdown(f"<b>{response}</b>"))

```

**异常现象（Anomaly），在不同应用领域也可能被称作异常值、例外、特殊情况、稀有现象或新奇现象，它们指的是与常规、标准或预期显著不同的异常对象。**

```
from IPython.display import display, Markdown

response = query_engine.query(
    "What are graph anomolies?",
)
display(Markdown(f"<b>{response}</b>"))

```

图异常可以被定义为结构性异常。

## 小结

这些简单的知识图谱有效地捕捉了实体间的复杂关系，这种能力显著提高了查询和推理的精确性、多样性和复杂性。此外，这些知识图谱还可以扩展应用到基于 RDF 的复杂本体图。欢迎大家动手尝试～👏
参考：

[https://link.springer.com/chapter/10.1007/978-3-642-21295-6_13](https://link.springer.com/chapter/10.1007/978-3-642-21295-6_13)

[https://github.com/nebula-contrib/nebulagraph-lite](https://github.com/nebula-contrib/nebulagraph-lite)

[https://docs.llamaindex.ai/en/stable](https://docs.llamaindex.ai/en/stable)

本文由 Rajesh K 原文发布在 Medium

图数据库和知识图谱是管理图结构数据（包括节点（实体）和边（关系））的两大主流方案。图数据库利用基于图的数据模型存储信息，支持通过专用的图查询语言实现对图数据的查询和遍历；知识图谱通过整合推理和派生新知识的机制，增强了图数据库的功能。

基于 Gemini 和 NebulaGraph 构建知识图谱问答系统

![nebula-stats-exporter](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-1.jpg)

大家好，这里是玖叁叁，目前从事全栈工程师工作，刚刚接触 NebulaGraph 不久，还在努力学习当中。图数据库可以高效地表达、存储和分析复杂关系和网络，在特定场景下有着不错的性能。希望通过这篇 nebula-stats-exporter 的实践文章可以给各位读者朋友们一点启发。

### 01 关于 nebula-stats-exporter

nebula-stats-exporter 是一个 stats 接口转换工具，可以将 stats 接口返回的数据转换为Prometheus 可接受的数据格式，实现对 NebulaGraph 数据采集以及监控。

### 02部署环境说明

本篇文章将会对二进制部署以及 docker-compose 部署两种部署方式使用 nebula-stats-exporter 进行说明，均使用目前最新版本 v3.8.0

## 二进制部署

环境部署参考官方文档（https://docs.nebula-graph.com.cn/3.8.0/4.deployment-and-installation/2.compile-and-install-nebula-graph/2.install-nebula-graph-by-rpm-or-deb/），使用 RPM/DEB 的方式部署。

```
# 安装
sudo dpkg -i nebula-graph-3.8.0.ubuntu1804.amd64.deb

# 启动
sudo /usr/local/nebula/scripts/nebula.service start all

# 确认服务状态
$ sudo /usr/local/nebula/scripts/nebula.service status all

# 下载console工具，从下面的页面找对对应的版本下载
https://github.com/vesoft-inc/nebula-console/releases

# 重命名，并修改权限
mv nebula-console-linux-amd64-v3.8.0 nebula-console
chmod 755 nebula-console

# 使用console连接，注意实际上都是默认参数，直接使用./nebula-console就可以连接本地，不需要任何参数，密码默认为空
./nebula-console -addr <ip> -port <port> -u <username> -p <password>

# 注册 Storage 服务
ADD HOSTS 127.0.0.1:9779

# 安装完成，截图留念
```
![二进制部署](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-2.png)

```
# 测试三个服务的stats接口，
Meta：curl 127.0.0.1:19559/stats
Graph：curl 127.0.0.1:19669/stats
Storage：curl 127.0.0.1:19779/stats
```
## docker-compose 部署

环境部署参考官方文档，使用 docker-compose 部署
```
# 下载
git clone -b release-3.8 https://github.com/vesoft-inc/nebula-docker-compose.git

# 切换路径
cd nebula-docker-compose/

# 修改docker-compose.yaml，为了开启stats接口访问
修改内容如下
Meta服务三处
- 29559:19559
- 39559:19559
- 49559:19559
Graph服务三处
- 29669:19669
- 39669:19669
- 49669:19669
Storage服务三处
- 29779:19779
- 39779:19779
- 49779:19779

# 启动服务
docker-compose up -d

# docker部署无需手动添加Storage，使用console连接查看，服务正常
```
![Storage](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-3.png)

```
# 测试服务的stats接口，
Meta
curl 127.0.0.1:29559/stats
curl 127.0.0.1:39559/stats
curl 127.0.0.1:49559/stats

Graph：
curl 127.0.0.1:29669/stats
curl 127.0.0.1:39669/stats
curl 127.0.0.1:49669/stats

Storage
curl 127.0.0.1:29779/stats
curl 127.0.0.1:39779/stats
curl 127.0.0.1:49779/stats`
```
## 03nebula-stats-exporter 安装配置

### RPM/DEB 方式部署的 nebula，对应使用二进制方式部署 nebula-stats-exporte
```
# 下载
git clone https://github.com/vesoft-inc/nebula-stats-exporter.git

# 编译
cd nebula-stats-exporter
make build

# 创建config.yaml
vim config.yaml

# 内容
clusters:
  - name: nebula
    instances:
      - name: metad
        endpointIP: 127.0.0.1
        endpointPort: 19559
        componentType: metad
      - name: graphd
        endpointIP: 127.0.0.1
        endpointPort: 19669
        componentType: graphd
      - name: storaged0
        endpointIP: 127.0.0.1
        endpointPort: 19779
        componentType: storaged

# 启动服务
./nebula-stats-exporter --bare-metal --bare-metal-config=./config.yaml

# 服务正常启动，改为后台运行模式，截图留念
nohup ./nebula-stats-exporter --bare-metal --bare-metal-config=./config.yaml > nebula-stats-exporter.log  2>&1 &
```
![ 测试接口](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-4.png)

```
# 测试接口
curl 127.0.0.1:9100/metrics
```
### docker-compose部署nebula，对应使用docker方式nebula-stats-exporte

```
# # 创建config.yaml
vim config.yaml

# 内容
clusters:
  - name: nebula
    instances:
      - name: metad0
        endpointIP: 127.0.0.1
        endpointPort: 29559
        componentType: metad
      - name: metad1
        endpointIP: 127.0.0.1
        endpointPort: 39559
        componentType: metad
      - name: metad2
        endpointIP: 127.0.0.1
        endpointPort: 49559
        componentType: metad
      - name: graphd0
        endpointIP: 127.0.0.1
        endpointPort: 29669
        componentType: graphd
      - name: graphd1
        endpointIP: 127.0.0.1
        endpointPort: 39669
        componentType: graphd
      - name: graphd2
        endpointIP: 127.0.0.1
        endpointPort: 49669
        componentType: graphd
      - name: storaged0
        endpointIP: 127.0.0.1
        endpointPort: 29779
        componentType: storaged
      - name: storaged1
        endpointIP: 127.0.0.1
        endpointPort: 39779
        componentType: storaged
      - name: storaged2
        endpointIP: 127.0.0.1
        endpointPort: 49779
        componentType: storaged
# 启动，需要注意config.yaml路径按实际修改，我为了方便使用127.0.0.1 将-p 9100:9100 换成了--network=host，直接使用主机网络（因为容器部署使用bridge网络，127.0.0.1只能连接容器内）
docker run -d --restart=always --name nebula-stats-exporter -p 9100:9100 \
    -v "$(pwd)/deploy/bare-metal/config.yaml:/config.yaml" \
    vesoft/nebula-stats-exporter:v3.3.0 --bare-metal --bare-metal-config=/config.yaml

# 查看日志
docker logs -f nebula-stats-exporter

# 截图留念
```
![Prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-5.png)

## 04 整合 Prometheus 和 Grafana

### Prometheus 配置文件

```
# 编辑prometheus.yml
vim prometheus.yml

# 内容，根据实际IP填写
scrape_configs:
  - job_name: 'nebula-stats-exporter'
    static_configs:
      - targets: ['127.0.0.1:9100']

# 访问9090端口，查看是否正常
# 截图留念
```

### Grafana 配置

- 添加 Prometheus 数据源
![Grafana](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-6.png)
![Prometheus 数据源](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-7.png)
![Prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-6-27-8.png)
![Prometheus 数据源](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-9.png)
- 导入 Dashboard 样式

```
# 下载地址
https://github.com/vesoft-inc/nebula-stats-exporter/blob/master/deploy/grafana/nebula-grafana.json
```
![Dashboard](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-10.png)
![nebula-stats-exporter](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-11.png)
![nebula](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-27-12.png)

## 05总结

本文阐述了使用 nebula-stats-exporter 对 nebula 各个服务进行监控的方式，希望能对大家有所帮助。

作者：玖叁叁
校对&审核：kristain

图数据库可以高效地表达、存储和分析复杂关系和网络，在特定场景下有着不错的性能。本篇文章将会对二进制部署以及 docker-compose 部署两种部署方式使用 nebula-stats-exporter 进行说明，均使用目前最新版本 v3.8.0。

实践分享｜关于 nebula-stats-exporter 的使用

![ngbatis系列](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-12-1.jpg)

各位朋友好久不见，这个系列自从上次的《ngbatis系列丨操纵字节码实现xml变代理类》，至今久未更新了。今天的话题是：日常开发中容易碰到的问题。

## 项目集成类

**Q1：与存在 MyBatis 的项目集成**

在与使用了 MyBatis 的项目集成时，最重要的是实现四部分代码的两两分离，例如以下配置方式：

| - | Java 接口 | xml |
| --- | --- | --- |
| MyBatis | MapperScan | mybatis.mapper-locations=classpath:mapper/*.xml |
| NgBatis | SpringBootApplication.scanBasePackages | cql.parser.mapper-locations=ng-mapper/**/*.xml

1.Java层面，MapperScan 与 SpringBootApplication 中的 ScanBasePackages 二者所指向的包不存在交叉，即：让 MyBatis 发现不了NgBatis 的 Java 接口，同理，让 NgBatis 发现不了 MyBatis 的 Java 接口，避免重复发生会导致异常的动态代理行为。导致异常的原因有：

 - 当 MyBatis 扫描到 NgBatis 的 Java 接口，会使用访问关系型数据库的逻辑来代理访问图数据库的接口，与期望相悖。
 - 另外 NgBatis 再代理一次，一个接口下产生两个 Bean，会导致通过接口的单例注入报错。
 - NgBatis 实现动态代理机制的入口是 xml 中的 namespace，如果添加了类似 @Component 或者 @Mapper 的注解，同样会导致报错。

2.xml 层面，同样需要使 mybatis.mapper-locations 与 cql.parser.mapper-location 所指向的路径不存在交叉。设计之初有不当之处，默认值状态下，二者路径重叠。两个框架的解析逻辑与约束不同，如果 NgBatis 通过 cql.parser.mapper-locations 指定的路径，扫描到 MyBatis的 xml，可能导致解析出错，反之亦然。另外，cql.parser.mapper-locations 所指向的路径至少需要包含一个 xml 文件，这一点会考虑在后续的版本优化。

**Q2：与 ```spring-boot```3.x 集成**

在主分支中，保持的版本是与 ```spring-boot``` 2.x 的集成，如果需要与 ```spring-boot``` 3.x 集成，可以使用带有 ```-jdk17```后缀的版本。

**Q3：与 SpringCloud 集成**

扫描接口所在包的注解可以使用 ```@ComponentScan(...)```，同样需要注意 Q1 中所提的包路径范围。

**Q4：与存在 org.apache.shardingsphere 的项目集成**

NgBatis 中所使用的 Beetl 模板引擎依赖了 antlr4，shardingsphere 同样依赖了 antlr4，这其中就有可能会产生 jar 包版本的冲突。以 shardingsphere 5.2.0 (antlr-4.9.2) 与 NgBatis 1.2.2 (antlr-4.11.1) 为例，两个版本冲突的解决方式如下：

```
<dependency>
       <groupId>org.nebula-contrib</groupId>
       <artifactId>ngbatis</artifactId>
       <version>1.2.2</version>
        <exclusions>
            <exclusion>
                <groupId>com.ibeetl</groupId>
                <artifactId>beetl-antlr4.11-support</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>com.ibeetl</groupId>
        <artifactId>beetl-default-antlr4.9-support</artifactId>
        <version>3.15.10.RELEASE</version>
    </dependency>

```

在项目中引入 NgBatis 的同时，排除掉高版本的 antlr，然后尝试引用相对低版本的 antlr，如不是例子中所提的版本，可以在 maven 中查找 beetl antlr support 这个系列的包，并引入相近版本。

## 自定义 nGQL 用法问题

**Q1：参数占位符问题**

参数的使用有两个时机可以选择，假如现在有一个参数 param：

- 执行到数据库时，由数据库读取参数，参数格式为：```$param```，前提是数据库支持该参数位置的参数化，正常用在查询子句的 == 后；

- 执行到数据库前，由 NgBatis 组装到 xml 的 nGQL 模板中，参数格式为：```$param```；

- 如果参数位置是 Schema，可以使用```${ng.valueFmt(param)} ```，等价于 `${param}`；

- 当参数不能确定具体类型时，可以使用 ```${ng.valueFmt(param)} ```进行占位，NgBatis 会根据类型处理成符合语法结构的形式，如 String 类型会在前后追加引号，时间类型会转换成调用 date、datetime 等时间函数的字符串形式，进而完成 nGQL 组装。

- 在模板中，参数还存在两种类型，模板参数类型与 Java 对象类型。如果访问参数方法，可使用 ```@param.methodName```的方式，如 param 是一个 Map 类型，可以使用```@param.get('keyName')```。(1.18 调用 Java 方法与属性 · Beetl3 官方文档 · 看云：https://www.kancloud.cn/xiandafu/beetl3_guide/2138960)

**Q2：参数名称问题**

- 当 Java 接口只有一个参数，且为 Map 或对象类型时，可以直接使用 key 或者对象的属性名。否则默认参数名按所处方法的参数位置，取 ```p0```、```p1```...

- 为了代码更具可读性，可在参数名中，对参数追加注解：```@Param("xxx")```，需要注意的是，该注解的包名为：org.springframework.data.repository.query，如误使用了包含 ibatis 的包名，并不会加以识别。

**Q3：如何在在多个集合元素使用“```,```”分隔**

可以使用 ```${ng.join(list)}```，List 为传入的变量名。更多 NgBatis 的模板函数用法详见：(https://graph-cn.github.io/ngbatis-docs/dev-example/built-in-function.html)

**Q4：如何判断参数是否为空**

可以使用 ```isEmpty(param) ```进行判断。更多模板函数详见：(https://www.kancloud.cn/xiandafu/beetl3_guide/2138956)

**小结**

在 xml 中自定义 nGQL 的用法中，基类 NebulaDaoBasic 实现的方式遵循着相同的模板方式，意味着源码中的 NebulaDaoBasic.xml 中有更多详尽的用例可以提供参考，当然基类为了满足更具通用性，整体用法会显得比常规模板写法要复杂一些。

##  NgBatis 结构下进行拓展

以下方式如果想对既有类型进行覆盖，需要建立在项目软件包在 org.nebula.contrib 包之后，如：


```
@SpringBootApplication(scanBasePackages={"org.nebula.contrib", "com.example.xxx"})
```

**Q1：复杂对象作为返回值，如何处理**

可以使用继承抽象类的方式对不兼容的类型进行处理，如：


```
@Component
public class MyTypeHandler extends AbstractResultHandler<MyType, MyType> {

  @Override
  public MyType handle(MyType newResult, ResultSet result, Class resultType) {
    // 在当前位置，从 result 读取数据，填入 newResult 中
    return null;
  }
}
```

如果复杂类型需要支持集合的方式，还需要拓展一个集合的接口：

```

@Component
public class CollectionMyTypeHandler extends AbstractResultHandler<Collection, MyType> {
  
  @Autowired private MyTypeHandler itemHandler;
  
  @Override
  public MyType handle(Collection newResult, ResultSet result, Class resultType) {
    // 在当前位置，从 result 读取数据，填入 newResult 中
    // 取对应元素值，调用 itemHandler 然后调用 newResult.add 完成添加
    return newResult;
  }
}
```
**Q2：还有哪些接口可以拓展：**

1.主键生成接口：PkGenerator，可根据入参获得 Vid 的类型，然后选择使用雪花算法或者 UUID 等方式，完成主键生成策略的指定；

2.模板引擎接口：TextResolver，当模板引擎的实现方式发生替换，需要将 NebulaDaoBasic.xml 迁移到项目的 resources 中，并用新模板引擎的方式进行重写；

3.传入参数的转换接口：ArgsResolver，如现有传入模板参数的转换方案不能满足需求，可对其进行替换，自定义实现类，对 ArgsResolver 进行实现，并注册成组件；

4....

##  配置相关问题

**Q1：如何在控制台中输出 nGQL**


```
logging:
  level:
    org.nebula.contrib: DEBUG
```

**Q2：如何指定 mapper xml 的放置路径：**


```
cql:
  parser:
    # 更换开发者自定义的 xml 所在位置
    mapper-locations: ng-mapper/**/*.xml # 默认为 mapper/**/*.xml
```

## 报错类问题

**StackOverflowError**

- 场景1

  - 报错时机：模板引擎生成语法树时产生报错
  - 解决方式：指定虚拟机启动参数 -Xss2m

- 场景2

  - 报错时机：参数传入数据库时，会经历一个类型转换的过程，将 Java 对象转换成 Nebula-Java 的可接受的 Value 类型，当 Java 对象的值存在循环依赖时，即 a 对象是 b 对象的属性值之一，同时 b 对象也是 a 对象的属性值之一，会导致递归过深问题。当前最新版本 v1.2.2 还未在类型转换时，做空对象缓存来规避循环问题。

  - 解决方式 1：改变参数类的结构；

  - 解决方式 2：对不需要写入数据库的属性添加 @Transient 注解。

## 优化类问题

**第一种情况，查询语句组装耗时**

在 NgBatis 对模板引擎的使用中，有一个比较重的资源使用了懒加载的方式。日志输出对应的是：nGQL make up costs 370ms，如果想把这部分时间挪到服务启动时， 可以在项目中使用以下方式，提前完成资源加载：

```
@Bean
public TextResolver textResolver(TextResolver resolver) {
  resolver.resolve("", Collections.emptyMap());
  return resolver;
}
```

**第二种情况，执行查询的耗时**

另外还有可能耗时的环节发生在数据库的查询上，日志输出对应的是：query costs 1091ms 如果最小连接数为 0，那么也会在第一次查询时创建连接，也会比单纯的查询本身额外消耗一些时间：可以让最小连接数大于 0，从而在服务启动时，完成连接创建，减少初次查询耗时。


```
nebula:
  pool-config:
    min-conns-size: 1
```

## 关于多个图空间的使用问题

当项目需要跨越多个图空间进行数据读写时，有以下几种方式可以实现跨空间：
1.在实体类中追加 @Space("myspace") 指定 tag 所属空间

2.在 xml 中的 <mapper space="myspace" namespace="...xxxMapper">

3.在接口方法的标签中指定 space，如：
<select id="..." space="myspace">

以上三种方式可以按需选择。其中第三种方式还支持使用参数的方式，如：

```
<select id="spaceFromParam" space="${paramMySpace}" spaceFromParam="true">
        RETURN true;
    </select>

```

```paramMySpace```通过接口的参数传入。据我所知，有开发者在此用法的基础上实现了多租户场景的适配。

## 总结

目前将 NgBatis 集成到项目中出现得比较多的问题大体上都列在上面了，可能有一些问题的表象会跟列举的内容不太相同，但可以通过类比跟对应问题点附带的参考文档来完成。如果你在开发中碰到一些比较典型或者比较反直觉的问题，也可以留言讨论。

原文作者：大叶
作者公众号：大叶的技术栈
校对&审核：kristain



在项目中引入 NgBatis 的同时，排除掉高版本的 antlr，然后尝试引用相对低版本的 antlr，如不是例子中所提的版本，可以在 maven 中查找 beetl antlr support 这个系列的包，并引入相近版本。

NgBatis丨开发常见问题

![NebulaGraph 安装](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-1.jpg)

## NebulaGraph 安装

本次安装选择 NebulaGraph 最新版本 v3.8.0，采用 docker-compose 的方式部署，新版本的安装要比之前顺滑很多，赞~ 

1. 找一台服务器，安装好 docker 和 docker-compose

2.  下载项目

```
`$ git clone -b release-3.8 https://github.com/vesoft-inc/nebula-docker-compose.git` 
```

3.  安装

```
`mkdir -p /work/nebula

#复制docker-compose.yaml
cp ../nebula-docker-compose-3.8.0/docker-compose.yaml /work/nebula/

# 复制环境变量文件
cp ../nebula-docker-compose-3.8.0/.env /work/nebula/

# 修改.env，时区使用Asia/Shanghai
vim .env

TZ=Asia/Shanghai

# 启动
docker-compose up -d

# 查看启动结果
docker-compose ps是 git clone -b release-3.8 https://github.com/vesoft-inc/nebula-docker-compose.git

![git clone -b release-3.8](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-2.png)

Prometheus 安装

安装过程如下:
# 创建目录
mkdir -p /work/prometheus

# 创建应用子目录
# 启动脚本路径
mkdir -p /work/prometheus/bin
# 数据文件路径
mkdir -p /work/prometheus/data/prometheus
# 配置文件路径
mkdir -p /work/prometheus/conf
# 日志文件路径
mkdir -p /work/prometheus/logs

# 创建启动脚本
cd /work/prometheus/bin
vim start.sh

#内容
docker run -d --restart=always --name=prometheus \
        -p 9090:9090 \
        --log-opt max-size=10m \
        -v /etc/localtime:/etc/localtime:ro \
        -v /etc/timezone:/etc/timezone \
        -v /work/prometheus/conf/prometheus.yml:/etc/prometheus/prometheus.yml \
        -v /work/prometheus/data/prometheus:/prometheus \
        prom/prometheus --config.file=/etc/prometheus/prometheus.yml --web.enable-lifecycle --storage.tsdb.retention.time=7d
        
# 创建一个空的prometheus.yml
touch prometheus.yml

# 修改/work/prometheus/data/prometheus，目录权限
chown 65534:65534 prometheus/

# 启动
chmod 755 start.sh
./start.sh

# 查看启动日志，确认正常启动
docker logs -f prometheus`
```
![docker logs -f prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-3.png)


## Grafana 安装

安装过程如下：
```
`#创建目录
mkdir -p /work/grafana

#创建应用子目录

#启动脚本路径
mkdir -p /work/grafana/bin

#数据文件路径
mkdir -p /work/grafana/data/grafana

#日志文件路径
mkdir -p /work/grafana/logs

#创建启动脚本
cd /work/grafana/bin
vim start.sh

#内容
docker run -d --restart=always --name grafana \
        -p 3000:3000 \
        --log-opt max-size=10m \
        -e GF_AUTH_PROXY_ENABLED=true \
        -e GF_AUTH_ANONYMOUS_ENABLED=true \
        -e GF_SERVER_ENABLE_LOCAL_HEALTH_CHECK=false \
        -v /etc/localtime:/etc/localtime:ro \
        -v /etc/timezone:/etc/timezone \
        -v /work//grafana/data/grafana:/var/lib/grafana \
        prom/prometheus --config.file=/etc/prometheus/prometheus.yml --web.enable-lifecycle --storage.tsdb.retention.time=7d

# 创建一个空的prometheus.yml
touch prometheus.yml

# 修改/work/prometheus/data/prometheus，目录权限
chown 65534:65534 prometheus/

# 启动
chmod 755 start.sh
./start.sh

# 查看启动日志，确认正常启动
docker logs -f prometheus
`
```

## Grafana 安装

安装过程如下：

```
# 创建目录
mkdir -p /work/grafana
# 创建应用子目录
# 启动脚本路径
mkdir -p /work/grafana/bin
# 数据文件路径
mkdir -p /work/grafana/data/grafana
# 日志文件路径
mkdir -p /work/grafana/logs

# 创建启动脚本
cd /work/grafana/bin
vim start.sh

#内容
docker run -d --restart=always --name grafana \
        -p 3000:3000 \
        --log-opt max-size=10m \
        -e GF_AUTH_PROXY_ENABLED=true \
        -e GF_AUTH_ANONYMOUS_ENABLED=true \
        -e GF_SERVER_ENABLE_LOCAL_HEALTH_CHECK=false \
      -v /etc/localtime:/etc/localtime:ro \
        -v /etc/timezone:/etc/timezone \
        -v /work//grafana/data/grafana:/var/lib/grafana \
        harbor.neuqsoft.com/dockerhub/grafana/grafana

# 修改/work//grafana/data/grafana，目录权限
chown 472:472 grafana/

# 启动
chmod 755 start.sh
./start.sh

# 查看启动日志,确认正常启动
docker logs -f grafana

```

![docker logs -f grafana](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-4.png)

整合阶段

1. 调整 NebulaGraph，打开监控

```
`docker-compose down
# 编辑docker-compose.yaml文件
vim docker-compose.yaml

# 在graphd服务后边增加 - --enable_space_level_metrics,注意我有三个节点，都需要修改
 - --enable_space_level_metrics`
```

![enable_space_level_metrics](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-5.png)

```
 # 调整端口，将ws_http_port对应的端口映射出来
 # 使用29669，39669，49669对应graphd服务的三个节点19669
 # 以下为部分内容，注意我有三个节点，都需要修改
 - 29669:19669
 - 29669:19669
 - 29669:19669`

```
![启动 NebulaGraph](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-6.png)

```

# 启动 NebulaGraph
docker-compose up -d

# 检查启动状态
docker-compose ps

```
2. 配置 Prometheus


```

# 编辑配置文件
vim prometheus.yml

scrape_configs:
  - job_name: nebula-graph
    metrics_path: /stats
    static_configs:
     - targets:
       - 127.0.0.1:29669
       - 127.0.0.1:39669
       - 127.0.0.1:49669

# 重启服务
docker restart prometheus

```
3. Grafana 配置数源

![docker restart prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-7.png)

![Grafana 配置数源](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-8.png)

4. 官方自带的 metrics 接口请求地址和 Prometheus 要求的不一样，通过修改 metrics_path 配置，指定到了 /stats 访问地址。

其次，返回数据格式也和 Prometheus 要求的不一样，导致 Prometheus 识别节点全部都是 down

![Prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-9.png)

5.最后，采集到的数据，也没有被 Prometheus 存储，Grafana 也没办法读取到。

![ Prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-10.png)


## 填坑环节

1. 期间试过很多种方法，失败的就不说了，就说最后成功的
自己实现一个数据转换服务，将官方的 metrics 返回数据转换为Prometheus 要求的格式。

用 GO 实现了一个转换的工具，上代码：

```

package main

import (
    "flag"
    "fmt"
    "io/ioutil"
    "net/http"
    "os"
    "strings"
)

// 端点和端口进行变量声明
var (
    targetEndpoint string
    port           string
)

func main() {
    // 使用 flag 包解析命令行参数
    flag.StringVar(&port, "port", "8000", "HTTP server 监听端口")
    flag.StringVar(&targetEndpoint, "target", "http://nebula-graph.local:19669/metrics", "目标 metrics 端点地址")
    flag.Parse()

    // 注册 /metrics 路由
    http.HandleFunc("/metrics", handleMetrics)

    // 启动 HTTP 服务器
    fmt.Printf("服务器启动在端口 %s，抓取指标来自 %s\n", port, targetEndpoint)
    if err := http.ListenAndServe(":"+port, nil); err != nil {
        fmt.Printf("启动服务器时遇到错误: %s\n", err)
        os.Exit(1)
    }
}

// handleMetrics 是处理指标抓取的主函数
func handleMetrics(w http.ResponseWriter, r *http.Request) {
    // 从目标端点抓取原始指标数据
    resp, err := http.Get(targetEndpoint)
    if err != nil {
        http.Error(w, "抓取指标失败", http.StatusInternalServerError)
        return
    }
    defer resp.Body.Close()

    // 读取响应体内容
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        http.Error(w, "读取指标失败", http.StatusInternalServerError)
        return
    }

    // 重格式化指标
    metrics := reformatMetrics(string(body))
    fmt.Fprint(w, metrics) // 返回格式化后的指标
}

// reformatMetrics 将原始指标重格式化为 Prometheus 兼容的格式
func reformatMetrics(rawMetrics string) string {
    var formattedLines []string
    lines := strings.Split(rawMetrics, "\n") // 按行拆分

    for _, line := range lines {
        // 跳过注释行和空行
        if strings.HasPrefix(line, "#") || line == "" {
            formattedLines = append(formattedLines, line)
            continue
        }

        // 自定义重格式化逻辑
        // 比如：num_queries_hit_memory_watermark.rate.5=0 -> num_queries_hit_memory_watermark_rate_5{interval="5"} 0
        parts := strings.Split(line, "=")
        if len(parts) != 2 {
            // 跳过无效行
            continue
        }
        metric, value := parts[0], parts[1]

        // 处理 metric 部分，将其拆分为名称和区间
        metricParts := strings.Split(metric, ".")
        if len(metricParts) < 3 {
            continue  // 不符合预期格式则跳过
        }

        // 将名称和区间拼接成 Prometheus 格式
        baseName := strings.Join(metricParts[:len(metricParts)-2], "_") // 将名称部分合并
        interval := metricParts[len(metricParts)-1]
        metricType := metricParts[len(metricParts)-2]

        // 拼接成 Prometheus 格式的字符串
        formattedMetric := fmt.Sprintf("%s_%s{interval=\"%s\"} %s", baseName, metricType, interval, value)
        formattedLines = append(formattedLines, formattedMetric)
    }

    return strings.Join(formattedLines, "\n") // 将所有行合并为一个字符串
}# 编译后得到linux服务器可执行文件metrics_converter
# 启动服务
./metrics_converter -port=8081 -target=http://127.0.0.1:29669/stats

# 测试
curl http://127.0.0.1:8081/metrics

# ok数据格式对了，不要纠结为啥全是0，刚装的啥也没有..

```
![调整 Prometheus 配置文件](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-11.png)

2. 调整 Prometheus 配置文件，调整了一个演示如下


```

# # 编辑配置文件
vim prometheus.yml

scrape_configs:
  - job_name'nebula-graph'
    static_configs:
     - targets:
       - 127.0.0.1:

# 重启服务
docker restart prometheus

```
![docker restart prometheus](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-12.png)

3. 查看 Grafana 数据指标，已经可以正常制作图表了

![Grafana 数据指标](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-06-06-13.png)

4.由于原来不支持 Prometheus + Grafana，所以官方图表库没有能直接用的

## 总结

通过不断的尝试，终于实现了目标，现在看来运维工作确实需要一些开发的基础，希望这篇文章能给需要的人带来一丝丝帮助吧。

注意：全篇文章使用 127.0.0.1 是为了隐藏 IP，各位测试的时候请使用真实IP！！

作者：堕落飞鸟

校对 & 编辑：Kristain# 

通过不断的尝试，终于实现了目标，现在看来运维工作确实需要一些开发的基础，希望这篇文章能给需要的人带来一丝丝帮助吧。

实践分享｜使用 Prometheus 监控 NebulaGraph

![](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-01.jpg)

### 环境描述

首先来说下本文的背景信息，主要是从原先用了多年的 v1.0.0 版本升级到 NebulaGraph 最新的 v3.6.0 版本。下面是本文可能会用到的前提信息：

- 当前 NebulaGraph 版本：v1.0.0
- 目标 NebulaGraph 版本：v3.6.0
- nebula-client版本：com.vesoft:client:1.0.0-rc4.20200323

相信 NebulaGraph 社区有很多和我类似用着非最新发行版的企业用户，因为为了保障业务的稳定运行，依旧用着 v2.x.0 版本，或者是和我们一样用着 v1.0.0 版本。所以，很多人会问：升级？为什么要升级呢？

这是我的答案：v3.6.0 版本，或者说最新发行版，会比 v1.0.0 版本具有**更高的可维护性和稳定性、更完善的周边生态**。此外 NebulaGraph v1.0.0 版本**出问题基本上很难得到解决，另外扩缩容比较麻烦。**

### 升级需要考虑的点

和许多依旧用着老版本的用户一样，我们其实也是做了一段时间的挣扎选择了升级。下面是我们想到的升级需要考虑到的点：

1.nGQL 的兼容性；

2.原地升级 or 导出导入的方式？这里我们测试过，原地升级经测试不可用，而且还会影响在线业务，风险大；

3.如何保证升级不影响线上的业务；

4.如何处理升级时产生的增量数据；

5.升级后如何数据一致性比对；

6.如何进行新老 nebula 替换；

如果要排个优先级的话，第 3，5，6 相比其他几点会更重要。

### 升级方案

![升级方案](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-1.png)

这是大致的升级方案，大体分为三个部分：

**升级前准备**

有些准备工作需要完成：

1.收集、整合业务线相关的所有 nGQL 并进行 v3.6.0 版本测试，修改 nGQL 以兼容 v3.6.0 版本 nebula。

2.编写 nebula 同步服务，这里无法使用 nebula-spark-connector 进行同步，因为 nebula 版本跨的太大了。

3.编写数据流量比对逻辑。

4.搭建 NebulaGraph v3.6.0 版本新集群环境，这里可以临时关闭自动 Compaction 功能，来加快写入速度。

**注意：这里并非在原来的业务应用上进行更新，而是复制一个新的出来，因为同一个应用无法兼容两套不同版本的 nebula**。

### 执行升级

我们这里是借助了 MQ（消息队列，Message Queue）来中间处理了下数据。涉及到 MQ 的步骤有：

1.开启同步过程增量数据写入 MQ 进行积压；

2.开启 nebula 数据同步，应用 A 从 nebula v1.0.0 中读取出来发送到 MQ，然后应用 B 消费 MQ 消息写入到 nebula v3.6.0；

3.同步完毕后将 MQ 中积压的增量数据写入 nebula v3.6.0；

### 升级后处理

这里再简述下升级之后需要做的操作：

1.数据一致性比对，通过流量复制的方式发送到新的应用上进行重放结果比对；

2.逐步切流量到新 nebula v3.6.0 集群；

### 内核升级的详细设计

名词说明：

- biz-app：业务应用 App，作用连接 nebula v1.0.0 进行图数据操作；

- biz-app-new：biz-app 的复制版本，只不过改成了连接 v3.6.0 版本 nebula，并更新 nGQL 以兼容 nebula v3.6.0；

- nebula-sink-app：用于接收 nebula v3.6.0 版本的更新语句消息，并写入到 nebula v3.6.0 集群；

**第一步：开启增量数据写入 MQ 积压**

![MQ 积压](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-2.png)

第二步：同步 nebula v1.0.0 数据到 v3.6.0 集群

![nebula v1.0.0](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-3.png)

第三步：同步完毕后消费增量数据

![消费增量数据](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-4.png)

第四步：数据一致性比对

![数据一致性比对](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-5.png)

第五步：nebula v3.6.0 集群切流

![nebula v3.6.0 集群切流](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-6.png)

### nebula-client v3.6.0 版本 SDK 改造

本次客户端的改造，主要是支持下面功能：主备写入同步、主备读取分流、读写 SessionPool 隔离、连接池监控、nGQL 执行监控。

![SDK 改造](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-7.png)

### 遇到的问题以及解决方案

当然升级不是一步到位，我们也遇到了不少的问题。这里罗列了几个印象深刻的错误：

- 导出 Timestamp 属性字段报错

- 无法导出多版本数据（Schema 发生更改）

- 每次 Scan 中断只能从头开始，无法接着上次的 cursor 继续导出

- 指定扫描单个 Edge 或者 Tag 出现磁盘 IO 使用率100%（见：nebula v1.0.0 版本导出部分边或者点出现磁盘 IO 负载过高）

好在的是，这些问题我们都顺利解决了。下面来讲讲我们的解决方案：

### 导出 Timestamp 属性字段报错

这个问题产生的原因是因为 RowReader.java 中不支持 TIMESPTMP 字段。

![Timestamp](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-8.png)

**解决方案：**

**重写 RowReader 代码支持 Timestamp 字段：**


```
`public RowReader(Schema schema, long schemaVersion) {
        this.schemaVersion = schemaVersion;
        int idx = 0;
        for (ColumnDef columnDef : schema.columns) {
            PropertyDef.PropertyType type = PropertyDef.PropertyType.getEnum(columnDef.getType().getType());
            String name = columnDef.getName();
            switch (type) {
                case BOOL:
                    defs.add(new Pair(name, Boolean.class.getName()));
                    break;
                case INT:
                // 这里加入TIMESPTMAP属性识别
                case TIMESTAMP:
                case VID:
                    defs.add(new Pair(name, Long.class.getName()));
                    break;
                case FLOAT:
                    defs.add(new Pair(name, Float.class.getName()));
                    break;
                case DOUBLE:
                    defs.add(new Pair(name, Double.class.getName()));
                    break;
                case STRING:
                    defs.add(new Pair(name, byte[].class.getName()));
                    break;
                default:
                    throw new IllegalArgumentException("Invalid type in schema: " + type);
            }
            types.add(type);
            propertyNameIndex.put(name, idx);
            idx++;
        }
    }

public Property[] decodeValue(byte[] value, long schemaVersion) {
        List<byte[]> decodedResult = NebulaCodec.decode(value, defs.toArray(new Pair[defs.size()]),
                schemaVersion);
        Property[] properties = new Property[defs.size()];
        try {
            for (int i = 0; i < defs.size(); i++) {
                String field = defs.get(i).getField();
                PropertyType type = types.get(i);
                byte[] data = decodedResult.get(i);
                switch (types.get(i)) {
                    case BOOL:
                        properties[i] = getBoolProperty(field, data);
                        break;
                    case INT:
                   // 加入TIMESTAMP识别
                    case TIMESTAMP:
                    case VID:
                        properties[i] = getIntProperty(field, data);
                        break;
                    case FLOAT:
                        properties[i] = getFloatProperty(field, data);
                        break;
                    case DOUBLE:
                        properties[i] = getDoubleProperty(field, data);
                        break;
                    case STRING:
                        properties[i] = getStringProperty(field, data);
                        break;
                    default:
                        throw new IllegalArgumentException("Invalid type in schema: " + type);
                }
            }
        } catch (BufferUnderflowException e) {
            LOGGER.error("Decode value failed: " + e.getMessage());
        }
        return properties;
    }
`

```

**无法导出多版本数据（Schema 发生更改）**

这个原因是 ScanVertexProcessor 和 ScanEdgeProcessor 仅支持一个版本的数据解析：

![Schema 发生更改](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-9.png)

**解决方案：重写 ScanVertexProcessor 和 ScanEdgeProcessor 自动识别多版本数据：**


```
`public TagItem getSpecialVersionTagItem(String spaceName, int tagId, long version) {
        if (!spaceTagItemVersions.containsKey(spaceName)) {
            Map<Integer, Map<Long, TagItem>> tagVersionMap = Maps.newHashMap();
            List<TagItem> allTagItemList = getTags(spaceName);
            if (!allTagItemList.isEmpty()) {
                allTagItemList.forEach(tagItem -> tagVersionMap.computeIfAbsent(tagItem.getTag_id(), k -> Maps.newHashMap()).put(tagItem.getVersion(), tagItem));
                spaceTagItemVersions.put(spaceName, tagVersionMap);
            }
        }
        Map<Integer, Map<Long, TagItem>> tagVersionMap = spaceTagItemVersions.get(spaceName);
        if (Objects.isNull(tagVersionMap)) {
            return null;
        }
        return tagVersionMap.getOrDefault(tagId, Collections.emptyMap()).get(version);
    }

private RowReader getRowReader(String spaceName, ScanVertex scanTag, Map<Integer, RowReader> readers) {
        int tagId = scanTag.getTagId();
        // 解析当前tag数据的schema版本
        long schemaVersion = NebulaUtils.parseSchemaVersion(scanTag.getValue());
        Map<Integer, Map<Long, RowReader>> tagVersionReaderMap = spaceTagVersionReaders.computeIfAbsent(spaceName, k -> new ConcurrentHashMap<>());
        Map<Long, RowReader> versionReaderMap = tagVersionReaderMap.computeIfAbsent(tagId, k -> new ConcurrentHashMap<>());
        RowReader reader = versionReaderMap.get(schemaVersion);
        if (reader != null) {
            return reader;
        }
        //构建对应schema版本的RowReader
        TagItem tagItem = metaClient.getSpecialVersionTagItem(spaceName, tagId, schemaVersion);
        if (tagItem != null) {
            log.debug("Add special version tagItem | spaceName:{} | tagId:{} | schemaVersion:{}", spaceName, tagId, schemaVersion);
            versionReaderMap.computeIfAbsent(schemaVersion, k -> new RowReader(tagItem.schema, tagItem.version));
            return versionReaderMap.get(schemaVersion);
        }
        RowReader rowReader = readers.get(tagId);
        if (rowReader == null) {
            log.error("Not match vertex reader | spaceName:{} | tagId:{} | schemaVersion:{} | data={}", spaceName, tagId, schemaVersion, Hex.encodeHexString(scanTag.value));
        }
        return rowReader;
    }
//解析数据的schema版本，根据nebula源码翻译成的java代码
public static long parseSchemaVersion(byte[] row) {
        if (row == null || row.length == 0) {
            System.err.println("Row data is empty, so there is no schema version");
            return 0;
        }
        // The first three bits indicate the number of bytes for the
        // schema version. If the number is zero, no schema version
        // presents
        int verBytes = row[0] >> 5;
        int ver = 0;
        if (verBytes > 0) {
            if (verBytes + 1 > row.length) {
                // Data is too short
                // System.err.println("Row data is too short");
                return 0;
            }
            // Schema Version is stored in Little Endian
            for (int i = 0; i < verBytes; i++) {
                ver |= ((int) row[i + 1] << (8 * i));
            }
        }
        return ver;
    }
`

```

**每次 Scan 中断只能从头开始，无法接着上次的 cursor 继续导出**

这个问题发生的原因是因为 StorageClient 中的 scan 方法并未支持 cursor 参数传入：

![StorageClient](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-10.png)

**解决方案：重写 StorageClient 提供可传入 cursor 参数，每次 next 之后将 cursor 保存到数据库中，中断重新跑的时候使用之前的 cursor：**


```
`//增加cursor参数
public Iterator<ScanVertexResponse> scanVertex(
            String space, int part, Map<String, List<String>> returnCols, boolean allCols,
            int limit, long startTime, long endTime, byte[] cursor) throws IOException {
        HostAndPort leader = getLeader(space, part);
        if (Objects.isNull(leader)) {
            throw new IllegalArgumentException("Part " + part + " not found in space " + space);
        }

        int spaceId = metaClient.getSpaceIdFromCache(space);
        ScanVertexRequest request = new ScanVertexRequest();
        Map<Integer, List<PropDef>> columns = getVertexReturnCols(space, returnCols);
        request.setSpace_id(spaceId)
                .setPart_id(part)
                .setReturn_columns(columns)
                .setAll_columns(allCols)
                .setLimit(limit)
                .setStart_time(startTime)
                .setEnd_time(endTime)
               //设置cursor参数到request中
                .setCursor(cursor);

        return doScanVertex(space, leader, request);
    }
`


```

**指定扫描单个 Edge 或者 Tag 出现磁盘 IO 使用率 100%**

问题的原因：当 Space 中部分点或者边数量极大（比如几百亿），部分点或者边数据极小（比如几百万），当扫描极小的点或者边的时候就会出现磁盘 IO 使用率 100%；

**解决方案：以扫描所有的点或者边，不指定单个 Edge 或者 Tag。**


### nebula 同步服务设计

设计原则：

- 导出时不能影响线上 nebula 服务

- 尽量充分使用 nebula 服务资源进行同步

- 能够实时监控同步进度

- 可以随时停止/启动同步任务

设计要点：

- 自动适配不同时间段，不同导出频率和单次扫描数据量

- 根据 nebula 服务器的压力自动调整扫描任务数和频率

- 自动将扫描任务均衡到每台 nebula 服务器，避免出现 nebula 集群服务器负载不一致的情况

**重点问题解决**

这里着重讲讲如何解决一些具体的问题：

问题：每台 nebula-storaged 节点有着不同的 partition 分布，处理扫描任务越多 nebula-storaged 服务器负载就越高，如何实现每台 nebula-storaged 处理 Scan 扫描任务的数量一样？

**解决方案：**

1.改造 StorageClient 支持指定 storage address 进行 scan 操作；

2.通过 nebula-client 执行 show parts 拿到每个 part 对应的 leader 分布；

3.根据 part 对应 leader 分布，即可进行指定 part 同步均衡到每台 nebula-storaged 服务器上。

问题：如何做自动同步流控，主要针对源头 nebula，也就是从哪里导出。

主要从 3 个方面解决问题：

1.扫描频率

2.扫描行数

3.scan 任务数

扫描流控：


```
`//开启SCAN操作并指定游标，此游标是上次scan保存下来的
                Iterator<RESP> iterator = scan(client, space, tagOrEdgeNameList, part, statusDomain.getNextCursor());
                boolean isScanLimitConfigIterator = (iterator instanceof ScanLimitConfigIterator);
                while (iterator.hasNext()) {
                    if (isScanLimitConfigIterator) {
                        //设置scan行数，这里根据不同的时间段、机器的负载返回不同的值
                        int scanLimit = nebulaScanLimitController != null ? nebulaScanLimitController.getLimit() : this.scanLimit;
                        ((ScanLimitConfigIterator<?>) iterator).setScanLimit(scanLimit);
                    }
                    Result<RESP> result = scanNext(dataProcessor, iterator);
                    //将查询结果组装成insert语句并发送到MQ
                    writeResult(result);
                    //保存游标到数据库中
                    saveNextCursor(result.getResp());
                    //控制扫描频率
                    Optional.ofNullable(nebulaScanFlowController).ifPresent(flowController -> flowController.controlConsumeFlow(storageIp));
                }
`


```

scan 任务自动缩减：


```
`private void autoReduceTask() {
        log.debug("Start autoReduceTask....");
        //从数据库中查询当前处理的任务列表
        List<NebulaDataScanTaskEntity> taskList = queryProcessingTaskList();
        //遍历处理中的任务列表，统计每台机器当前处理的任务数量，如果超过限制，则停止超出任务
        List<NebulaDataScanTaskEntity> needCancelTaskList = calCancelTaskList(taskList);
        if (needCancelTaskList.isEmpty()) {
            log.debug("AutoReduceTask is fail, needCancelTaskList is empty");
            return;
        }
        Set<Long> cancelTaskIdList = needCancelTaskList.stream().map(NebulaDataScanTaskEntity::getId).collect(Collectors.toSet());
        log.info("Need cancel task list: {}", cancelTaskIdList);
        //取消需要停止的任务
        cancelSpecialTask(cancelTaskIdList);
    }

//计算需要取消的任务列表
private List<NebulaDataScanTaskEntity> calCancelTaskList(List<NebulaDataScanTaskEntity> taskList) {
        Map<String, List<NebulaDataScanTaskEntity>> nodeProcessingTaskCountMap = taskList.stream().collect(Collectors.groupingBy(NebulaDataScanTaskEntity::getScanStorageHost));
        List<NebulaDataScanTaskEntity> needCancelTaskList = new ArrayList<>();
        for (Map.Entry<String, List<NebulaDataScanTaskEntity>> et : nodeProcessingTaskCountMap.entrySet()) {
            List<NebulaDataScanTaskEntity> nodeProcessingTaskList = et.getValue();
            //根据节点并发限制（也就是一个nebula-storaged节点能处理几个scan任务），计算需要停止的任务
            int nodeConcurrencyLimit = nebulaNodeConcurrencyLimitController.getNodeConcurrencyLimit(HostAndPort.fromString(et.getKey()).getHostText());
            if (nodeProcessingTaskList.size() > nodeConcurrencyLimit) {
                //这里根据id进行排序，为了解决多机器并发取消问题
                Collections.sort(nodeProcessingTaskList, Comparator.comparing(NebulaDataScanTaskEntity::getScanTotalRowCount));
                needCancelTaskList.addAll(nodeProcessingTaskList.subList(0, nodeProcessingTaskList.size() - nodeConcurrencyLimit));
            }
        }
        return needCancelTaskList;
    }
`


```


流控配置信息：

![流控配置信息](https://nebula-website-cn.oss-cn-hangzhou.aliyuncs.com/nebula-website-5.0/share/2024-05-24-11.png)

以上，便是我完成的内核升级工作的分享。如果有你想了解更具体的细节，请留言评论。

作者：江一旺

校对 & 编辑：kristain

对图数据库 NebulaGraph 感兴趣？欢迎前往 GitHub ✨ 查看源码：[https://github.com/vesoft-inc/nebula；](https://github.com/vesoft-inc/nebula)

v3.6.0 版本，或者说最新发行版，会比 v1.0.0 版本具有更高的可维护性和稳定性、更完善的周边生态。此外 NebulaGraph v1.0.0 版本出问题基本上很难得到解决，另外扩缩容比较麻烦。