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，则通过添加额外参数 --env NEO4J_PLUGINS='["genai"]' 来启动 Docker 容器。欲了解更多信息，请参阅操作手册 → 配置插件。

在 Neo4j 5.23 之前，GenAI 插件仅在 Neo4j Enterprise Edition 中可用。

示例图

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

GenAI 提供商

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

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

表 2. 配置映射
键 类型 描述 默认值

token

STRING

API 访问令牌。

必需

model

STRING

您要调用的模型的名称。

"text-embedding-ada-002"

dimensions

INTEGER

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

取决于模型。

Azure OpenAI

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

token

STRING

API 访问令牌。

必需

resource

STRING

部署模型的资源的名称。

必需

deployment

STRING

模型部署的名称。

必需

dimensions

INTEGER

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

取决于模型。

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"