# 管理向量检索缓存
在构建亿级向量检索系统时，海量的高维向量索引需要驻留在内存中以支撑毫秒级的响应。然而，不同于传统的Elasticsearch/OpenSearch堆内存管理，CSS向量检索引擎基于C++构建，采用更具性能优势的堆外内存技术。随着索引规模的增长，如果缺乏有效的生命周期管理，系统可能会因非活跃索引占据过多空间而导致内存溢出（OOM），或因索引项频繁"换入换出"导致查询延迟波动。为了解决这一问题，CSS向量数据库提供了一套堆外内存管理策略，支持实时监控内存水位，通过预加载消除首查延迟，或利用"自动过期"动态释放冗余空间，确保集群在高负载下依然具备检索稳定性。
#### 功能介绍
CSS向量数据库将集群的物理内存划分为JVM堆内存和堆外内存，堆外内存的管理策略如下：
- 当首次查询命中时，向量索引文件会以Segment（段）为单位从磁盘加载至堆外内存，会有时延波动。
- 当再次查询该索引时，检索请求可以直接访问堆外内存中的索引，实现快速响应。
- 当内存满了或超过预设超时时间了，可以回收长时间不被访问的非活跃缓存，释放不再使用的堆外内存，保障集群在高负载下的稳定性。
 
#### 监控缓存状态
实时获取当前集群的节点堆外内存的负载情况及命中率，定位性能瓶颈。
执行以下命令监控缓存状态：
```
GET /_vector/stats
```
返回示例：
```
{
  "_nodes" : {  # 节点信息
    "total" : 1, # 总节点数
    "successful" : 1,          # 成功返回节点数
    "failed" : 0  # 执行失败节点数
  },
  "cluster_name" : "css-d3a7", # 集群名称
  "cpu_circuit_breaker_triggered" : false, # 是否已触发写入熔断
  "nodes" : {
    "cAHmVUZTR9ON7t6jxcDCkg" : {  # 节点UUID
      "cpu_cache_capacity_reached" : false,     # 当前节点的堆外内存是否达到使用上限
      "cpu_eviction_count" : 0,  # 当前节点segment级别缓存换出次数
      "cpu_hit_count" : 0,  # 当前节点segment级别缓存命中次数
      "cpu_load_exception_count" : 0,  # 当前节点segment级别索引加载异常次数
      "cpu_load_success_count" : 0,  # 当前节点segment级别索引加载正常次数
      "cpu_miss_count" : 0,   # 当前节点segment级别索引缓存未命中次数
      "cpu_query_memory_usage" : 0,  # 当前节点堆外内存使用量，单位为KB
      "cpu_total_load_time" : 0  # 当前节点segment级别索引加载到堆外内存的总耗时，单位为ms
    }
  }
}
```
#### 预加载核心索引
对新导入或核心业务的索引执行预加载，将索引预先加载到堆外内存中，消除首次查询时的磁盘加载延迟。
执行以下命令预加载指定索引：
```
PUT /_vector/warmup/{index_name}
```
表1参数说明 
| 参数         | 类型     | 默认值 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|:---|:---|:---|:---|
| index_name | String | 无   | 指定索引名称。只支持向量索引。 - 单个索引：直接输入索引名称（如"my_index"）。  - 多个索引：用英文逗号分隔多个索引（如"my_index1,my_index2"）。  - 通配符：支持通配符 \*（匹配任意字符），如"myindex\*"表示匹配所有以myindex开头的索引。   |
   
返回示例：
```
{
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  }
}
```
#### 配置自动清理缓存策略
在数据更新频繁或内存资源紧张的场景下，通过设置"缓存超时自动清理"，实现自动回收长时间不被访问的非活跃缓存，释放不再使用的堆外内存，保障集群在高负载下的稳定性。
执行以下命令启用"缓存超时自动清理"：
```
PUT _cluster/settings
{
  "persistent": {
    "native.cache.expiry.enabled": "true",
    "native.cache.expiry.time": "30m"
  }
}
```
表2参数说明 
| 参数                          | 类型      | 默认值   | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
|:---|:---|:---|:---|
| native.cache.expiry.enabled | Boolean | false | 是否启用缓存超时自动清理功能。开启后，长时间未访问的索引项将被释放。 取值范围： - true：开启缓存超时自动清理。  - false：关闭缓存超时自动清理。                                                                                                                                                                                                                                                                     |
| native.cache.expiry.time    | String  | 24h   | 缓存非活跃超时时间。 取值格式：数字+单位 - 数字：自然数  - 单位：s（秒）、m（分钟）、h（小时）、d（天）   例如"24h"（24小时）、"30m"（30分钟）。 |
   
#### 手动清除缓存
当向量索引的总大小超过缓存限制时，系统会自动执行索引项的换进换出操作。然而，这种频繁的换进换出可能会影响集群的查询性能。在删除索引或业务切换后，手动释放非活跃索引占用的堆外内存，确保热数据索引的查询性能不受影响。
- 清除全量索引的缓存
  ```
  PUT /_vector/clear/cache
  ```
  
- 清除指定索引的缓存
  ```
  PUT /_vector/clear/cache/{index_name}
  ```
  
返回示例：
```
{
  "acknowledged" : "true"
}
```