RuView RaBitQ 相似性传感器：用 1-bit Sketch 为 CSI / Pose 嵌入打造廉价的“见过它吗“感知层-平芜编程栈

RuView RaBitQ 相似性传感器：用 1-bit Sketch 为 CSI / Pose 嵌入打造廉价的"见过它吗"感知层

【免费下载链接】RuViewπ RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.项目地址: https://gitcode.com/GitHub_Trending/wi/RuView

导读

本文围绕 RuView 的架构决策记录 ADR-084，系统讲解如何把 RaBitQ 风格的 1-bit 二值量化从"向量压缩技巧"升格为部署在 AETHER 重识别、房间指纹、新颖性检测、网格同步与事件日志五大环节的廉价相似性传感器。文章会带你读懂规范中的"草图先行、全精度裁决"模式，逐层拆解 sketch.rs、rotation.rs、estimator.rs 等已落地源码的 API 与测试，掌握 8×–30× 比较成本压缩、≥90% Top-K 覆盖与 <1pp 端到端精度回归的可验证判据，以及基于过取回（over-fetch）"候选集 + 全精度精排"的工程部署范式。

背景：整条管道上无处不在的"见过它吗"问题

RuView 的信号管道在多个层次持续产出稠密浮点嵌入，本文档所记的实现位于该决策驱动的wifi-densepose-ruvectorcrate（见 lib.rs）：

嵌入来源	维度	对应 ADR
AETHER 行人重识别嵌入（每条`PoseTrack`一份）	128 维	ADR-024
CSI 频谱图嵌入	64–256 维	ADR-076
每房间场模型本征模向量	—	ADR-030
每帧多站融合向量	—	ADR-029

它们最终都回答同一类问题："我是否曾经见过与此类似的东西？"在引入本文方案之前，这个答案依赖对候选集做全量浮点点积 / 马氏距离比较。该成本随存储向量数线性增长，而当它被用于动态 mincut 图维护、重识别重新打分、跨环境域检测时又会进一步演化为平方级开销——这正是 ADR-084 所要解决的规模瓶颈。

值得注意的是：vendored 的ruvector-core早已提供 1-bit 量化类型BinaryQuantized（32× 压缩、SIMD popcnt + 海明距离），其在功能上等价于 RaBitQ 一族二值草图——每个向量维度压缩为 1 bit，以海明距离比较，作为全精度精排之前的粗筛。同一模块还暴露了ScalarQuantized（int8、4×）与ProductQuantized（PQ、8–16×），因此分层量化的实现早已存在，缺的只是部署形态。ADR-084 的切入点是一个观察：RaBitQ 草图不只是向量压缩技巧，而是一种廉价的相似性传感器，它可以带来：

常开的新颖性 / 异常门控，只在出现有意义的改变时才唤醒重型 CNN；
集群 Pi 的记忆路由（优先查询哪个分片 / 房间 / 模型）；
节点间网格以压缩草图而非原始向量交换；
隐私友好的事件日志（只存草图，不可反演出信号）。

决策：把 RaBitQ 草图当作一等公民的廉价相似性传感器

ADR-084 正式在 RuView 管道中四个位置采用RaBitQ 风格二值草图：

集群 Pi 上的CSI / Pose 嵌入热缓存过滤器；
实时观测与每房间常态库之间的漂移 / 新颖性传感器；
传感节点间上报跨集群事件时的网格交换压缩；
集群 Pi 与网关上隐私保护的事件日志。

每个位置的规范模式都是同一条链：

dense embedding ──► RaBitQ sketch ──► hamming/popcnt compare ├──► candidate set (top-K) └──► novelty score (0..1) │ ▼ ┌── below threshold ──► emit summary, no escalation │ └── above threshold ──► full-precision refinement ├──► ruvector mincut / HNSW ├──► AETHER re-ID rescoring └──► pose model / CNN wake

该 ADR 同时承诺以ruvector::quantization::BinaryQuantized作为规范化实现。其核心设计原则是：决策边界不变——全精度仍持有最终裁决权，草图只是决定"哪些比较需要跑"的传感器，而非"它们如何裁决"。

