向量数据库 sqlite-vec 详解

作者：马育民 • • 阅读：10120

介绍

sqlite-vec 是轻量级、零依赖、跨平台的 SQLite 向量搜索扩展，由 Alex Garcia 开发，作为 sqlite-vss 的继任者，可直接在 SQLite 中存储、索引、检索高维向量，适配嵌入式/边缘/浏览器等全场景，核心优势是单文件、纯C、无依赖、SQL原生接口。

定位

  • 嵌入式向量引擎：给 SQLite 加向量能力，替代独立向量库（如 FAISS、Pinecone）做轻量检索
  • 混合搜索底座：支持“结构化过滤 + 向量相似度”联合查询
  • 全场景适配：服务器/桌面/移动端/浏览器（WASM）/树莓派等，无外部依赖

设计哲学

  • 单文件极简：核心仅 sqlite-vec.c/.h，编译后 ~100KB
  • SQL 原生：用标准 SQL 做向量 CRUD，无新查询语言
  • 虚拟表（Virtual Table）：vec0 虚拟表封装索引逻辑，对用户透明
  • 零依赖：纯 C 编写，静态链接，适配资源受限环境

应用场景

  1. 轻量 RAG：本地知识库、文档问答（替代 Chroma）
  2. 嵌入式 AI：手机/平板/物联网设备的图像/文本检索
  3. 混合搜索：电商商品（标题+图片向量）、内容平台（文本+语义）
  4. 多租户系统：分区键隔离不同用户向量数据

缺点

  • 大规模瓶颈：>100 万向量时，性能低于 FAISS
  • ANN 功能有限：仅支持 PQ，无 HNSW（计划中）
  • WASM 性能：浏览器中比原生慢 2–3 倍

特性

v0.1.x 最新

1. 向量类型支持

  • float32：默认，768/1536 维常见（如 OpenAI Embedding）
  • int8：量化压缩，节省50%空间，适合大规模数据
  • bit：二进制向量（如 256/512 位），汉明距离检索

2. 距离 metric（相似度计算）

  • L2 距离（欧氏距离）：默认，数值越小越相似
  • 余弦相似度：归一化后，值越大越相似（文本/图像常用）
  • 汉明距离：二进制向量专用，差异位计数

3. 索引与性能

  • 默认暴力检索（Brute-force）：精确、无训练成本，10万维内足够快
  • ANN 近似索引（可选）：v0.1+ 支持 PQ（Product Quantization），百万级向量提速 5–10 倍
  • 分区键（Partition Key）：支持多租户，按 tenant_id 分区隔离数据
  • 预过滤优化：结构化 WHERE 先过滤，再算向量距离，大幅提速

4. 平台与集成

  • 全平台编译：Linux/macOS/Windows（x86/ARM）、WASM、iOS/Android
  • 多语言绑定：Python/Node.js/Rust/Go/Java
  • 许可证：MIT/Apache-2.0 双许可，商业友好

架构原理

1. 虚拟表模型

CREATE VIRTUAL TABLE vec_movies 
USING vec0(
  embedding float[768],  -- 768维float32向量
  title TEXT,            -- 结构化字段
  partition_id INTEGER    -- 分区键（可选）
);
  • vec0：核心虚拟表模块，管理向量存储、索引、检索
  • 存储层：向量以紧凑 BLOB 存，元数据存在 SQLite 系统表
  • 索引层：暴力检索直接扫描 BLOB；ANN 索引用 PQ 压缩+聚类

2. 数据流向

  1. 写入：INSERT 时，向量转 BLOB 存，同时建索引（暴力/ANN）
  2. 查询：MATCH 子句触发向量检索，先过滤分区/结构化条件，再算距离排序
  3. 结果：返回 rowid、distance、关联字段，支持 LIMIT/KNN

python安装

pip安装

pip install sqlite-vec  # 含预编译扩展，自动适配系统

uv安装

uv add sqlite-vec  # 含预编译扩展，自动适配系统

目前稳定版

uv add sqlite-vec==0.1.9

基础用法（Python）

import sqlite3
import sqlite_vec

# 1. 连接并加载扩展
conn = sqlite3.connect(":memory:")
conn.enable_load_extension(True)
sqlite_vec.load(conn)  # 加载 vec0 扩展
conn.enable_load_extension(False)

# 2. 创建向量虚拟表
conn.execute("""
CREATE VIRTUAL TABLE vec_docs 
USING vec0(embedding float[768], content TEXT);
""")

# 3. 插入向量（JSON 或 BLOB）
# 示例：生成随机 768 维向量
import numpy as np
vec = np.random.rand(768).astype(np.float32).tobytes()
conn.execute(
    "INSERT INTO vec_docs (embedding, content) VALUES (?, ?)",
    (vec, "示例文本")
)

# 4. KNN 相似度查询（余弦距离，Top5）
query_vec = np.random.rand(768).astype(np.float32).tobytes()
rows = conn.execute("""
  SELECT rowid, distance, content 
  FROM vec_docs 
  WHERE embedding MATCH ? 
  ORDER BY distance 
  LIMIT 5;
""", (query_vec,)).fetchall()

print(rows)

关键 SQL 语法

1. 创建虚拟表

-- 基础：768维float32向量
CREATE VIRTUAL TABLE vec1 USING vec0(embedding float[768]);

-- 带分区+结构化字段
CREATE VIRTUAL TABLE vec2 USING vec0(
  emb float[512],
  user_id INTEGER,
  partition_id INTEGER
);

2. 插入向量

-- 方式1：JSON 数组（方便调试）
INSERT INTO vec1 (embedding) VALUES ('[0.1, 0.2, ...]');

-- 方式2：BLOB（高性能，推荐）
INSERT INTO vec1 (embedding) VALUES (X'010203...');

3. 相似度查询（MATCH 子句）

-- L2 距离（默认），Top10
SELECT rowid, distance FROM vec1 WHERE embedding MATCH ? ORDER BY distance LIMIT 10;

-- 余弦相似度（需指定）
SELECT rowid, distance FROM vec1 
WHERE embedding MATCH ? 
DISTANCE_METRIC = 'cosine'
ORDER BY distance LIMIT 10;

-- 混合查询：结构化过滤 + 向量
SELECT rowid, distance FROM vec2 
WHERE user_id = 123 AND embedding MATCH ? 
ORDER BY distance LIMIT 5;

性能与选型建议

1. 暴力检索（默认）

  • 适用：向量数 < 10 万，维度 < 1536
  • 优势：精确、无训练、无内存开销
  • 性能：10 万 768 维向量，单查询 ~10ms（普通 CPU）

2. ANN 索引（PQ，v0.1+）

  • 适用：向量数 > 10 万，需低延迟
  • 优势：提速 5–10 倍，内存占用降 70%
  • 代价：训练成本（一次性），召回率略降（95%+）

3. 选型对比

方案 优势 劣势 适用场景
sqlite-vec 零依赖、SQL原生、全平台 大规模（>100万）略慢 嵌入式、边缘、轻量RAG
FAISS 极致性能、ANN优化 依赖重、C++、难集成 服务器大规模检索
Pinecone 托管、弹性 成本高、网络依赖 云原生大规模RAG

总结

sqlite-vec 是嵌入式向量搜索的最优解，以零依赖、跨平台、SQL 原生为核心，完美适配轻量 RAG、边缘 AI、混合搜索场景。若需大规模检索，可作为 FAISS/Pinecone 的补充；若追求极简部署，直接替代独立向量库。

吉ICP备15003043号