Kiwi Redis 8 Vector Set 存储设计（Phase 1 FLAT / Phase 2 HNSW） #331

AlexStocks · 2026-07-17T02:21:01Z

AlexStocks
Jul 17, 2026
Maintainer

# Kiwi Redis 8 Vector Set 存储设计

状态：Draft，等待整体 Review
日期：2026-07-16
最近更新：2026-07-18（补充 RocksDB / FAISS IVF 非阻塞预研策略）
目标版本：Phase 1（FLAT）与 Phase 2（HNSW）
讨论来源：arana-db/kiwi Discussion #301
集群前置依赖：Kiwi Raft Apply Correctness：父 Issue 与子 Issue 拆分方案

1. 背景与结论

Kiwi 需要增加原生向量能力。此前 Discussion #301 和 PR #326 采用的是 Redis Query Engine / RediSearch 路线：在 HASH 字段上挂载向量，通过 FT.CREATE 定义 schema，通过 FT.SEARCH 执行 KNN，并使用 SearchCF 维护二级索引。

该路线适合全文检索、JSON、标量过滤和向量混合查询，但会引入全局 schema、文档前缀匹配、二级索引一致性、跨 RocksDB instance 路由和跨分片查询聚合。对于当前目标“给 Kiwi 增加原生向量接口”，成本过高。

本设计改为兼容 Redis 8 原生 Vector Set：

VADD / VSIM / VREM / VCARD / VDIM / VEMB / VISMEMBER / VINFO

Vector Set 是一个真正的 Redis key，不依赖 HASH、JSON、FT.CREATE 或全局二级索引。

本设计的核心结论：

沿用 Kiwi 当前从 Pika/Floyd 演进来的统一 key 类型模型：MetaCF + 类型专属 CF + version + slot 路由 + RocksDB 多实例。
在 Rust 存储层增加原生 VectorSet 数据类型，不嵌入 Pika/Floyd C++ 引擎。
单个 Vector Set 的全部成员只存在于一个 RocksDB instance；不同 Vector Set key 通过 slot 分散。
Phase 1 以 MetaCF + VectorDataCF 为权威数据，使用 FLAT 精确搜索。
Phase 2 增加 HNSW，但 HNSW 只是本地可重建派生索引；权威源仍是 VectorDataCF。
Raft 复制 canonical logical mutation，不复制 HNSW 图，也不由 leader 预先计算 MetaCF 最终 count；通用 apply 正确性由 PR0 契约提供。
集群模式下 Vector Set 读默认采用 PR0 提供的 leader 线性一致读屏障。
大 Vector Set 的 DEL 只删除 MetaCF，成员数据通过 storage_incarnation + generation 隔离并由 compaction 后台回收。
多实例 snapshot 的单一 applied frontier 由 PR0 保证；VectorSet 只声明自身 schema、权威 CF 和恢复校验。

1.1 与 Raft PR0 的边界

本文不重复设计 Kiwi 的通用 Raft apply、crash replay、typed result、slot/instance 二次校验、确定性 TTL、snapshot barrier 和 ReadIndex 机制。这些能力统一由 Raft Apply Correctness 方案提供。

VectorSet cluster 模式只依赖该文第 9 节定义的能力契约，并在以下两类门禁都完成后才能开放：

PR0-A～PR0-D 的通用正确性门禁；
本文定义的 VectorSet codec、mutation、FLAT、生命周期、三节点和恢复门禁。

Standalone VectorSet 可以先行开发，但单机验证不能替代 PR0，也不能据此打开 cluster feature gate。

Cluster FLUSHDB/FLUSHALL 使用独立 feature gate。其优先设计方向是 database epoch；在该全局语义完成前，命令必须在 proposal 前确定性拒绝，不能执行本地物理 flush。该门禁只约束 cluster FLUSH，不自动阻断已经通过 PR0 与 VectorSet 门禁的其他 VectorSet 命令。

2. 设计目标

2.1 功能目标

Phase 1 支持以下核心命令：

VADD
VSIM
VREM
VCARD
VDIM
VEMB
VISMEMBER
VINFO

支持的参数：

VADD:
  FP32
  VALUES
  NOQUANT（Phase 1 必须显式指定）

VSIM:
  ELE
  FP32
  VALUES
  COUNT
  WITHSCORES
  TRUTH

Phase 1 同时完成：

原生 VectorSet 数据类型；
RocksDB 单实例和多实例存储；
Meta/member 原子写；
FLAT bounded top-K；
TTL、DEL、TYPE、EXISTS、SCAN 和 standalone FLUSH 生命周期；
基于 PR0 契约的 VectorSet logical mutation；
基于 PR0 契约的 leader 线性一致读；
VectorSet snapshot schema、restore validation、leader failover；
Redis 8 NOQUANT differential tests；
资源限制、超时、并发控制和指标。

2.2 一致性目标

写命令 VADD、VREM：

只能由 leader 接受，或者由 follower 按 Kiwi 统一策略转发/重定向；
必须经过 Raft quorum commit；
只在状态机 apply 和 RocksDB WriteBatch 成功后回复；
回复成功后 leader 的 MetaCF 和 VectorDataCF 已经持久化；
follower 按相同日志顺序 apply；
已确认成功的写在 leader 切换后不能丢失。

读命令 VSIM、VCARD、VDIM、VEMB、VISMEMBER、VINFO：

Phase 1 默认走 leader；
通过 OpenRaft ReadIndex / ensure_linearizable() 建立读屏障；
等待本地 state machine 追到 read index；
使用 RocksDB snapshot 读取稳定视图。

2.3 非目标

Phase 1 不实现：

REDUCE
CAS
Q8 / BIN 量化
EF / M
SETATTR / VSETATTR / VGETATTR
FILTER / FILTER-EF / WITHATTRIBS
EPSILON
NOTHREAD
VRANGE
VRANDMEMBER
VLINKS
跨 RocksDB instance 的单个 Vector Set 分片
全文检索、JSON 或标量混合查询