实现落点与版本治理

草图类型与 SIMD 原语：BinaryQuantized（aarch64 走 NEON、x86_64 走 POPCNT 的 SIMD 海明距离），在 sketch.rs 中以use ruvector_core::quantization::{BinaryQuantized, QuantizedVector};引入，并通过新的crates/wifi-densepose-ruvector/src/sketch.rs模块以 RuView 风格 API 重新导出，使signal、train、mat、sensing-server的消费者不直接绑定 vendor crate。
每房间常态库：按 ADR-083 部署在集群 Pi 上，而非传感 MCU 上。MCU 继续以既有rv_feature_state_t报文形态发出稠密嵌入，草图化在持有候选库的 Pi 端完成。
草图版本号：每个草图携带 16-bitsketch_version字段，当嵌入模型升级导致草图不兼容时，Pi 可据此区分新旧版本——每次嵌入模型变更都会使版本号递增。

在 sketch.rs 的真实实现中，Sketch结构体内除BinaryQuantized打包字节外还保存embedding_dim: u16（源向量维度）与sketch_version: u16，并在Sketch::distance比较时强制两者一致，不一致即抛出类型化错误SketchError::EmbeddingDimMismatch/SketchError::SketchVersionMismatch，从根源上杜绝"不同嵌入模型代际 / 不同维度的草图被静默比较"。另外，面向 PR #435 安全评审的 L2 加固让超长嵌入不再经debug_assert!静默截断：try_from_embedding对超过u16::MAX（65,535）维的输入返回SketchError::EmbeddingDimOverflow，而from_embedding在 release 下以饱和到u16::MAX而非截断的方式处理（sketch.rs 有对应单元测试try_from_embedding_rejects_over_long_input佐证）。

传感器在管道中的位置：六处热路径对照

管道环节	现状（全浮点）	引入 RaBitQ 相似性传感器后
AETHER 重识别匹配	每条活跃轨迹 × 候选做全 128 维余弦	海明预筛到 Top-K，再对 K 个做全余弦
mincut 子载波选择	全图重新评估	草图标记"疑似变化"边界边，仅对其做全 mincut
CSI 房间指纹	对全嵌入跑训练好的分类器	草图对每房间草图做海明，未命中才跑分类器
场模型新颖性（ADR-030）	残差能量阈值	草图新颖性作为 SVD 重算前的第二道闸门
网格 / 跨集群同步	广播稠密嵌入	广播草图；未命中才传全向量
事件日志留存	存全嵌入	存草图 + witness 哈希；原始嵌入仅短暂驻留

每一行遵循同样的原则：决策边界不变，全精度仍然给出最终答案。

系统级验收判据

ADR-084 给出系统级验收测试：

RaBitQ 应将比较成本降低8× 到 30×，同时保持 top-k 决策足够好，使全精度精排后最终结果变化少于 10%。

具体拆解为三条独立判据：

草图比较必须可测出比其替代的浮点比较便宜 8×（signal/中的 criterion-bench）；
由草图选出的 Top-K 候选集必须包含全浮点通过会选出的候选的 ≥ 90%（针对录制 CSI 的离线回放）；
在既有评估集上，端到端姿态 / 重识别精度相比全浮点基线回归 < 1 个百分点。

这三条中若任何一条失败，传感器就在该管道点回滚，失败点恢复全浮点，其余位置继续使用草图——逐点回滚，而非全有全无。

源码视角：Sketch、SketchBank 与 WireSketch 的落地实现

ADR-084 的"Pass 1"即wifi-densepose-ruvector::sketch模块的建立，文件头部注释原样固化了三条验收判据（8×–30× 成本削减、≥90% Top-K 覆盖、<1pp 端到端回归），可对照阅读 sketch.rs。

Sketch：一维一比特的符号量化

Sketch::from_embedding按每维一个符号位完成量化：值> 0.0记 1、否则记 0，这是 RaBitQ 一族的标准符号量化步骤。相较源[f32]向量，草图体积缩小32×，并用 SIMD 加速的海明距离（aarch64 的 NEONvcnt、x86_64 的 POPCNT）做比较——这正是"32× 更小、popcnt 友好"表述的代码级来源。

