sqlite-vss (SQLite Vector Similarity Search，SQLite 向量相似度搜索) 是一个 SQLite 扩展，它基于 Faiss，为 SQLite 带来了向量搜索能力。它可用于构建语义搜索引擎、推荐系统或问答工具。

有关更多详情和实时示例，请参阅 Introducing sqlite-vss: A SQLite Extension for Vector Search（《介绍 sqlite-vss：一个用于向量搜索的 SQLite 扩展》，2023 年 2 月）！

如果您的公司或组织认为此库有用，请考虑支持我的工作！

.load ./vector0
.load ./vss0

select vss_version(); -- 'v0.0.1'

sqlite-vss 具有类似于 fts5 全文搜索扩展 的 API。使用 vss0 模块创建虚拟表，以高效地存储和查询您的向量。

-- 384 == number of dimensions for this example
create virtual table vss_articles using vss0(
  headline_embedding(384),
  description_embedding(384),
);

sqlite-vss 是一个 自备向量（Bring-your-own-vectors） 数据库，它兼容您拥有的任何嵌入或向量数据。可以考虑使用 OpenAI 的嵌入 API、HuggingFace 的推理 API、sentence-transformers 或 任何这些开源模型。在此示例中，我们使用 sentence-transformers/all-MiniLM-L6-v2 从文本生成嵌入，这些嵌入具有 384 维度。

您可以将向量以 JSON 或原始字节的形式插入到 vss0 表中。

insert into vss_articles(rowid, headline_embedding)
  select rowid, headline_embedding from articles;

要查询相似向量（“k 最近邻”），请在 WHERE 子句中使用 vss_search 函数。在这里，我们正在搜索 articles 表中第 #123 行嵌入向量的 100 个最近邻。

select rowid, distance
from vss_articles
where vss_search(
  headline_embedding,
  (select headline_embedding from articles where rowid = 123)
)
limit 100;

您可以根据需要对这些表执行 INSERT 和 DELETE 操作，但 尚不支持 UPDATE 操作。这可以与触发器一起使用，以实现自动更新索引。另请注意，“少量”的 INSERT/DELETE 操作（仅插入几行）可能较慢，因此必要时请批量处理。

begin;

delete from vss_articles
  where rowid between 100 and 200;

insert into vss_articles(rowid, headline_embedding, description_embedding)
  values (:rowid, :headline_embedding, :description_embedding)

commit;

您可以为特定列传入自定义的 Faiss factory strings，以控制 Faiss 索引的存储和查询方式。默认情况下，factory string 是 "Flat,IDMap2"，随着数据库增长，查询可能会变慢。在这里，我们添加了一个包含 4096 个质心的 倒排文件索引，这是一个非穷举选项，可以显著加快大型数据库查询速度。

create virtual table vss_ivf_articles using vss0(
  headline_embedding(384) factory="IVF4096,Flat,IDMap2",
  description_embedding(384) factory="IVF4096,Flat,IDMap2"
);

这种 IVF 索引需要训练！您可以在单个事务中使用带有特殊约束 operation="training" 的 INSERT 命令来定义训练数据。

insert into vss_ivf_articles(operation, headline_embedding, description_embedding)
  select
    'training',
    headline_embedding,
    description_embedding
  from articles;

注意！需要训练的索引可能需要很长时间。基于本示例使用的 新闻分类数据集（包含超过 21 万个向量，维度为 386），默认索引需要 8 秒来构建。但是使用自定义的 "IVF4096,Flat,IDMap2" factory，训练花费了 45 分钟，数据插入花费了 4.5 分钟！这可能可以通过使用更小的训练集来减少时间，但更快的查询速度很有帮助。

有关如何自行编译 sqlite-vss 以及完整的 SQL API 参考，请参阅 docs.md。

发布页面包含适用于 Linux x86_64 和 MacOS x86_64（MacOS Big Sur 11 或更高版本）的预构建二进制文件。未来将提供更多预编译目标版本。此外，sqlite-vss 也通过常见的包管理器发布，例如适用于 Python 的 pip 和适用于 Node.js 的 npm，详情请见下文。

请注意，在 Linux 机器上，您需要安装一些软件包才能使这些选项生效

sudo apt-get update
sudo apt-get install -y libgomp1 libatlas-base-dev liblapack-dev