Phase 1 只支持 Redis Vector Set 的 NOQUANT 数据格式，并要求 VADD 显式指定 NOQUANT。Redis 8 省略量化选项时默认使用 Q8；Kiwi Phase 1 不得把省略选项静默解释为 NOQUANT，而是返回：

ERR default Q8 quantization is not supported in Phase 1; specify NOQUANT

3. 架构概览

Redis 8 VSet Commands
        |
        v
Command Parser
        |
        v
Canonical Vector
(normalized FP32 + original L2)
        |
        +----------------------+
        |                      |
        v                      v
Standalone Apply        Raft Logical Mutation
                               |
                               v
                       State Machine Apply
        |                      |
        +----------+-----------+
                   v
           key -> slot -> instance
                   |
                   v
             Atomic WriteBatch
              /             \
             v               v
        MetaCF          VectorDataCF
                             |
                             v
                  Phase 1 FlatVectorEngine
                             |
                             v
                         VSIM/TRUTH

Phase 2:
VectorDataCF -> local rebuild -> VectorIndexCF/HNSW -> VSIM

架构不变量：

1. VectorSet 是一个原生 Redis key。
2. 一个 VectorSet 永远只位于一个 RocksDB instance。
3. MetaCF + VectorDataCF 是唯一权威业务状态。
4. Meta 与成员在一个 RocksDB WriteBatch 中原子提交。
5. Raft 复制 logical mutation 和 canonical vector。
6. cluster 新 key 的 generation sequence 来自创建它的 Raft log index。
7. Phase 1 的 FLAT 直接扫描权威 VectorDataCF，不复制第二份 Flat index。
8. Phase 2 的 HNSW 可删除、可重建、可降级。
9. 索引故障只能造成性能下降，不能造成权威数据丢失。

4. Redis 8 接口兼容范围

兼容性判断以 2026-07-17 检查的 Redis unstable 提交 a4d0e84a47717e751cc218bababf02df0b0b5c17 中 Vector Set 命令实现为基线。Phase 1 明确记录偏差，不使用“内部同为 FP32”替代命令语义兼容。

4.1 VADD

支持：

VADD key FP32 blob element NOQUANT
VADD key VALUES num value [value ...] element NOQUANT

返回：

新增 element：1
更新已有 element：0

规则：

第一条 VADD 创建 VectorSet 并固定 dimension；
后续 VADD 的 dimension 必须一致；
key 已存在且不是 VectorSet 时返回 WRONGTYPE；
element 使用原始 bytes，不要求 UTF-8；
空 bulk string 是合法 element；RESP parser 必须区分空 bulk、null bulk 和参数缺失；
FP32 blob 使用 little-endian；
所有分量必须是有限 f32；
零向量或无效 norm 被拒绝；
Phase 1 只接受显式 NOQUANT；
省略量化选项按 Redis 默认 Q8 处理，但由于 Phase 1 不支持 Q8，返回明确错误；
显式 Q8 或 BIN 返回明确的 unsupported 错误；
不支持的选项必须返回明确错误，不能静默忽略。

示例错误：

ERR invalid vector specification
ERR vector dimension mismatch
ERR default Q8 quantization is not supported in Phase 1; specify NOQUANT
ERR VADD option Q8 is not supported yet
ERR VADD option BIN is not supported yet
WRONGTYPE Operation against a key holding the wrong kind of value

4.2 VSIM

支持：

VSIM key ELE element [WITHSCORES] [COUNT num] [TRUTH]
VSIM key FP32 blob [WITHSCORES] [COUNT num] [TRUTH]
VSIM key VALUES num value [value ...] [WITHSCORES] [COUNT num] [TRUTH]

默认：

COUNT = 10
WITHSCORES = false
TRUTH = false

Phase 1：

普通 VSIM -> FlatVectorEngine
VSIM TRUTH -> FlatVectorEngine

两者返回相同的精确结果，但代码中仍保留 Approximate 与 Truth 搜索模式。Phase 2 中普通模式切换到 HNSW，TRUTH 永远使用 FLAT。

ELE 的 element 不存在时返回：

ERR element not found in set

key 不存在时返回空数组，key 类型错误返回 WRONGTYPE。

4.3 VREM

VREM key element

返回：

删除成功：1
key/element 不存在：0
类型错误：WRONGTYPE

删除最后一个 element 后，整个 key 消失。

4.4 VCARD

VCARD key

VectorSet：返回 MetaCF.count；
key 不存在：返回 0；
类型错误：WRONGTYPE；
复杂度 O(1)，不扫描 VectorDataCF。

4.5 VDIM

VDIM key

VectorSet：返回 dimension；
key 不存在：ERR key does not exist；
类型错误：WRONGTYPE。

4.6 VEMB

VEMB key element

Phase 1 不支持：

VEMB key element RAW

RAW 不是普通 FP32 VEMB 的别名。Phase 1 必须返回明确的 unsupported 错误，不能用普通 double array 冒充 Redis RAW 结构；正确的 RAW 编码留到 Phase 2 单独实现。

普通 VEMB 从 value 中读取 normalized FP32 与 original L2，返回反标准化后的 double array：

output[i] = normalized[i] * original_l2

key 不存在：null；
element 不存在：null；
类型错误：WRONGTYPE。

4.7 VISMEMBER

VISMEMBER key element

element 存在：1；
key/element 不存在：0；
类型错误：WRONGTYPE；
使用 VectorDataCF point lookup，复杂度 O(1)。

4.8 VINFO

VINFO key

Phase 1 保持 Redis 当前九个字段：

字段	Phase 1 值
`quant-type`	`fp32`
`hnsw-m`	`0`，表示当前没有 HNSW
`vector-dim`	MetaCF.dimension
`projection-input-dim`	`0`
`size`	MetaCF.count
`max-level`	`0`，FLAT sentinel
`attributes-count`	`0`
`vset-uid`	当前 generation sequence，即 MetaCF.version
`hnsw-max-node-uid`	`0`，FLAT sentinel

缺失 key 返回 Redis 兼容的 null array，类型错误返回 WRONGTYPE。

Kiwi 私有状态不加入 VINFO，改由 INFO VECTOR 暴露，其中必须包含 index-kind=flat。