比较 API 提供两条路径：Sketch::distance先校验embedding_dim与sketch_version再做海明计数（返回None/Err以表达"比较无意义"）；Sketch::distance_unchecked则跳过校验，仅供同一SketchBank内已保证同源的草图使用。packed_bytes()暴露(embedding_dim + 7) / 8字节的打包数据，供 WireSketch 直接上帧。

SketchBank：带模式锁定的 Top-K 邻居库

SketchBank承载"我在每个见过此物的地方"的索引查询语义，具有两条核心不变量：

库内所有草图共享同一embedding_dim与sketch_version（首次insert时锁定，后续不匹配插入即返回类型化错误）；
u32库 ID 由调用方赋予，且在topk调用间保持稳定、不因插入删除重排。

SketchBank::topk内部有一条值得一提的演进故事：旧实现用BinaryHeap<Reverse<...>>存 Top-K，而Reverse会把最大堆变成最小堆，导致n > k堆路径把 k 个最远邻居当最近邻返回；原有单测只覆盖了n ≤ k快路径，故该反转让 bug 长时间潜伏，直到 Pass-2 覆盖度评测（n > k）把它暴露。修复后的实现以 max-heap 保留 k 个最小距离、总复杂度O(n log k)，并以回归测试topk_heap_path_returns_nearest与tight_clusters_give_high_coverage_with_overfetch钉死（sketch.rs）。因此本文档此前所有 Top-K 验收数字只有在修复后的路径上才有意义。

SketchBank::novelty给出文档定义的新颖性评分：min_distance / embedding_dim，取值范围[0.0, 1.0]——0.0 表示库中存在逐位完全匹配，1.0 表示与最近草图逐位全异，空库直接返回 1.0（最大新颖性）。单元测试novelty_zero_for_exact_match_one_for_empty、novelty_is_proportional_to_min_distance分别钉住了边界与线性比例语义。

WireSketch：28 字节的 AETHER 128-d 草图帧

WireSketch把"草图 + 新颖性分"序列化为可在集群↔集群网格、传感器→Pi UDP、网关→云 QUIC 等任意信道上传输的小端紧打包帧。128 维 AETHER 草图的总开销为12 字节定长头 + 16 字节负载 = 28 字节，其中头布局如下：

偏移	字段	宽度	说明
0	`magic`	u32	`WIRE_SKETCH_MAGIC = 0xC511_0084`，与既有 RuView magic 区分
4	`format_version`	u16	当前`WIRE_SKETCH_FORMAT_VERSION = 1`
6	`sketch_version`	u16	嵌入模型 schema 版本（与线格式版本是两个概念）
8	`embedding_dim`	u16	源嵌入维度
10	`novelty_q15`	u16	新颖性`[0,1]`× 32767 的 q15 定点量化
12	`bits[]`	变长	`ceil(embedding_dim/8)`字节

反序列化端是"偏执"的：magic、format_version、embedding_dim → 负载字节数一致性、总长四重校验全过才触碰BinaryQuantized，恶意 UDP 包只会得到类型化WireSketchError而绝不 panic；WIRE_SKETCH_MAX_BYTES = 9 KiB上限配合TooLarge错误防御基于伪造超大维度的内存耗尽攻击。novelty在编码时钳制到[0,1]并做 q15 定点，解码端再除以 32767 还原（wire_serialize_round_trip验证往返误差 < 2/32767）。

五段落地与三层验证

ADR-084 把实现拆成五个各自独立可测的阶段，每阶段都被同一验收判据门控，失败即逐点回滚：

