向量检索与 ANN 索引：HNSW、usearch 与相似度查询

选型对照：
□ 纯向量库（FAISS、Qdrant）：召回强、过滤弱，元数据要另存
□ 向量插件（pgvector）：过滤强、规模受单机与行存限制
□ ClickHouse ANN：列存加向量索引一体，过滤与聚合都在 SQL 内

适用场景：
- 亿级向量且带强元数据过滤（时间、租户、类目）
- 已有 ClickHouse 数仓，不想再引入一套向量基础设施
- 检索结果需要直接参与聚合、排序、去重的混合分析

-- 打开实验开关后才允许创建向量相似度索引
SET allow_experimental_vector_similarity_index = 1;

CREATE TABLE doc_embeddings
(
    doc_id     UInt64,
    tenant_id  UInt32,
    category   LowCardinality(String),
    created_at DateTime,
    embedding  Array(Float32),
    INDEX ann_embedding embedding
        TYPE vector_similarity('hnsw', 'cosineDistance')
        GRANULARITY 1
)
ENGINE = MergeTree
ORDER BY (tenant_id, doc_id);

优化器选择 ANN 索引的条件：
□ 查询包含 ORDER BY distance(col, const) 且带 LIMIT
□ 距离函数与索引定义中的距离函数完全一致
□ 实验开关 allow_experimental_vector_similarity_index 为 1
□ 过滤条件与主键、分区配合，候选集不过大

-- 维度校验与典型写入
INSERT INTO doc_embeddings VALUES
    (1, 100, 'tech', now(), [0.12, -0.34, 0.56, 0.78]);

SELECT doc_id,
       length(embedding) AS dim,
       toTypeName(embedding) AS typ
FROM doc_embeddings
LIMIT 5;

-- 用 arrayMap 做 L2 归一化，余弦检索前必备
SELECT doc_id,
       arrayMap(x -> x / sqrt(arraySum(y -> y * y, embedding)), embedding) AS unit_vec
FROM doc_embeddings
LIMIT 3;

存储账本（768 维）：
□ Array(Float32) 原始 = 768 * 4 = 3072 字节/行
□ ZSTD 列存实测约 1.1~1.4 KB/行（浮点低位随机，压缩有限）
□ 1 亿行 ≈ 110~140 GB 压缩后，未含 HNSW 图结构

-- 找出维度异常的行，作为写入链路的巡检
SELECT length(embedding) AS dim, count() AS rows
FROM doc_embeddings
GROUP BY dim
HAVING dim != 768;

-- 在已有表上追加索引并为存量数据物化
ALTER TABLE doc_embeddings
    ADD INDEX ann_embedding embedding
    TYPE vector_similarity('hnsw', 'cosineDistance')
    GRANULARITY 1;

ALTER TABLE doc_embeddings MATERIALIZE INDEX ann_embedding;

-- 观察索引是否被查询规划使用
EXPLAIN indexes = 1
SELECT doc_id
FROM doc_embeddings
ORDER BY cosineDistance(embedding, [0.1, 0.2, 0.3])
LIMIT 10;

HNSW 关键参数与经验值：
□ hnsw_max_connections_per_layer  默认 32，图度数 M，越大召回越高、内存越大
□ hnsw_max_connections_per_node   节点总连接上限，控制多层图的总边数
□ hnsw_ef_construction            构建候选队列，默认 200，越大建索引越慢越准
□ hnsw_candidate_list_size_for_search  查询候选队列，默认 256，越大越准越慢
□ index_granularity               默认 8192，向量表建议调小到 1024 以减少块内候选

-- 切换到 usearch 后端
ALTER TABLE doc_embeddings
    DROP INDEX ann_embedding;

ALTER TABLE doc_embeddings
    ADD INDEX ann_embedding embedding
    TYPE vector_similarity('usearch', 'cosineDistance')
    GRANULARITY 1;

ALTER TABLE doc_embeddings MATERIALIZE INDEX ann_embedding;

usearch 相关设置：
□ vector_similarity_index_cache_size        索引缓存上限，默认 5 GiB
□ vector_similarity_index_cache_max_entries 缓存条目数上限
□ vector_similarity_index_max_distance      过滤距离阈值，超出不参与候选
□ max_threads                              并行构建与查询的线程数，构建期可拉满
□ 建议：缓存不小于热索引段大小，否则每次查询回落到磁盘映射

-- 确认当前索引后端与距离函数
SELECT name, type, expr, granularity
FROM system.data_skipping_indices
WHERE table = 'doc_embeddings';

-- 余弦距离：文本嵌入的默认选择
SELECT doc_id,
       cosineDistance(embedding, [0.1, 0.2, 0.3]) AS dist
