@h-ai/vecdb 1.0.0-beta.17 → 1.0.0-beta.19

package/README.en.md

@@ -16,6 +16,8 @@ A vector database module with a unified `vecdb` object for LanceDB, pgvector, Qd
 
 ## Getting started
 
+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.
+
 ### Quick start
 
 ```ts
@@ -31,7 +33,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' }
+  },
 ])
 
 // 搜索
@@ -92,7 +99,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.
 
@@ -142,7 +151,7 @@ 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.
 
 ### Error handling
 

package/README.ja.md

@@ -16,6 +16,8 @@
 
 ## 使い始める
 
+すべての 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
@@ -31,7 +33,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' }
+  },
 ])
 
 // 搜索
@@ -92,7 +99,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・複雑なメタデータ・フィルターの意味はバックエンドごとに確認してください。
 
@@ -142,7 +151,7 @@ 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 のマスク処理を使います。
 
 ### エラー処理
 

package/README.md

@@ -16,6 +16,8 @@
 
 ## 使用入门
 
+所有 Provider 的 `score` 都为 0–1，越大越相似；`minScore` 在转换后过滤。余弦使用 `(1 + cosine) / 2`，内积使用 `sigmoid(dotProduct)`，欧氏使用 `1 / (1 + distance)`；LanceDB/Chroma 的 distance 是原生 squared L2，其余后端使用原生 L2。不同 metric/后端的阈值仍需按业务校准，score 不代表概率。Qdrant 不再将公开 minScore 直接当作原生距离阈值。
+
 ### 快速开始
 
 ```ts
@@ -31,7 +33,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' }
+  },
 ])
 
 // 搜索
@@ -92,7 +99,9 @@ Chroma 的可选 `apiKey` 按本模块约定发送 `Authorization: Bearer <apiKe
 
 直连初始化的总截止为 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、复杂元数据与过滤语义需单独核对。
 
@@ -142,7 +151,7 @@ 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 脱敏。
 
 ### 错误处理
 

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 };