wifi-densepose-ruvector::sketch模块：重导出BinaryQuantized，提供 RuView 风味 API（Sketch::from_embedding、Sketch::distance、SketchBank::topk），并给公开类型增加sketch_version: u16与embedding_dim: u16字段；配套 criterion 基准测草图 ↔ 浮点比较成本比。此即 sketch.rs 现状，含约 30 个单元测试。
AETHER 重识别预筛：在 wifi-densepose-signal/src/ruvsense/pose_tracker.rs 计算全 128 维余弦前，先对活跃轨迹 × 候选两侧做草图并海明取 Top-K；基准测每帧重识别耗时与跨房间切换下的 ID 稳定性。
集群 Pi 新颖性传感器：在wifi-densepose-sensing-server维护每房间"常态"SketchBank；每个进入的rv_feature_state_t计算嵌入草图、对库打分，并把novelty_score作为新字段追加到 WebSocket 更新信封；重型 CNN 唤醒门控直接消费该分数。
网格交换压缩：跨集群广播（ADR-066 群桥信道）在新颖性低时携带草图 + witness 而非全嵌入，仅当新颖性越阈才交换全向量。
隐私保护事件日志：集群 Pi 的事件日志表存(sketch_bytes, sketch_version, novelty_score, witness_sha256)而非原始嵌入；既有日志读取 API 不变，仅存储层重写。对应源码见 event_log.rs——PrivacyEventLog是定容 FIFO 环形缓冲，最坏驻留内存为capacity × (sketch_bytes + 50)，事件witness_sha256是对WireSketch序列化负载（头 + 打包位 + q15 新颖性量子）做 SHA-256，两个 witness 相同即线上逐字节相同，天然支持去重与网关免重复存储的检查点。

每个 Pass 配套三类测试：属性测试（草图 ↔ 浮点 Top-K 一致率 ≥ 90%）、criterion 基准（≥ 8× 比较成本削减）、端到端精度回归测试（< 1pp 降幅）。

验证方面，ADR-084 明确接受（Accepted）门槛是：上述三条验收数字需在五个实现点中的至少三个（负载最重的 AETHER 重识别、集群 Pi 新颖性、事件日志）成立；网格交换与 mincut 预筛是可选的锦上添花项，可在各自单点数字达标后跟进。验证运行环境包括：

既有1,539 测试的 workspace 套件必须保持全绿；
新增tests/integration/rabitq_sketch_pipeline.rs集成测试，驱动录制 CSI 分别以有 / 无草图方式完整过管道，比较 Top-K 决策与端到端姿态精度；
ESP32-S3（COM7）冒烟测试——传感 MCU 不变、草图在集群 Pi 完成，故该验证仅确认传感器 → Pi UDP 路径在集群 Pi 增加草图库后依然正常。

影响评估

正面：凡是"我见过它吗"问题所在的路径（AETHER 重识别、mincut 维护、房间指纹、新颖性检测、网格同步、事件日志留存）都先跑一遍小 32×、popcnt 友好的比较；常开异常门控变得负担得起（静默房间稳态下 CNN / 姿态模型只有草图新颖性越阈才唤醒，单节点能耗预算显著下降）；隐私叙事提升（事件日志与跨集群网格流量携带的是草图与 witness 哈希，1-bit 量化对原始 CSI 不可逆）；与 ADR-083 干净组合（集群 Pi 天然承载草图库，MCU 零改动）；零新增依赖。

负向 / 风险：草图质量依赖嵌入分布——纯 1-bit 符号量化（BinaryQuantized的实现）在嵌入空间大致零中心且各向同性时表现最好，AETHER 与 CSI 频谱嵌入需为此假设做基准测试，若失败需在草图前加随机旋转（Johnson-Lindenstrauss / RaBitQ 论文式），本 ADR 将其划为验收失败后的跟进项；候选集 < 16 时 Top-K 覆盖可能选错 K，逐点回退全浮点已纳入上线计划；嵌入模型升级会使存量草图全部失效，sketch_version递增后集群 Pi 必须重算候选库，成本有界但非零。

中性：ADR-024、ADR-027、ADR-029、ADR-030、ADR-076 在"算什么"上不变，只是比较步骤获得草图预筛；ADR-082 的确认轨迹输出过滤器位于草图层上游，保持正确。

Pass 2 与 Pass 2b：随机旋转与无偏距离估计器的实测结论