上述命令形状和九个字段与 Redis 8 对齐，但 hnsw-m=0、max-level=0 和 hnsw-max-node-uid=0 是 Kiwi Phase 1 对 FLAT 的明确 sentinel，不表示已经具备 Redis HNSW 的完整语义兼容性。

4.9 RESP2/RESP3

VSIM WITHSCORES：

RESP2：element, score, element, score 的扁平数组
RESP3：element -> double score 的 map

VINFO：

RESP2：字段名和值交替数组
RESP3：map

如果 Kiwi 当前 RESP 层缺少 Map，需要增加正式的 RESP3 Map 类型，不能在 RESP3 模式继续返回 RESP2 扁平数组后宣称完全兼容。

5. DataType 与 Column Family

5.1 DataType

保留已有值并追加：

pub enum DataType {
    String = 0,
    Hash = 1,
    Set = 2,
    List = 3,
    ZSet = 4,
    None = 5,
    All = 6,
    VectorSet = 7,
}

禁止重排已有数字。

补充：

DATA_TYPE_STRINGS += "vectorset"
DATA_TYPE_TAG += 'v'

TYPE key 返回 vectorset，SCAN TYPE vectorset 能识别该类型。

5.2 Phase 1 CF

新增：

VectorDataCF

如果实现时现有最后一个 CF index 是 5，则 VectorDataCF 追加为 6；如果仓库已经增加其他 CF，则继续追加，禁止重排。

Phase 1 不创建空的 VectorIndexCF。FLAT 直接扫描 VectorDataCF。

5.3 Phase 2 CF

Phase 2 追加：

VectorIndexCF

它是派生状态，不是权威数据。

6. MetaCF 编码

VectorSet 保留 Floyd/Kiwi 统一 metadata envelope：

| type | count | version | reserve | ctime | etime |
|  1B  |  8B   |   8B    |   16B   |  8B   |  8B   |

16 字节 reserve 解释为：

| meta_format | vector_encoding | metric | flags |
|     1B      |       1B        |   1B   |  1B   |

| dimension |
|    4B LE   |

| data_revision |
|     8B LE    |

Phase 1 固定：

meta_format       = 1
vector_encoding   = FP32_LE
metric            = COSINE
flags             = 0
data_revision     >= 1

Phase 1 的 metric 只允许 COSINE。其他 metric 必须返回明确的 unsupported 错误，不能写入 MetaCF。

version 字段在 VectorSet 中解释为 per-key generation sequence，标识该 key 的一次生命周期；data_revision 标识当前 generation 内的权威成员数据版本。两者职责不同：

generation sequence：DEL/过期/最后成员删除后重建必须变化
data_revision：当前 generation 内每次成功的 VADD/VREM 都递增

全局持久化的 storage_incarnation: u64 存在 schema/database manifest 中，不塞入 16 字节 reserve。它与 generation sequence 共同形成完整 generation identity：

VectorGeneration = (storage_incarnation, generation_sequence)

集群模式的 generation sequence 使用创建该 key 的 Raft log index；standalone 使用持久化单调生成器。Snapshot 必须保留 storage incarnation。复用旧数据目录或改变 cluster identity 时必须显式校验或迁移，不能静默重新解释旧 generation。

HNSW 的 index kind、index generation、M、quant type、build state、data revision 和构建来源 log id 都是 Phase 2 的本地派生状态，放入 VectorIndexCF manifest，不进入权威 VectorSet MetaCF。

Meta 包含：

struct VectorSetMeta {
    count: u64,
    generation_sequence: u64, // 编码在统一 envelope.version
    ctime: u64,
    etime: u64,
    meta_format: u8,
    vector_encoding: VectorEncoding,
    metric: VectorMetric,
    flags: VectorSetFlags,
    dimension: u32,
    data_revision: u64,
}

7. VectorDataCF 编码

7.1 Key

冻结的 V1 物理布局：

| codec_version | key_len | user_key | storage_incarnation | generation_sequence | element |
|      1B       | 4B BE   | key_len  |        8B BE        |        8B BE         | remainder |

规则：

codec_version = 1；
key_len 使用 u32 big-endian，拒绝不能表示的 key 长度；
element 占剩余全部字节，因此不需要单独长度字段，长度可以为 0；
big-endian 固定宽度整数保证默认 RocksDB bytewise comparator 下同一 prefix 连续；
decoder 必须校验最小长度、key_len 边界和 codec version，畸形 key 返回 corruption，不得 panic 或无界分配。

建议定义独立类型：

struct VectorMemberDataKey<'a> {
    key: &'a [u8],
    storage_incarnation: u64,
    generation_sequence: u64,
    element: &'a [u8],
}

支持：

encode_full(key, storage_incarnation, generation_sequence, element)
encode_prefix(key, storage_incarnation, generation_sequence)
prefix_upper_bound(prefix)

访问方式：

VEMB / VISMEMBER / VREM：full-key get/delete
VSIM：按完整 generation prefix scan

encode_prefix 正好结束在 generation sequence 之后；encode_full 只追加原始 element。使用默认 RocksDB bytewise comparator，不需要自定义数值 comparator。迭代器必须同时设置 lower bound 和由 prefix_upper_bound 计算的 exclusive upper bound，不能只依赖遇到非 prefix key 后退出。

7.2 Value V1

| magic | format | encoding | flags |
|  1B   |   1B   |    1B    |  1B   |

| dimension |
|    4B LE   |

| original_l2 |
|   4B FP32   |

| payload_len |
|    4B LE    |

| normalized FP32 payload |
|       dimension * 4B      |

建议：

magic       = 0x56
format      = 1
encoding    = FP32_LE
flags       = NORMALIZED

读取时校验：

magic；
format；
encoding；
dimension 与 MetaCF 一致；
payload_len 等于 dimension × 4；
实际长度一致；
original L2 有效；
payload 分量 finite。

8. Canonical Vector

8.1 写入转换

客户端 FP32/VALUES
    -> 解码 f32
    -> finite 校验
    -> 使用 f64 累加 norm²
    -> original_l2
    -> 拒绝零/非法 norm
    -> 标准化
    -> canonical little-endian FP32 bytes

