@h-ai/vecdb 0.1.0-alpha.56 → 0.1.0-alpha.58

package/README.en.md

@@ -0,0 +1,145 @@
+# @h-ai/vecdb
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
+
+A vector database module with a unified `vecdb` object for LanceDB, pgvector, Qdrant, and Chroma.
+
+## Supported vector databases
+
+- LanceDB (embedded, local file storage, zero configuration)
+- pgvector (PostgreSQL + pgvector extension)
+- Qdrant (high-performance vector search engine; server 1.10.0+ with the Query API)
+- Chroma (automatically start a local service in embedded mode, or connect to an existing service)
+
+## Quick start
+
+```ts
+import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
+
+// 初始化（LanceDB）
+await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
+
+// 创建集合
+await vecdb.collection.create('docs', { dimension: 1536 })
+
+// 插入向量
+await vecdb.vector.insert('docs', [
+  { id: 'doc-1', vector: Array.from({ length: 1536 }).fill(0.1), content: '文档内容', metadata: { source: 'wiki' } },
+])
+
+// 搜索
+const searchResult = await vecdb.vector.search('docs', Array.from({ length: 1536 }).fill(0.2), { topK: 5, minScore: 0.7 })
+if (searchResult.success) {
+  for (const item of searchResult.data) {
+    // item.id, item.score, item.content
+  }
+}
+
+// 关闭
+const closeResult = await vecdb.close()
+if (!closeResult.success) {
+  throw new Error(closeResult.error.message)
+}
+```
+
+## Configuration
+
+```ts
+// LanceDB（默认，嵌入式本地存储）
+await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
+
+// pgvector（连接字符串）
+await vecdb.init({ type: 'pgvector', url: 'postgres://user:pass@localhost:5432/mydb' })
+
+// pgvector（分字段）
+await vecdb.init({
+  type: 'pgvector',
+  host: 'localhost',
+  port: 5432,
+  database: 'mydb',
+  user: 'admin',
+  password: 'secret',
+  indexType: 'hnsw',
+  tablePrefix: 'vec_',
+})
+
+// Qdrant
+await vecdb.init({ type: 'qdrant', url: 'http://localhost:6333', apiKey: 'optional-key' })
+
+// Chroma（嵌入式：自动拉起本地 `chroma run` 服务并持久化到 path）
+await vecdb.init({ type: 'chroma', path: './data/chroma' })
+
+// Chroma（直连已有服务，不拉起进程）
+await vecdb.init({ type: 'chroma', url: 'http://localhost:8000' })
+```
+
+> On Node, Chroma provides only an HTTP client, with no in-process embedded database. In embedded mode, `vecdb.init`
+> starts a local service with `serverCommand` (default: `chroma`, from the `chromadb` package), and `vecdb.close`
+> stops the process. Install the optional `chromadb` dependency; if the command is unavailable, `init` returns `CONNECTION_FAILED`.
+
+### Operation logging
+
+Enable operation logging with `operationLog` in the vector database configuration. Logs are emitted before collection/vector operations reach the real provider, without a shared wrapper in `vecdb-main.ts`.
+
+```yaml
+# config/_vecdb.yml
+type: lancedb
+path: ./data/vecdb
+operationLog:
+  read: false # collection.exists/info/list, vector.search/count
+  write: false # collection.create/drop, vector.insert/upsert/delete
+  maxLength: 1000 # 参数序列化后的最大输出长度，超出会截断
+  level: debug # info | debug | trace，默认 debug
+```
+
+```ts
+await vecdb.init({
+  type: 'lancedb',
+  path: './data/vecdb',
+  operationLog: {
+    read: true,
+    write: true,
+    maxLength: 500,
+    level: 'debug',
+  },
+})
+```
+
+> Note: `vecdb.config` returns a **redacted configuration snapshot**. Connection-string usernames/passwords, standalone `password`, and `apiKey` are replaced with `[REDACTED]`.
+
+> Behavior: empty batch `insert/upsert/delete` calls are no-ops. Writes and searches validate vector dimensions, returning `HaiVecdbError.DIMENSION_MISMATCH` on a mismatch; missing optional drivers return `HaiVecdbError.DRIVER_NOT_FOUND`.
+
+## Error handling
+
+All operations return `HaiResult<T>`; check `result.success` for success or failure.
+
+```ts
+const result = await vecdb.collection.create('docs', { dimension: 1536 })
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiVecdbError.NOT_INITIALIZED.code:
+      // 请先调用 vecdb.init()
+      break
+    case HaiVecdbError.COLLECTION_ALREADY_EXISTS.code:
+      // 集合已存在
+      break
+    case HaiVecdbError.CONNECTION_FAILED.code:
+      // 连接失败
+      break
+  }
+}
+```
+
+## Tests
+
+```bash
+pnpm --filter @h-ai/vecdb test
+```
+
+> pgvector / Qdrant tests require Docker.
+
+## License
+
+Apache-2.0

