创建并存储向量嵌入

Neo4j 的 向量索引 和 向量函数 允许您计算图中节点和关系属性之间的相似度。使用这些功能的前提是必须先将向量嵌入（Embeddings）设置为这些实体的属性。本页面展示了如何使用 GenAI 插件在 Neo4j 数据库中创建这些嵌入并将其存储为节点和关系的属性。

有关如何在 Neo4j 数据库上使用 GenAI 插件的实践指南，请参阅 嵌入与向量索引教程 → 使用云 AI 提供商创建嵌入。

生成并存储单个嵌入

使用 ai.text.embed() 函数为单个值生成向量嵌入。

ai.text.embed() 的签名
函数2025.11 版本引入

语法

ai.text.embed(resource, provider, configuration = {}) :: VECTOR

描述

使用指定的提供商将资源编码为向量。

输入

名称

类型

描述

resource（资源）

STRING

要转换为嵌入的字符串。

provider

STRING

要使用的 AI 提供商的标识符（不区分大小写）。请参阅 提供商 获取支持的选项。

配置

MAP

提供商特定的配置选项。有关每个支持提供商的详细信息，请参阅 提供商。请注意，由于此参数可能包含敏感数据，因此它在 query.log 中会被脱敏处理。但是，如果函数调用拼写错误或查询格式不正确，它将被记录且不进行脱敏。

返回

VECTOR

为资源生成的向量嵌入。
此函数每次调用都会发送一个 API 请求，这可能会在网络流量和延迟方面产生大量开销。如果您想一次性生成多个嵌入，请使用 生成并存储一批嵌入。

企业版

ai.text.embed() 返回一个 VECTOR。在自托管实例上存储 VECTOR 值需要企业版和 块存储格式（block format）。

为《教父》（The Godfather）创建一个 VECTOR 嵌入属性
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, ai.text.embed(titleAndPlot, 'OpenAI', { token: $openaiToken, model: 'text-embedding-3-small' }) AS vector (2)
SET m.embedding = vector (3)
RETURN m.embedding AS embedding
1 将 Movie 的 title 和 plot 连接成一个单一的 STRING。
2 根据 titleAndPlot 创建嵌入。
3 将 propertyVector 存储到 The Godfather 节点的 embedding 属性（类型为 VECTOR）中。
结果（输出截断为前 4 项）
+----------------------------------------------------------------------------------------------------+
| embedding                                                                                          |
+----------------------------------------------------------------------------------------------------+
| [0.005239539314061403, -0.039358530193567276, -0.0005175105179660022, -0.038706034421920776, ... ] |
+----------------------------------------------------------------------------------------------------+

ai.text.embed() 返回一个 VECTOR，可以使用 toFloatList() 将其转换为列表。

要在社区版上运行此工作流，您需要使用 此转储文件（存储格式为 aligned）。
为《教父》创建一个 LIST<FLOAT> 嵌入属性
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, ai.text.embed(titleAndPlot, 'OpenAI', { token: $openaiToken, model: 'text-embedding-3-small' }) AS vector (2)
CALL db.create.setNodeVectorProperty(m, 'embedding', toFloatList(vector)) (3)
RETURN m.embedding AS embedding
1 将 Movie 的 title 和 plot 连接成一个单一的 STRING。
2 根据 titleAndPlot 创建嵌入。
3 将 propertyVector 存储到 The Godfather 节点的 embedding 属性（类型为 LIST<FLOAT>）中。过程 db.create.setNodeVectorProperty 和 db.create.setRelationshipVectorProperty 以更节省空间的方式存储列表。
结果（输出截断为前 4 项）
+----------------------------------------------------------------------------------------------------+
| embedding                                                                                          |
+----------------------------------------------------------------------------------------------------+
| [0.005239539314061403, -0.039358530193567276, -0.0005175105179660022, -0.038706034421920776, ... ] |
+----------------------------------------------------------------------------------------------------+

生成并存储一批嵌入

使用 ai.text.embedBatch 过程通过单个 API 请求生成多个向量嵌入。此过程接受一组资源列表作为输入，并返回相同数量的结果行。

ai.text.embedBatch() 的签名
过程2025.11 版本引入

语法

ai.text.embedBatch(resources, provider, configuration = {}) :: (index, resource, vector)

描述

使用指定的提供商将给定的资源批次编码为向量。

输入

名称

类型

描述

resources

LIST<STRING>

要转换为嵌入的字符串。

provider

STRING

要使用的 AI 提供商的标识符（不区分大小写）。请参阅 提供商 获取支持的选项。

配置

MAP

提供商特定的配置选项。有关每个支持提供商的详细信息，请参阅 提供商。请注意，由于此参数可能包含敏感数据，因此它在 query.log 中会被脱敏处理。但是，如果函数调用拼写错误或查询格式不正确，它将被记录且不进行脱敏。

返回

名称

类型

描述

index

INTEGER（整数）

输入列表中对应元素的索引，用于将结果关联回输入。

resource（资源）

STRING

给定的输入资源。

向量 (vector)

VECTOR

为该资源生成的向量嵌入。

