@h-ai/vecdb 0.1.0-alpha.33 → 0.1.0-alpha.35

package/README.md

@@ -1,12 +1,13 @@
 # @h-ai/vecdb
 
-向量数据库模块，通过统一的 `vecdb` 对象访问 LanceDB、pgvector、Qdrant。
+向量数据库模块，通过统一的 `vecdb` 对象访问 LanceDB、pgvector、Qdrant、Chroma。
 
 ## 支持的向量数据库
 
 - LanceDB（嵌入式，本地文件存储，零配置）
 - pgvector（PostgreSQL + pgvector 扩展）
 - Qdrant（高性能向量搜索引擎）
+- Chroma（支持嵌入式自动拉起本地服务，或直连已有服务）
 
 ## 快速开始
 
@@ -62,8 +63,18 @@ await vecdb.init({
 
 // 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' })
 ```
 
+> Chroma 在 Node 端只有 HTTP 客户端（无进程内嵌入式）。嵌入式模式下 `vecdb.init` 会
+> 通过 `serverCommand`（默认 `chroma`，来自 `chromadb` 包）拉起本地服务，`vecdb.close`
+> 时关闭进程。需安装可选依赖 `chromadb`；服务命令不可用时 `init` 返回 `CONNECTION_FAILED`。
+
 ### 操作日志
 
 可在向量数据库配置中通过 `operationLog` 开启操作日志。日志在集合/向量操作进入真实 Provider 前输出，不在 `vecdb-main.ts` 中做统一包装。

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { HaiResult } from '@h-ai/core';
  * @h-ai/vecdb — 向量数据库配置 Schema
  *
  * 本文件定义向量数据库模块的错误码常量、Zod Schema 和配置类型。
- * 支持 LanceDB（默认）、pgvector、Qdrant 三种后端。
+ * 支持 LanceDB（默认）、pgvector、Qdrant、Chroma 四种后端。
  * @module vecdb-config
  */
 
@@ -17,9 +17,10 @@ import { HaiResult } from '@h-ai/core';
  * - `lancedb` — LanceDB 嵌入式向量数据库（默认）
  * - `pgvector` — PostgreSQL + pgvector 扩展
  * - `qdrant` — Qdrant 向量搜索引擎
+ * - `chroma` — Chroma 向量数据库（支持嵌入式自动拉起本地服务）
  */
 /** 向量数据库类型 */
-type VecdbType = 'lancedb' | 'pgvector' | 'qdrant';
+type VecdbType = 'lancedb' | 'pgvector' | 'qdrant' | 'chroma';
 /**
  * 距离度量类型
  *
@@ -154,6 +155,50 @@ declare const QdrantConfigSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Qdrant 配置类型 */
 type QdrantConfig = z.infer<typeof QdrantConfigSchema>;
+/**
+ * Chroma 配置 Schema
+ *
+ * Chroma 在 Node 端只有 HTTP 客户端（无进程内嵌入式）。本 Provider 支持两种模式：
+ * - **嵌入式**：提供 `path` 且不提供 `url` 时，init 自动拉起本地 `chroma run` 服务
+ *   （持久化到 `path`），close 时关闭；数据落地本地目录，无需手动启动服务。
+ * - **直连**：提供 `url`（或已运行的 host:port）时，直接连接已有 Chroma 服务，不拉起进程。
+ *
+ * @example
+ * ```ts
+ * // 嵌入式（自动拉起本地服务）
+ * { type: 'chroma', path: './data/chroma' }
+ *
+ * // 直连已有服务
+ * { type: 'chroma', url: 'http://localhost:8000' }
+ * ```
+ */
+declare const ChromaConfigSchema: z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
+    type: z.ZodLiteral<"chroma">;
+    path: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    serverCommand: z.ZodDefault<z.ZodString>;
+    startupTimeout: z.ZodDefault<z.ZodNumber>;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
+}, z.core.$strip>;
+/** Chroma 配置类型 */
+type ChromaConfig = z.infer<typeof ChromaConfigSchema>;
 /**
  * 统一向量数据库配置 Schema（判别联合体）
  *
@@ -224,6 +269,30 @@ declare const VecdbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         euclidean: "euclidean";
         dot: "dot";
     }>>>;
+}, z.core.$strip>, z.ZodObject<{
+    operationLog: z.ZodOptional<z.ZodObject<{
+        read: z.ZodDefault<z.ZodBoolean>;
+        write: z.ZodDefault<z.ZodBoolean>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+        level: z.ZodDefault<z.ZodEnum<{
+            info: "info";
+            debug: "debug";
+            trace: "trace";
+        }>>;
+    }, z.core.$strip>>;
+    type: z.ZodLiteral<"chroma">;
+    path: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    serverCommand: z.ZodDefault<z.ZodString>;
+    startupTimeout: z.ZodDefault<z.ZodNumber>;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
 }, z.core.$strip>], "type">;
 /** 向量数据库配置类型（判别联合体） */
 type VecdbConfig = z.infer<typeof VecdbConfigSchema>;
@@ -508,6 +577,13 @@ interface VecdbFunctions {
     close: () => Promise<HaiResult<void>>;
     /** 当前脱敏配置快照（未初始化时为 null） */
     readonly config: VecdbConfig | null;
+    /**
+     * 获取底层后端的原始连接信息（含凭证，未初始化时为 null）
+     *
+     * 供需要直连同一向量库的外部引擎（如 mem0 OSS）复用后端。返回值包含未脱敏的凭证，
+     * 仅供同进程内集成使用，禁止写入日志或返回给外部调用方。
+     */
+    readonly rawConnection: VecdbConnection | null;
     /** 是否已初始化 */
     readonly isInitialized: boolean;
     /** 集合管理操作 */
@@ -515,6 +591,33 @@ interface VecdbFunctions {
     /** 向量操作 */
     readonly vector: VectorOperations;
 }
+/**
+ * 向量库原始连接信息
+ *
+ * 由 `vecdb.rawConnection` 暴露，字段按后端类型填充。包含凭证，仅供同进程内集成使用。
+ */
+interface VecdbConnection {
+    /** 后端类型 */
+    type: VecdbConfig['type'];
+    /** 服务 URL（qdrant） */
+    url?: string;
+    /** API Key（qdrant） */
+    apiKey?: string;
+    /** 主机（pgvector） */
+    host?: string;
+    /** 端口（pgvector） */
+    port?: number;
+    /** 数据库名（pgvector） */
+    database?: string;
+    /** 用户名（pgvector） */
+    user?: string;
+    /** 密码（pgvector） */
+    password?: string;
+    /** 连接串（pgvector） */
+    connectionString?: string;
+    /** 本地路径（lancedb） */
+    path?: string;
+}
 
 /**
  * @h-ai/vecdb — 向量数据库服务主入口
@@ -558,4 +661,4 @@ interface VecdbFunctions {
  */
 declare const vecdb: VecdbFunctions;
 
-export { type CollectionCreateOptions, type CollectionInfo, type CollectionOperations, type DistanceMetric, DistanceMetricSchema, HaiVecdbError, type LancedbConfig, type PgvectorConfig, type QdrantConfig, type VecdbConfig, type VecdbConfigInput, VecdbConfigSchema, type VecdbFunctions, type VecdbOperationLogConfig, VecdbOperationLogConfigSchema, type VecdbType, type VectorDocument, type VectorOperations, type VectorSearchOptions, type VectorSearchResult, vecdb };
+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 };