@h-ai/vecdb 1.0.0-beta.2 → 1.0.0-beta.21

package/README.en.md

@@ -4,19 +4,11 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
 
-## Introduction
-
 A vector database module with a unified `vecdb` object for LanceDB, pgvector, Qdrant, and Chroma.
 
-## Core features
-
-- Create collections with a defined vector dimension.
-- Store document vectors, search by similarity and filter metadata.
-- Use LanceDB, pgvector, Qdrant or Chroma; backend setup is described below.
+## Quick Start
 
-## Getting started
-
-### Quick start
+Every provider returns `score` in 0–1, with larger values indicating greater similarity; `minScore` filters converted scores. Cosine uses `(1 + cosine) / 2`, dot uses `sigmoid(dotProduct)`, and Euclidean uses `1 / (1 + distance)`. LanceDB/Chroma use native squared L2 while other backends use native L2. Calibrate thresholds for each metric/backend; scores are not probabilities. Qdrant no longer treats the public minScore as a native distance threshold.
 
 ```ts
 import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
@@ -31,7 +23,12 @@ 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' } },
+  {
+    id: 'doc-1',
+    vector: Array.from({ length: 1536 }).fill(0.1),
+    content: '文档内容',
+    metadata: { source: 'wiki' }
+  },
 ])
 
 // 搜索
@@ -49,7 +46,53 @@ if (!closeResult.success) {
 }
 ```
 
-### Configuration
+## Features
+
+- Create collections with a defined vector dimension.
+- Store document vectors, search by similarity and filter metadata.
+- Use LanceDB, pgvector, Qdrant or Chroma; backend setup is described below.
+
+### Operations and results
+
+Use the complete initialization flow in this section first. The host validates and authorizes example business values; check success before reading data from asynchronous domain results. Here void means completion without data, null means absent; synchronous factories/tools return the listed type directly.
+
+#### vecdb.collection
+
+Manage vector collections: create takes name/dimension options, drop a name and both yield void; exists yields boolean, info metadata, list names without arguments.
+
+| Entry                     | Input parameters | Successful result | Call example                                                      |
+| ------------------------- | ---------------- | ----------------- | ----------------------------------------------------------------- |
+| `vecdb.collection.create` | name, options    | `void`            | `await vecdb.collection.create('documents', { dimension: 1536 })` |
+| `vecdb.collection.drop`   | name             | `void`            | `await vecdb.collection.drop('documents')`                        |
+| `vecdb.collection.exists` | name             | `boolean`         | `await vecdb.collection.exists('documents')`                      |
+| `vecdb.collection.info`   | name             | `CollectionInfo`  | `await vecdb.collection.info('documents')`                        |
+| `vecdb.collection.list`   | No arguments     | `string[]`        | `await vecdb.collection.list()`                                   |
+
+#### vecdb.vector
+
+Insert/upsert take collection/documents, delete IDs, yielding void; search takes a vector and filter/topK and yields hits, count a total. Scores are normalized similarity, not probabilities.
+
+| Entry                 | Input parameters            | Successful result      | Call example                                                       |
+| --------------------- | --------------------------- | ---------------------- | ------------------------------------------------------------------ |
+| `vecdb.vector.insert` | collection, documents       | `void`                 | `await vecdb.vector.insert('documents', vectorDocuments)`          |
+| `vecdb.vector.upsert` | collection, documents       | `void`                 | `await vecdb.vector.upsert('documents', vectorDocuments)`          |
+| `vecdb.vector.delete` | collection, ids             | `void`                 | `await vecdb.vector.delete('documents', ['doc-1'])`                |
+| `vecdb.vector.search` | collection, vector, options | `VectorSearchResult[]` | `await vecdb.vector.search('documents', queryVector, { topK: 5 })` |
+| `vecdb.vector.count`  | collection                  | `number`               | `await vecdb.vector.count('documents')`                            |
+
+### Production shared state
+
+Production uses Qdrant, pgvector or remote Chroma. LanceDB and embedded Chroma are for development/explicit tests. Initialization checks apply when NODE_ENV or HAI_CORE_ENV is production; only explicit HAI_E2E=1/HAI_E2E_MOCK=1 tests are exempt. [State, concurrency and recovery (Chinese)](../../.agents/instructions/distributed-state.md).
+
+### Closing and recovery
+
+close immediately stops current operations, including previously captured operation references. Failed candidates and resources that failed to close retain cleanup ownership without serving requests. Concurrent close calls coalesce; an in-flight init settles ownership before close proceeds. error.ext.cleanupPending requires retrying close on the same module. init cannot replace a resource until cleanup succeeds. Embedded Chroma waits for the actual spawn event and direct child exit: 1.5 seconds after normal termination it sends a forced signal, then waits another 1.5 seconds. Unconfirmed exit returns failure and retains the handle. Direct-child verification does not establish process-tree termination or live Chroma CLI readiness.
+
+## Configuration
+
+Lifecycle: init takes backend/business configuration; use the module only after success. Await close before releasing borrowed dependencies. Follow the quick-start example and public signatures for exact return values.
+
+pgvector persists each collection metric in its vector column comment; indexes, info and queries use that definition. Changing the connection default leaves existing collections unchanged. Legacy collections recover the metric from their vector index; missing both index and valid metadata returns CONFIG_ERROR until repaired.
 
 ```ts
 // LanceDB（默认，嵌入式本地存储）
@@ -90,7 +133,9 @@ For Chroma, this module sends the optional `apiKey` as `Authorization: Bearer <a
 
 Direct initialization has a total deadline of 5 seconds; local server startup uses `startupTimeout`. Expiry aborts candidate HTTP requests. Successful initialization clears the timer, so this deadline does not limit subsequent business requests.
 