此过程尝试在单个 API 请求中为所有提供的资源生成嵌入。提供过多的资源可能会导致 AI 提供商超时或拒绝请求。

企业版

ai.text.embedBatch() 为每个输入资源返回一个 VECTOR。在本地部署的实例上存储 VECTOR 值需要企业版和 块存储格式。

从有限数量的属性创建嵌入并将其存储为 VECTOR 属性
MATCH (m:Movie WHERE m.plot IS NOT NULL) LIMIT 20
WITH collect(m) AS moviesList (1)
WITH moviesList, [movie IN moviesList | movie.title + ': ' + movie.plot] AS batch (2)
CALL ai.text.embedBatch(batch, 'OpenAI', { token: $openaiToken, model: 'text-embedding-3-small' }) YIELD index, vector
WITH moviesList, index, vector
MATCH (toUpdate:Movie {title: moviesList[index]['title']})
SET toUpdate.embedding = vector  (3)
1 收集 所有 20 个 Movie 节点到一个 LIST<NODE> 中。
2 列表推导式 ([]) 将 moviesList 中电影的 title 和 plot 属性提取到一个新的 LIST<STRING> 中。
3 SET 对 ai.text.embedBatch() 返回的每个 vector 执行，并将该向量存储为相应节点上名为 embedding 的属性。
从大量属性创建嵌入并将其存储为 VECTOR 属性
MATCH (m:Movie WHERE m.plot IS NOT NULL) LIMIT 500
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 ai.text.embedBatch(batch, 'OpenAI', { token: $openaiToken, model: 'text-embedding-3-small' }) YIELD index, vector
    MATCH (toUpdate:Movie {title: moviesList[batchStart + index]['title']})
    SET toUpdate.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 子查询使用了 变量作用域子句。
5 batch 是一个字符串列表，每个字符串都是一部电影的 title 和 plot 的拼接。
6 此过程将 vector 设置为 moviesList 中位置为 batchStart + index 的节点的 embedding 属性的值。
7 将同时处理的批次数量设置为 1。有关事务中并发性的更多信息，请参阅 CALL 子查询 → 并发事务。
此示例可能无法扩展到更大的数据集，因为 collect(m) 要求将整个结果集加载到内存中。对于更适合处理大量数据的替代方法，请参阅 嵌入与向量索引教程 → 使用云 AI 提供商创建嵌入。

ai.text.embedBatch() 为每个输入资源返回一个 VECTOR，可以使用 toFloatList() 将其转换为列表。