Raft 只复制 canonical bytes 与 original L2，不让各副本重新解析字符串或重新标准化。

8.2 Score

内部 normalized cosine：

dot ∈ [-1, 1]
score = (dot + 1) / 2
score clamp 到 [0, 1]

距离累加使用 f64，最终 RESP 返回 double。

8.3 稳定排序

score 降序
score 相同时 element 原始 bytes 升序

9. 多 RocksDB Instance 路由

所有 VectorSet 操作只按 user key 路由一次：

let slot_id = key_to_slot_id(key);
let instance_id = slot_indexer.get_instance_id(slot_id);
self.insts[instance_id].vector_operation(...)

禁止：

按 element 路由
同一 VectorSet 跨 instance
VSIM fan-out 所有 instance
Meta 与 member 跨 instance

多实例扩展单位是不同 VectorSet key，不是同一 VectorSet 的成员。

Phase 1 不支持在线修改 db_instance_num。磁盘元信息必须记录 instance 数，启动时配置不一致应拒绝打开。

10. 原子状态转换

10.1 新建 VectorSet

获取 key 独占锁
确认 key 不存在
取得 storage_incarnation
生成 deterministic generation_sequence

WriteBatch:
  PUT MetaCF[key] = meta(count=1, generation_sequence, data_revision=1)
  PUT VectorDataCF[key, storage_incarnation, generation_sequence, element] = vector

COMMIT
返回 1

10.2 新增 element

获取 key 独占锁
读取 MetaCF 和 element

WriteBatch:
  PUT member
  PUT MetaCF count+1
  PUT MetaCF data_revision+1

COMMIT
返回 1

10.3 更新 element

WriteBatch:
  PUT existing member = new vector
  PUT MetaCF data_revision+1

count 不变
返回 0

10.4 VREM

element 不存在：返回 0

count > 1:
  DELETE member
  UPDATE Meta count-1
  UPDATE Meta data_revision+1

count == 1:
  DELETE member
  DELETE MetaCF key

返回 1

最后一个成员删除时，该 generation 的生命周期结束；逻辑 mutation 仍对应下一 data revision，但 MetaCF 已在同一 batch 中删除，无需为已死亡 generation 单独保留 revision。后续同名重建必须取得新的 generation sequence，并从 data_revision=1 开始。

DEL、TTL 过期和 standalone FLUSH* 同样结束当前 generation。Cluster FLUSHDB/FLUSHALL 在 database epoch 方案完成前不进入 mutation apply。所有输入和格式错误必须在创建 WriteBatch 前返回。

11. FLAT 查询引擎

接口：

trait VectorIndexEngine {
    fn search(
        &self,
        snapshot: &VectorSetSnapshot,
        query: &CanonicalVector,
        options: SearchOptions,
    ) -> Result<Vec<VectorHit>>;
}

Phase 1：

struct FlatVectorEngine;

流程：

1. leader 线性一致读屏障
2. 路由到唯一 RocksDB instance
3. 创建 RocksDB snapshot
4. 从同一 snapshot 读取 MetaCF
5. 构造 storage incarnation + generation prefix
6. seek + forward scan VectorDataCF
7. 逐条解码并计算 score
8. 使用容量 K 的 bounded heap
9. 每处理固定 entry 数或 byte 数检查取消、deadline 和 scan budget
10. 稳定排序并返回

复杂度：

时间：O(N × DIM + N log K)
额外内存：O(K + DIM)

禁止把全部向量或全部 hit 收集到 Vec 后全排序。查询 deadline 从进入 FLAT 队列时开始计算，包含 semaphore/线程池排队时间；超时、取消、budget 超限或 decode 错误都必须通过 RAII 释放 snapshot、iterator、permit 和临时 heap，并返回完整错误，不返回部分结果。

12. 并发与 RocksDB Snapshot

VADD/VREM 使用一个 WriteBatch 提交 Meta/member。VSIM 使用同一 RocksDB snapshot 读取 Meta/member，因此只能看到完整的提交前状态或提交后状态。

VSIM 期间发生 VADD：本次可看不到新成员，下次必须看到。
VSIM 期间发生 VREM/DEL：本次可以继续看到 snapshot 中旧成员。

VSIM 不应在全量扫描期间持有 key 写锁。

13. VectorSet Logical Mutation 契约

本节只定义 VectorSet 专属 payload 和状态转换。通用 proposal、apply marker、durable frontier、fatal/business error 分类、结果重放、slot/instance 校验及 crash recovery 由 Raft PR0 能力契约提供。

13.1 复制逻辑 mutation，而不是最终物理状态

并发请求可能同时读取相同旧 count。如果 leader 在 proposal 前生成物理 MetaCF count，顺序 apply 后会发生成员数与 count 不一致。Raft 日志只复制：

Add(element, canonical_vector)
Remove(element)

状态机按日志顺序读取当前 Meta/member，决定新增、更新、删除、count、generation 和 data revision，再在目标 RocksDB instance 内构造一个原子 WriteBatch。HNSW 图和本地派生状态不进入日志。

13.2 VectorSet mutation V1

VectorSet logical mutation 必须有显式版本，并封装在 PR0 的通用 LogicalMutation 中：

enum VectorSetMutationV1 {
    Add {
        element: Vec<u8>,
        dimension: u32,
        original_l2: f32,
        canonical_vector: Vec<u8>,
    },
    Remove {
        element: Vec<u8>,
    },
}

mutation 中不包含最终 count、最终 data revision、HNSW node/edge 或本地 index generation。空 element 是合法 payload；decoder 必须区分空 bytes 和字段缺失。

13.3 Proposal 前校验

不依赖数据库状态的错误不进入 Raft：

arity 和选项顺序
显式 NOQUANT；省略选项产生默认 Q8 unsupported 错误
FP32 长度或 VALUES 数量
dimension 和资源上限
NaN/Infinity、零向量或无效 norm
element/blob/K 限制
mutation codec 合法性

解析成功后只传 canonical FP32 + original L2，所有副本不得重复执行可能产生浮点差异的输入归一化。

13.4 Apply 阶段的 VectorSet 决策

