ByteNoteByteNote
字

字节笔记本

2026年2月20日

sqlite-vec：SQLite 向量搜索扩展

#开源工具

本文介绍 sqlite-vec，一个可以在任何地方运行的 SQLite 向量搜索扩展，支持存储和查询 float、int8、binary 向量，无需依赖，纯 C 编写。

sqlite-vec 简介

sqlite-vec 是由 Alex Garcia (asg017) 开发的开源 SQLite 扩展，为 SQLite 数据库提供向量搜索功能。该项目在 GitHub 上已获得 7k stars 和 282 forks，采用 Apache-2.0 和 MIT 双许可证。

核心定位：A vector search SQLite extension that runs anywhere!

项目状态：pre-v1（可能存在破坏性变更）

核心特性

  • 纯 C 编写：无依赖，可在任何 SQLite 运行的地方运行
  • 多平台支持：Linux/MacOS/Windows、WASM 浏览器环境、Raspberry Pi 等
  • 多种向量类型：支持 float、int8、binary 向量
  • 虚拟表设计：使用 vec0 虚拟表存储向量数据
  • 元数据支持：支持元数据列、辅助列和分区键列
  • 多语言绑定：Python、Node.js、Ruby、Go、Rust 等

技术栈

语言占比用途
C59.9%核心扩展实现
Python31.1%Python 绑定和工具
Makefile2.1%构建系统
Rust1.8%Rust 绑定
TypeScript1.7%TypeScript 支持
Vue1.1%文档网站

安装方法

Python

bash
pip install sqlite-vec

Node.js

bash
npm install sqlite-vec

Ruby

bash
gem install sqlite-vec

Go

bash
go get -u github.com/asg017/sqlite-vec/bindings/go

Rust

bash
cargo add sqlite-vec

Datasette

bash
datasette install datasette-sqlite-vec

sqlite-utils

bash
sqlite-utils install sqlite-utils-sqlite-vec

快速开始

SQL 方式使用

sql
-- 加载扩展
.load ./vec0

-- 创建向量虚拟表
create virtual table vec_examples using vec0(
  sample_embedding float[8]
);

-- 插入向量数据（JSON 格式）
insert into vec_examples(rowid, sample_embedding)
  values
    (1, '[-0.200, 0.250, 0.341, -0.211, 0.645, 0.935, -0.316, -0.924]'),
    (2, '[0.443, -0.501, 0.355, -0.771, 0.707, -0.708, -0.185, 0.362]');

-- KNN 相似度搜索
select rowid, distance from vec_examples
where sample_embedding match '[0.890, 0.544, 0.825, 0.961, 0.358, 0.0196, 0.521, 0.175]'
order by distance
limit 2;

Python 示例

python
import sqlite_vec
import sqlite3

# 连接数据库
db = sqlite3.connect(":memory:")
db.enable_load_extension(True)
sqlite_vec.load(db)
db.enable_load_extension(False)

# 创建向量表
db.execute("""
    CREATE VIRTUAL TABLE vec_items USING vec0(
        embedding float[4]
    )
""")

# 插入向量
db.execute("""
    INSERT INTO vec_items(rowid, embedding)
    VALUES
        (1, '[0.1, 0.2, 0.3, 0.4]'),
        (2, '[0.5, 0.6, 0.7, 0.8]')
""")

# 搜索相似向量
results = db.execute("""
    SELECT rowid, distance
    FROM vec_items
    WHERE embedding MATCH '[0.1, 0.2, 0.3, 0.4]'
    ORDER BY distance
    LIMIT 3
""").fetchall()

for rowid, distance in results:
    print(f"rowid={rowid}, distance={distance}")

支持的向量类型

类型说明示例
float[n]浮点向量float[768]
int8[n]8位整数向量int8[128]
binary[n]二进制向量binary[64]

核心概念

虚拟表 vec0

vec0 是 sqlite-vec 的核心虚拟表，用于存储向量数据：

sql
CREATE VIRTUAL TABLE my_vectors USING vec0(
    -- 向量列（必需）
    embedding float[768],

    -- 元数据列（可选）
    +text_content TEXT,
    +created_at INTEGER,

    -- 分区键（可选，用于优化）
    partition_key TEXT
);

查询语法

使用 MATCH 操作符进行相似度搜索：

sql
SELECT rowid, distance
FROM my_vectors
WHERE embedding MATCH ?
ORDER BY distance
LIMIT 10;

输入格式

  • JSON 数组：'[0.1, 0.2, 0.3, 0.4]'
  • 紧凑二进制：更高效的二进制格式（大向量推荐）

高级用法

元数据过滤

sql
-- 结合元数据进行过滤
SELECT rowid, distance, text_content
FROM vec_items
WHERE embedding MATCH '[0.1, 0.2, 0.3, 0.4]'
  AND created_at > 1700000000
ORDER BY distance
LIMIT 10;

分区键优化

对于大规模数据，使用分区键可以提高查询性能：

sql
CREATE VIRTUAL TABLE partitioned_vectors USING vec0(
    embedding float[768],
    partition_key TEXT
);

-- 查询特定分区
SELECT * FROM partitioned_vectors
WHERE embedding MATCH '[...]'
  AND partition_key = 'category_a'
ORDER BY distance;

适用场景

  • 本地 RAG 应用：无需外部向量数据库
  • 边缘设备：Raspberry Pi 等资源受限环境
  • 浏览器应用：WASM 支持，纯前端向量搜索
  • 嵌入式系统：零依赖，轻量级部署
  • 快速原型：SQLite 的便利性 + 向量搜索能力

相关项目

  • sqlite-vss：sqlite-vec 的前身项目
  • sqlite-ecosystem：更多 SQLite 扩展集合
  • sqlite-rembed：远程 API 嵌入生成
  • sqlite-lembed：本地 .gguf 模型嵌入

赞助商

  • Mozilla Builders：主要赞助商
  • Fly.io：云服务支持
  • Turso：SQLite 云服务
  • SQLite Cloud：数据库云服务
  • Shinkai：AI 基础设施

项目链接

总结

sqlite-vec 为 SQLite 带来了强大的向量搜索能力，其纯 C 实现确保了极致的可移植性和性能。无论是构建本地 RAG 应用、边缘设备部署，还是浏览器端向量搜索，sqlite-vec 都是一个轻量级且功能完善的选择。

开源工具
上一篇

OpenAI Codex 多智能体配置完全指南

下一篇

sqlite-vec：SQLite 向量搜索扩展

分享: