@dao-xyz/sqlite3-vec (英语)

统一 SQLite + sqlite-vec (vec0) 两种浏览器和Node.js.

• 浏览器使用官方的 SQLite Wasm 构建(有 sqlite-vec)——没有设置.
• 节点使用更好的sqlite3(XQ12)并自动加载一个预建的sqlite-vec扩展名 当可用时.
• 两者都有一个导入: import { createDatabase } from '@dao-xyz/sqlite3-vec'。 。 。 .

快速类型脚本示例(浏览器和节点中的工作)

// src/app.ts
import { createDatabase } from '@dao-xyz/sqlite3-vec';

// Pick options per environment (optional)
const isBrowser = typeof window !== 'undefined';
const options = isBrowser
  ? { directory: '/myapp' } // Browser (OPFS when available, otherwise in-memory)
  : {}; // Node (native via better-sqlite3)

const db = await createDatabase(options);
await db.open();

// Confirm sqlite-vec is available
const vStmt = await db.prepare('select vec_version() as v');
const vRow = vStmt.get?.({});
console.log('sqlite-vec', vRow?.v);

// Create a small vec0 table and query
await db.exec(
  'CREATE VIRTUAL TABLE IF NOT EXISTS v USING vec0(vector float[3])',
);
const toVec = () =>
  new Float32Array([Math.random(), Math.random(), Math.random()]);

const ins = await db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
for (let i = 1; i <= 3; i++) ins.run([i, toVec().buffer]);

const probe = toVec();
const q = await db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
console.log('Top-2:', q.all([probe.buffer]));

await db.close();

注释:

• 在浏览器中, directory 在可用时启用 OPFS 备份存储( 落地) 回到记忆中.
• 在节点中,不需要选项. 软件包自动装入本地 sqlite-vec 如果存在扩展名.

安装

npm install @dao-xyz/sqlite3-vec
# optional (for local E2E)
npx playwright install --with-deps chromium

脚本

• 构建 : npm run build
• 演示词:
  • 浏览器 : npm start - 打开 http://127.0.0.1:4321/demo/index.html
  • 节点( 瓦斯姆/ 记忆中): npm run start:node
  • 节点( 本地) : npm run start:node:native
• 测试 :
  • 节点 : npm run test:node
  • 浏览器 (Playwright) : npm run test:e2e

项目结构

• src/:用于统一和本土节点条目的源模块.
• 根号 unified.mjs, (中文(简体) ), native.mjs, (中文(简体) ), node.mjs: 从 src/。 。 。 .
• index.mjs: 无害环境管理的入站电线接通上层sqlite-wasm有效载荷.
• wasm.mjs: 演示/测试所使用的本地桥; 已公布的镜像 /wasm 子路径.
• sqlite-wasm/jswasm/: 上游原子弹有效载荷文件(.mjs/.wasm).

类型脚本

• 这包货船满了 .d.ts 所有入境点的申报.
• 有条件出口的图示 .d.ts 环境:
  • 根:浏览器 dist/unified-browser.js,节点 + dist/unified-node.js, (中文(简体) ), 类型 • dist/unified.d.ts。 。 。 .
  • 子路径 : ./unified, (中文(简体) ), ./native,以及 ./wasm 与联署材料匹配的每个点 财务报告和审定财务报表 .d.ts。 。 。 .
• 您不需要额外的配置; 编辑器自动拾取类型 .

常见陷阱

• COOP/COEP信头:需要浏览器 Cross-Origin-Opener-Policy: same-origin 财务报告和审定财务报表 Cross-Origin-Embedder-Policy: require-corp 装入瓦姆 共享箭头缓冲器(由OPFS SAH 池使用). 使用所提供的服务器 (单位:千美元)npm run start:dev)或配置您的服务器.
• MIME 类型: 确保 .mjs 作为 application/javascript 财务报告和审定财务报表 .wasm 作为 application/wasm。提供的测试服务器处理此操作.
• OPFS的可用性:一些浏览器/环境(例如:交叉发源地iframes, 不安全起源)屏蔽了OPFS. 统一的API回到记忆中 OPFS无法使用.
• 工人: 如果浏览器缺少模块工人支持,演示加载 a 混合填充剂。 在你的应用程序中,检查模块工人的支持 如果你依赖工人.
• Bundlers:与Vite一起,将这个包件排除在预捆绑之外,并设置COOP/COEP 页: 1 其他捆绑商可能需要等同的配置.

快例 (浏览器, 主线程)