依赖当前状态的结果由状态机决定：

key 是否存在以及类型
dimension 是否匹配
element 是否存在
新增还是更新
删除是否生效
count 和 data_revision 的下一值
首次创建时的 generation_sequence

首次创建的 generation_sequence 使用 ApplyContext.log_id.index；已有 key 的 VADD/VREM 保持 generation 不变。Standalone 走同一 mutation 函数，但从持久化单调生成器取得首次创建的 generation sequence。

13.5 唯一 mutation API

pub fn apply_vector_set_mutation(
    &self,
    key: &[u8],
    mutation: &VectorSetMutationV1,
    ctx: &ApplyContext,
) -> Result<VectorSetApplyResult, VectorSetApplyError>;

Standalone 和 Raft apply 必须复用此入口。Cluster 模式禁止先本地写再 proposal；leader 也只能通过 state machine apply 修改权威数据。

返回值只表达命令所需的 typed result，例如 VADD 的新增/更新和 VREM 的删除/未命中；RESP 编码留在 cmd 层。通用层负责把 typed business error 与 fatal storage/protocol error 分开，VectorSet 不定义第二套错误与重放机制。

14. 读一致性

Phase 1 所有 VectorSet 读默认 leader 线性一致：

leader
  -> ReadIndex / ensure_linearizable
  -> 等待 applied >= read index
  -> RocksDB snapshot
  -> 查询

PR0 的 ReadIndex/linearizable barrier 保证本地状态机追到 committed 点，RocksDB snapshot 保证扫描期间读取稳定本地视图。

Phase 1 不开放默认 follower read。未来可显式增加 eventual consistency 模式。

15. 错误分类

15.1 用户状态错误

例如 WRONGTYPE、dimension mismatch：

mutation 可能已经 committed；
apply 不修改数据；
返回确定性业务错误；
继续后续日志。

15.2 协议/日志损坏

例如：

logical envelope 无法解码
未知 format version
slot 不匹配
canonical blob 非法
logical/physical entry 混合

节点停止正常 apply，并通过 snapshot 或人工恢复。禁止跳过日志。

15.3 RocksDB I/O 错误

WriteBatch commit、CF、磁盘或 checksum 错误：

节点标记 unhealthy；
停止提供线性一致读；
不声称写成功；
重试 apply 或通过 snapshot 恢复；
不能 warn 后继续下一条日志。

16. 大 Key 删除与 Compaction

16.1 DEL

VectorSet DEL 前台只删除 MetaCF：

WriteBatch:
  DELETE MetaCF[key]

禁止同步扫描全部 VectorDataCF 成员。

删除后旧 generation 成员不可见，新建同名 key 使用新的 generation sequence。

16.2 类型化 del_key

通用 del_key 改为按 metadata type dispatch。VectorSet 使用 O(1) 逻辑删除，不能继续扫描所有 CF。

16.3 Compaction Filter

VectorDataCF 接入 DataCompactionFilter。以下情况删除 member：

MetaCF 不存在
MetaCF type != VectorSet
MetaCF 已过期
data storage_incarnation != 当前 schema manifest
Meta generation_sequence != data generation_sequence

无法读取/证明 stale 时保留，不删除。

16.4 后台清理

DEL 后轻量 enqueue：

BgTask::CompactSpecificKey(
    VectorSet,
    key,
    old_storage_incarnation,
    old_generation_sequence,
)

enqueue 失败不回滚 DEL，由自然 compaction 兜底。

Engine 已有 DeleteRange 能力，但它只是可基准验证的性能优化，不是正确性前提。Phase 1 默认仍采用 Meta 删除 + targeted compact + natural compaction；只有证明 range tombstone 对目标 workload、snapshot 和 compaction amplification 有净收益后，才能单独引入 DeleteRange。

16.5 VREM

VREM 写单个 delete tombstone；最后成员时同时删除 MetaCF。物理 SST 空间由 RocksDB compaction 回收。

17. Snapshot

17.1 构建 barrier

多个 RocksDB instance 的单一 applied frontier、checkpoint barrier、失败回滚和 durable snapshot metadata 全部由 PR0 snapshot 契约提供。VectorSet 不在自身模块重新实现暂停 apply 或协调 checkpoint 的逻辑。

17.2 Snapshot Meta V2

struct RaftSnapshotMetaV2 {
    version: u32,
    last_included_index: u64,
    last_included_term: u64,
    storage_schema_version: u32,
    storage_incarnation: u64,
    db_instance_num: u32,
    column_families: Vec<String>,
    vector_value_format_max: u8,
}

拒绝不支持的未来版本、storage incarnation/cluster identity 不合法、instance 数不一致、缺失 CF 或未知 value format。

17.3 恢复

暂停请求
解包临时目录
校验 meta/CF/instance
关闭旧 Storage
恢复 checkpoint
重新打开全部 instance
抽样解码 VectorSet
ArcSwap 切换
由 PR0 恢复 durable applied frontier
恢复请求

不在恢复路径全量扫描所有向量。

18. Leader 切换

Phase 1 没有派生 HNSW。新 leader 通过 PR0 恢复并追到 committed/applied frontier 后，即可通过 FLAT 提供正确查询。

Phase 2：

HNSW READY，且 manifest generation/data_revision 与当前 Meta 完全相等：使用该 immutable index generation
HNSW 缺失、BUILDING/DIRTY 或 generation/revision 不匹配：使用 FLAT，后台追平或重建

leader 切换不能因为 HNSW 未准备好而让 VSIM 不可用。

19. 滚动升级门禁

新增 VectorDataCF 和 LogicalCommand 后，旧 follower 无法安全 apply 新日志。

升级分两阶段：

部署支持新 CF、decoder、apply、snapshot 的 binary，但 vector.enabled=false。
确认所有 voting members 具备以下 capability 后显式启用：

vector_set_storage_v1
vector_set_raft_mutation_v1
snapshot_schema_v2

一旦集群写入 VectorSet，不能直接降级到不识别新 CF/日志格式的版本。

20. 数据损坏处理

MetaCF 格式损坏：