-Qdrant uses the actual types and Query API of `@qdrant/js-client-rest 1.18.0`. It supports an unnamed vector field with cosine/euclidean/dot metrics. Info, writes and searches on external named-vector or Manhattan collections return `CONFIG_ERROR`, without guessing zero dimensions or a default cosine metric. Only HTTP 404 means a collection is absent. Provider URL logs use core's shared sanitizer.
+Qdrant uses fixed REST endpoints over native HTTP without an extra SDK. Unnamed cosine/euclidean/dot vectors are supported. The 30-second timeout covers the full response body; responses over 16 MiB fail explicitly. Path segments are encoded and writes/deletes await server application. External named-vector or Manhattan collections return `CONFIG_ERROR`; only HTTP 404 means absent. Logs use core sanitization.
+
+Fixed Qdrant requests reject HTTP redirects, preventing API Key forwarding to redirect targets.
 
 Chroma metadata/filter values follow native `chromadb 3.5.0` validation. Invalid values return operation errors without dropping filters or issuing unfiltered queries. Document content may be omitted and search still returns `undefined`; internal writes use the SDK's string field. Check each backend's null, complex-metadata and filter semantics separately.
 
@@ -108,7 +153,7 @@ LanceDB stores `metadata` in a native JSON field, accepts nested JSON, and resto
 
 LanceDB `filter` supports AND equality on literal top-level keys, for example `{ tenant: 'acme', page: 1, active: true, removedAt: null }`. Values may be strings, finite numbers, booleans, or null. Types remain distinct: `1` differs from `'1'`, and `true` from `'true'`. Null matches explicit JSON null, never a missing key. Dots/brackets are literal key characters; quotes, backslashes, `%`, and `_` have no SQL or wildcard meaning. An empty object adds no restriction. Objects, arrays, undefined, and nonfinite numbers return `CONFIG_ERROR`, never an unfiltered query. Filtering precedes vector topK selection; minScore then filters scores. Other providers retain native restrictions and do not promise identical null, complex-value, or path semantics. Check capabilities when switching backends. Sources: [Lance 13 JSON UDF](https://github.com/lance-format/lance/blob/v13.0.0/rust/lance-datafusion/src/udf/json.rs), [Node 0.40.0 JSON field](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/arrow.ts).
 
-#### Operation logging
+### 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`.
 
@@ -140,9 +185,15 @@ await vecdb.init({
 
 > 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`.
 
-Qdrant `insert/upsert/delete` use `wait: true`, so success means the server applied that operation. `vector.count` requests an exact count rather than approximate collection statistics. Multiple operations do not form a transaction.
+Qdrant uses fixed REST endpoints over native HTTP without an extra SDK. Unnamed cosine/euclidean/dot vectors are supported. The 30-second timeout covers the full response body; responses over 16 MiB fail explicitly. Path segments are encoded and writes/deletes await server application. External named-vector or Manhattan collections return `CONFIG_ERROR`; only HTTP 404 means absent. Logs use core sanitization.
+
+The host loads and validates configuration before passing it to this module. Keep secrets in private server environment files. Select the backend, capacity, deadlines and logging for the actual use case; reinitialize and check the result after changes.
+
+[Per-option purpose, use cases and examples](../../docs/usage/configuration/data.md).
 
-### Error handling
+## Error Handling
+
+Check result.success for domain operations. Handle failures with the module error definitions and safe messages; retain codes, correlation IDs and sanitized causes in server logs. Synchronous tools, factories, stream iteration and lifecycle calls follow their own signatures. A completed Promise alone is not business success. See each feature for recovery limits.
 
 All operations return `HaiResult<T>`; check `result.success` for success or failure.
 
@@ -163,15 +214,7 @@ if (!result.success) {
 }
 ```
 
-## Production shared state
-
-Production uses Qdrant, pgvector or remote Chroma. LanceDB and embedded Chroma are for development/explicit tests. Initialization checks apply when NODE_ENV or HAI_CORE_ENV is production; only explicit HAI_E2E=1/HAI_E2E_MOCK=1 tests are exempt. [State, concurrency and recovery (Chinese)](../../.agents/instructions/distributed-state.md)。
-
-## Closing and recovery
-
-close immediately stops current operations, including previously captured operation references. Failed candidates and resources that failed to close retain cleanup ownership without serving requests. Concurrent close calls coalesce; an in-flight init settles ownership before close proceeds. error.ext.cleanupPending requires retrying close on the same module. init cannot replace a resource until cleanup succeeds. Embedded Chroma waits for the actual spawn event and direct child exit: 1.5 seconds after normal termination it sends a forced signal, then waits another 1.5 seconds. Unconfirmed exit returns failure and retains the handle. Direct-child verification does not establish process-tree termination or live Chroma CLI readiness.
-
-## Development and testing
+## Development
 
 ```bash
 pnpm --filter @h-ai/vecdb test

package/README.ja.md

@@ -4,19 +4,11 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
 
-## 概要
-
 共通の `vecdb` オブジェクトで LanceDB、pgvector、Qdrant、Chroma を操作するベクトルデータベースモジュールです。
 
-## 主な機能
-
-- ベクトル次元を指定したコレクションの作成・管理。
-- 文書ベクトルの保存、類似検索、メタデータ条件の絞り込み。
-- LanceDB・pgvector・Qdrant・Chroma に対応。準備方法は下記設定を参照。
+## クイックスタート
 
-## 使い始める
-
-### クイックスタート
+すべての Provider の `score` は 0–1 で、高いほど類似し、`minScore` は変換後に適用します。cosine は `(1 + cosine) / 2`、dot は `sigmoid(dotProduct)`、euclidean は `1 / (1 + distance)` です。LanceDB/Chroma はネイティブの squared L2、他のバックエンドはネイティブ L2 を使います。閾値は metric・バックエンドごとに業務で校正し、score を確率とは扱いません。Qdrant は公開 minScore をネイティブ距離の閾値として直接送信しません。
 
 ```ts
 import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
@@ -31,7 +23,12 @@ 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' } },
+  {
+    id: 'doc-1',
+    vector: Array.from({ length: 1536 }).fill(0.1),
+    content: '文档内容',
+    metadata: { source: 'wiki' }
+  },
 ])
 
 // 搜索
@@ -49,7 +46,53 @@ if (!closeResult.success) {
 }
 ```
 
-### 設定
+## 機能
+
+- ベクトル次元を指定したコレクションの作成・管理。
+- 文書ベクトルの保存、類似検索、メタデータ条件の絞り込み。
+- LanceDB・pgvector・Qdrant・Chroma に対応。準備方法は下記設定を参照。
+
+### 操作と入出力
+
+本節の完全な初期化手順を先に実行します。例の業務値はホストが検証・認可し、非同期領域結果は success を確認してから data を読みます。void はデータなし完了、null は不存在、同期ファクトリー/ツールは表の型を直接返します。
+
+#### vecdb.collection
+
+ベクトル集合を管理。create は名前/次元等、drop は名前から void。exists は boolean、info は次元等、list は引数なしで名前配列。
+
+| 入口                      | 入力引数      | 成功結果         | 呼出し例                                                          |
+| ------------------------- | ------------- | ---------------- | ----------------------------------------------------------------- |
+| `vecdb.collection.create` | name, options | `void`           | `await vecdb.collection.create('documents', { dimension: 1536 })` |
+| `vecdb.collection.drop`   | name          | `void`           | `await vecdb.collection.drop('documents')`                        |
+| `vecdb.collection.exists` | name          | `boolean`        | `await vecdb.collection.exists('documents')`                      |
+| `vecdb.collection.info`   | name          | `CollectionInfo` | `await vecdb.collection.info('documents')`                        |
+| `vecdb.collection.list`   | 引数なし      | `string[]`       | `await vecdb.collection.list()`                                   |
+
+#### vecdb.vector
+
+insert/upsert は集合と文書配列、delete は ID 配列から void。search はベクトルと filter/topK からヒット配列、count は件数。点数は類似度で確率ではない。
+
+| 入口                  | 入力引数                    | 成功結果               | 呼出し例                                                           |
+| --------------------- | --------------------------- | ---------------------- | ------------------------------------------------------------------ |
+| `vecdb.vector.insert` | collection, documents       | `void`                 | `await vecdb.vector.insert('documents', vectorDocuments)`          |
+| `vecdb.vector.upsert` | collection, documents       | `void`                 | `await vecdb.vector.upsert('documents', vectorDocuments)`          |
+| `vecdb.vector.delete` | collection, ids             | `void`                 | `await vecdb.vector.delete('documents', ['doc-1'])`                |
+| `vecdb.vector.search` | collection, vector, options | `VectorSearchResult[]` | `await vecdb.vector.search('documents', queryVector, { topK: 5 })` |
+| `vecdb.vector.count`  | collection                  | `number`               | `await vecdb.vector.count('documents')`                            |
+
+### 本番の共有状態
+
+本番は Qdrant・pgvector・リモート Chroma を使います。LanceDB と組み込み Chroma は開発・明示的テスト用です。 NODE_ENV または HAI_CORE_ENV が production の場合、初期化成功前に検証します。明示的な HAI_E2E=1/HAI_E2E_MOCK=1 テストのみ除外します。 [状態・並行制御・復旧範囲（中国語）](../../.agents/instructions/distributed-state.md).
+
+### 終了と失敗からの回復
+
+close は取得済みの操作参照も含めて業務処理を停止します。初期化や終了に失敗したリソースは後処理の所有権だけを保持します。同時 close は統合し、実行中の init の所有権確定を待ちます。error.ext.cleanupPending があれば同じモジュールの close を再試行し、後処理が成功するまで init は代替リソースを作成しません。内嵌 Chroma は実際の spawn と直接子プロセスの exit を確認します。通常終了から1.5秒後に強制終了へ進み、さらに1.5秒待っても確認できなければハンドルを保持して失敗を返します。直接子プロセスの検証はプロセスツリー全体や実際の Chroma CLI 起動の証明ではありません。
+
+## 設定
+
+ライフサイクル。init にバックエンド/業務設定を渡し成功後に使用します。借用依存先の解放前に close の完了を待ち、正確な戻り値は例と公開署名に従います。
+
+pgvector は距離尺度を vector 列コメントに保存し、索引・info・検索で共有します。接続の既定値変更は既存集合に影響しません。旧集合は実際の索引から復元し、索引と有効なメタデータが両方ない場合は CONFIG_ERROR を返します。
 
 ```ts
 // LanceDB（默认，嵌入式本地存储）
@@ -90,7 +133,9 @@ Chroma の任意の `apiKey` は、このモジュールの規約として `Auth
 
 直接接続の初期化全体の期限は 5 秒です。ローカルサービス起動では `startupTimeout` を使用します。期限を超えると候補 HTTP リクエストを中止します。成功時はタイマーを解除するため、この期限は以後の業務リクエストには適用されません。
 
-Qdrant は `@qdrant/js-client-rest 1.18.0` の実際の型と Query API を使用し、名前のない単一ベクトルフィールドと cosine/euclidean/dot に対応します。外部の named-vector・Manhattan 集合の info・書き込み・検索は `CONFIG_ERROR` を返し、ゼロ次元や既定 cosine と推測しません。集合が存在しないと判断するのは HTTP 404 のみです。Provider の URL ログは core の共通マスク処理を使います。
+Qdrant は追加 SDK なしでネイティブ HTTP の固定 REST エンドポイントを使い、名前のない cosine/euclidean/dot ベクトルに対応します。30 秒のタイムアウトは本文全体を含み、16 MiB 超の応答は明示的に失敗します。パスをエンコードし、書き込み・削除は適用完了を待ちます。named-vector・Manhattan は `CONFIG_ERROR`、存在しないと判断するのは HTTP 404 のみです。ログは core のマスク処理を使います。
+
+Qdrant の固定バックエンド要求は HTTP リダイレクトを拒否し、API Key を転送先に渡しません。
 
 Chroma の metadata/filter は `chromadb 3.5.0` の検証に従います。不正値は操作エラーとなり、フィルターの削除や無条件検索にはフォールバックしません。content は省略でき、検索結果は `undefined` のままです。内部書き込みでは SDK の文字列フィールドに合わせます。null・複雑なメタデータ・フィルターの意味はバックエンドごとに確認してください。
 
@@ -100,15 +145,15 @@ LanceDB はローカルファイルを使う組み込みバックエンドです
 
 検索は集合の metric を使い、`euclidean` を LanceDB の `l2` に対応させます。score は公開 API の 0–1、高いほど類似する契約に従い、cosine は `clamp(1 - distance / 2, 0, 1)`、euclidean は `1 / (1 + squaredL2)`、dot は順位を保つ `sigmoid(dotProduct)` を使います（確率ではありません）。`minScore` は変換後に適用し、異なる metric・バックエンド間で閾値が共通に校正されているとは扱いません。
 
-原子書き込みの検証対象は `@lancedb/lancedb 0.40.0 / Lance 13` です。新規集合は初期 Arrow schema で id を非 null 主キーにし、insert/upsert は id を使う原生 merge の厳密なキー競合検出を使用します。根拠：[Lance 13 table format](https://github.com/lance-format/lance/blob/v13.0.0/docs/src/format/table/index.md#unenforced-primary-key)、[Lance 13 transaction](https://github.com/lance-format/lance/blob/v13.0.0/protos/transaction.proto)、[Node binding 0.40.0](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/table.ts)。
+原子書き込みの検証対象は `@lancedb/lancedb 0.40.0 / Lance 13` です。新規集合は初期 Arrow schema で id を非 null 主キーにし、insert/upsert は id を使う原生 merge の厳密なキー競合検出を使用します。根拠：[Lance 13 table format](https://github.com/lance-format/lance/blob/v13.0.0/docs/src/format/table/index.md#unenforced-primary-key)、[Lance 13 transaction](https://github.com/lance-format/lance/blob/v13.0.0/protos/transaction.proto)、[Node binding 0.40.0](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/table.ts).
 
 LanceDB の `insert` は既存 ID を上書きせず、`upsert` は追加または行全体を置換します。バッチ内の重複 ID、merge 能力・永続主キーの欠落は書き込み前に `CONFIG_ERROR` を返します。旧形式の集合は再作成が必要で、自動移行や削除はしません。原子性は各 merge に限られ、並行処理の勝者はコミット順で決まります。複数 merge や reldb/vecdb 間の共通トランザクションはありません。delete/add への切り替えはなく、不明な結果は ID で照合します。外部の原生 add はこの保護を迂回します。
 
 LanceDB の `metadata` はネイティブ JSON フィールドです。入れ子の JSON を保存でき、検索結果ではオブジェクトに復元します。insert/upsert とも明示的な Arrow JSON schema で JSONB に変換します。旧 Utf8 metadata テーブルへの書き込み・フィルターは `CONFIG_ERROR` を返し、再作成が必要です。自動移行はしません。
 
-LanceDB の `filter` は最上位のリテラルキーを AND で完全一致させます。例：`{ tenant: 'acme', page: 1, active: true, removedAt: null }`。値は文字列・有限数値・真偽値・null のみで、`1` と `'1'`、`true` と `'true'` を区別します。null は明示的な JSON null のみに一致し、欠落キーには一致しません。点や括弧はパスではなくキー文字です。引用符・バックスラッシュ・`%`・`_` に SQL/ワイルドカードの意味はありません。空オブジェクトは制限なしです。オブジェクト・配列・undefined・非有限数値は `CONFIG_ERROR` を返し、無条件検索に変更しません。フィルターはベクトル topK の前、minScore はその後に適用します。他の Provider の null・複合値・パスの意味は同一とは保証しません。バックエンド変更時は固有の制約を確認してください。根拠：[Lance 13 JSON UDF](https://github.com/lance-format/lance/blob/v13.0.0/rust/lance-datafusion/src/udf/json.rs)、[Node 0.40.0 JSON field](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/arrow.ts)。
+LanceDB の `filter` は最上位のリテラルキーを AND で完全一致させます。例：`{ tenant: 'acme', page: 1, active: true, removedAt: null }`。値は文字列・有限数値・真偽値・null のみで、`1` と `'1'`、`true` と `'true'` を区別します。null は明示的な JSON null のみに一致し、欠落キーには一致しません。点や括弧はパスではなくキー文字です。引用符・バックスラッシュ・`%`・`_` に SQL/ワイルドカードの意味はありません。空オブジェクトは制限なしです。オブジェクト・配列・undefined・非有限数値は `CONFIG_ERROR` を返し、無条件検索に変更しません。フィルターはベクトル topK の前、minScore はその後に適用します。他の Provider の null・複合値・パスの意味は同一とは保証しません。バックエンド変更時は固有の制約を確認してください。根拠：[Lance 13 JSON UDF](https://github.com/lance-format/lance/blob/v13.0.0/rust/lance-datafusion/src/udf/json.rs)、[Node 0.40.0 JSON field](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/arrow.ts).
 
-#### 操作ログ
+### 操作ログ
 
 ベクトルデータベース設定の `operationLog` で操作ログを有効にできます。ログはコレクション・ベクトル操作が実際の Provider に渡る前に出力され、`vecdb-main.ts` で一括ラップはしません。
 
@@ -140,9 +185,15 @@ await vecdb.init({
 
 > 動作：空の一括 `insert/upsert/delete` は何もしません。書き込み・検索時にはベクトル次元を検証し、不一致なら `HaiVecdbError.DIMENSION_MISMATCH`、任意ドライバーの不足なら `HaiVecdbError.DRIVER_NOT_FOUND` を返します。
 
-Qdrant の `insert/upsert/delete` は `wait: true` を使用し、成功はサーバーでの適用完了を表します。`vector.count` は集合情報の近似値ではなく正確な件数を取得します。複数操作をまとめたトランザクションではありません。
+Qdrant は追加 SDK なしでネイティブ HTTP の固定 REST エンドポイントを使い、名前のない cosine/euclidean/dot ベクトルに対応します。30 秒のタイムアウトは本文全体を含み、16 MiB 超の応答は明示的に失敗します。パスをエンコードし、書き込み・削除は適用完了を待ちます。named-vector・Manhattan は `CONFIG_ERROR`、存在しないと判断するのは HTTP 404 のみです。ログは core のマスク処理を使います。
+
+設定はホストが読込・検証してから渡します。秘密はサーバーの非公開環境に保存し、利用場面に応じてバックエンド・容量・期限・ログを選びます。変更後は再初期化の結果を確認してください。
+
+[項目別の用途・適用場面・例](../../docs/usage/configuration/data.md).
 
-### エラー処理
+## エラー処理
+
+領域操作は result.success を確認し、失敗時はモジュールのエラー定義と安全な説明を使います。コード・関連 ID・秘匿した原因をサーバーログに残します。同期ツール・ファクトリー・ストリーム反復・ライフサイクルは各署名に従い、Promise 完了だけで成功と判断しません。回復条件は各機能を参照してください。
 
 すべての操作は `HaiResult<T>` を返し、`result.success` で成功・失敗を判定します。
 
@@ -163,14 +214,6 @@ if (!result.success) {
 }
 ```
 
-## 本番の共有状態
-
-本番は Qdrant・pgvector・リモート Chroma を使います。LanceDB と組み込み Chroma は開発・明示的テスト用です。 NODE_ENV または HAI_CORE_ENV が production の場合、初期化成功前に検証します。明示的な HAI_E2E=1/HAI_E2E_MOCK=1 テストのみ除外します。 [状態・並行制御・復旧範囲（中国語）](../../.agents/instructions/distributed-state.md)。
-
-## 終了と失敗からの回復
-
-close は取得済みの操作参照も含めて業務処理を停止します。初期化や終了に失敗したリソースは後処理の所有権だけを保持します。同時 close は統合し、実行中の init の所有権確定を待ちます。error.ext.cleanupPending があれば同じモジュールの close を再試行し、後処理が成功するまで init は代替リソースを作成しません。内嵌 Chroma は実際の spawn と直接子プロセスの exit を確認します。通常終了から1.5秒後に強制終了へ進み、さらに1.5秒待っても確認できなければハンドルを保持して失敗を返します。直接子プロセスの検証はプロセスツリー全体や実際の Chroma CLI 起動の証明ではありません。
-
 ## 開発とテスト
 
 ```bash

package/README.md

@@ -4,19 +4,11 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
 
-## 简介
-
 向量数据库模块，通过统一的 `vecdb` 对象访问 LanceDB、pgvector、Qdrant、Chroma。
 
-## 核心功能清单
-
-- 创建和管理固定向量维度的集合。
-- 写入文档向量，按相似度检索并过滤元数据。
-- 支持 LanceDB、pgvector、Qdrant 与 Chroma；后端准备方式见下方配置。
+## 快速开始
 
-## 使用入门
-
-### 快速开始
+所有 Provider 的 `score` 都为 0–1，越大越相似；`minScore` 在转换后过滤。余弦使用 `(1 + cosine) / 2`，内积使用 `sigmoid(dotProduct)`，欧氏使用 `1 / (1 + distance)`；LanceDB/Chroma 的 distance 是原生 squared L2，其余后端使用原生 L2。不同 metric/后端的阈值仍需按业务校准，score 不代表概率。Qdrant 的公开 minScore 使用统一相似度，而非原生距离阈值。
 
 ```ts
 import { HaiVecdbError, vecdb } from '@h-ai/vecdb'
@@ -31,7 +23,12 @@ 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' } },
+  {
+    id: 'doc-1',
+    vector: Array.from({ length: 1536 }).fill(0.1),
+    content: '文档内容',
+    metadata: { source: 'wiki' }
+  },
 ])
 
 // 搜索