注意：文件名中（vss0.dylib/ vss0.so）的 0 表示 sqlite-vss 的主版本号。目前 sqlite-vss 处于 v1 之前，因此未来版本可能会有重大更改。

语言	安装命令	更多信息
Python	pip install sqlite-vss	在 Python 中使用 sqlite-vss
Datasette	datasette install datasette-sqlite-vss	在 Datasette 中使用 sqlite-vss
Node.js	npm install sqlite-vss	在 Node.js 中使用 sqlite-vss
Deno	deno.land/x/sqlite_vss	在 Deno 中使用 sqlite-vss
Ruby	gem install sqlite-vss	在 Ruby 中使用 sqlite-vss
Elixir	hex.pm/packages/sqlite_vss	在 Elixir 中使用 sqlite-vss
Go	go get -u github.com/asg017/sqlite-vss/bindings/go	在 Go 中使用 sqlite-vss
Rust	cargo add sqlite-vss	在 Rust 中使用 sqlite-vss
Github 发布版本

要使用 sqlite-vss 配合 官方 SQLite 命令行工具，请从发布版本下载 vector0.dylib/vss0.dylib（适用于 MacOS Big Sur 11 或更高版本）或 vector0.so/vss0.so（适用于 Linux）文件，并将其加载到您的 SQLite 环境中。

vector0 扩展是一个必需的依赖项，因此请确保在加载 vss0 之前加载它。

.load ./vector0
.load ./vss0
select vss_version();
-- v0.0.1

对于 Python 开发者，请使用以下命令安装 sqlite-vss 包：

pip install sqlite-vss

import sqlite3
import sqlite_vss

db = sqlite3.connect(':memory:')
db.enable_load_extension(True)
sqlite_vss.load(db)

version, = db.execute('select vss_version()').fetchone()
print(version)

更多详情请参阅 bindings/python。

对于 Node.js 开发者，请使用以下命令安装 sqlite-vss npm 包：

npm install sqlite-vss

import Database from "better-sqlite3"; // also compatible with node-sqlite3
import * as sqlite_vss from "sqlite-vss";

const db = new Database(":memory:");
sqlite_vss.load(db);

const version = db.prepare("select vss_version()").pluck().get();
console.log(version);

更多详情请参阅 npm/sqlite-vss/README.md。

对于 Deno 开发者，请使用 deno.land/x/sqlite_vss 模块：

// Requires all permissions (-A) and the --unstable flag

import { Database } from "https://deno.land/x/sqlite3@0.8.0/mod.ts";
import * as sqlite_vss from "https://deno.land/x/sqlite_vss/mod.ts";

const db = new Database(":memory:");

db.enableLoadExtension = true;
sqlite_vss.load(db);

const [version] = db.prepare("select vss_version()").value<[string]>()!;

console.log(version);

更多详情请参阅 deno/sqlite-vss/README.md。

对于 Datasette，请使用以下命令安装 datasette-sqlite-vss 插件：

datasette install datasette-sqlite-vss

更多详情请参阅 bindings/datasette。

• 底层 Faiss 索引上限为 1GB。关注 #1 以获取更新。
• 尚不支持在 KNN 搜索之上进行附加过滤。关注 #2 以获取更新。
• 目前仅支持 CPU Faiss 索引，尚不支持 GPU。关注 #3 以获取更新。
• 尚不支持 mmap'ed 索引，因此索引必须能放入内存（RAM）。关注 #4 以获取更新。
• 此扩展用 C++ 编写，尚无模糊测试。关注 #5 以获取更新。
• 尚不支持对 vss0 虚拟表执行 UPDATE 语句，但支持 INSERT 和 DELETE 语句。关注 #7 以获取更新。

我 (Alex 👋🏼) 在此项目和 许多其他开源项目 上投入了大量时间和精力。如果您的公司或组织使用此库（或您慷慨解囊），请考虑赞助我的工作、与朋友分享此项目，或聘请我进行合同/咨询工作！

• sqlite-http，一个用于发起 HTTP 请求的 SQLite 扩展
• sqlite-xsv，一个用于查询 CSV 的快速 SQLite 扩展
• sqlite-loadable-rs，一个用于在 Rust 中构建 SQLite 扩展的框架