要在社区版上运行这些工作流，您需要使用 此转储文件（存储格式为 aligned）。
从有限数量的属性创建嵌入并将其存储为 LIST<FLOAT> 属性
MATCH (m:Movie WHERE m.plot IS NOT NULL) LIMIT 20
WITH collect(m) AS moviesList (1)
WITH moviesList, [movie IN moviesList | movie.title + ': ' + movie.plot] AS batch (2)
CALL ai.text.embedBatch(batch, 'OpenAI', { token: $openaiToken, model: 'text-embedding-3-small' }) YIELD index, vector
WITH moviesList, index, vector
CALL db.create.setNodeVectorProperty(moviesList[index], 'embedding', toFloatList(vector)) (3)
1 收集 所有 20 个 Movie 节点到一个 LIST<NODE> 中。
2 列表推导式 ([]) 将 moviesList 中电影的 title 和 plot 属性提取到一个新的 LIST<STRING> 中。
3 每个向量被转换为浮点数列表并作为 embedding 属性（类型 LIST<FLOAT>）存储在相应节点上。过程 db.create.setNodeVectorProperty 和 db.create.setRelationshipVectorProperty 以更节省空间的方式存储列表。
从大量属性创建嵌入并将其存储为 LIST<FLOAT> 值
MATCH (m:Movie WHERE m.plot IS NOT NULL) LIMIT 500
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 ai.text.embedBatch(batch, 'OpenAI', { token: $openaiToken, model: 'text-embedding-3-small' }) YIELD index, vector
    CALL db.create.setNodeVectorProperty(moviesList[batchStart + index], 'embedding', toFloatList(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 子查询使用了 变量作用域子句。
5 batch 是一个字符串列表，每个字符串都是一部电影的 title 和 plot 的拼接。
6 此过程将 vector 设置为 moviesList 中位置为 batchStart + index 的节点的 embedding 属性的值。
7 将同时处理的批次数量设置为 1。有关事务中并发性的更多信息，请参阅 CALL 子查询 → 并发事务。
此示例可能无法扩展到更大的数据集，因为 collect(m) 要求将整个结果集加载到内存中。对于更适合处理大量数据的替代方法，请参阅 GenAI 文档 - 嵌入与向量索引教程 → 使用云 AI 提供商创建嵌入。

提供商

您可以通过以下提供商创建向量嵌入

  • OpenAI (openai)

  • Azure OpenAI (azure-openai)

  • Google Vertex AI (vertexai)

  • Amazon Bedrock Titan 模型 (bedrock-titan)

查询 CALL ai.text.embed.providers()（参见 参考）会显示插件安装版本中支持的提供商列表。

OpenAI

OpenAI 参数
名称 类型 默认 描述

model

STRING

-

模型 ID（参见 OpenAI → 模型）。

令牌 (token)

STRING

-

OpenAI API 密钥（参见 OpenAI → API 密钥）。

vendorOptions

MAP

{}

可选的供应商选项，将按原样传递给 OpenAI 的请求（参见 OpenAI → 创建嵌入）。
示例 — 嵌入字符串 Hello World!
WITH
  {
    token: $openaiToken,
    model: 'text-embedding-3-small',
    vendorOptions: {
      dimensions: 1024
    }
  } AS conf
RETURN ai.text.embed('Hello World!', 'openai', conf) AS result
您可以通过 genai.openai.baseurl 设置更改 OpenAI 的基础 URL（默认为 https://api.openai.com）。该更改适用于所有使用 OpenAI 的 ai.text.* 调用，包括 ai.text.embed、ai.text.embedBatch 和 ai.text.completion。请参阅 配置选项 → genai.openai.baseurl。

Azure OpenAI

OpenAI 参数
名称 类型 默认 描述

model

STRING

-

模型 ID（参见 Azure → Azure OpenAI in Foundry 模型）。

resource（资源）

STRING

-

Azure 资源名称。

令牌 (token)

STRING

-

Azure OAuth2 持有者令牌 (bearer token)。

vendorOptions

MAP

{}

可选的供应商选项，将按原样传递给 Azure 的请求。
示例 — 嵌入字符串 Hello World!
WITH
  {
    token: $azureToken,
    resource: 'my-azure-openai-resource',
    model: 'text-embedding-3-small',
    vendorOptions: {
      dimensions: 1024
    }
  } AS conf
RETURN ai.text.embed('Hello World!', 'azure-openai', conf) AS result

Google VertexAI

VertexAI 参数
名称 类型 默认 描述

model

STRING

-

模型资源名称（参见 Vertex AI → 模型库 (Model Garden)）。

project

STRING

-

Google Cloud 项目 ID。

region

STRING

-

Google Cloud 区域（参见 Vertex AI → 地点）。

publisher

STRING

'google'

模型发布者。

apiKey

STRING

-

Vertex AI API 密钥。

令牌 (token)

STRING

-

Vertex AI API 访问令牌。

vendorOptions

MAP

{}

可选的供应商选项，将按原样传递给 Vertex 的请求（参见 Vertex AI → 方法：models.predict）。
必须提供 apiKey 或 token 中的其中一个。
示例 — 嵌入字符串 Hello World!
WITH
  {
    token: $vertexaiApiAccessKey,
    model: 'gemini-embedding-001',
    publisher: 'google',
    project: 'my-google-cloud-project',
    region: 'asia-northeast1',
    vendorOptions: {
      outputDimensionality: 1024
    }
  } AS conf
RETURN ai.text.embed('Hello World!', 'vertexai', conf) AS result

Amazon Bedrock Titan 模型

此提供商支持所有使用与 Titan 文本模型 相同请求参数和响应字段的模型。

Amazon Bedrock Titan 配置
名称 类型 默认 描述

model

STRING

-

模型 ID 或其 ARN。

region

STRING

-

Amazon 区域（参见 Amazon Bedrock → 模型支持）。

accessKeyId

STRING

-

Amazon 访问密钥 ID。

secretAccessKey

STRING

-

Amazon 私有访问密钥。

vendorOptions

MAP

{}

可选的供应商选项，将按原样传递给 Bedrock 的请求（参见 Amazon Bedrock → 推理请求参数和响应字段）。
示例 — 嵌入字符串 Hello World!
WITH
  {
    accessKeyId: $awsAccessKeyId,
    secretAccessKey: $secretAccessKey,
    model: 'amazon.titan-embed-text-v1',
    region: 'eu-west-2',
    vendorOptions: {
      dimensions: 1024
    }
  } AS conf
RETURN ai.text.embed('Hello World!', 'bedrock-titan', conf) AS result

（旧版）提供商
已在 2025.11 版本中弃用

以下提供商配置用于 genai.vector.encode 函数和 genai.vector.encodeBatch 过程。这两个可调用对象已在 2025.11 版本中被弃用，并被 ai.text.embed 和 ai.text.embedBatch 所取代。有关旧可调用对象的更多信息，请参阅 旧版本文档。

OpenAI

配置映射
键 类型 描述 默认

令牌 (token)

STRING

API 访问令牌。

必填

model

STRING

要调用的模型的名称。

"text-embedding-ada-002"

dimensions

INTEGER（整数）

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

依赖于模型。

Vertex AI

配置映射
键 类型 描述 默认

令牌 (token)

STRING

API 访问令牌。

必填

项目 ID (projectId)

STRING

GCP 项目 ID。

必填

model

STRING

要调用的模型的名称。

"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 将应用于批次中的所有资源。

标题

STRING

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

Azure OpenAI

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

令牌 (token)

STRING

API 访问令牌。

必填

resource（资源）

STRING

模型部署所在的资源名称。

必填

deployment

STRING

模型部署名称。

必填

dimensions

INTEGER（整数）

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

依赖于模型。

Amazon Bedrock

配置映射
键 类型 描述 默认

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"