@h-ai/vecdb 0.1.0-alpha.66 → 0.1.0-alpha.67

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.en.md +16 -11
  2. package/README.ja.md +17 -12
  3. package/README.md +17 -12
  4. package/package.json +2 -2
package/README.en.md CHANGED
@@ -4,22 +4,27 @@
4
4
 
5
5
  [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
6
6
 
7
+ ## Introduction
8
+
7
9
  A vector database module with a unified `vecdb` object for LanceDB, pgvector, Qdrant, and Chroma.
8
10
 
9
- ## Supported vector databases
11
+ ## Core features
12
+
13
+ - Create collections with a defined vector dimension.
14
+ - Store document vectors, search by similarity and filter metadata.
15
+ - Use LanceDB, pgvector, Qdrant or Chroma; backend setup is described below.
10
16
 
11
- - LanceDB (embedded, local file storage, zero configuration)
12
- - pgvector (PostgreSQL + pgvector extension)
13
- - Qdrant (high-performance vector search engine; server 1.10.0+ with the Query API)
14
- - Chroma (automatically start a local service in embedded mode, or connect to an existing service)
17
+ ## Getting started
15
18
 
16
- ## Quick start
19
+ ### Quick start
17
20
 
18
21
  ```ts
19
22
  import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
20
23
 
21
24
  // 初始化（LanceDB）
22
- await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
25
+ const initialized = await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
26
+ if (!initialized.success)
27
+ throw new Error(initialized.error.message)
23
28
 
24
29
  // 创建集合
25
30
  await vecdb.collection.create('docs', { dimension: 1536 })
@@ -44,7 +49,7 @@ if (!closeResult.success) {
44
49
  }
45
50
  ```
46
51
 
47
- ## Configuration
52
+ ### Configuration
48
53
 
49
54
  ```ts
50
55
  // LanceDB（默认，嵌入式本地存储）
@@ -79,7 +84,7 @@ await vecdb.init({ type: 'chroma', url: 'http://localhost:8000' })
79
84
  > starts a local service with `serverCommand` (default: `chroma`, from the `chromadb` package), and `vecdb.close`
80
85
  > stops the process. Install the optional `chromadb` dependency; if the command is unavailable, `init` returns `CONNECTION_FAILED`.
81
86
 
82
- ### Operation logging
87
+ #### Operation logging
83
88
 
84
89
  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`.
85
90
 
@@ -111,7 +116,7 @@ await vecdb.init({
111
116
 
112
117
  > 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`.
113
118
 
114
- ## Error handling
119
+ ### Error handling
115
120
 
116
121
  All operations return `HaiResult<T>`; check `result.success` for success or failure.
117
122
 
@@ -132,7 +137,7 @@ if (!result.success) {
132
137
  }
133
138
  ```
134
139
 
135
- ## Tests
140
+ ## Development and testing
136
141
 
137
142
  ```bash
138
143
  pnpm --filter @h-ai/vecdb test
package/README.ja.md CHANGED
@@ -4,22 +4,27 @@
4
4
 
5
5
  [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
6
6
 
7
+ ## 概要
8
+
7
9
  共通の `vecdb` オブジェクトで LanceDB、pgvector、Qdrant、Chroma を操作するベクトルデータベースモジュールです。
8
10
 
9
- ## 対応ベクトルデータベース
11
+ ## 主な機能
12
+
13
+ - ベクトル次元を指定したコレクションの作成・管理。
14
+ - 文書ベクトルの保存、類似検索、メタデータ条件の絞り込み。
15
+ - LanceDB・pgvector・Qdrant・Chroma に対応。準備方法は下記設定を参照。
10
16
 
11
- - LanceDB（組み込み型、ローカルファイル保存、設定不要）
12
- - pgvector（PostgreSQL + pgvector 拡張）
13
- - Qdrant（高性能ベクトル検索エンジン。Query API を使用するため、サーバー 1.10.0 以降が必要）
14
- - Chroma（組み込みモードでローカルサービスを自動起動、または既存サービスへ直接接続）
17
+ ## 使い始める
15
18
 
16
- ## クイックスタート
19
+ ### クイックスタート
17
20
 
18
21
  ```ts
19
22
  import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
20
23
 
21
24
  // 初始化（LanceDB）
22
- await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
25
+ const initialized = await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
26
+ if (!initialized.success)
27
+ throw new Error(initialized.error.message)
23
28
 
24
29
  // 创建集合
25
30
  await vecdb.collection.create('docs', { dimension: 1536 })
@@ -44,7 +49,7 @@ if (!closeResult.success) {
44
49
  }
45
50
  ```
46
51
 
47
- ## 設定
52
+ ### 設定
48
53
 
49
54
  ```ts
50
55
  // LanceDB（默认，嵌入式本地存储）
@@ -79,7 +84,7 @@ await vecdb.init({ type: 'chroma', url: 'http://localhost:8000' })
79
84
  > `serverCommand`（既定は `chromadb` パッケージの `chroma`）でローカルサービスを起動し、`vecdb.close` が
80
85
  > そのプロセスを停止します。任意依存の `chromadb` をインストールしてください。コマンドが利用できない場合、`init` は `CONNECTION_FAILED` を返します。
81
86
 
82
- ### 操作ログ
87
+ #### 操作ログ
83
88
 
84
89
  ベクトルデータベース設定の `operationLog` で操作ログを有効にできます。ログはコレクション・ベクトル操作が実際の Provider に渡る前に出力され、`vecdb-main.ts` で一括ラップはしません。
85
90
 
@@ -111,7 +116,7 @@ await vecdb.init({
111
116
 
112
117
  > 動作：空の一括 `insert/upsert/delete` は何もしません。書き込み・検索時にはベクトル次元を検証し、不一致なら `HaiVecdbError.DIMENSION_MISMATCH`、任意ドライバーの不足なら `HaiVecdbError.DRIVER_NOT_FOUND` を返します。
113
118
 
114
- ## エラー処理
119
+ ### エラー処理
115
120
 
116
121
  すべての操作は `HaiResult<T>` を返し、`result.success` で成功・失敗を判定します。
117
122
 
@@ -132,7 +137,7 @@ if (!result.success) {
132
137
  }
133
138
  ```
134
139
 
135
- ## テスト
140
+ ## 開発とテスト
136
141
 
137
142
  ```bash
138
143
  pnpm --filter @h-ai/vecdb test
@@ -140,6 +145,6 @@ pnpm --filter @h-ai/vecdb test
140
145
 
141
146
  > pgvector / Qdrant のテストには Docker が必要です。
142
147
 
143
- ## License
148
+ ## ライセンス
144
149
 
145
150
  Apache-2.0
package/README.md CHANGED
@@ -4,22 +4,27 @@
4
4
 
5
5
  [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
6
6
 
7
+ ## 简介
8
+
7
9
  向量数据库模块，通过统一的 `vecdb` 对象访问 LanceDB、pgvector、Qdrant、Chroma。
8
10
 
9
- ## 支持的向量数据库
11
+ ## 核心功能清单
12
+
13
+ - 创建和管理固定向量维度的集合。
14
+ - 写入文档向量，按相似度检索并过滤元数据。
15
+ - 支持 LanceDB、pgvector、Qdrant 与 Chroma；后端准备方式见下方配置。
10
16
 
11
- - LanceDB（嵌入式，本地文件存储，零配置）
12
- - pgvector（PostgreSQL + pgvector 扩展）
13
- - Qdrant（高性能向量搜索引擎；服务端需 1.10.0+，使用 Query API）
14
- - Chroma（支持嵌入式自动拉起本地服务，或直连已有服务）
17
+ ## 使用入门
15
18
 
16
- ## 快速开始
19
+ ### 快速开始
17
20
 
18
21
  ```ts
19
22
  import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
20
23
 
21
24
  // 初始化（LanceDB）
22
- await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
25
+ const initialized = await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
26
+ if (!initialized.success)
27
+ throw new Error(initialized.error.message)
23
28
 
24
29
  // 创建集合
25
30
  await vecdb.collection.create('docs', { dimension: 1536 })
@@ -44,7 +49,7 @@ if (!closeResult.success) {
44
49
  }
45
50
  ```
46
51
 
47
- ## 配置
52
+ ### 配置
48
53
 
49
54
  ```ts
50
55
  // LanceDB（默认，嵌入式本地存储）
@@ -79,7 +84,7 @@ await vecdb.init({ type: 'chroma', url: 'http://localhost:8000' })
79
84
  > 通过 `serverCommand`（默认 `chroma`，来自 `chromadb` 包）拉起本地服务，`vecdb.close`
80
85
  > 时关闭进程。需安装可选依赖 `chromadb`；服务命令不可用时 `init` 返回 `CONNECTION_FAILED`。
81
86
 
82
- ### 操作日志
87
+ #### 操作日志
83
88
 
84
89
  可在向量数据库配置中通过 `operationLog` 开启操作日志。日志在集合/向量操作进入真实 Provider 前输出，不在 `vecdb-main.ts` 中做统一包装。
85
90
 
@@ -111,7 +116,7 @@ await vecdb.init({
111
116
 
112
117
  > 行为说明：空批量 `insert/upsert/delete` 会被视为 no-op；写入与搜索会校验向量维度，不匹配时返回 `HaiVecdbError.DIMENSION_MISMATCH`；缺少可选驱动时返回 `HaiVecdbError.DRIVER_NOT_FOUND`。
113
118
 
114
- ## 错误处理
119
+ ### 错误处理
115
120
 
116
121
  所有操作返回 `HaiResult<T>`，通过 `result.success` 判断成功或失败。
117
122
 
@@ -132,7 +137,7 @@ if (!result.success) {
132
137
  }
133
138
  ```
134
139
 
135
- ## 测试
140
+ ## 开发测试
136
141
 
137
142
  ```bash
138
143
  pnpm --filter @h-ai/vecdb test
@@ -140,6 +145,6 @@ pnpm --filter @h-ai/vecdb test
140
145
 
141
146
  > pgvector / Qdrant 测试需要 Docker。
142
147
 
143
- ## License
148
+ ## 许可证
144
149
 
145
150
  Apache-2.0
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@h-ai/vecdb",
3
3
  "type": "module",
4
- "version": "0.1.0-alpha.66",
4
+ "version": "0.1.0-alpha.67",
5
5
  "description": "Hai Framework vector database module for LanceDB, pgvector, Qdrant, and Chroma.",
6
6
  "license": "Apache-2.0",
7
7
  "exports": {
@@ -23,7 +23,7 @@
23
23
  "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
24
24
  },
25
25
  "dependencies": {
26
- "@h-ai/core": "0.1.0-alpha.66",
26
+ "@h-ai/core": "0.1.0-alpha.67",
27
27
  "zod": "^4.6.5"
28
28
  },
29
29
  "optionalDependencies": {