@dofe/infra-vector 0.1.1

package/dist/vikingdb-client.service.js

@@ -0,0 +1,900 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VikingDbClientService = void 0;
+/**
+ * VikingDB Client Service
+ * VikingDB 向量数据库客户端服务
+ */
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const nest_winston_1 = require("nest-winston");
+const winston_1 = require("winston");
+const axios_1 = require("@nestjs/axios");
+const rxjs_1 = require("rxjs");
+const infra_common_1 = require("@dofe/infra-common");
+const vikingdb_types_1 = require("./vikingdb.types");
+const openapi_1 = require("@volcengine/openapi");
+let VikingDbClientService = class VikingDbClientService {
+    logger;
+    configService;
+    httpService;
+    config;
+    volcService;
+    constructor(logger, configService, httpService) {
+        this.logger = logger;
+        this.configService = configService;
+        this.httpService = httpService;
+    }
+    onModuleInit() {
+        const keysConfig = (0, infra_common_1.getKeysConfig)();
+        const vikingKeys = keysConfig?.vikingdb;
+        // keys/config.json 优先，其次才 fallback env（兼容旧配置）
+        const provider = vikingKeys?.provider ??
+            this.configService.get('VIKINGDB_PROVIDER') ??
+            'custom-http';
+        this.config = {
+            provider,
+            baseUrl: vikingKeys?.baseUrl ??
+                this.configService.get('VIKINGDB_BASE_URL', ''),
+            authToken: vikingKeys?.authToken ??
+                this.configService.get('VIKINGDB_AUTH_TOKEN'),
+            database: vikingKeys?.database ??
+                this.configService.get('VIKINGDB_DATABASE', ''),
+            collection: vikingKeys?.collection ??
+                this.configService.get('VIKINGDB_COLLECTION', ''),
+            ak: vikingKeys?.volcengine?.ak ??
+                this.configService.get('VIKINGDB_VOLCENGINE_AK'),
+            sk: vikingKeys?.volcengine?.sk ??
+                this.configService.get('VIKINGDB_VOLCENGINE_SK'),
+            region: vikingKeys?.volcengine?.region ??
+                this.configService.get('VIKINGDB_VOLCENGINE_REGION', 'cn-beijing'),
+            sessionToken: vikingKeys?.volcengine?.sessionToken ??
+                this.configService.get('VIKINGDB_VOLCENGINE_SESSION_TOKEN'),
+            indexName: vikingKeys?.volcengine?.indexName ??
+                this.configService.get('VIKINGDB_VOLCENGINE_INDEX_NAME'),
+            collectionName: vikingKeys?.volcengine?.collectionName ??
+                this.configService.get('VIKINGDB_VOLCENGINE_COLLECTION_NAME'),
+            collectionAlias: vikingKeys?.volcengine?.collectionAlias ??
+                this.configService.get('VIKINGDB_VOLCENGINE_COLLECTION_ALIAS'),
+            primaryKeyField: vikingKeys?.fields?.primaryKey ??
+                this.configService.get('VIKINGDB_FIELD_PRIMARY_KEY', 'id'),
+            textField: vikingKeys?.fields?.text ??
+                this.configService.get('VIKINGDB_FIELD_TEXT', 'text'),
+            vectorField: vikingKeys?.fields?.vector ??
+                this.configService.get('VIKINGDB_FIELD_VECTOR', 'embedding'),
+            summaryField: vikingKeys?.fields?.summary ??
+                this.configService.get('VIKINGDB_FIELD_SUMMARY', 'summary'),
+            metadataField: vikingKeys?.fields?.metadata ??
+                this.configService.get('VIKINGDB_FIELD_METADATA', 'metadata'),
+            tagsField: vikingKeys?.fields?.tags ??
+                this.configService.get('VIKINGDB_FIELD_TAGS', 'tags'),
+            taskTypeField: vikingKeys?.fields?.taskType ??
+                this.configService.get('VIKINGDB_FIELD_TASK_TYPE', 'taskType'),
+            createdAtField: vikingKeys?.fields?.createdAt ??
+                this.configService.get('VIKINGDB_FIELD_CREATED_AT', 'createdAt'),
+            updatedAtField: vikingKeys?.fields?.updatedAt ??
+                this.configService.get('VIKINGDB_FIELD_UPDATED_AT', 'updatedAt'),
+            // scope/source 字段映射（Volcengine 建议使用扁平化字段做过滤）
+            tenantIdField: vikingKeys?.fields?.tenantId ??
+                this.configService.get('VIKINGDB_FIELD_TENANT_ID', 'tenantId'),
+            botIdField: vikingKeys?.fields?.botId ??
+                this.configService.get('VIKINGDB_FIELD_BOT_ID', 'botId'),
+            scopeTypeField: vikingKeys?.fields?.scopeType ??
+                this.configService.get('VIKINGDB_FIELD_SCOPE_TYPE', 'scopeType'),
+            scopeIdField: vikingKeys?.fields?.scopeId ??
+                this.configService.get('VIKINGDB_FIELD_SCOPE_ID', 'scopeId'),
+            sourceTypeField: vikingKeys?.fields?.sourceType ??
+                this.configService.get('VIKINGDB_FIELD_SOURCE_TYPE', 'sourceType'),
+            createdByIdField: vikingKeys?.fields?.createdById ??
+                this.configService.get('VIKINGDB_FIELD_CREATED_BY_ID', 'createdById'),
+            timeoutMs: vikingKeys?.timeoutMs ??
+                this.configService.get('VIKINGDB_TIMEOUT_MS', 20000),
+            vectorSearchPath: vikingKeys?.paths?.vectorSearch ??
+                this.configService.get('VIKINGDB_VECTOR_SEARCH_PATH', '/vector/search'),
+            bm25SearchPath: vikingKeys?.paths?.bm25Search ??
+                this.configService.get('VIKINGDB_BM25_SEARCH_PATH', '/bm25/search'),
+            upsertPath: vikingKeys?.paths?.upsert ??
+                this.configService.get('VIKINGDB_UPSERT_PATH', '/documents/upsert'),
+            deletePath: vikingKeys?.paths?.delete ??
+                this.configService.get('VIKINGDB_DELETE_PATH', '/documents/delete'),
+            healthPath: vikingKeys?.paths?.health ??
+                this.configService.get('VIKINGDB_HEALTH_PATH', '/health'),
+            headers: vikingKeys?.headers ??
+                this.parseHeaders(this.configService.get('VIKINGDB_HEADERS', '{}')),
+        };
+        if (this.config.provider === 'volcengine') {
+            if (this.config.ak && this.config.sk) {
+                this.volcService = new openapi_1.vikingdb.VikingdbService({
+                    ak: this.config.ak,
+                    sk: this.config.sk,
+                    region: this.config.region,
+                    sessionToken: this.config.sessionToken,
+                });
+            }
+            this.logger.info('[VikingDB] Volcengine client initialized', {
+                region: this.config.region,
+                indexName: this.config.indexName,
+                collectionName: this.config.collectionName,
+                collectionAlias: this.config.collectionAlias,
+            });
+            return;
+        }
+        this.logger.info('[VikingDB] Client initialized', {
+            baseUrl: this.config.baseUrl,
+            database: this.config.database,
+            collection: this.config.collection,
+        });
+    }
+    // ============================================================================
+    // Public API
+    // ============================================================================
+    /**
+     * Volcengine: 获取 collection schema（字段列表）
+     */
+    async getVolcengineCollectionSchema() {
+        if (this.config.provider !== 'volcengine') {
+            return null;
+        }
+        if (!this.volcService) {
+            throw new Error('Volcengine VikingDB client not configured (missing AK/SK)');
+        }
+        const collectionName = this.resolveCollectionName();
+        const resp = await this.volcService.collection.GetCollectionInfo({
+            CollectionName: collectionName,
+        });
+        const info = resp?.CollectionInfo;
+        const fields = Array.isArray(info?.Fields) ? info.Fields : [];
+        return {
+            collectionName,
+            fields: fields.map((f) => ({
+                FieldName: f.FieldName,
+                FieldType: f.FieldType,
+                ...(f.Dim !== undefined ? { Dim: f.Dim } : {}),
+            })),
+            indexNames: Array.isArray(info?.IndexNames) ? info.IndexNames : [],
+        };
+    }
+    /**
+     * Volcengine: 连通性自检（不写入数据）
+     */
+    async volcengineSelfCheck() {
+        if (this.config.provider !== 'volcengine') {
+            return null;
+        }
+        const start = Date.now();
+        const warnings = [];
+        try {
+            if (!this.volcService) {
+                throw new Error('Volcengine VikingDB client not configured (missing AK/SK)');
+            }
+            const collectionName = this.resolveCollectionName();
+            const indexName = this.resolveIndexName();
+            // 1) CollectionInfo
+            const collectionResp = await this.volcService.collection.GetCollectionInfo({
+                CollectionName: collectionName,
+            });
+            const info = collectionResp?.CollectionInfo;
+            const indexNames = Array.isArray(info?.IndexNames) ? info.IndexNames : [];
+            if (indexNames.length > 0 && !indexNames.includes(indexName)) {
+                warnings.push(`IndexName not found in collection.IndexNames: ${indexName} (available: ${indexNames.join(', ')})`);
+            }
+            // 2) IndexInfo
+            await this.volcService.index.GetIndexInfo({
+                CollectionName: collectionName,
+                IndexName: indexName,
+            });
+            // 3) Sample search (empty filter, tiny limit)
+            // 用 SearchByText 做一次最轻量的 API 可用性验证
+            await this.volcService.search.SearchByText({
+                IndexName: indexName,
+                Limit: 1,
+                Text: 'ping',
+                OutputFields: [this.config.primaryKeyField ?? 'id'],
+                ...this.resolveCollectionNameOrAlias(),
+            });
+            return {
+                ok: true,
+                provider: 'volcengine',
+                region: this.config.region,
+                collectionName,
+                indexName,
+                latencyMs: Date.now() - start,
+                checks: {
+                    collectionInfo: true,
+                    indexInfo: true,
+                    sampleSearch: true,
+                },
+                warnings,
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                ok: false,
+                provider: 'volcengine',
+                region: this.config.region,
+                collectionName: this.config.collectionName,
+                indexName: this.config.indexName,
+                latencyMs: Date.now() - start,
+                checks: {
+                    collectionInfo: false,
+                    indexInfo: false,
+                    sampleSearch: false,
+                },
+                warnings,
+                error: msg,
+            };
+        }
+    }
+    /**
+     * Volcengine: 校验远程 collection schema 是否匹配预期
+     * 返回缺失字段/类型不匹配的警告列表
+     */
+    async validateVolcengineSchema() {
+        if (this.config.provider !== 'volcengine') {
+            return null;
+        }
+        const warnings = [];
+        const errors = [];
+        const schema = await this.getVolcengineCollectionSchema();
+        if (!schema) {
+            return null;
+        }
+        const remoteFieldMap = new Map(schema.fields.map((f) => [f.FieldName, f]));
+        // 检查期望字段是否存在、类型是否匹配
+        for (const expected of vikingdb_types_1.VOLCENGINE_MEMORY_COLLECTION_SCHEMA) {
+            const remote = remoteFieldMap.get(expected.FieldName);
+            if (!remote) {
+                warnings.push(`Missing expected field: ${expected.FieldName} (type: ${expected.FieldType})`);
+                continue;
+            }
+            // 类型兼容校验（允许一定灵活性）
+            if (remote.FieldType !== expected.FieldType) {
+                // 特殊情况：string/text 可视为兼容
+                const isTextStringCompat = (expected.FieldType === 'text' && remote.FieldType === 'string') ||
+                    (expected.FieldType === 'string' && remote.FieldType === 'text');
+                if (!isTextStringCompat) {
+                    warnings.push(`Field type mismatch: ${expected.FieldName} expected ${expected.FieldType}, got ${remote.FieldType}`);
+                }
+            }
+            // 向量维度检查
+            if (expected.FieldType === 'vector' && expected.Dim) {
+                if (remote.Dim && remote.Dim !== expected.Dim) {
+                    warnings.push(`Vector dimension mismatch: ${expected.FieldName} expected ${expected.Dim}, got ${remote.Dim}`);
+                }
+            }
+        }
+        // 列出未知字段（不警告，只记录）
+        const expectedNames = new Set(vikingdb_types_1.VOLCENGINE_MEMORY_COLLECTION_SCHEMA.map((f) => f.FieldName));
+        const extraFields = schema.fields
+            .filter((f) => !expectedNames.has(f.FieldName))
+            .map((f) => f.FieldName);
+        if (extraFields.length > 0) {
+            this.logger.debug('[VikingDB] Extra fields in collection', {
+                extraFields,
+            });
+        }
+        return {
+            ok: errors.length === 0,
+            collectionName: schema.collectionName,
+            warnings,
+            errors,
+            remoteFields: schema.fields,
+            expectedFields: vikingdb_types_1.VOLCENGINE_MEMORY_COLLECTION_SCHEMA,
+        };
+    }
+    /**
+     * 健康检查
+     */
+    async healthCheck() {
+        const startTime = Date.now();
+        try {
+            if (this.config.provider === 'volcengine') {
+                if (!this.volcService) {
+                    throw new Error('Volcengine VikingDB client not configured (missing AK/SK)');
+                }
+                const collectionName = this.resolveCollectionName();
+                // 轻量级检查：拉取 CollectionInfo
+                await this.volcService.collection.GetCollectionInfo({
+                    CollectionName: collectionName,
+                });
+                return {
+                    healthy: true,
+                    latency: Date.now() - startTime,
+                };
+            }
+            await this.request('GET', this.config.healthPath);
+            return {
+                healthy: true,
+                latency: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('[VikingDB] Health check failed', {
+                error: errorMessage,
+            });
+            return {
+                healthy: false,
+                latency: Date.now() - startTime,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * 向量搜索
+     */
+    async vectorSearch(vector, scope, options = {}) {
+        if (this.config.provider === 'volcengine') {
+            if (!this.volcService) {
+                throw new Error('Volcengine VikingDB client not configured (missing AK/SK)');
+            }
+            const indexName = this.resolveIndexName();
+            const limit = options.topK ?? 50;
+            const collectionNameOrAlias = this.resolveCollectionNameOrAlias();
+            const volcFilter = this.buildVolcFilter(scope, options.taskType);
+            const response = await this.volcService.search.SearchByVector({
+                IndexName: indexName,
+                Limit: limit,
+                DenseVectors: [vector],
+                Filter: volcFilter,
+                OutputFields: [
+                    this.config.primaryKeyField ?? 'id',
+                    this.config.textField ?? 'text',
+                    this.config.summaryField ?? 'summary',
+                    this.config.metadataField ?? 'metadata',
+                    this.config.tagsField ?? 'tags',
+                    this.config.taskTypeField ?? 'taskType',
+                    this.config.createdAtField ?? 'createdAt',
+                    this.config.updatedAtField ?? 'updatedAt',
+                ],
+                ...collectionNameOrAlias,
+            });
+            return this.normalizeVolcSearchResponse(response, scope);
+        }
+        const response = await this.request('POST', this.config.vectorSearchPath, {
+            vector,
+            topK: options.topK ?? 50,
+            scope,
+            taskType: options.taskType,
+        });
+        return this.normalizeCandidates(response);
+    }
+    /**
+     * BM25 搜索
+     */
+    async bm25Search(query, scope, options = {}) {
+        if (this.config.provider === 'volcengine') {
+            if (!this.volcService) {
+                throw new Error('Volcengine VikingDB client not configured (missing AK/SK)');
+            }
+            const indexName = this.resolveIndexName();
+            const limit = options.topK ?? 50;
+            const collectionNameOrAlias = this.resolveCollectionNameOrAlias();
+            const volcFilter = this.buildVolcFilter(scope, options.taskType);
+            const response = await this.volcService.search.SearchByText({
+                IndexName: indexName,
+                Limit: limit,
+                Text: query,
+                Filter: volcFilter,
+                OutputFields: [
+                    this.config.primaryKeyField ?? 'id',
+                    this.config.textField ?? 'text',
+                    this.config.summaryField ?? 'summary',
+                    this.config.metadataField ?? 'metadata',
+                    this.config.tagsField ?? 'tags',
+                    this.config.taskTypeField ?? 'taskType',
+                    this.config.createdAtField ?? 'createdAt',
+                    this.config.updatedAtField ?? 'updatedAt',
+                ],
+                ...collectionNameOrAlias,
+            });
+            return this.normalizeVolcSearchResponse(response, scope);
+        }
+        const response = await this.request('POST', this.config.bm25SearchPath, {
+            query,
+            topK: options.topK ?? 50,
+            scope,
+            taskType: options.taskType,
+        });
+        return this.normalizeCandidates(response);
+    }
+    /**
+     * 混合搜索（向量 + BM25）
+     */
+    async hybridSearch(vector, query, scope, options = {}) {
+        const candidateK = options.candidateK ?? 50;
+        // 并行执行向量搜索和 BM25 搜索
+        const [vectorResults, bm25Results] = await Promise.all([
+            this.vectorSearch(vector, scope, {
+                topK: candidateK,
+                taskType: options.taskType,
+            }),
+            this.bm25Search(query, scope, {
+                topK: candidateK,
+                taskType: options.taskType,
+            }),
+        ]);
+        // 使用 Reciprocal Rank Fusion 合并结果
+        const fused = this.reciprocalRankFusion(vectorResults, bm25Results, options.vectorWeight ?? 0.7, options.bm25Weight ?? 0.3);
+        // 返回 topK 结果
+        return fused.slice(0, options.topK ?? 10);
+    }
+    /**
+     * Upsert 文档
+     */
+    async upsert(documents) {
+        if (documents.length === 0) {
+            return;
+        }
+        if (this.config.provider === 'volcengine') {
+            if (!this.volcService) {
+                throw new Error('Volcengine VikingDB client not configured (missing AK/SK)');
+            }
+            const { primaryKeys, fields } = this.buildVolcUpsertFields(documents);
+            const collectionNameOrAlias = this.resolveCollectionNameOrAlias();
+            await this.volcService.data.UpsertData({
+                Fields: fields,
+                ...collectionNameOrAlias,
+            });
+            this.logger.info('[VikingDB] Volcengine upserted', {
+                count: primaryKeys.length,
+            });
+            return;
+        }
+        await this.request('POST', this.config.upsertPath, {
+            documents: documents.map((doc) => ({
+                ...doc,
+                timestamp: doc.timestamp ?? new Date().toISOString(),
+                createdAt: doc.createdAt ?? new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            })),
+        });
+        this.logger.info('[VikingDB] Documents upserted', {
+            count: documents.length,
+        });
+    }
+    /**
+     * 更新文档（部分更新，仅更新指定字段）
+     */
+    async update(documents) {
+        if (documents.length === 0) {
+            return;
+        }
+        if (this.config.provider === 'volcengine') {
+            if (!this.volcService) {
+                throw new Error('Volcengine VikingDB client not configured (missing AK/SK)');
+            }
+            const pkField = this.config.primaryKeyField ?? 'id';
+            const fields = documents.map((doc) => ({
+                [pkField]: doc.id,
+                ...doc,
+            }));
+            const collectionNameOrAlias = this.resolveCollectionNameOrAlias();
+            await this.volcService.data.UpdateData({
+                Fields: fields,
+                ...collectionNameOrAlias,
+            });
+            this.logger.info('[VikingDB] Volcengine updated', {
+                count: fields.length,
+            });
+            return;
+        }
+        // For custom-http provider, use a dedicated update endpoint if available
+        // Otherwise, we need to fetch existing documents and merge updates
+        throw new Error('Update operation is not supported for custom-http provider. Use upsert instead.');
+    }
+    /**
+     * 删除文档
+     */
+    async delete(options) {
+        const ids = options.ids ?? (options.id ? [options.id] : []);
+        if (this.config.provider === 'volcengine') {
+            if (!this.volcService) {
+                throw new Error('Volcengine VikingDB client not configured (missing AK/SK)');
+            }
+            const collectionNameOrAlias = this.resolveCollectionNameOrAlias();
+            if (options.scope) {
+                // 火山云 SDK 仅支持按主键删除或全量删除；scope 删除需上层自行维护主键集合。
+                throw new Error('Volcengine VikingDB does not support delete by scope; delete by ids only');
+            }
+            if (ids.length === 0) {
+                return;
+            }
+            await this.volcService.data.DeleteData({
+                PrimaryKeys: ids,
+                ...collectionNameOrAlias,
+            });
+            this.logger.info('[VikingDB] Volcengine deleted', {
+                ids: ids.length,
+            });
+            return;
+        }
+        if (ids.length === 0 && !options.scope) {
+            return;
+        }
+        await this.request('POST', this.config.deletePath, {
+            ids: ids.length > 0 ? ids : undefined,
+            scope: options.scope,
+        });
+        this.logger.info('[VikingDB] Documents deleted', {
+            ids: ids.length,
+            scope: options.scope,
+        });
+    }
+    /**
+     * 按作用域删除所有文档
+     */
+    async deleteByScope(scope) {
+        await this.delete({ scope });
+    }
+    // ============================================================================
+    // Volcengine helpers
+    // ============================================================================
+    resolveIndexName() {
+        if (!this.config.indexName) {
+            throw new Error('VIKINGDB_VOLCENGINE_INDEX_NAME is required when VIKINGDB_PROVIDER=volcengine');
+        }
+        return this.config.indexName;
+    }
+    resolveCollectionName() {
+        if (this.config.collectionName) {
+            return this.config.collectionName;
+        }
+        if (this.config.collectionAlias) {
+            // healthCheck 需要 CollectionName；这里给出更明确的错误
+            throw new Error('VIKINGDB_VOLCENGINE_COLLECTION_NAME is required (collectionAlias is not enough for this operation)');
+        }
+        throw new Error('VIKINGDB_VOLCENGINE_COLLECTION_NAME or VIKINGDB_VOLCENGINE_COLLECTION_ALIAS is required');
+    }
+    resolveCollectionNameOrAlias() {
+        if (this.config.collectionName) {
+            return { CollectionName: this.config.collectionName };
+        }
+        if (this.config.collectionAlias) {
+            return { CollectionAlias: this.config.collectionAlias };
+        }
+        throw new Error('VIKINGDB_VOLCENGINE_COLLECTION_NAME or VIKINGDB_VOLCENGINE_COLLECTION_ALIAS is required when VIKINGDB_PROVIDER=volcengine');
+    }
+    buildVolcFilter(scope, taskType) {
+        const conditions = [];
+        // Volcengine SDK 的 filter 依赖 scalar / list scalar 字段。
+        // 因此这里优先使用扁平化字段（tenantId/botId/scopeType/scopeId）。
+        const pushEq = (fieldName, value) => {
+            if (!fieldName)
+                return;
+            if (value === undefined || value === null || String(value).length === 0)
+                return;
+            conditions.push({
+                Operation: 'must',
+                FieldName: fieldName,
+                Conditions: [String(value)],
+            });
+        };
+        pushEq(this.config.tenantIdField, scope.tenantId);
+        pushEq(this.config.botIdField, scope.botId);
+        pushEq(this.config.scopeTypeField, scope.scopeType);
+        pushEq(this.config.scopeIdField, scope.scopeId);
+        // 兜底：如果没有配置扁平化字段，则继续用 metadata.scope.xxx（需要 collection schema 支持）
+        if (conditions.length === 0) {
+            for (const [k, v] of Object.entries(scope ?? {})) {
+                if (v === undefined || v === null || String(v).length === 0)
+                    continue;
+                conditions.push({
+                    Operation: 'must',
+                    FieldName: `${this.config.metadataField ?? 'metadata'}.scope.${k}`,
+                    Conditions: [String(v)],
+                });
+            }
+        }
+        if (taskType) {
+            conditions.push({
+                Operation: 'must',
+                FieldName: this.config.taskTypeField ?? 'taskType',
+                Conditions: [String(taskType)],
+            });
+        }
+        if (conditions.length === 0)
+            return undefined;
+        if (conditions.length === 1)
+            return conditions[0];
+        return {
+            Operation: 'and',
+            Conditions: conditions,
+        };
+    }
+    normalizeVolcSearchResponse(response, fallbackScope) {
+        const data = response?.Data ?? [];
+        const rows = data[0] ?? [];
+        return rows.map((row) => {
+            const fields = row?.Fields ?? {};
+            const id = String(fields[this.config.primaryKeyField ?? 'id'] ??
+                row[this.config.primaryKeyField ?? 'id'] ??
+                row?.Id ??
+                row?.id ??
+                '');
+            const text = String(fields[this.config.textField ?? 'text'] ?? '');
+            const summary = fields[this.config.summaryField ?? 'summary'];
+            const metadataRaw = fields[this.config.metadataField ?? 'metadata'];
+            // metadata 存储为 JSON 字符串，需要解析
+            const metadata = this.parseMetadata(metadataRaw);
+            const tags = fields[this.config.tagsField ?? 'tags'] ?? [];
+            const taskType = fields[this.config.taskTypeField ?? 'taskType'];
+            const createdAt = fields[this.config.createdAtField ?? 'createdAt'];
+            const updatedAt = fields[this.config.updatedAtField ?? 'updatedAt'];
+            const scope = metadata?.scope ?? fallbackScope ?? {};
+            const scoreFinal = typeof row.Score === 'number' ? row.Score : 0;
+            return {
+                id: id || 'unknown',
+                text,
+                summary: summary ? String(summary) : undefined,
+                scope,
+                metadata: metadata ?? {},
+                tags: Array.isArray(tags) ? tags.map(String) : [],
+                taskType: taskType ? String(taskType) : undefined,
+                role: undefined,
+                pinned: false,
+                createdAt: createdAt ? String(createdAt) : undefined,
+                updatedAt: updatedAt ? String(updatedAt) : undefined,
+                scoreVector: scoreFinal,
+                scoreBm25: scoreFinal,
+                scoreHybrid: scoreFinal,
+                scoreRerank: undefined,
+                scoreFinal,
+            };
+        });
+    }
+    parseMetadata(raw) {
+        if (!raw)
+            return {};
+        if (typeof raw === 'object')
+            return raw;
+        if (typeof raw === 'string') {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return {};
+            }
+        }
+        return {};
+    }
+    buildVolcUpsertFields(documents) {
+        const pkField = this.config.primaryKeyField ?? 'id';
+        const primaryKeys = [];
+        const fields = documents.map((doc) => {
+            const id = String(doc.id ?? '');
+            if (!id) {
+                throw new Error(`MemoryDocument.id is required for volcengine upsert (field: ${pkField})`);
+            }
+            primaryKeys.push(id);
+            const now = new Date().toISOString();
+            // 过滤掉 null/undefined 值的 metadata
+            const metadata = this.buildMetadata(doc.metadata, doc.scope);
+            const scope = doc.scope ?? {};
+            // 提取 bots 字段（如果在 metadata 中存在）
+            const bots = doc.metadata?.bots ?? [];
+            return {
+                [pkField]: id,
+                [this.config.textField ?? 'text']: doc.text,
+                ...(doc.summary !== undefined
+                    ? { [this.config.summaryField ?? 'summary']: doc.summary }
+                    : {}),
+                [this.config.vectorField ?? 'embedding']: doc.embedding ?? [],
+                [this.config.tagsField ?? 'tags']: doc.tags ?? [],
+                ...(doc.taskType !== undefined
+                    ? { [this.config.taskTypeField ?? 'taskType']: doc.taskType }
+                    : {}),
+                // 扁平化 scope/source 字段（用于 Volcengine filter）
+                ...(this.config.tenantIdField
+                    ? { [this.config.tenantIdField]: scope.tenantId }
+                    : {}),
+                ...(this.config.botIdField
+                    ? { [this.config.botIdField]: scope.botId }
+                    : {}),
+                ...(this.config.scopeTypeField
+                    ? { [this.config.scopeTypeField]: scope.scopeType }
+                    : {}),
+                ...(this.config.scopeIdField
+                    ? { [this.config.scopeIdField]: scope.scopeId }
+                    : {}),
+                ...(this.config.sourceTypeField
+                    ? { [this.config.sourceTypeField]: doc.metadata?.sourceType }
+                    : {}),
+                ...(this.config.createdByIdField
+                    ? {
+                        [this.config.createdByIdField]: doc.metadata
+                            ?.createdById,
+                    }
+                    : {}),
+                // bots 字段（知识库元数据使用）
+                ...(bots.length > 0 ? { bots } : {}),
+                [this.config.createdAtField ?? 'createdAt']: doc.createdAt ?? now,
+                [this.config.updatedAtField ?? 'updatedAt']: doc.updatedAt ?? now,
+                // metadata 字段为 string 类型，需要 JSON 序列化
+                [this.config.metadataField ?? 'metadata']: JSON.stringify(metadata),
+            };
+        });
+        return { primaryKeys, fields };
+    }
+    buildMetadata(metadata, scope) {
+        const result = {};
+        // 添加 scope
+        if (scope) {
+            result.scope = scope;
+        }
+        // 过滤掉 null/undefined 值
+        if (metadata) {
+            for (const [key, value] of Object.entries(metadata)) {
+                if (value !== null && value !== undefined) {
+                    result[key] = value;
+                }
+            }
+        }
+        return result;
+    }
+    async request(method, path, body) {
+        if (this.config.provider === 'volcengine') {
+            throw new Error('request() is not supported for volcengine provider; use SDK methods');
+        }
+        const url = this.buildUrl(path);
+        const headers = this.buildHeaders();
+        this.logger.debug('[VikingDB] Making request', {
+            method,
+            url,
+            hasBody: !!body,
+        });
+        try {
+            const observable$ = method === 'GET'
+                ? this.httpService.get(url, { headers })
+                : this.httpService.post(url, body, { headers });
+            const response = await (0, rxjs_1.firstValueFrom)(observable$.pipe((0, rxjs_1.timeout)(this.config.timeoutMs), (0, rxjs_1.retry)({
+                count: 2,
+                delay: 1000,
+            })));
+            return response.data;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger.error('[VikingDB] Request failed', {
+                method,
+                url,
+                error: errorMessage,
+            });
+            throw new Error(`VikingDB request failed: ${errorMessage}`);
+        }
+    }
+    buildUrl(path) {
+        const baseUrl = this.config.baseUrl.endsWith('/')
+            ? this.config.baseUrl.slice(0, -1)
+            : this.config.baseUrl;
+        const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+        return `${baseUrl}${normalizedPath}`;
+    }
+    buildHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            ...this.config.headers,
+        };
+        if (this.config.authToken) {
+            headers['Authorization'] = `Bearer ${this.config.authToken}`;
+        }
+        return headers;
+    }
+    parseHeaders(headersJson) {
+        try {
+            const parsed = JSON.parse(headersJson);
+            if (typeof parsed === 'object' && parsed !== null) {
+                return Object.fromEntries(Object.entries(parsed)
+                    .filter(([, v]) => typeof v === 'string')
+                    .map(([k, v]) => [k, String(v)]));
+            }
+        }
+        catch {
+            // Ignore parse errors
+        }
+        return {};
+    }
+    normalizeCandidates(response) {
+        if (!response) {
+            return [];
+        }
+        const candidates = response.candidates ?? response.results ?? response.data;
+        if (!Array.isArray(candidates)) {
+            return [];
+        }
+        return candidates.map((item, index) => ({
+            id: String(item.id ?? `unknown-${index}`),
+            text: String(item.text ?? ''),
+            summary: item.summary ? String(item.summary) : undefined,
+            scope: item.scope ?? {},
+            metadata: item.metadata ?? {},
+            tags: Array.isArray(item.tags) ? item.tags : [],
+            taskType: item.taskType ? String(item.taskType) : undefined,
+            role: item.role ? String(item.role) : undefined,
+            pinned: Boolean(item.pinned),
+            createdAt: item.createdAt ? String(item.createdAt) : undefined,
+            updatedAt: item.updatedAt ? String(item.updatedAt) : undefined,
+            scoreVector: item.scoreVector ?? item.score_vector ?? 0,
+            scoreBm25: item.scoreBm25 ?? item.score_bm25 ?? 0,
+            scoreHybrid: item.scoreHybrid ?? item.score_hybrid ?? 0,
+            scoreRerank: item.scoreRerank
+                ? item.scoreRerank
+                : item.score_rerank
+                    ? item.score_rerank
+                    : undefined,
+            scoreFinal: item.scoreFinal ??
+                item.score_final ??
+                item.score ??
+                0,
+            embedding: Array.isArray(item.embedding)
+                ? item.embedding
+                : undefined,
+        }));
+    }
+    /**
+     * Reciprocal Rank Fusion 算法
+     * 合并向量搜索和 BM25 搜索的结果
+     */
+    reciprocalRankFusion(vectorResults, bm25Results, vectorWeight, bm25Weight, k = 60) {
+        const scoreMap = new Map();
+        // 计算向量搜索的 RRF 分数
+        vectorResults.forEach((candidate, index) => {
+            const rrfScore = vectorWeight / (k + index + 1);
+            const existing = scoreMap.get(candidate.id);
+            if (existing) {
+                existing.score += rrfScore;
+                existing.candidate.scoreHybrid = existing.score;
+            }
+            else {
+                scoreMap.set(candidate.id, {
+                    candidate: { ...candidate, scoreHybrid: rrfScore },
+                    score: rrfScore,
+                });
+            }
+        });
+        // 计算 BM25 搜索的 RRF 分数
+        bm25Results.forEach((candidate, index) => {
+            const rrfScore = bm25Weight / (k + index + 1);
+            const existing = scoreMap.get(candidate.id);
+            if (existing) {
+                existing.score += rrfScore;
+                existing.candidate.scoreHybrid = existing.score;
+            }
+            else {
+                scoreMap.set(candidate.id, {
+                    candidate: { ...candidate, scoreHybrid: rrfScore },
+                    score: rrfScore,
+                });
+            }
+        });
+        // 按分数排序
+        return Array.from(scoreMap.values())
+            .sort((a, b) => b.score - a.score)
+            .map((item) => ({
+            ...item.candidate,
+            scoreFinal: item.candidate.scoreRerank ?? item.candidate.scoreHybrid,
+        }));
+    }
+};
+exports.VikingDbClientService = VikingDbClientService;
+exports.VikingDbClientService = VikingDbClientService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(nest_winston_1.WINSTON_MODULE_PROVIDER)),
+    __metadata("design:paramtypes", [winston_1.Logger,
+        config_1.ConfigService,
+        axios_1.HttpService])
+], VikingDbClientService);
+//# sourceMappingURL=vikingdb-client.service.js.map