@@ -49,7 +46,53 @@ if (!closeResult.success) {
 }
 ```
 
-### 配置
+## 功能
+
+- 创建和管理固定向量维度的集合。
+- 写入文档向量，按相似度检索并过滤元数据。
+- 支持 LanceDB、pgvector、Qdrant 与 Chroma；后端准备方式见下方配置。
+
+### 功能输入输出
+
+以下片段依赖本节完整初始化流程。示例中的业务值由宿主校验和授权后传入；异步领域结果先判断 success，再读取 data。表中 void 表示操作已完成且没有返回数据，null 表示不存在；同步工厂/工具直接返回表中类型。
+
+#### vecdb.collection
+
+管理向量集合；create 输入名称/维度等定义，drop 输入名称均返回 void；exists 返回 boolean，info 返回维度等元数据，list 无参数返回名称数组。
+
+| 入口                      | 输入参数      | 成功结果         | 调用示例                                                          |
+| ------------------------- | ------------- | ---------------- | ----------------------------------------------------------------- |
+| `vecdb.collection.create` | name, options | `void`           | `await vecdb.collection.create('documents', { dimension: 1536 })` |
+| `vecdb.collection.drop`   | name          | `void`           | `await vecdb.collection.drop('documents')`                        |
+| `vecdb.collection.exists` | name          | `boolean`        | `await vecdb.collection.exists('documents')`                      |
+| `vecdb.collection.info`   | name          | `CollectionInfo` | `await vecdb.collection.info('documents')`                        |
+| `vecdb.collection.list`   | 无参数        | `string[]`       | `await vecdb.collection.list()`                                   |
+
+#### vecdb.vector
+
+写入/替换输入集合和文档数组，删除输入 ID 数组，均返回 void；search 输入查询向量和过滤/topK 返回命中数组，count 返回总数。分数为统一相似度，不是概率。
+
+| 入口                  | 输入参数                    | 成功结果               | 调用示例                                                           |
+| --------------------- | --------------------------- | ---------------------- | ------------------------------------------------------------------ |
+| `vecdb.vector.insert` | collection, documents       | `void`                 | `await vecdb.vector.insert('documents', vectorDocuments)`          |
+| `vecdb.vector.upsert` | collection, documents       | `void`                 | `await vecdb.vector.upsert('documents', vectorDocuments)`          |
+| `vecdb.vector.delete` | collection, ids             | `void`                 | `await vecdb.vector.delete('documents', ['doc-1'])`                |
+| `vecdb.vector.search` | collection, vector, options | `VectorSearchResult[]` | `await vecdb.vector.search('documents', queryVector, { topK: 5 })` |
+| `vecdb.vector.count`  | collection                  | `number`               | `await vecdb.vector.count('documents')`                            |
+
+### 生产共享状态
+
+生产使用 Qdrant、pgvector 或远端 Chroma；LanceDB 和嵌入式 Chroma 只用于开发/明确测试。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化发布成功前校验；仅 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试可豁免。 [状态、并发和恢复边界](../../.agents/instructions/distributed-state.md).
+
+### 关闭与失败恢复
+
+close 立即停止当前操作与此前取得的操作引用；连接失败候选和关闭失败资源仅作为待清理所有权保留，不再提供业务服务。并发 close 合并，进行中的 init 先确定资源归属再关闭。失败结果的 error.ext.cleanupPending 表示仍须用同一模块的 close 重试；清理成功前 init 不创建替代资源。内嵌 Chroma 等待实际 spawn，终止直接启动的服务器后等待 exit；普通终止超过 1.5 秒后升级强制终止，再等待 1.5 秒，未确认退出返回失败并保留句柄。该验证覆盖直接子进程，不把信号回执等同于进程树退出或真实 Chroma CLI 上线验收。
+
+## 配置
+
+生命周期：init 输入后端/业务配置，成功后才能使用；close 在释放借用依赖前等待完成。返回值以快速开始示例和公开签名为准。
+
+pgvector 创建集合时将距离算法保存在 vector 列注释，索引、info 与查询均读取该集合定义；修改连接默认 metric 不改变已有集合。旧集合从实际向量索引恢复算法；索引和有效注释均缺失时返回 CONFIG_ERROR，须先恢复集合定义。
 
 ```ts
 // LanceDB（默认，嵌入式本地存储）