服务文件时需要COOP/COEP头.

// main.js
import sqlite3InitModule from '@dao-xyz/sqlite3-vec/wasm';

const sqlite3 = await sqlite3InitModule({
  print: console.log,
  printErr: console.error,
});
const db = new sqlite3.oo1.DB('/vec.sqlite3', 'ct');

// Confirm sqlite-vec is present
const s = db.prepare('select vec_version() as v');
s.step();
console.log('sqlite-vec', s.get({}).v);
s.finalize();

// Create table and run a tiny vector query
db.exec('CREATE VIRTUAL TABLE v USING vec0(vector float[3])');
const toVec = () =>
  Uint8Array.from({ length: 3 }, () => Math.floor(Math.random() * 256));
const ins = db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
for (let i = 1; i <= 4; i++) ins.bind({ 1: i, 2: toVec().buffer }).stepReset();
ins.finalize();

const probe = toVec();
const q = db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
q.bind({ 1: probe.buffer });
while (q.step()) console.log(q.get());
q.finalize();
db.close();

统一 API( 浏览器和节点中的工作)

使用选择正确运行时间的单一工厂:

import { createDatabase } from '@dao-xyz/sqlite3-vec';

// Auto: browser -> wasm; Node -> better-sqlite3 if available, else wasm
const db = await createDatabase({ mode: 'auto', directory: '/my/app' });

await db.open();
await db.exec('CREATE VIRTUAL TABLE v USING vec0(vector float[3])');
const stmt = await db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
const toVec = () =>
  new Float32Array([Math.random(), Math.random(), Math.random()]);
for (let i = 1; i <= 3; i++) stmt.run([i, toVec().buffer]);

const probe = toVec();
const q = await db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
console.log(q.all([probe.buffer]));
await db.close();

节点快例( 按包名导入, vec0) :

// node.mjs (ESM)
import {
  createDatabase,
  resolveNativeExtensionPath,
} from '@dao-xyz/sqlite3-vec';

const db = await createDatabase({
  /* optionally: loadExtension: '/abs/path/sqlite-vec-<triple>.<ext>' */
});
await db.open();
console.log('native ext:', resolveNativeExtensionPath() || '(none)');

// vec0 table
await db.exec(
  'CREATE VIRTUAL TABLE IF NOT EXISTS v USING vec0(vector float[3])',
);
const toVec = () =>
  new Float32Array([Math.random(), Math.random(), Math.random()]);
const ins = await db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
for (let i = 1; i <= 4; i++) ins.run([i, toVec().buffer]);

const probe = toVec();
const q = await db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
console.log('top-2:', q.all([probe.buffer]));
await db.close();

选项 :

• mode数字 : 'auto' | 'native' | 'wasm' (默认) 'auto') (中文(简体) ).
• directory:持续位置. 在浏览器中,可用时使用OPFS; 否则就回到记忆中 在节点原生地,指向文件路径 节点被忽略了.
• extensionPath (仅节点本地化): sqlite-vec 可加载扩展路径 二进制( 可选) .

捐款

见 DEVS.md 详细开发、建造、测试和发布说明.

运行演示

使用 COOP/COEP 头或 包含微小服务器或您自己的服务器 :

# simple COOP/COEP server (recommended)
npm run start:dev
# then open http://127.0.0.1:4321/demo/index.html

# or use http-server (requires a build that your browser allows)
npm start

错误报告

[! 警告]

此工程将包含 SQLite 瓦斯 与 没有 变化, 除已添加类型脚本外。 请吧 没有 文件问题或特性 关于这里的SQLite Wasm密码的请求。 相反,请 跟着 SQLite 错误归档指令。 。 。 . 归档类型Script类型的相关问题和功能请求是好的.

节点.js 支持

[! 警告]

节点.js支持两种模式:

• 通过更好的sqlite3(建议;支持持久性)实现原生. 提供 路径到 sqlite-vec 可加载扩展.
• 瓦斯姆(仅存于记忆;没有持久性).

预建二进制( 建议)

安装时, 软件包试图下载一个预建的 sqlite- vec 可装入 用于您的平台的扩展并放在下面 ./dist/native/。这个镜像 更好的sqlite3使用的方法,在节点上提供了"公正的工作"经验.