返回 storage corruption；
阻止继续修改该 key；
不自动重建 count；
通过 snapshot/repair 恢复。

FLAT 扫描发现单个 VectorValue 损坏：

整个 VSIM 失败；
不跳过损坏成员返回部分 top-K；
记录脱敏诊断和指标。

21. 资源控制

建议配置：

[vector]
enabled = true
max_dimension = 4096
max_k = 1000
max_element_bytes = 1048576
max_vector_bytes = 16777216
max_concurrent_flat_queries = 4
flat_query_timeout_ms = 5000
flat_cancel_check_interval = 256
flat_scan_max_entries = 1000000
flat_scan_max_bytes = 1073741824

硬上限：

dimension <= 65536

FLAT 查询运行在独立 blocking/CPU 执行面，使用 semaphore 限制并发。deadline 包含排队时间；扫描每 N 个 entries 或 bytes 协作检查取消、timeout 和 budget。任何中止都通过 RAII 清理资源并返回完整错误，不返回部分结果。

22. INFO VECTOR 与指标

Redis 兼容 VINFO 不增加私有字段。Kiwi 运维信息通过：

INFO VECTOR

Phase 1 至少暴露：

index-kind=flat

建议指标：

vector_sets
vector_elements
vector_storage_bytes
vector_flat_queries_total
vector_flat_query_duration_seconds
vector_flat_query_timeouts_total
vector_flat_query_errors_total
vector_search_capacity_rejected_total
vector_raft_mutations_applied_total
vector_raft_mutation_errors_total
vector_stale_cleanup_queue_depth
vector_stale_cleanup_completed_total
vector_stale_cleanup_failed_total
vector_compaction_deleted_entries_total

Phase 2 增加 HNSW READY/BUILDING/DIRTY 和 FLAT fallback 指标。

23. 模块边界

23.1 storage

src/storage/src/vector/
├── mod.rs
├── types.rs
├── meta.rs
├── key.rs
├── value.rs
├── codec.rs
├── mutation.rs
├── flat.rs
├── snapshot.rs
└── metrics.rs

src/storage/src/redis_vectors.rs

23.2 cmd

src/cmd/src/vector/
├── mod.rs
├── parser.rs
├── vadd.rs
├── vsim.rs
├── vrem.rs
├── vcard.rs
├── vdim.rs
├── vemb.rs
├── vismember.rs
└── vinfo.rs

23.3 职责

命令层：argv、选项、无状态校验、RESP 编解码、构造 mutation。
存储层：类型、路由、锁、Meta/member、WriteBatch、snapshot、FLAT。
Raft 层：日志、共识、apply 顺序、ReadIndex、typed response、snapshot index。

禁止 cmd 直接拼 RocksDB key，禁止 storage 创建 RespData，禁止 Raft 实现 cosine。

24. 测试门禁

24.1 Codec 与 Property Tests

Meta reserve V1；
Member key V1 golden/property tests：空 element、包含 0x00、key/element 前缀关系、最大 key 长度边界、畸形长度/codec version、prefix upper bound、full/prefix round trip；
Value V1；
FP32 LE；
normalize/de-normalize；
binary 和空 element；
长度、溢出、NaN、Infinity、零向量；
encode/decode round trip；
parser/codec fuzz 无 panic 和无界分配。

24.2 单实例 Storage

首次、新增、更新 VADD；
显式 NOQUANT 成功、省略选项返回默认 Q8 unsupported、显式 Q8/BIN unsupported；
dimension mismatch、WRONGTYPE；
空 element 在 RESP2/RESP3 下的 VADD/VISMEMBER/VEMB/VREM；
VREM 与最后成员；
VCARD、VDIM、VEMB、VISMEMBER；
VEMB RAW 明确 unsupported；
VINFO 九字段、FLAT sentinel、RESP2 array、RESP3 map 和缺失 key null array；
VSIM top-K/TRUTH；
TTL、DEL、同名重建；
generation/data_revision 生命周期；
WriteBatch 原子性；
compaction cleanup：Meta 缺失、type/generation/incarnation 不匹配时删除，Meta 无法读取时保留。

24.3 多实例

使用至少 3 个 RocksDB instance，生成分别路由到不同 instance 的 VectorSet key，验证 Meta/member 只存在目标 instance，element 不参与路由，snapshot/restore 后映射不变。

24.4 三节点 Raft

quorum commit；
并发 VADD；
并发首次创建不同 dimension；
类型竞争；
response 丢失后重试；
follower 追赶；
leader failover；
snapshot install + log replay；
网络分区；
少数派拒绝写；
各副本 MetaCF/VectorDataCF bytes 完全一致。

24.5 Redis Differential

同一测试发送给 Redis 8 和 Kiwi，双方都显式使用 NOQUANT，比较 RESP2/RESP3、返回类型、错误类别、空/binary element、element 顺序、score/VEMB 容差。Redis 默认 Q8 的成功路径不伪装成 Phase 1 已兼容；Kiwi 对省略选项的 Phase 1 错误单独做契约测试。

24.6 故障注入

覆盖 Meta read、member read、batch put/commit、Raft proposal/commit、snapshot 每个 instance、snapshot meta write、cleanup enqueue、compaction Meta lookup，以及长时间 FLAT 扫描中的排队超时、协作取消和 RAII 清理。

25. 性能门禁

VADD/VREM：O(1)，不扫描成员或其他 instance。
VCARD/VDIM/VEMB/VISMEMBER：point lookup。
DEL：前台 O(1)，不构造与成员数线性相关的 batch。
VSIM：O(N×DIM + N log K)，额外内存 O(K+DIM)。

建议 benchmark：

普通 CI 使用 10K，定时 benchmark 运行 100K/1M。

26. Phase 1 完成标准

只有同时满足以下条件才宣布正式支持：