package/README.ja.md

@@ -0,0 +1,145 @@
+# @h-ai/vecdb
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
+
+共通の `vecdb` オブジェクトで LanceDB、pgvector、Qdrant、Chroma を操作するベクトルデータベースモジュールです。
+
+## 対応ベクトルデータベース
+
+- LanceDB（組み込み型、ローカルファイル保存、設定不要）
+- pgvector（PostgreSQL + pgvector 拡張）
+- Qdrant（高性能ベクトル検索エンジン。Query API を使用するため、サーバー 1.10.0 以降が必要）
+- Chroma（組み込みモードでローカルサービスを自動起動、または既存サービスへ直接接続）
+
+## クイックスタート
+
+```ts
+import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
+
+// 初始化（LanceDB）
+await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
+
+// 创建集合
+await vecdb.collection.create('docs', { dimension: 1536 })
+
+// 插入向量
+await vecdb.vector.insert('docs', [
+  { id: 'doc-1', vector: Array.from({ length: 1536 }).fill(0.1), content: '文档内容', metadata: { source: 'wiki' } },
+])
+
+// 搜索
+const searchResult = await vecdb.vector.search('docs', Array.from({ length: 1536 }).fill(0.2), { topK: 5, minScore: 0.7 })
+if (searchResult.success) {
+  for (const item of searchResult.data) {
+    // item.id, item.score, item.content
+  }
+}
+
+// 关闭
+const closeResult = await vecdb.close()
+if (!closeResult.success) {
+  throw new Error(closeResult.error.message)
+}
+```
+
+## 設定
+
+```ts
+// LanceDB（默认，嵌入式本地存储）
+await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
+
+// pgvector（连接字符串）
+await vecdb.init({ type: 'pgvector', url: 'postgres://user:pass@localhost:5432/mydb' })
+
+// pgvector（分字段）
+await vecdb.init({
+  type: 'pgvector',
+  host: 'localhost',
+  port: 5432,
+  database: 'mydb',
+  user: 'admin',
+  password: 'secret',
+  indexType: 'hnsw',
+  tablePrefix: 'vec_',
+})
+
+// Qdrant
+await vecdb.init({ type: 'qdrant', url: 'http://localhost:6333', apiKey: 'optional-key' })
+
+// Chroma（嵌入式：自动拉起本地 `chroma run` 服务并持久化到 path）
+await vecdb.init({ type: 'chroma', path: './data/chroma' })
+
+// Chroma（直连已有服务，不拉起进程）
+await vecdb.init({ type: 'chroma', url: 'http://localhost:8000' })
+```
+
+> Node 版の Chroma は HTTP クライアントのみで、プロセス内の組み込み DB はありません。組み込みモードでは `vecdb.init` が
+> `serverCommand`（既定は `chromadb` パッケージの `chroma`）でローカルサービスを起動し、`vecdb.close` が
+> そのプロセスを停止します。任意依存の `chromadb` をインストールしてください。コマンドが利用できない場合、`init` は `CONNECTION_FAILED` を返します。
+
+### 操作ログ
+
+ベクトルデータベース設定の `operationLog` で操作ログを有効にできます。ログはコレクション・ベクトル操作が実際の Provider に渡る前に出力され、`vecdb-main.ts` で一括ラップはしません。
+
+```yaml
+# config/_vecdb.yml
+type: lancedb
+path: ./data/vecdb
+operationLog:
+  read: false # collection.exists/info/list, vector.search/count
+  write: false # collection.create/drop, vector.insert/upsert/delete
+  maxLength: 1000 # 参数序列化后的最大输出长度，超出会截断
+  level: debug # info | debug | trace，默认 debug
+```
+
+```ts
+await vecdb.init({
+  type: 'lancedb',
+  path: './data/vecdb',
+  operationLog: {
+    read: true,
+    write: true,
+    maxLength: 500,
+    level: 'debug',
+  },
+})
+```
+
+> 注：`vecdb.config` は**機密情報をマスクした設定スナップショット**を返します。接続文字列のユーザー名・パスワード、個別の `password`、`apiKey` は `[REDACTED]` に置換されます。
+
+> 動作：空の一括 `insert/upsert/delete` は何もしません。書き込み・検索時にはベクトル次元を検証し、不一致なら `HaiVecdbError.DIMENSION_MISMATCH`、任意ドライバーの不足なら `HaiVecdbError.DRIVER_NOT_FOUND` を返します。
+
+## エラー処理
+
+すべての操作は `HaiResult<T>` を返し、`result.success` で成功・失敗を判定します。
+
+```ts
+const result = await vecdb.collection.create('docs', { dimension: 1536 })
+if (!result.success) {
+  switch (result.error.code) {
+    case HaiVecdbError.NOT_INITIALIZED.code:
+      // 请先调用 vecdb.init()
+      break
+    case HaiVecdbError.COLLECTION_ALREADY_EXISTS.code:
+      // 集合已存在
+      break
+    case HaiVecdbError.CONNECTION_FAILED.code:
+      // 连接失败
+      break
+  }
+}
+```
+
+## テスト
+
+```bash
+pnpm --filter @h-ai/vecdb test
+```
+
+> pgvector / Qdrant のテストには Docker が必要です。
+
+## License
+
+Apache-2.0

