SonnetDB 向量索引声明：HNSW、IVF、IVF-PQ 与 Vamana 的 C# 用法

SonnetDB 的 VECTOR(N) 不只是能存向量，也已经把向量索引声明纳入 schema。当前 parser 和 catalog 支持的索引类型包括 hnsw、ivf、ivf_pq 和 vamana。这些索引都声明在 FIELD VECTOR(N) 列上。

最常见的是 HNSW：

using SonnetDB.Engine;
using SonnetDB.Sql;

using var db = Tsdb.Open(new TsdbOptions
{
    RootDirectory = "data/vector-index-demo"
});

SqlExecutor.Execute(db, """
    CREATE MEASUREMENT alarm_vectors (
        device_id TAG,
        embedding FIELD VECTOR(384) WITH INDEX hnsw(m=16, ef=200)
    )
    """);

HNSW 适合通用 ANN 检索。m 控制图连接数，ef 控制构建和搜索候选宽度。一般来说，m 和 ef 越大，召回越好，但写入、构建和内存成本也越高。

IVF

IVF 更偏向大规模向量集合的粗分桶召回：

SqlExecutor.Execute(db, """
    CREATE MEASUREMENT image_vectors (
        source TAG,
        embedding FIELD VECTOR(384)
            WITH INDEX ivf(nlist=64, nprobe=8, max_iterations=12)
    )
    """);

nlist 可以理解为聚类桶数量，nprobe 是查询时探测多少个桶。nprobe 越大，召回越好，查询成本越高。

IVF-PQ

如果向量很多，且希望降低索引体积，可以使用 IVF-PQ：

SqlExecutor.Execute(db, """
    CREATE MEASUREMENT compact_vectors (
        tenant TAG,
        embedding FIELD VECTOR(384)
            WITH INDEX ivf_pq(
                nlist=64,
                nprobe=8,
                max_iterations=12,
                m=8,
                nbits=8)
    )
    """);

PQ 会引入量化误差，适合“能接受近似、希望节省空间”的召回层。生产中通常需要用抽样集做召回率验证。

Vamana

Vamana 更适合磁盘友好型图索引方向：

SqlExecutor.Execute(db, """
    CREATE MEASUREMENT disk_ann_vectors (
        asset TAG,
        embedding FIELD VECTOR(384)
            WITH INDEX vamana(
                max_degree=32,
                search_list_size=75,
                alpha=1.2,
                beam_width=4)
    )
    """);

这类索引的意义不只是“查得快”，而是让 SonnetDB 可以在同一个数据目录里保存向量主数据、索引声明和可重建派生索引。索引不是第二份权威数据，真正的主数据仍然是 measurement 里的 VECTOR field。

用 EXPLAIN 检查路径

建好索引后，可以用 KNN 查询验证结果：

var result = SqlExecutor.Execute(db, """
    SELECT *
    FROM knn(alarm_vectors, embedding, [0.1, 0.2, 0.3], 10)
    """);

需要注意，向量维度必须和列声明完全一致。示例里为了简短写了 3 维查询向量，如果实际列是 VECTOR(384)，就必须传 384 个浮点数。

---

官网地址：https://sonnetdb.com

技术文章站：https://iotpaper.net

开源仓库：https://github.com/IoTSharp/SonnetDB