向量数据库 sqlite-vec 详解-马育民老师

# 介绍

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. 虚拟表模型
```sql
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安装

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

### uv安装

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

目前稳定版

```bash
uv add sqlite-vec==0.1.9
```

# 基础用法（Python）

```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. 创建虚拟表
```sql
-- 基础：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. 插入向量
```sql
-- 方式1：JSON 数组（方便调试）
INSERT INTO vec1 (embedding) VALUES ('[0.1, 0.2, ...]');

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

### 3. 相似度查询（MATCH 子句）
```sql
-- 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 的补充；若追求极简部署，直接替代独立向量库。

原文出处：/show_1GW3LZtFy58s.html