八个核心命令；
RESP2/RESP3；
显式 NOQUANT 与 Redis differential，省略/Q8/BIN 明确 unsupported；
空 binary element；
VINFO FLAT sentinel 和缺失 key null array；
冻结的 Member Key V1 codec；
Meta/member 原子；
storage incarnation、generation sequence、data revision 生命周期；
单 key 单 instance；
FLAT bounded top-K、scan budget、deadline 和协作取消；
DEL/TTL/TYPE/EXISTS/SCAN 和 standalone FLUSH；
cluster FLUSHDB/FLUSHALL 在 database epoch 设计完成前由独立 feature gate 确定性拒绝；
compaction cleanup；
PR0 已完成且 VectorSet logical mutation/generation/typed result 契约通过；
leader 线性一致读；
三节点 failover；
snapshot barrier/restore/log replay；
capability gate；
Linux 集成测试及全平台构建；
fuzz、故障注入和运维文档。

只有命令能运行和单机测试通过，不代表 Phase 1 完成。

27. Phase 2：HNSW 派生索引

新增 VectorIndexCF，状态：

ABSENT
BUILDING
READY
DIRTY

每个 VectorSet 的 VectorIndexCF manifest 至少包含：

vector_generation = (storage_incarnation, generation_sequence)
data_revision
index_generation
index_format_version
source_applied_log_id
state = ABSENT / BUILDING / READY / DIRTY
M
quant_type

HNSW node/edge/element map 归属于一个 immutable index_generation。普通 VSIM 只有同时满足以下条件才能使用 HNSW：

state == READY
manifest.vector_generation == 当前 Meta generation（含 storage incarnation）
manifest.data_revision == 当前 Meta data_revision
查询全过程 pin 同一个 immutable index_generation

任一条件不满足都回退 FLAT。source_applied_log_id 只用于构建来源、诊断和可观测性，不能替代 per-set generation/data_revision 新鲜度判断。

构建流程从权威 VectorDataCF snapshot 生成新的 immutable index generation；发布前重新读取 Meta，确认 generation 和 data revision 未变化，再原子切换为 READY。旧 index generation 延迟清理，不能在仍有查询 pin 时删除。

TRUTH：永远扫描 VectorDataCF。
Raft：不复制 node/edge/index generation。
Q8/BIN：由 canonical FP32 + original L2 本地构建。

27.1 RocksDB / FAISS IVF 的非阻塞预研策略

RocksDB 从 10.0 起通过实验性的 SecondaryIndex 框架提供 FaissIVFIndex。它包装的是预训练的 FAISS IndexIVF，使用 coarse list + inverted lists 做 KNN，并依赖 TransactionDBOptions.secondary_indices 维护主列与二级列的一致性。它是 IVF 能力，不是 HNSW，也不是 Kiwi 当前 Phase 2 的直接依赖。

已确认的定位：

Phase 1 仍然只实现权威 VectorDataCF + 精确 FLAT；Phase 2 的当前主线仍然是本地派生 HNSW。本节不改变两阶段范围、完成门禁或 PR 顺序。
arana-db/rust-rocksdb 暂未暴露上游 SecondaryIndex / FaissIVFIndex 接口，不视为预研阻断项。Kiwi 可以借鉴 RocksDB C++ 实现的算法分层、RocksDB inverted-list 布局和 iterator adapter，在 Rust 存储层实现自己的磁盘 IVF 适配器；这里是设计复刻，不要求逐行移植，也不提前冻结持久化 codec。
如果小型 PoC 证明成本可控，也允许在 arana-db/rust-rocksdb 增加最小 Rust/C++ bridge。bridge 可以只暴露 FAISS 训练/量化/搜索原语，也可以评估直接绑定 SecondaryIndex / FaissIVFIndex；但不得因为复用该实验接口，就默认把 Kiwi 现有普通 RocksDB DB 全面迁移到 TransactionDB。
Rust 原生实现和最小 bridge 不预先指定胜者，最终选择必须由相同数据集、相同持久化语义和相同故障模型下的 PoC 结果决定。若直接绑定要求大范围改造 DB 生命周期、写路径或跨平台构建，则按高成本方案淘汰，而不是为复用 C++ 接口改写 Kiwi 主架构。
无论采用哪条路径，向量成员仍是权威数据；IVF 与 HNSW 一样只能是本地可删除、可重建的派生索引。Raft 不复制 coarse centroid、posting list、PQ code 或 FAISS 内部状态；索引缺失、损坏、过期或版本不兼容时必须回退 FLAT。
磁盘 IVF 目前不创建实现 Issue、不纳入 Phase 1/PR0 门禁。只有在 HNSW 基线、真实数据规模和运维目标证明有磁盘 ANN 需求后，再从本 Discussion 拆出独立预研 Issue。

PoC 至少要回答：

三平台构建：Linux、macOS、Windows；FAISS、C++ runtime、静态/动态链接和发布包体积是否可接受；
Rust/FFI 边界：错误传播、panic/exception 隔离、所有权、线程安全、取消和资源释放是否可证明；
存储侵入性：是否需要 TransactionDB，是否影响现有 WriteBatch、snapshot、compaction、backup/restore 和普通数据类型；
多实例路由：一个 VectorSet 的派生索引必须与其权威 key 位于同一 RocksDB instance，后台构建不得形成跨 instance 全局索引；
多租户数据模型：不同 key 的 dimension、metric、generation 和 index version 必须隔离，不能套用上游测试中的单库固定 dimension 假设；
新鲜度与恢复：继续使用 vector_generation + data_revision + immutable index_generation；重启、snapshot restore、leader 切换和旧 generation 清理后仍能检测 stale 并回退 FLAT；
训练状态：coarse quantizer / PQ codebook 的来源、版本、checksum、发布、回滚和重建流程必须明确；训练产物属于派生状态；
质量与成本：对同一数据集比较 recall@K、P95/P99、建索引时间、内存、磁盘、写放大、读放大和重建时间；同时比较 Rust 原生路径与 bridge 路径；
维护风险：上游接口仍为 experimental，必须评估版本漂移、许可证、供应链和 arana-db/rust-rocksdb 长期维护成本。

如后续引入该能力，建议把它建模为独立的 VectorIndexKind::IvfFlat / VectorIndexKind::IvfPq，与 HNSW 共享派生索引 manifest、generation 校验和 FLAT fallback，不把 FAISS 类型泄漏到 Redis 命令协议或权威 VectorSet codec。

