GenAI 集成

Neo4j 的 向量索引 和 向量函数 允许您计算图中节点和关系属性之间的相似度。使用这些功能的先决条件是将向量嵌入设置为这些实体的属性。GenAI 插件允许使用 GenAI 提供程序创建此类嵌入。

要使用 GenAI 插件，您需要从以下任何 GenAI 提供程序获取帐户和 API 凭据：Vertex AI、OpenAI、Azure OpenAI 和 Amazon Bedrock。

要详细了解在 Neo4j 中使用嵌入，请参阅 向量索引 → Neo4j 中的向量和嵌入。

有关如何使用 GenAI 插件的动手指南，请参阅 GenAI 文档 - 嵌入和向量索引教程 → 使用云 AI 提供程序创建嵌入。

安装

GenAI 插件在 Neo4j Aura 中默认启用。

需要在自管理实例上安装插件。方法是将 neo4j-genai.jar 文件从 Neo4j 主目录中的 /products 移动到 /plugins，或者如果您使用的是 Docker，则在启动 Docker 容器时添加参数 --env NEO4J_PLUGINS='["genai"]'。有关更多信息，请参阅 操作手册 → 配置插件。

在 Neo4j 5.23 之前，GenAI 插件仅在 Neo4j 企业版上可用。

示例图

本页上的示例使用 Neo4j 电影推荐 数据集，重点关注 Movie 节点的 plot 和 title 属性。

genai graph

该图包含 28863 个节点和 332522 个关系。有 9083 个 Movie 节点具有 plot 和 title 属性。

要重新创建该图，请将此 转储文件 下载并导入到空的 Neo4j 数据库（运行版本 5.17 或更高版本）。转储文件可以导入 Aura 和 本地 实例。

此嵌入使用 OpenAI（模型 text-embedding-ada-002）生成，产生 1536 维向量。

生成单个嵌入并将其存储

使用 genai.vector.encode() 函数为单个值生成向量嵌入。

genai.vector.encode() 的签名 函数
genai.vector.encode(resource :: STRING, provider :: STRING, configuration :: MAP = {}) :: LIST<FLOAT>

  • resource（一个 STRING）是要转换为嵌入的对象，例如文本片段或节点/关系属性。

  • provider（一个 STRING）是要使用的提供程序的不区分大小写的标识符。请参阅 GenAI 提供程序 中的标识符以了解支持的选项。

  • configuration（一个 MAP）包含特定于提供程序的设置，例如要调用的模型以及任何必需的 API 凭据。请参阅 GenAI 提供程序 以了解每个支持的提供程序的详细信息。请注意，由于此参数可能包含敏感数据，因此它在 query.log 中被混淆。但是，如果函数调用拼写错误或查询以其他方式格式错误，则它可能会在未被混淆的情况下被记录。

此函数每次被调用时都会发送一个 API 请求，这可能会在网络流量和延迟方面导致大量开销。如果您想一次生成多个嵌入，请使用 生成一批嵌入并将它们存储。

使用 db.create.setNodeVectorProperty 过程将嵌入存储到节点属性中。

db.create.setNodeVectorProperty 的签名 过程
db.create.setNodeVectorProperty(node :: NODE, key :: STRING, vector :: ANY)

使用 db.create.setRelationshipVectorProperty 过程将嵌入存储到关系属性中。

db.create.setRelationshipVectorProperty 的签名 过程 在 5.18 中引入
db.create.setRelationshipVectorProperty(relationship :: RELATIONSHIP, key :: STRING, vector :: ANY)

  • node 或 relationship 是将存储新属性的实体。

  • key（一个 STRING）是包含嵌入的新属性的名称。

  • vector 是包含嵌入的对象。

嵌入以 LIST<INTEGER | FLOAT> 类型存储在节点或关系的属性中。