package/README.md

@@ -1,12 +1,16 @@
 # @h-ai/vecdb
 
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
+
 向量数据库模块，通过统一的 `vecdb` 对象访问 LanceDB、pgvector、Qdrant、Chroma。
 
 ## 支持的向量数据库
 
 - LanceDB（嵌入式，本地文件存储，零配置）
 - pgvector（PostgreSQL + pgvector 扩展）
-- Qdrant（高性能向量搜索引擎）
+- Qdrant（高性能向量搜索引擎；服务端需 1.10.0+，使用 Query API）
 - Chroma（支持嵌入式自动拉起本地服务，或直连已有服务）
 
 ## 快速开始

package/dist/index.js

@@ -619,6 +619,9 @@ var logger2 = core.logger.child({ module: "vecdb", scope: "lancedb" });
 function escapeLanceFilterValue(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "\\%").replace(/_/g, "\\_");
 }
+function escapeLanceSqlValue(value) {
+  return value.replace(/'/g, "''");
+}
 function createLancedbProvider() {
   let connection = null;
   let config = null;
@@ -692,7 +695,7 @@ function createLancedbProvider() {
         metadata: "{}"
       };
       const table = await connection.createTable(name, [initRecord]);
-      await table.delete('id = "__init__"');
+      await table.delete("id = '__init__'");
       collectionMetas.set(name, { dimension, metric });
       logger2.info("Collection created", { name, dimension, metric });
       return ok(void 0);
@@ -775,7 +778,7 @@ function createLancedbProvider() {
         await table.mergeInsert("id").whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(records);
       } else {
         logger2.warn("LanceDB mergeInsert is unavailable, falling back to delete/add upsert");
-        const ids = documents.map((d) => `"${escapeLanceFilterValue(d.id)}"`).join(", ");
+        const ids = documents.map((d) => `'${escapeLanceSqlValue(d.id)}'`).join(", ");
         await table.delete(`id IN (${ids})`);
         await table.add(records);
       }
@@ -788,7 +791,7 @@ function createLancedbProvider() {
       if (!table) {
         return err(HaiVecdbError.COLLECTION_NOT_FOUND, vecdbM("vecdb_collectionNotFound", { params: { name: collection } }));
       }
-      const idList = ids.map((id) => `"${escapeLanceFilterValue(id)}"`).join(", ");
+      const idList = ids.map((id) => `'${escapeLanceSqlValue(id)}'`).join(", ");
       await table.delete(`id IN (${idList})`);
       logger2.info("Vectors deleted", { collection, count: ids.length });
       return ok(void 0);
@@ -1494,14 +1497,14 @@ function createQdrantProvider() {
         }));
         filter = { must: mustConditions };
       }
-      const searchResult = await client.search(collection, {
-        vector,
+      const searchResult = await client.query(collection, {
+        query: vector,
         limit: topK,
         score_threshold: minScore > 0 ? minScore : void 0,
         filter,
         with_payload: true
       });
-      const results = searchResult.map((point) => {
+      const results = searchResult.points.map((point) => {
         const payload = point.payload ?? {};
         const { _id, _content, ...metadata } = payload;
         return {