导入向量数据

功能介绍

CSS向量数据库支持两种传输格式：

• 浮点数组：标准JSON格式（如[1.0, 2.0]），可读性强，便于调试，适用于小规模数据。
• Base64编码：将单精度浮点数（小端字节序）转换为字符串。在相同维度的向量，Base64编码后的体积仅为JSON数组约1/3，显著降低网络带宽消耗，提升高维向量的处理效率。

根据业务场景可以选择合适的向量数据导入方式。

• 单条数据导入：适用于小规模数据或测试场景。
• Bulk批量导入：适用于大规模数据写入场景，通过合并多个写入请求降低网络开销。

向量数据库采用类LSM-Tree的持久化模型。数据写入时先进入内存缓冲区，随后定期刷新为磁盘上的“索引段（Segment）”。

• 实时构建（默认方式）：每产生一个Segment，系统立即为其构建HNSW图索引。这会造成写入抖动，且小Segment的合并会导致向量索引的重复计算。
• 离线构建：通过设置向量索引的“lazy_indexing”为“true”，系统仅保存向量数值。待全量数据导入后，由用户手动触发离线构建接口，系统会一次性完成Segment合并与索引构建，端到端提升写入和索引合并的性能。适用于海量数据离线导入、追求写入吞吐量且在导入期间无需进行实时检索的场景。

约束限制

• 写入的向量维度必须与创建索引时定义的“dimension”严格一致。
• 以Base64编码方式导入数据时，需确保数组已转换为小端字节序后再进行Base64编码，避免解析错误。
• 离线构建API仅适用于业务无实时性要求的场景，要求Elasticsearch集群的镜像版本号不低于7.10.2_24.3.3_x.x.x、OpenSearch集群的版本号为2.19.0。

单条数据导入

• 浮点数组格式

  POST my_index/_doc
  {
    "my_vector": [1.0, 2.0]
  }

• Base64编码格式

  POST my_index/_doc
  {
    "my_vector": "AACAPwAAAEA="
  }

Bulk批量导入

批量提交时，建议单批次大小控制在5MB ~ 15MB之间（约100~1000条数据），以平衡CPU负载与网络延迟。

• 浮点数组格式

  POST my_index/_bulk
  {"index": {}}
  {"my_vector": [1.0, 2.0], "my_label": "red"}
  {"index": {}}
  {"my_vector": [2.0, 2.0], "my_label": "green"}
  {"index": {}}
  {"my_vector": [2.0, 3.0], "my_label": "red"}

• Base64编码格式

  POST my_index/_bulk
  {"index":{}}
  {"my_vector":"AACAPwAAAEA=", "my_label": "red"}
  {"index":{}}
  {"my_vector":"AAAAQAAAAEA=", "my_label": "green"}
  {"index":{}}
  {"my_vector":"AAAAQAAAQEA=", "my_label": "red"}

Bulk API的详细使用说明请参见Bulk API。

（可选）触发离线构建

当向量字段启用了lazy_indexing（延迟构建索引）功能，则必须在写入数据后执行离线构建。否则VectorQuery标准查询将无法正常执行，系统会返回错误码500，错误信息包含“Load native index failed exception”。要解决此问题，需先完成离线构建操作，再进行查询。

离线构建API仅适用于业务无实时性要求的场景，要求Elasticsearch集群的镜像版本号不低于7.10.2_24.3.3_x.x.x、OpenSearch集群的版本号为2.19.0。

离线构建的执行流程包含两个步骤：

1. 合并索引段。
2. 基于最终的索引段构建向量索引。

执行以下命令，触发离线构建：

POST _vector/indexing/{index_name}
{
  "field": "my_vector"
}