示例 1. 从单个属性创建嵌入并将其存储
为《教父》创建嵌入属性
MATCH (m:Movie {title:'Godfather, The'})
WHERE m.plot IS NOT NULL AND m.title IS NOT NULL
WITH m, m.title || ' ' || m.plot AS titleAndPlot (1)
WITH m, genai.vector.encode(titleAndPlot, 'OpenAI', { token: $token }) AS propertyVector (2)
CALL db.create.setNodeVectorProperty(m, 'embedding', propertyVector) (3)
RETURN m.embedding AS embedding
1 将 Movie 的 title 和 plot 连接到一个 STRING 中。
2 从 titleAndPlot 创建一个 1536 维嵌入。
3 将 propertyVector 作为新 embedding 属性存储到《教父》节点上。
结果
+----------------------------------------------------------------------------------------------------+
| embedding                                                                                          |
+----------------------------------------------------------------------------------------------------+
| [0.005239539314061403, -0.039358530193567276, -0.0005175105179660022, -0.038706034421920776, ... ] |
+----------------------------------------------------------------------------------------------------+
此结果仅显示嵌入中 1536 个数字中的前 4 个数字。

生成一批嵌入并将它们存储

使用genai.vector.encodeBatch过程通过单个 API 请求生成多个向量嵌入。此过程以资源列表作为输入，并返回相同数量的结果行，而不是单个结果行。

此过程尝试在单个 API 请求中为所有提供的资源生成嵌入。因此，建议参考相应提供商的文档以获取详细信息，例如每个请求可生成的嵌入最大数量。
genai.vector.encodeBatch 的签名 过程
genai.vector.encodeBatch(resources :: LIST<STRING>, provider :: STRING, configuration :: MAP = {}) :: (index :: INTEGER, resource :: STRING, vector :: LIST<FLOAT>)

  • resources（一个LIST<STRING>）参数是将转换为嵌入的对象列表，例如文本片段。

  • provider（一个STRING）是将要使用的提供商的区分大小写的标识符。请参见 GenAI 提供商 以了解受支持的选项。

  • configuration（一个MAP）指定提供商特定的设置，例如要调用的模型，以及任何必需的 API 凭据。请参见 GenAI 提供商 以了解每个受支持提供商的详细信息。请注意，由于此参数可能包含敏感数据，因此在 query.log 中被混淆。但是，如果函数调用拼写错误或查询格式错误，则可能会在未混淆的情况下进行日志记录。

每行返回的数据包含以下列

  • index（一个INTEGER）是输入列表中对应元素的索引，用于帮助将结果关联回输入。

  • resource（一个STRING）是输入资源的名称。

  • vector（一个LIST<FLOAT>）是为该资源生成的向量嵌入。

示例 2. 从有限数量的属性创建嵌入并将其存储
MATCH (m:Movie WHERE m.plot IS NOT NULL)
WITH m
LIMIT 20
WITH collect(m) AS moviesList (1)
WITH moviesList, [movie IN moviesList | movie.title || ': ' || movie.plot] AS batch (2)
CALL genai.vector.encodeBatch(batch, 'OpenAI', { token: $token }) YIELD index, vector
WITH moviesList, index, vector
CALL db.create.setNodeVectorProperty(moviesList[index], 'embedding', vector) (3)
1 将所有 20 个Movie 节点收集到LIST<NODE> 中。
2 使用 列表推导式（[]）从moviesList 中的电影中提取title 和plot 属性到新的LIST<STRING> 中。
3 db.create.setNodeVectorProperty 针对genai.vector.encodeBatch 返回的每个vector 执行，并将该向量存储为对应节点上名为embedding 的属性。
示例 3. 从大量属性创建嵌入并将其存储
MATCH (m:Movie WHERE m.plot IS NOT NULL)
WITH collect(m) AS moviesList (1)
     count(*) AS total,
     100 AS batchSize (2)
UNWIND range(0, total, batchSize) AS batchStart (3)
CALL (moviesList, batchStart, batchSize) { (4)
    WITH [movie IN moviesList[batchStart .. batchStart + batchSize] | movie.title || ': ' || movie.plot] AS resources (5)
    CALL genai.vector.encodeBatch(batch, 'OpenAI', { token: $token }) YIELD index, vector
    CALL db.create.setNodeVectorProperty(moviesList[batchStart + index], 'embedding', vector) (6)
} IN TRANSACTIONS OF 1 ROW (7)
1 将所有返回的Movie 节点收集到LIST<NODE> 中。
2 batchSize 定义了moviesList 中要一次处理的节点数量。由于向量嵌入可能非常大，更大的批次大小可能需要 Neo4j 服务器上更多内存。过大的批次大小也可能超过提供商的阈值。
3 以batchSize 为增量处理Movie 节点。
4 一个 CALL 子查询 为每个批次执行一个单独的事务。请注意，此CALL 子查询使用 变量作用域子句（在 Neo4j 5.23 中引入）导入变量。如果您使用的是较旧版本的 Neo4j，请改用 导入WITH 子句。
5 resources 是一个字符串列表，每个字符串都是一部电影的title 和plot 的串联。
6 该过程将vector 设置为moviesList 中位置为batchStart + index 的节点上名为embedding 的属性的值。
7 将要一次处理的批次数量设置为1。
此示例可能无法扩展到更大的数据集，因为collect(m) 要求将整个结果集加载到内存中。有关更适合处理大量数据的替代方法，请参见 GenAI 文档 - 嵌入和向量索引教程 → 使用云 AI 提供商创建嵌入。