Pass 2——随机旋转 + 多比特（ADR-156 §8，2026-06 落地）

ADR-084 开放问题"BinaryQuantized是否需要随机旋转预pass"如今有了实测数字的答案。Pass 2 已在 rotation.rs 实现：确定性R = H·D（快速 Hadamard 变换 + 种子化 ±1 符号翻转），O(d log d)/O(d)复杂度、保范、可由存储的u64seed 复现。选 FHT 而非稠密d×d正交阵的原因写得很清楚：稠密旋转在d = u16::MAX = 65,535维下约需 17 GiB，对集群 Pi / 边缘目标完全不可行（rotation.rs）。API 上通过Sketch::from_embedding_rotated/SketchBank::with_rotation选入，Pass-1 API 与线格式不变；索引端与查询端必须使用同一Rotation（同 seed + dim），否则海明距离在不同旋转坐标系下毫无意义。

各向异性植入簇夹具（cosine 真值、dim=128、N=2048、K=8）上的实测结果为：

严格candidate_k = K栏下，旋转把覆盖率从36.13% 提升到 46.39%；
Pass 2 在candidate_k = 24（约3× over-fetch）处到达≥90%验收栏；
多比特（≤4-bit）在严格栏达到 74%。

诚实的结论：旋转与 ≤4-bit 多比特都无法在这个分布上越过"严格 K = 90%"栏；验收栏是靠本文档决策章节规定的 over-fetch"候选集"模式（草图选候选集、全精度精排）达成的。此外 Pass-2 工作还修复了前述SketchBank::topk的堆反转 bug，并使其成为既有 Top-K 验收数字生效的前提。

Pass 2b——RaBitQ 无偏距离估计器（ADR-156 §11）

RaBitQ 论文（Gao & Long, SIGMOD 2024）的真正贡献——从 1-bit 码 + 每向量侧信息恢复内积 / 距离的无偏估计器——已在 estimator.rs 实现并同样接受本文档 ≥90% 严格-K 栏的实测检验：

实现：EstimatorSketch（Pass-2 符号码 + 每向量 8 字节侧信息：residual_norm+x_dot_o = ⟨x̄, o'⟩）、DistanceEstimator（⟨o',q'⟩ ≈ ⟨x̄,q'⟩ / x_dot_o，即论文的无偏重缩放）、EstimatorBank（按估计值而非原始海明重排候选）。代码明确记录了零质心简化（c = 0），论文忠实的质心路径也以with_centroid保留。整体纯增量：Pass-1 / Pass-2 与线格式不动。
实测严格-K 覆盖（同 Pass-2 夹具）：估计器把严格栏从 46.39%（Pass-2 符号）抬到49.71%（估计器 + cosine 重排），是真实的+3.3pp增益，但距 90% 严格栏仍差约 40pp；在 over-fetch 下估计器优于纯符号（candidate_k = 24处 95.12% vs 91.60%）。
诚实的结论：无偏估计器无法在该分布上越过严格-K 90% 栏——制约瓶颈是 1-bit 码的信息天花板而非估计器方差；≥90% 验收栏依然只通过 over-fetch"候选集"模式达成，估计器的价值在于降低了所需的 over-fetch 倍率而非消除它。这是一个如实发表的负面结果。

开放问题与演进方向

BinaryQuantized需要随机旋转预pass吗？——已由 ADR-156 §10 回答：旋转已构建并实测，严格-K 栏下提升约 +10pp，但在各向异性分布上单独不足以达到严格-K 90%，over-fetch 候选集模式可达标；纯符号量化假设零中心各向同性嵌入，旋转按 RaBitQ 论文（Gao & Long, SIGMOD 2024）规定对相关坐标去相关。
草图维度目标：默认取嵌入原生维度（AETHER 为 128、频谱图为 256）；更高维草图（Johnson-Lindenstrauss 投影到 512）以算力换召回，需基准后再定。
按房间 vs 按部署建库：新颖性检测默认按房间建库；跨房间重识别可能需要共享库，待跨房间 AETHER 轨迹可用后再定。