# 导入向量数据
在大型搜索分析场景时，您需要将千万级甚至亿级高维向量高效地存入CSS向量数据库中。然而，向量数据体积远超普通文本，且HNSW等复杂索引结构的实时构建会占用大量CPU资源，直接影响写入吞吐量。为了解决这一矛盾，CSS向量数据库不仅支持直观的"浮点数组"导入，还提供了"Base64 编码"方案以压榨网络传输效率；同时，针对非实时检索场景，支持"先写入、后构建"的异步模式。通过这种方式，您可以先利用Bulk接口实现海量数据的急速"落盘"，再在业务低峰期触发离线构建，从而在有限的硬件资源下实现高效的数据接入。
#### 功能介绍
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或3.4.0（镜像版本不低于3.4.0_26.6.0_xxx） 。
 
#### 单条数据导入
- 浮点数组格式
  ```
  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](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/docs-bulk.html)。
 #### （可选）触发离线构建
当向量字段启用了lazy_indexing（延迟构建索引）功能，则必须在写入数据后执行离线构建。否则VectorQuery标准查询将无法正常执行，系统会返回错误码500，错误信息包含"Load native index failed exception"。要解决此问题，需先完成离线构建操作，再进行查询。
![](https://support.huaweicloud.com/usermanual-css/public_sys-resources/caution_3.0-zh-cn.png)
离线构建API仅适用于业务无实时性要求的场景，要求Elasticsearch集群的镜像版本号不低于7.10.2_24.3.3_x.x.x、OpenSearch集群的版本号为2.19.0或3.4.0（镜像版本不低于3.4.0_26.6.0_xxx）。
离线构建的执行流程包含两个步骤：
1. 合并索引段。
2. 基于最终的索引段构建向量索引。
执行以下命令，触发离线构建：
```
POST _vector/indexing/{index_name}
{
  "field": "my_vector"
}
```
表1离线构建的参数说明 
| 参数         | 是否必选 | 类型     | 说明                                                                                                            |
|:---|:---|:---|:---|
| index_name | 是    | String | 指定需要离线构建的索引名称。                                                                                                |
| field      | 是    | String | 指定需要构建索引的向量字段名称。 约束限制：该字段在Mapping中必须已设置"lazy_indexing"为"true"。 |