GenAI 提供商

以下 GenAI 提供商支持生成向量嵌入。每个提供商都有自己的配置映射，可以传递给genai.vector.encode 或genai.vector.encodeBatch。

Vertex AI

Vertex AI 提供商详细信息
表 1. 配置映射
键 类型 描述 默认值

token

STRING

API 访问令牌。

必需

projectId

STRING

GCP 项目 ID。

必需

model

STRING

您要调用的模型的名称。

支持的值

  • "textembedding-gecko@001" 在 5.17 中引入

  • "textembedding-gecko@002" 在 5.19 中引入

  • "textembedding-gecko@003" 在 5.19 中引入

  • "textembedding-gecko-multilingual@001" 在 5.19 中引入

"textembedding-gecko@001"

region

STRING

要发送 API 请求的 GCP 区域。

支持的值

  • "us-west1"

  • "us-west2"

  • "us-west3"

  • "us-west4"

  • "us-central1"

  • "us-east1"

  • "us-east4"

  • "us-south1"

  • "northamerica-northeast1"

  • "northamerica-northeast2"

  • "southamerica-east1"

  • "southamerica-west1"

  • "europe-west2"

  • "europe-west1"

  • "europe-west4"

  • "europe-west6"

  • "europe-west3"

  • "europe-north1"

  • "europe-central2"

  • "europe-west8"

  • "europe-west9"

  • "europe-southwest1"

  • "asia-south1"

  • "asia-southeast1"

  • "asia-southeast2"

  • "asia-east2"

  • "asia-east1"

  • "asia-northeast1"

  • "asia-northeast2"

  • "australia-southeast1"

  • "australia-southeast2"

  • "asia-northeast3"

  • "me-west1"

"us-central1"

taskType

STRING

预期的下游应用（请参见 提供商文档）。指定的taskType 将应用于批次中的所有资源。 在 5.19 中引入

title

STRING

正在编码的文档的标题（请参见 提供商文档）。指定的title 将应用于批次中的所有资源。 在 5.19 中引入

OpenAI

OpenAI 提供商详细信息
表 2. 配置映射
键 类型 描述 默认值

token

STRING

API 访问令牌。

必需

model

STRING

您要调用的模型的名称。

"text-embedding-ada-002"

dimensions

INTEGER

您希望将向量缩减到的维度数量。仅对某些模型支持。

模型相关。

Azure OpenAI

与其他提供商不同，模型是在 Azure 上创建部署时配置的，因此它不是配置映射的一部分。
Azure OpenAI 提供商详细信息
表 3. 配置映射
键 类型 描述 默认值

token

STRING

API 访问令牌。

必需

resource

STRING

已部署模型的资源的名称。

必需

deployment

STRING

模型部署的名称。

必需

dimensions

INTEGER

您希望将向量缩减到的维度数量。仅对某些模型支持。

模型相关。

Amazon Bedrock

Amazon Bedrock 提供商详细信息
表 4. 配置映射
键 类型 描述 默认值

accessKeyId

STRING

AWS 访问密钥 ID。

必需

secretAccessKey

STRING

AWS 密钥。

必需

model

STRING

您要调用的模型的名称。

支持的值

  • "amazon.titan-embed-text-v1"

"amazon.titan-embed-text-v1"

region

STRING

要发送 API 请求的 AWS 区域。

支持的值

  • "us-east-1"

  • "us-west-2"

  • "ap-southeast-1"

  • "ap-northeast-1"

  • "eu-central-1"

"us-east-1"