@@ -84,13 +127,15 @@ await vecdb.init({ type: 'chroma', url: 'http://localhost:8000' })
 > 通过 `serverCommand`（默认 `chroma`）拉起本地服务，`vecdb.close` 时关闭进程。
 > npm 可选依赖 `chromadb` 提供 HTTP 客户端；服务端 CLI 需另行安装，命令不可用时 `init` 返回 `CONNECTION_FAILED`。
 
-Chroma 直连 `url` 仅接受 HTTP(S) 根端点（例如 `https://chroma.example.com:8443/`），优先于 `host/port`；不接受 URL 凭据、路径前缀、query 或 fragment。未提供 `url` 时使用 `host/port` 的 HTTP 连接。配置使用 `chromadb 3.5.0` 的 `host/port/ssl/headers` 参数，依据：[官方 TypeScript 客户端](https://docs.trychroma.com/reference/typescript/client)。
+Chroma 直连 `url` 仅接受 HTTP(S) 根端点（例如 `https://chroma.example.com:8443/`），优先于 `host/port`；不接受 URL 凭据、路径前缀、query 或 fragment。未提供 `url` 时使用 `host/port` 的 HTTP 连接。配置使用 `chromadb 3.5.0` 的 `host/port/ssl/headers` 参数，依据：[官方 TypeScript 客户端](https://docs.trychroma.com/reference/typescript/client).
 
 Chroma 的可选 `apiKey` 按本模块约定发送 `Authorization: Bearer <apiKey>`，仅用于采用该认证协议的自托管服务或网关；远程凭据传输应使用 HTTPS。空串表示不带凭据，非空值不得包含空白、控制字符或非 ASCII 字符。本接口使用默认 tenant/database，不提供 Chroma Cloud 的客户端与租户配置。初始化在心跳后验证集合计数数据端点；认证/权限失败返回 `CONNECTION_FAILED`，不会发布已连接状态，调用方必须检查 `success`。
 
 直连初始化的总截止为 5 秒，本地服务拉起使用 `startupTimeout`。超时中止候选 HTTP 请求；成功后清除初始化 timer，此截止不限制后续业务请求。
 
-Qdrant 使用 `@qdrant/js-client-rest 1.18.0` 的实际类型与 Query API，支持未命名向量字段的 cosine/euclidean/dot 集合。外部 named-vector 或 Manhattan 集合的 info/写入/搜索返回 `CONFIG_ERROR`，不猜测为零维或默认 cosine；仅 HTTP 404 表示集合不存在。Provider 的 URL 日志复用 core 的统一脱敏。
+Qdrant 使用原生 HTTP 固定 REST 端点，无额外 SDK 依赖，支持未命名向量字段的 cosine/euclidean/dot。30 秒超时覆盖完整响应体，16 MiB 响应上限超出时明确失败；路径段编码，写入/删除等待实际应用完成。外部 named-vector 或 Manhattan 集合返回 `CONFIG_ERROR`，仅 HTTP 404 表示集合不存在，日志复用 core 脱敏。
+
+Qdrant 固定后端请求拒绝 HTTP 重定向，API Key 不会被转发到重定向目标。
 
 Chroma 的 metadata/filter 遵循 `chromadb 3.5.0` 原生校验，非法值返回操作错误，不丢弃过滤或回退为无过滤查询。可省略文档 content，搜索仍返回 `undefined`；内部按 SDK 的字符串字段传递。各后端的 null、复杂元数据与过滤语义需单独核对。
 
@@ -100,15 +145,15 @@ LanceDB 是嵌入式本地文件后端。只有访问相同持久目录、且底
 
 搜索始终使用集合 metric，`euclidean` 映射 LanceDB 的 `l2`。`score` 延续公开 API 的 0–1、越大越相似约定：cosine 为 `clamp(1 - distance / 2, 0, 1)`；euclidean 为 `1 / (1 + squaredL2)`；dot 为 `sigmoid(dotProduct)`，用于保持内积排序而非概率。`minScore` 在该转换后过滤；不同 metric/后端的阈值不应视为通用校准值。
 
-LanceDB 原子写入的验证基线为 `@lancedb/lancedb 0.40.0 / Lance 13`。新集合在初始 Arrow schema 声明 id 为不可空主键；insert/upsert 均使用原生 merge，以 id 参与严格键冲突检测。依据：[Lance 13 table format](https://github.com/lance-format/lance/blob/v13.0.0/docs/src/format/table/index.md#unenforced-primary-key)、[Lance 13 transaction](https://github.com/lance-format/lance/blob/v13.0.0/protos/transaction.proto)、[Node binding 0.40.0](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/table.ts)。
+LanceDB 原子写入的验证基线为 `@lancedb/lancedb 0.40.0 / Lance 13`。新集合在初始 Arrow schema 声明 id 为不可空主键；insert/upsert 均使用原生 merge，以 id 参与严格键冲突检测。依据：[Lance 13 table format](https://github.com/lance-format/lance/blob/v13.0.0/docs/src/format/table/index.md#unenforced-primary-key)、[Lance 13 transaction](https://github.com/lance-format/lance/blob/v13.0.0/protos/transaction.proto)、[Node binding 0.40.0](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/table.ts).
 
 LanceDB 的 `insert` 仅插入新 ID，已有 ID 保留不覆盖；`upsert` 新增或整体替换。同批重复 ID、缺失 merge 能力/持久主键均返回 `CONFIG_ERROR`，不执行写入。旧表需重建，不自动迁移或清空。每个 merge 独立原子提交；并发胜者由提交顺序决定，不提供多个 merge 或 reldb/vecdb 间的共同事务。框架不会回退到 delete/add；写入结果不明时按 ID 核对。直接使用原生 add 的外部写入会绕过该保护，不属于本接口保证。
 
 LanceDB 的 `metadata` 使用原生 JSON 字段，仍可存储嵌套 JSON 对象，搜索结果还原为对象。写入时显式使用 Arrow JSON schema，确保 insert/upsert 都经过 JSONB 编码；旧 Utf8 metadata 表写入或过滤返回 `CONFIG_ERROR`，须重建，不自动迁移。
 
-LanceDB 的 `filter` 仅支持顶层键的 AND 精确匹配，例如 `{ tenant: 'acme', page: 1, active: true, removedAt: null }`。值支持字符串、有限数值、布尔和 null，严格区分 `1`/`'1'`、`true`/`'true'`；null 只匹配显式 JSON null，不匹配缺失字段。键是字面量，点号/括号不代表嵌套路径，引号、反斜线、`%`、`_` 均无 SQL/通配符含义。空对象不筛选；对象、数组、undefined、非有限数值返回 `CONFIG_ERROR`，不会执行无过滤查询。过滤在向量 topK 选取前执行，随后应用 minScore。其它 Provider 沿用各自原生过滤约束，不保证相同 null、复杂值或路径语义；跨后端时须核对实际能力。JSON 查询依据：[Lance 13 JSON UDF](https://github.com/lance-format/lance/blob/v13.0.0/rust/lance-datafusion/src/udf/json.rs)、[Node 0.40.0 JSON field](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/arrow.ts)。
+LanceDB 的 `filter` 仅支持顶层键的 AND 精确匹配，例如 `{ tenant: 'acme', page: 1, active: true, removedAt: null }`。值支持字符串、有限数值、布尔和 null，严格区分 `1`/`'1'`、`true`/`'true'`；null 只匹配显式 JSON null，不匹配缺失字段。键是字面量，点号/括号不代表嵌套路径，引号、反斜线、`%`、`_` 均无 SQL/通配符含义。空对象不筛选；对象、数组、undefined、非有限数值返回 `CONFIG_ERROR`，不会执行无过滤查询。过滤在向量 topK 选取前执行，随后应用 minScore。其它 Provider 沿用各自原生过滤约束，不保证相同 null、复杂值或路径语义；跨后端时须核对实际能力。JSON 查询依据：[Lance 13 JSON UDF](https://github.com/lance-format/lance/blob/v13.0.0/rust/lance-datafusion/src/udf/json.rs)、[Node 0.40.0 JSON field](https://github.com/lancedb/lancedb/blob/v0.40.0/nodejs/lancedb/arrow.ts).
 
-#### 操作日志
+### 操作日志
 
 可在向量数据库配置中通过 `operationLog` 开启操作日志。日志在集合/向量操作进入真实 Provider 前输出，不在 `vecdb-main.ts` 中做统一包装。
 
@@ -140,9 +185,15 @@ await vecdb.init({
 
 > 行为说明：空批量 `insert/upsert/delete` 会被视为 no-op；写入与搜索会校验向量维度，不匹配时返回 `HaiVecdbError.DIMENSION_MISMATCH`；缺少可选驱动时返回 `HaiVecdbError.DRIVER_NOT_FOUND`。
 
-Qdrant 的 `insert/upsert/delete` 使用 `wait: true`，成功表示服务端已应用该操作；`vector.count` 使用精确计数，不使用集合信息的近似 points_count。多个操作之间仍不构成事务。
+Qdrant 使用原生 HTTP 固定 REST 端点，无额外 SDK 依赖，支持未命名向量字段的 cosine/euclidean/dot。30 秒超时覆盖完整响应体，16 MiB 响应上限超出时明确失败；路径段编码，写入/删除等待实际应用完成。外部 named-vector 或 Manhattan 集合返回 `CONFIG_ERROR`，仅 HTTP 404 表示集合不存在，日志复用 core 脱敏。
+
+配置由宿主加载和校验，再传入本模块；私密值放服务端私有环境，不传到浏览器。按实际使用场景逐项选择后端、容量、期限和日志策略，修改后重新初始化并核验成功结果。
+
+[逐项配置说明、适用场景和示例](../../docs/usage/configuration/data.md).
 
-### 错误处理
+## 错误处理
+
+领域操作先判断 `result.success`，失败按本模块错误定义与安全提示处理，服务端保留错误码、关联编号和脱敏原因。同步工具、工厂、流迭代及生命周期按各自签名处理，不把 Promise 完成视为业务成功。具体失败与恢复边界见对应功能。
 
 所有操作返回 `HaiResult<T>`，通过 `result.success` 判断成功或失败。
 
@@ -163,14 +214,6 @@ if (!result.success) {
 }
 ```
 
-## 生产共享状态
-
-生产使用 Qdrant、pgvector 或远端 Chroma；LanceDB 和嵌入式 Chroma 只用于开发/明确测试。 NODE_ENV 或 HAI_CORE_ENV 为 production 时在初始化发布成功前校验；仅 HAI_E2E=1/HAI_E2E_MOCK=1 明确测试可豁免。 [状态、并发和恢复边界](../../.agents/instructions/distributed-state.md)。
-
-## 关闭与失败恢复
-
-close 立即停止当前操作与此前取得的操作引用；连接失败候选和关闭失败资源仅作为待清理所有权保留，不再提供业务服务。并发 close 合并，进行中的 init 先确定资源归属再关闭。失败结果的 error.ext.cleanupPending 表示仍须用同一模块的 close 重试；清理成功前 init 不创建替代资源。内嵌 Chroma 等待实际 spawn，终止直接启动的服务器后等待 exit；普通终止超过 1.5 秒后升级强制终止，再等待 1.5 秒，未确认退出返回失败并保留句柄。该验证覆盖直接子进程，不把信号回执等同于进程树退出或真实 Chroma CLI 上线验收。
-
 ## 开发测试
 
 ```bash

package/dist/index.d.ts

@@ -660,7 +660,7 @@ interface VecdbFunctions {
     /**
      * 获取底层后端的原始连接信息（含凭证，未初始化时为 null）
      *
-     * 供需要直连同一向量库的外部引擎（如 mem0 OSS）复用后端。返回值包含未脱敏的凭证，
+     * 供需要直连同一向量库的格式适配器（如 Mem0 数据格式存储）复用后端。返回值包含未脱敏的凭证，
      * 仅供同进程内集成使用，禁止写入日志或返回给外部调用方。
      */
     readonly rawConnection: VecdbConnection | null;
@@ -741,4 +741,5 @@ interface VecdbConnection {
  */
 declare const vecdb: VecdbFunctions;
 
-export { type ChromaConfig, type CollectionCreateOptions, type CollectionInfo, type CollectionOperations, type DistanceMetric, DistanceMetricSchema, HaiVecdbError, type LancedbConfig, type PgvectorConfig, type QdrantConfig, type VecdbConfig, type VecdbConfigInput, VecdbConfigSchema, type VecdbConnection, type VecdbFunctions, type VecdbOperationLogConfig, VecdbOperationLogConfigSchema, type VecdbType, type VectorDocument, type VectorOperations, type VectorSearchOptions, type VectorSearchResult, vecdb };
+export { DistanceMetricSchema, HaiVecdbError, VecdbConfigSchema, VecdbOperationLogConfigSchema, vecdb };
+export type { ChromaConfig, CollectionCreateOptions, CollectionInfo, CollectionOperations, DistanceMetric, LancedbConfig, PgvectorConfig, QdrantConfig, VecdbConfig, VecdbConfigInput, VecdbConnection, VecdbFunctions, VecdbOperationLogConfig, VecdbType, VectorDocument, VectorOperations, VectorSearchOptions, VectorSearchResult };