28. PR 拆分建议

先完成独立的 PR0-A～PR0-D：Raft Apply Correctness。
DataType、VectorDataCF、storage incarnation/schema manifest、Meta/Member/Value codec、配置。
单机 mutation、generation/revision 生命周期、DEL O(1)、compaction、多实例 storage tests。
读取命令底层、RocksDB snapshot、FlatVectorEngine、budget、限流、超时和取消。
八个命令、NOQUANT、空 element、VINFO sentinel、RESP2/RESP3、Redis differential tests。
在 PR0 契约上接入 VectorSet LogicalMutation、typed result、线性一致读和三节点测试。
VectorSet snapshot schema/restore validation、capability gate 和混版本测试。
INFO VECTOR、指标、cleanup queue、故障注入、benchmark 和运维文档。

Standalone 可以按 1～4 逐步开放。其他 VectorSet cluster 命令只有在 PR0 全部关闭且 VectorSet 1～6 的 cluster 门禁完成后才能开放；cluster FLUSHDB/FLUSHALL 保持独立关闭，直到 database epoch 方案完成。

29. 当前 FT 原型的定位

PR #326 验证了 FP32、距离计算、RocksDB prefix scan、命令解析和多 instance 路由问题，但产品模型是 HASH + SearchCF 二级索引，与原生 VectorSet 不同。

建议：

不在 feat(search): support FT.CREATE and FT.SEARCH for flat vector indexes #326 上直接改造成 VectorSet；
迁移可复用的 codec、distance 和测试思想；
Phase 1 不依赖 SearchCF；
Discussion 明确路线切换；
feat(search): support FT.CREATE and FT.SEARCH for flat vector indexes #326 保留为调研原型或由维护者决定关闭/转 Draft。

30. 待 Review 的关键决策清单

31. 参考资料

AlexStocks · 2026-07-17T07:48:48Z

AlexStocks
Jul 17, 2026
Maintainer Author

VectorSet cluster 的 P0 Raft 前置 Issue

本 Discussion 的 cluster 能力依赖以下父 Issue：

#332 feat(raft): establish crash-safe state machine apply semantics

其 8 个原生 sub-issues 为 #333～#340，覆盖 apply 顺序、durable metadata、ApplyMarkerCF/typed outcome、RESP→Raft 路由、slot/多 RocksDB instance、TTL/key lifecycle、单一 snapshot frontier，以及三节点故障注入验收。

Raft 设计和完整依赖图见 Discussion #330。除独立关闭的 cluster FLUSHDB/FLUSHALL gate 外，#332 的 P0 门禁和 VectorSet 自身 cluster 测试完成前，不开放本 Discussion 设计的 VectorSet cluster 能力。

0 replies

AlexStocks · 2026-07-18T08:15:57Z

AlexStocks
Jul 18, 2026
Maintainer Author

已按确认意见更新 Discussion 正文的 27.1 RocksDB / FAISS IVF 的非阻塞预研策略：

不改变 Phase 1 FLAT、Phase 2 HNSW 与 Raft PR0 的既定优先级；
rust-rocksdb 缺少上游接口不作为阻断项，允许在 Rust 存储层复刻磁盘 IVF 设计；
如果 PoC 证明成本低，也允许增加最小 Rust/C++ bridge；
两条路径以同一数据集、持久化语义、故障模型和跨平台构建结果择优；
IVF 继续是本地派生索引，不进入 Raft 权威状态，stale 或异常时回退 FLAT；
当前不新建实现 Issue，等真实规模和运维需求证明必要后再拆预研任务。

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Kiwi Redis 8 Vector Set 存储设计（Phase 1 FLAT / Phase 2 HNSW） #331

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Kiwi Redis 8 Vector Set 存储设计（Phase 1 FLAT / Phase 2 HNSW） #331

Uh oh!

Uh oh!

AlexStocks Jul 17, 2026 Maintainer

1. 背景与结论

1.1 与 Raft PR0 的边界

2. 设计目标

2.1 功能目标

2.2 一致性目标

2.3 非目标

3. 架构概览

4. Redis 8 接口兼容范围

4.1 VADD

4.2 VSIM

4.3 VREM

4.4 VCARD

4.5 VDIM

4.6 VEMB

4.7 VISMEMBER

4.8 VINFO

4.9 RESP2/RESP3

5. DataType 与 Column Family

5.1 DataType

5.2 Phase 1 CF

5.3 Phase 2 CF

6. MetaCF 编码

7. VectorDataCF 编码

7.1 Key

7.2 Value V1

8. Canonical Vector

8.1 写入转换

8.2 Score

8.3 稳定排序

9. 多 RocksDB Instance 路由

10. 原子状态转换

10.1 新建 VectorSet

10.2 新增 element

10.3 更新 element

10.4 VREM

11. FLAT 查询引擎

12. 并发与 RocksDB Snapshot

13. VectorSet Logical Mutation 契约

13.1 复制逻辑 mutation，而不是最终物理状态

13.2 VectorSet mutation V1

13.3 Proposal 前校验

13.4 Apply 阶段的 VectorSet 决策

13.5 唯一 mutation API

14. 读一致性

15. 错误分类

15.1 用户状态错误

15.2 协议/日志损坏

15.3 RocksDB I/O 错误

16. 大 Key 删除与 Compaction

16.1 DEL

16.2 类型化 del_key

16.3 Compaction Filter

16.4 后台清理

16.5 VREM

17. Snapshot

17.1 构建 barrier

17.2 Snapshot Meta V2

17.3 恢复

18. Leader 切换

19. 滚动升级门禁

20. 数据损坏处理

21. 资源控制

22. INFO VECTOR 与指标

23. 模块边界

23.1 storage

23.2 cmd

23.3 职责

24. 测试门禁

24.1 Codec 与 Property Tests

24.2 单实例 Storage

24.3 多实例

24.4 三节点 Raft

24.5 Redis Differential

24.6 故障注入

25. 性能门禁

AlexStocks
Jul 17, 2026
Maintainer

AlexStocks
Jul 17, 2026
Maintainer Author

AlexStocks
Jul 18, 2026
Maintainer Author