• 支持的三进制 :
  • 马可斯: darwin-x64, (中文(简体) ), darwin-arm64
  • 窗口 : win32-x64, (中文(简体) ), win32-arm64
  • Linux glibc : (中文(简体) ) linux-x64-gnu, (中文(简体) ), linux-arm64-gnu
  • Linux musl (阿尔卑斯山): linux-x64-musl, (中文(简体) ), linux-arm64-musl, (中文(简体) ), linux-armv7-musl

控件 :

• SQLITE3_VEC_PREBUILT=0 ——禁用预建下载(如离线CI).
• SQLITE3_VEC_POSTINSTALL=1 SQLITE_VEC_DIR=../sqlite-vec ——倒计时:建设 安装时来自本地来源.

跑步时, initNative() 如果您不这样做, 将自动发现已下载的二进制 通过 loadExtension 当然.

在节点中也可以按程序解决检测到的路径 :

import { resolveNativeExtensionPath } from '@dao-xyz/sqlite3-vec';
console.log('Resolved sqlite-vec extension:', resolveNativeExtensionPath());

调试 :

• 设定 SQLITE3_VEC_DEBUG=1 以登录在 initNative()。 。 。 .

决议细节:

• 相对于安装的软件包, 本地扩展是自动发现的 dist/native/ 目录( 不是应用程序的 cwd ) 。 你可以通过路过来覆盖 loadExtension 改为 createDatabase({ loadExtension })。 。 。 .

可选:安装时自动本地建置( opt- in)

# If you want the sqlite-vec native extension built automatically during npm install:
# 1) Ensure you have a local sqlite-vec checkout
# 2) Opt-in via env var and point to the repo
SQLITE3_VEC_POSTINSTALL=1 SQLITE_VEC_DIR=../sqlite-vec npm install

# Postinstall will attempt to run scripts/build-sqlite-vec.sh and place the
# resulting binary under ./dist/native/.

节点演示

# Wasm (in-memory)
npm run start:node

# Native (better-sqlite3); uses $SQLITE_VEC_EXT if provided, otherwise tries ./dist/native
npm run start:node:native

节点( 瓦斯, 内存)

// node-wasm.mjs (Node ESM)
import sqlite3InitModule from '@dao-xyz/sqlite3-vec/wasm';

const sqlite3 = await sqlite3InitModule({
  print: console.log,
  printErr: console.error,
});

// In-memory DB only
const db = new sqlite3.oo1.DB();

// Confirm sqlite-vec is present
const s = db.prepare('select vec_version() as v');
s.step();
console.log('sqlite-vec', s.get({}).v);
s.finalize();

// Minimal vec demo
db.exec('CREATE VIRTUAL TABLE v USING vec0(vector float[3])');
const toVec = () =>
  Uint8Array.from({ length: 3 }, () => Math.floor(Math.random() * 256));
const ins = db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
for (let i = 1; i <= 3; i++) ins.bind({ 1: i, 2: toVec().buffer }).stepReset();
ins.finalize();

const probe = toVec();
const q = db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
q.bind({ 1: probe.buffer });
while (q.step()) console.log(q.get());
q.finalize();
db.close();

排除本地扩展( 节点)

• 错误 : undefined symbol: sqlite3_<something>_init

  • 装入器现在尝试标准切入点,顺序为: sqlite3_extension_init, (中文(简体) ), sqlite3_sqlitevec_init, (中文(简体) ), sqlite3_vec_init,则 返回到文件名生成的默认值。 设定 SQLITE3_VEC_DEBUG=1 来看 尝试了.
  • 在此软件包下确保二进制 dist/native/ 匹配您的平台 三重(例如, linux-x64-gnu, (中文(简体) ), linux-arm64-musl, (中文(简体) ), darwin-arm64(中文(简体) ).
  • 您可以通过 createDatabase({ loadExtension: '/abs/path/sqlite-vec-<triple>.<ext>' })。 。 。 .

• 在节点绑定矢量

  • 你可以通过 ArrayBuffer将转换为 节点 Buffer 自动为 BLOB 列。 示例 ins.run([id, float32.buffer])。 。 。 .

安装

npm install @dao-xyz/sqlite3-vec

使用此软件包的项目

发布到 npm 时为 @dao-xyz/sqlite3-vec你可以浏览 npm 受抚养人 改为 发现使用它的项目.

许可证

阿帕奇2.0 (英语).

鸣谢

该项目的基础是: SQLite 瓦斯,哪个 方便地包装成一个ES模块,并在顶部上再建. 上游软件包是 已发布为 npm @sqlite.org/sqlite-wasm。 。 。 .

较好的sqlite3 用于 本地节点.js支持.