@h-ai/vecdb 0.1.0-alpha5

package/dist/index.d.ts

@@ -0,0 +1,477 @@
+import { z } from 'zod';
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult } from '@h-ai/core';
+
+/**
+ * @h-ai/vecdb — 向量数据库配置 Schema
+ *
+ * 本文件定义向量数据库模块的错误码常量、Zod Schema 和配置类型。
+ * 支持 LanceDB（默认）、pgvector、Qdrant 三种后端。
+ * @module vecdb-config
+ */
+
+/**
+ * 向量数据库类型枚举
+ *
+ * 支持的向量数据库类型：
+ * - `lancedb` — LanceDB 嵌入式向量数据库（默认）
+ * - `pgvector` — PostgreSQL + pgvector 扩展
+ * - `qdrant` — Qdrant 向量搜索引擎
+ */
+declare const VecdbTypeSchema: z.ZodEnum<{
+    lancedb: "lancedb";
+    pgvector: "pgvector";
+    qdrant: "qdrant";
+}>;
+/** 向量数据库类型 */
+type VecdbType = z.infer<typeof VecdbTypeSchema>;
+/**
+ * 距离度量类型
+ *
+ * - `cosine` — 余弦相似度（默认，适用于文本嵌入）
+ * - `euclidean` — 欧氏距离（L2）
+ * - `dot` — 内积（点积）
+ */
+declare const DistanceMetricSchema: z.ZodDefault<z.ZodEnum<{
+    cosine: "cosine";
+    euclidean: "euclidean";
+    dot: "dot";
+}>>;
+/** 距离度量类型 */
+type DistanceMetric = z.infer<typeof DistanceMetricSchema>;
+/**
+ * LanceDB 配置 Schema
+ *
+ * @example
+ * ```ts
+ * { type: 'lancedb', path: './data/vecdb' }
+ * ```
+ */
+declare const LancedbConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"lancedb">;
+    path: z.ZodString;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
+}, z.core.$strip>;
+/** LanceDB 配置类型 */
+type LancedbConfig = z.infer<typeof LancedbConfigSchema>;
+/**
+ * pgvector 索引类型
+ *
+ * - `ivfflat` — IVFFlat 索引（适合中等规模数据）
+ * - `hnsw` — HNSW 索引（适合大规模数据，检索速度更快）
+ */
+declare const PgvectorIndexTypeSchema: z.ZodDefault<z.ZodEnum<{
+    ivfflat: "ivfflat";
+    hnsw: "hnsw";
+}>>;
+/**
+ * pgvector 配置 Schema
+ *
+ * @example
+ * ```ts
+ * // 使用连接字符串
+ * { type: 'pgvector', url: 'postgres://user:pass@localhost:5432/mydb' }
+ *
+ * // 使用分开的字段
+ * {
+ *     type: 'pgvector',
+ *     host: 'localhost',
+ *     port: 5432,
+ *     database: 'mydb',
+ *     user: 'admin',
+ *     password: 'secret'
+ * }
+ * ```
+ */
+declare const PgvectorConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"pgvector">;
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    database: z.ZodString;
+    user: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    indexType: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        ivfflat: "ivfflat";
+        hnsw: "hnsw";
+    }>>>;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
+    tablePrefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/** pgvector 配置类型 */
+type PgvectorConfig = z.infer<typeof PgvectorConfigSchema>;
+/**
+ * Qdrant 配置 Schema
+ *
+ * @example
+ * ```ts
+ * { type: 'qdrant', url: 'http://localhost:6333' }
+ * ```
+ */
+declare const QdrantConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"qdrant">;
+    url: z.ZodDefault<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
+}, z.core.$strip>;
+/** Qdrant 配置类型 */
+type QdrantConfig = z.infer<typeof QdrantConfigSchema>;
+/**
+ * 统一向量数据库配置 Schema（判别联合体）
+ *
+ * 根据 `type` 字段区分不同向量数据库类型的配置。
+ */
+declare const VecdbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"lancedb">;
+    path: z.ZodString;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"pgvector">;
+    url: z.ZodOptional<z.ZodString>;
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    database: z.ZodString;
+    user: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    indexType: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        ivfflat: "ivfflat";
+        hnsw: "hnsw";
+    }>>>;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
+    tablePrefix: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"qdrant">;
+    url: z.ZodDefault<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    metric: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        cosine: "cosine";
+        euclidean: "euclidean";
+        dot: "dot";
+    }>>>;
+}, z.core.$strip>], "type">;
+/** 向量数据库配置类型（判别联合体） */
+type VecdbConfig = z.infer<typeof VecdbConfigSchema>;
+/**
+ * 向量数据库配置输入类型（用于 init 等入口）
+ *
+ * 说明：Zod 的 default 会让输入端字段可省略，但输出端字段为必填。
+ * 因此对外 API（如 vecdb.init）更适合接收 VecdbConfigInput。
+ */
+type VecdbConfigInput = z.input<typeof VecdbConfigSchema>;
+
+/**
+ * Vecdb 模块标准错误定义对象。
+ */
+declare const HaiVecdbError: {
+    readonly CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly QUERY_FAILED: _h_ai_core.HaiErrorDef;
+    readonly COLLECTION_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly COLLECTION_ALREADY_EXISTS: _h_ai_core.HaiErrorDef;
+    readonly DIMENSION_MISMATCH: _h_ai_core.HaiErrorDef;
+    readonly INSERT_FAILED: _h_ai_core.HaiErrorDef;
+    readonly DELETE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly UPDATE_FAILED: _h_ai_core.HaiErrorDef;
+    readonly INDEX_BUILD_FAILED: _h_ai_core.HaiErrorDef;
+    readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+    readonly UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
+    readonly DRIVER_NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly SERIALIZATION_FAILED: _h_ai_core.HaiErrorDef;
+};
+/**
+ * 向量文档接口
+ *
+ * 表示一条存入向量数据库的记录，包含向量、文本内容和元数据。
+ *
+ * @example
+ * ```ts
+ * const doc: VectorDocument = {
+ *   id: 'doc-001',
+ *   vector: [0.1, 0.2, 0.3, ...],
+ *   content: '这是文档内容',
+ *   metadata: { source: 'wiki', page: 1 },
+ * }
+ * ```
+ */
+interface VectorDocument {
+    /** 文档唯一标识 */
+    id: string;
+    /** 向量数据（浮点数组） */
+    vector: number[];
+    /** 文本内容（可选，用于存储原始文本） */
+    content?: string;
+    /** 元数据（可选，用于存储附加信息） */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 向量搜索选项
+ *
+ * @example
+ * ```ts
+ * const options: VectorSearchOptions = {
+ *   topK: 10,
+ *   filter: { source: 'wiki' },
+ *   minScore: 0.7,
+ * }
+ * ```
+ */
+interface VectorSearchOptions {
+    /** 返回的最大结果数（默认 10） */
+    topK?: number;
+    /** 元数据过滤条件（键值对，精确匹配） */
+    filter?: Record<string, unknown>;
+    /** 最低相似度阈值（0-1，低于此值的结果将被过滤） */
+    minScore?: number;
+}
+/**
+ * 向量搜索结果
+ *
+ * 包含匹配的文档和相似度得分。
+ */
+interface VectorSearchResult {
+    /** 文档唯一标识 */
+    id: string;
+    /** 相似度得分（0-1，越高越相似） */
+    score: number;
+    /** 文本内容（如果存储时包含） */
+    content?: string;
+    /** 元数据（如果存储时包含） */
+    metadata?: Record<string, unknown>;
+    /** 原始向量（可选，默认不返回以节省传输） */
+    vector?: number[];
+}
+/**
+ * 集合信息接口
+ *
+ * 描述一个向量集合的元信息。
+ */
+interface CollectionInfo {
+    /** 集合名称 */
+    name: string;
+    /** 向量维度 */
+    dimension: number;
+    /** 距离度量类型 */
+    metric: DistanceMetric;
+    /** 集合中的文档数量 */
+    count: number;
+}
+/**
+ * 集合管理操作接口
+ *
+ * 通过 `vecdb.collection` 访问，管理向量集合的创建、删除和查询。
+ *
+ * @example
+ * ```ts
+ * // 创建集合
+ * await vecdb.collection.create('my-docs', { dimension: 1536 })
+ *
+ * // 列出集合
+ * const result = await vecdb.collection.list()
+ * ```
+ */
+interface CollectionOperations {
+    /**
+     * 创建集合
+     *
+     * @param name - 集合名称
+     * @param options - 创建选项
+     * @returns 成功返回 ok(undefined)；集合已存在返回 COLLECTION_ALREADY_EXISTS
+     */
+    create: (name: string, options: CollectionCreateOptions) => Promise<HaiResult<void>>;
+    /**
+     * 删除集合
+     *
+     * @param name - 集合名称
+     * @returns 成功返回 ok(undefined)；集合不存在返回 COLLECTION_NOT_FOUND
+     */
+    drop: (name: string) => Promise<HaiResult<void>>;
+    /**
+     * 判断集合是否存在
+     *
+     * @param name - 集合名称
+     * @returns 存在返回 true，不存在返回 false
+     */
+    exists: (name: string) => Promise<HaiResult<boolean>>;
+    /**
+     * 获取集合信息
+     *
+     * @param name - 集合名称
+     * @returns 集合信息
+     */
+    info: (name: string) => Promise<HaiResult<CollectionInfo>>;
+    /**
+     * 列出所有集合
+     *
+     * @returns 集合名称列表
+     */
+    list: () => Promise<HaiResult<string[]>>;
+}
+/**
+ * 集合创建选项
+ */
+interface CollectionCreateOptions {
+    /** 向量维度（必填） */
+    dimension: number;
+    /** 距离度量（可选，默认使用全局配置中的 metric） */
+    metric?: DistanceMetric;
+}
+/**
+ * 向量操作接口
+ *
+ * 通过 `vecdb.vector` 访问，管理向量文档的增删改查和搜索。
+ *
+ * @example
+ * ```ts
+ * // 插入向量
+ * await vecdb.vector.insert('my-docs', [
+ *   { id: 'doc-1', vector: [...], content: '文档1' },
+ *   { id: 'doc-2', vector: [...], content: '文档2' },
+ * ])
+ *
+ * // 搜索向量
+ * const result = await vecdb.vector.search('my-docs', queryVector, { topK: 5 })
+ * ```
+ */
+interface VectorOperations {
+    /**
+     * 插入向量文档
+     *
+     * @param collection - 集合名称
+     * @param documents - 文档列表
+     * @returns 成功返回 ok(undefined)
+     */
+    insert: (collection: string, documents: VectorDocument[]) => Promise<HaiResult<void>>;
+    /**
+     * 更新向量文档（按 id 匹配，整体替换）
+     *
+     * @param collection - 集合名称
+     * @param documents - 待更新的文档（id 必须已存在）
+     * @returns 成功返回 ok(undefined)
+     */
+    upsert: (collection: string, documents: VectorDocument[]) => Promise<HaiResult<void>>;
+    /**
+     * 删除向量文档
+     *
+     * @param collection - 集合名称
+     * @param ids - 文档 ID 列表
+     * @returns 成功返回 ok(undefined)
+     */
+    delete: (collection: string, ids: string[]) => Promise<HaiResult<void>>;
+    /**
+     * 向量搜索
+     *
+     * @param collection - 集合名称
+     * @param vector - 查询向量
+     * @param options - 搜索选项
+     * @returns 搜索结果列表（按相似度降序排列）
+     */
+    search: (collection: string, vector: number[], options?: VectorSearchOptions) => Promise<HaiResult<VectorSearchResult[]>>;
+    /**
+     * 获取集合中的文档数量
+     *
+     * @param collection - 集合名称
+     * @returns 文档数量
+     */
+    count: (collection: string) => Promise<HaiResult<number>>;
+}
+/**
+ * 向量数据库服务接口（通过 `vecdb` 对象访问）
+ *
+ * @example
+ * ```ts
+ * import { 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: '1', vector: [...], content: '...' }])
+ *
+ * // 搜索
+ * const result = await vecdb.vector.search('docs', queryVector, { topK: 5 })
+ *
+ * // 关闭
+ * await vecdb.close()
+ * ```
+ */
+interface VecdbFunctions {
+    /** 初始化向量数据库连接 */
+    init: (config: VecdbConfigInput) => Promise<HaiResult<void>>;
+    /** 关闭连接 */
+    close: () => Promise<HaiResult<void>>;
+    /** 当前配置（未初始化时为 null） */
+    readonly config: VecdbConfig | null;
+    /** 是否已初始化 */
+    readonly isInitialized: boolean;
+    /** 集合管理操作 */
+    readonly collection: CollectionOperations;
+    /** 向量操作 */
+    readonly vector: VectorOperations;
+}
+
+/**
+ * @h-ai/vecdb — 向量数据库服务主入口
+ *
+ * 本文件提供统一的 `vecdb` 对象，聚合所有向量数据库操作功能。
+ * @module vecdb-main
+ */
+
+/**
+ * 向量数据库服务对象
+ *
+ * 统一的向量数据库访问入口，提供以下功能：
+ * - `vecdb.init()` - 初始化连接
+ * - `vecdb.close()` - 关闭连接
+ * - `vecdb.collection` - 集合管理（创建/删除/查询）
+ * - `vecdb.vector` - 向量操作（插入/搜索/删除）
+ * - `vecdb.config` - 当前配置
+ * - `vecdb.isInitialized` - 初始化状态
+ *
+ * @example
+ * ```ts
+ * import { 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: '1', vector: [...], content: '文档内容' },
+ * ])
+ *
+ * // 搜索
+ * const result = await vecdb.vector.search('docs', queryVector, { topK: 5 })
+ *
+ * // 关闭
+ * await vecdb.close()
+ * ```
+ */
+declare const vecdb: VecdbFunctions;
+
+export { type CollectionCreateOptions, type CollectionInfo, type CollectionOperations, type DistanceMetric, DistanceMetricSchema, HaiVecdbError, type LancedbConfig, LancedbConfigSchema, type PgvectorConfig, PgvectorConfigSchema, PgvectorIndexTypeSchema, type QdrantConfig, QdrantConfigSchema, type VecdbConfig, type VecdbConfigInput, VecdbConfigSchema, type VecdbFunctions, type VecdbType, VecdbTypeSchema, type VectorDocument, type VectorOperations, type VectorSearchOptions, type VectorSearchResult, vecdb };