FROM doc_embeddings
ORDER BY dist ASC
LIMIT 10;

-- 内积：等价于按得分降序，注意索引需按 dotProduct 建图
SELECT doc_id,
       dotProduct(embedding, [0.1, 0.2, 0.3]) AS score
FROM doc_embeddings
ORDER BY score DESC
LIMIT 10;

三者关系（单位向量下）：
□ cosineDistance(a, b) = 1 - cosineSimilarity(a, b)
□ 单位向量时：cosineDistance = L2Distance 平方的一半
□ dotProduct 不做归一化，模长越大得分越高
□ 建图距离与查询距离函数不一致，索引会静默不生效

-- 观察后台合并与索引构建压力
SELECT database, table, elapsed, progress,
       formatReadableSize(memory_usage) AS mem
FROM system.merges
WHERE table = 'doc_embeddings';

SELECT partition, name, rows,
       formatReadableSize(bytes_on_disk) AS size
FROM system.parts
WHERE table = 'doc_embeddings' AND active
ORDER BY rows DESC
LIMIT 10;

写入与合并代价控制：
□ 批量写入：单批 10 万行以上，避免 Part 碎片化
□ 控制 Part 数：active parts 长期超 300 说明合并追不上写入
□ 索引物化：先灌数据后 MATERIALIZE INDEX，比逐批建图省数倍时间
□ 后台线程：构建与合并共享后台池，写入高峰别把池占满
□ 合并放大：HNSW 图重建近似 O(N log N)，大 Part 合并一次代价可观

-- 查看插入相关的后台任务与耗时
SELECT event_time, query_duration_ms, read_rows,
       formatReadableSize(memory_usage) AS peak_mem
FROM system.query_log
WHERE query_kind = 'Insert' AND has(tables, 'doc_embeddings')
ORDER BY event_time DESC
LIMIT 10;

-- 租户 + 时间窗 + 类目，再叠加向量近邻
SELECT doc_id, category,
       cosineDistance(embedding, [0.1, 0.2, 0.3]) AS dist
FROM doc_embeddings
WHERE tenant_id = 100
  AND category = 'tech'
  AND created_at >= now() - INTERVAL 30 DAY
ORDER BY dist ASC
LIMIT 10;

-- 用 EXPLAIN 确认裁剪与索引是否都生效
EXPLAIN indexes = 1
SELECT doc_id FROM doc_embeddings
WHERE tenant_id = 100 AND created_at >= now() - INTERVAL 30 DAY
ORDER BY cosineDistance(embedding, [0.1, 0.2, 0.3]) LIMIT 10;

-- 统计过滤后的候选规模，评估是否值得先裁剪
SELECT count() AS candidates
FROM doc_embeddings
WHERE tenant_id = 100
  AND created_at >= now() - INTERVAL 30 DAY;

-- BFloat16 降精度存储
CREATE TABLE doc_embeddings_bf16
(
    doc_id    UInt64,
    embedding Array(BFloat16),
    INDEX ann_embedding embedding
        TYPE vector_similarity('usearch', 'cosineDistance')
        GRANULARITY 1
)
ENGINE = MergeTree
ORDER BY doc_id;

-- 查看向量索引与缓存的内存占用
SELECT metric, formatReadableSize(value) AS size
FROM system.asynchronous_metrics
WHERE metric LIKE '%VectorSimilarity%' OR metric LIKE '%IndexCache%';

内存账本（1 亿行，768 维，M=32）：
□ 原始向量 Float32 约 307 GB；BFloat16 约 154 GB；Int8 约 77 GB
□ HNSW 图：约 2*M*4 字节每节点 ≈ 256 字节每行，合计约 25.6 GB
□ usearch 缓存：vector_similarity_index_cache_size 默认 5 GiB，按热集调大
□ 经验：内存预算 = 原始向量（按量化档位） + 图结构 + 缓存

量化档位对比（768 维，1 亿行）：
□ Float32：内存约 307 GB，召回基线，无精度损失
□ BFloat16：内存约 154 GB，召回下降约 0.5%~1%
□ Int8：内存约 77 GB，召回下降约 3%~8%，适合粗排阶段

踩坑清单：
□ 距离函数不匹配：建图用 L2、查询用余弦，索引静默退化为全扫
□ 忘记 SET allow_experimental_vector_similarity_index=1，索引不参与规划
□ 过滤后候选过大：租户裁剪失效，向量图搜索在大集合上退化
□ 小批量写入：Part 碎片导致后台建图与合并长期排队
□ 缓存过小：索引段反复换入换出，P99 延迟周期性尖刺
□ 维度不一致：写入时不校验，合并期才报错，排查成本高