WeKnora 向量数据库集成指南从 RetrieveEngine 接口到 Doris 与 Tencent VectorDB 实战【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora本文是面向开发者的 WeKnora 向量检索引擎扩展指南。WeKnora 将 RAG 检索、Agent 推理与 Wiki 等能力建立在可插拔的检索引擎之上通过一组标准化接口支持 PostgreSQL、Elasticsearch、Qdrant、Milvus、Weaviate、Doris、SQLite、OpenSearch 与 Tencent VectorDB 等不同后端。读完本文你将掌握 WeKnora 检索引擎的三层接口抽象、接入新向量数据库的六步完整流程并深入理解 Apache Doris 4.1 与 Tencent VectorDB 两个内置适配器的实现细节双通道协议、维度分表、倒排/ANN 索引、Stream Load 批量更新、sparse vector 关键词检索等可直接在此基础上集成自定义向量数据库。WeKnora 的检索引擎抽象三层接口体系在动手集成之前先理解 WeKnora 如何抽象检索能力。检索引擎相关的接口统一定义在 internal/types/interfaces/retriever.go共分为三层基础检索引擎、存储层与服务层。1. 基础检索引擎接口 RetrieveEngine最底层是RetrieveEngine定义检索引擎的核心检索能力仅含三个方法type RetrieveEngine interface { // EngineType 返回检索引擎的类型标识 EngineType() types.RetrieverEngineType // Retrieve 执行检索操作返回匹配结果 Retrieve(ctx context.Context, params types.RetrieveParams) ([]*types.RetrieveResult, error) // Support 返回该引擎支持的检索类型列表 Support() []types.RetrieverType }EngineType()引擎类型标识对应 internal/types/retriever.go 中定义的RetrieverEngineType字符串常量Retrieve()核心检索入口入参为types.RetrieveParams返回[]*types.RetrieveResultSupport()声明引擎支持的检索类型。RetrieverType目前有三类keywords关键词检索、vector向量检索、websearch网络搜索见 internal/types/retriever.go#L33-L37。检索入参RetrieveParams覆盖了查询文本、查询向量Embedding []float32、知识库/知识/分块 ID 过滤、Tag 过滤、TopK、相似度阈值Threshold、KnowledgeType如faq、manual决定使用哪个索引以及可扩展的AdditionalParams等字段。返回的RetrieveResult内嵌IndexWithScore结构包含ChunkID、KnowledgeID、KnowledgeBaseID、TagID、Score与匹配类型等信息。2. 存储层接口 RetrieveEngineRepositoryRetrieveEngineRepository在基础检索能力之上扩展了索引管理能力同样定义在 internal/types/interfaces/retriever.go#L22-L65type RetrieveEngineRepository interface { Save(ctx context.Context, indexInfo *types.IndexInfo, params map[string]any) error BatchSave(ctx context.Context, indexInfoList []*types.IndexInfo, params map[string]any) error EstimateStorageSize(ctx context.Context, indexInfoList []*types.IndexInfo, params map[string]any) int64 DeleteByChunkIDList(ctx context.Context, indexIDList []string, dimension int, knowledgeType string) error DeleteBySourceIDList(ctx context.Context, sourceIDList []string, dimension int, knowledgeType string) error CopyIndices(ctx context.Context, sourceKnowledgeBaseID string, sourceToTargetKBIDMap map[string]string, sourceToTargetChunkIDMap map[string]string, targetKnowledgeBaseID string, dimension int, knowledgeType string) error DeleteByKnowledgeIDList(ctx context.Context, knowledgeIDList []string, dimension int, knowledgeType string) error BatchUpdateChunkEnabledStatus(ctx context.Context, chunkStatusMap map[string]bool) error BatchUpdateChunkTagID(ctx context.Context, chunkTagMap map[string]string) error RetrieveEngine }对比原文档中的版本当前仓库的接口还新增了两个批量更新方法BatchUpdateChunkEnabledStatus批量启停分块与BatchUpdateChunkTagID批量设置分块 Tag这是后续 Doris 走 Stream Load partial update 实现的功能基础。CopyIndices用于知识库复制场景直接复制索引数据以避免重新计算嵌入向量。3. 服务层接口 RetrieveEngineServiceRetrieveEngineService负责索引创建与管理的业务编排除了继承存储层能力还引入了embedding.Embedder参数在写索引时完成向量化type RetrieveEngineService interface { Index(ctx context.Context, embedder embedding.Embedder, indexInfo *types.IndexInfo, retrieverTypes []types.RetrieverType) error BatchIndex(ctx context.Context, embedder embedding.Embedder, indexInfoList []*types.IndexInfo, retrieverTypes []types.RetrieverType) error EstimateStorageSize(ctx context.Context, embedder embedding.Embedder, indexInfoList []*types.IndexInfo, retrieverTypes []types.RetrieverType) int64 CopyIndices(...) error DeleteByChunkIDList(...) error DeleteBySourceIDList(...) error DeleteByKnowledgeIDList(...) error BatchUpdateChunkEnabledStatus(...) error BatchUpdateChunkTagID(...) error RetrieveEngine }此外internal/types/interfaces/retriever.go#L67-L99 定义了RetrieveEngineRegistry注册表接口支持Register/GetRetrieveEngineService/GetAllRetrieveEngineServices以及按 store ID 获取引擎的GetByStoreID与GetOrLoadByStoreID。从源码注释可以看到多实例部署下引擎注册表是进程内的某实例注册的引擎在其他实例上缺失GetOrLoadByStoreID允许按需从数据库重建且按租户范围查询作为防跨租户越权的纵深防御。六步集成流程接入一个新向量数据库WeKnora 为接入新向量数据库规定了固定流程核心是接口实现 注册 DI 依赖注入。以下每一步都有对应的源码佐证。第 1 步实现基础检索引擎接口按上文RetrieveEngine接口实现三个方法。通常你的仓库实现会通过内嵌一个通用混合检索引擎来减少重复代码——参考现有实现均使用retriever.NewKVHybridRetrieveEngine(repo, engineType)将存储层 repo 包装为同时支持 keyword/vector 的混合引擎。第 2 步实现存储层接口实现RetrieveEngineRepository的全部方法Save/BatchSave保存索引、EstimateStorageSize估算存储空间、DeleteByChunkIDList/DeleteByKnowledgeIDList/DeleteBySourceIDList删除索引、CopyIndices复制索引避免重算向量、BatchUpdateChunkEnabledStatus/BatchUpdateChunkTagID批量更新。注意删除方法均携带dimension与knowledgeType参数因为 WeKnora 按向量维度分表/分集合删除时必须定位到具体维度。第 3 步实现服务层接口创建RetrieveEngineService实现负责索引创建与管理的业务逻辑。一般直接由NewKVHybridRetrieveEngine包装存储层 repo 即可获得完整的服务能力。第 4 步添加环境变量配置在RETRIEVE_DRIVER中加入新驱动名逗号分隔支持多驱动并存并补充连接参数# 多个驱动用逗号分隔可同时启用多个检索引擎 RETRIEVE_DRIVERpostgres,elasticsearch_v8,your_database # 新数据库的连接参数 YOUR_DATABASE_ADDRyour_database_host:port YOUR_DATABASE_USERNAMEusername YOUR_DATABASE_PASSWORDpassword # 其他必要的连接参数...第 5 步注册检索引擎在 internal/container/container.go 的initRetrieveEngineRegistry函数定义于 container.go#L1117中添加初始化与注册逻辑。函数签名如下func initRetrieveEngineRegistry( db *gorm.DB, cfg *config.Config, auditSvc interfaces.AuditLogService, storeRepo interfaces.VectorStoreRepository, engineFactory interfaces.EngineFactory, ) (interfaces.RetrieveEngineRegistry, error) { registry : retriever.NewRetrieveEngineRegistry(storeRepo, engineFactory) retrieveDriver : strings.Split(os.Getenv(RETRIEVE_DRIVER), ,) // 通过 slices.Contains(retrieveDriver, your_database) 判断是否启用 // ... return registry, nil }新增驱动的注册代码模式如下if slices.Contains(retrieveDriver, your_database) { client, err : your_database.NewClient(your_database.Config{ Addresses: []string{os.Getenv(YOUR_DATABASE_ADDR)}, Username: os.Getenv(YOUR_DATABASE_USERNAME), Password: os.Getenv(YOUR_DATABASE_PASSWORD), }) if err ! nil { log.Errorf(Create your_database client failed: %v, err) } else { yourDatabaseRepo : your_database.NewYourDatabaseRepository(client, cfg) if err : registry.Register( retriever.NewKVHybridRetrieveEngine( yourDatabaseRepo, types.YourDatabaseRetrieverEngineType, ), ); err ! nil { log.Errorf(Register your_database retrieve engine failed: %v, err) } else { log.Infof(Register your_database retrieve engine success) } } }initRetrieveEngineRegistry通过 DI 容器container.Provide注入见 container.go#L131注册完成后的 registry 还会同时暴露为StoreRegistry供上层按 store ID 解析引擎。第 6 步定义检索引擎类型常量在 internal/types/retriever.go 中追加新的引擎类型常量const ( PostgresRetrieverEngineType RetrieverEngineType postgres ElasticsearchRetrieverEngineType RetrieverEngineType elasticsearch DorisRetrieverEngineType RetrieverEngineType doris TencentVectorDBRetrieverEngineType RetrieverEngineType tencent_vectordb // 新增 YourDatabaseRetrieverEngineType RetrieverEngineType your_database )当前仓库已注册的引擎类型包括postgres、elasticsearch、infinity、elasticfaiss、qdrant、milvus、weaviate、doris、sqlite、tencent_vectordb与opensearch见 internal/types/retriever.go#L7-L27。参考实现以现有驱动为模板仓库提供了多个完整的驱动实现可作为开发模板PostgreSQLinternal/application/repository/retriever/postgres/Elasticsearch V7internal/application/repository/retriever/elasticsearch/v7/Elasticsearch V8internal/application/repository/retriever/elasticsearch/v8/Apache Doris 4.1internal/application/repository/retriever/doris/Tencent VectorDBinternal/application/repository/retriever/tencentvectordb/其中 Doris 与 Tencent VectorDB 是仓库中较新的适配器实现文件包含repository.go、structs.go、move.go索引迁移等并配有repository_test.go测试。Doris 目录下还有schema.go表结构管理、streamload.go批量更新、query.go检索查询、compat.go兼容模式等文件下文详细展开。Apache Doris 4.1 集成要点Doris 是 MPP 风格的分析型 SQL 数据库其接入方式与 NoSQL 向量库Qdrant/Milvus/Weaviate有显著差异WeKnora 适配器做了针对性设计实现在internal/application/repository/retriever/doris/。双通道协议通道端口用途MySQL 协议FE 9030主链路 CRUD、ANN 检索、全文检索HTTP APIFE 8030 / BE 8040Stream Load partial updateWeKnora 通过database/sql go-sql-driver/mysql调用 MySQL 协议通过net/http调用 Stream Load。两条通道复用同一份用户名/密码。注册代码位于 container.go#L1346-L1392DSN 构造为username:passwordtcp(addr)/database?charsetutf8mb4parseTimetruelocLocalinterpolateParamstrue连接池设置为最大 20 个连接、最大空闲 5 个、单连接最长 1 小时HTTP 基础地址则由 FE 地址主机名拼接DORIS_HTTP_PORT默认 8030得到。表结构与维度分表每个 embedding 维度对应一张物理表DORIS_TABLE_PREFIX_dim如weknora_embeddings_768getTableName实现于 schema.go#L28-L30。表关键属性ENGINEOLAP UNIQUE KEY(id) DISTRIBUTED BY HASH(id) BUCKETS 10 PROPERTIES( replication_num1, enable_unique_key_merge_on_writetrue );enable_unique_key_merge_on_writetrue是 Stream Load partial update 的前提条件。从 schema.go#L14-L22 可见WeKnora 将默认桶数设为 10、副本数设为 1这是对单机/小集群更友好的保守值。表创建结果缓存在initializedTables中同一进程内同一维度只会真正执行一次SHOW TABLES DDL。索引设计倒排索引INVERTEDchunk_id / knowledge_id / knowledge_base_id / source_id / tag_id / is_enabled等过滤字段建索引content字段使用parserchinese在数据库端完成中文分词与全文检索。ANN 索引在embedding ARRAYFLOAT列上构建 HNSW cosine_distance。关键细节Doris 的 ANN 索引在建表后是异步构建的索引未就绪期间查询会退化为 brute-force结果正确但速度慢。WeKnora 在ensureTable中于后台 goroutine 轮询SHOW INDEX FROM table等待idx_emb进入FINISHED/NORMAL状态超时上限 30 秒、轮询间隔 1 秒见 schema.go#L37-L80。这样写入路径不被阻塞——索引未就绪时检索退化为 brute-force比让首批写入卡 30 秒更可接受。分数语义向量检索使用1 - cosine_distance_approximate(embedding, vec) AS score将 distance 翻转为 similarity与 Qdrant cosine 相似度方向一致值越大越相似。threshold 比较使用HAVING score ?、排序使用ORDER BY score DESC LIMIT ?。关键词检索依赖 Doris 内建的MATCH_ANY与chineseparser无需在 Go 端做 jieba 分词。跨维度的多张表会逐表查询并合并取 topK与 Milvus/Weaviate 的现状一致。批量字段更新Stream Load partial updateBatchUpdateChunkEnabledStatus与BatchUpdateChunkTagID通过 Stream Load partial update 实现见internal/application/repository/retriever/doris/streamload.goHTTP PUThttp://fe_http/api/db/table/_stream_loadHeaderspartial_columns: true、columns: id,is_enabled、merge_type: APPEND、format: json、strip_outer_array: trueBody[{id: ..., is_enabled: true}, ...]每批 ≤ 1MiB 自动拆批请求体通过bytes.Readerreq.GetBody闭包构造确保 FE → BE 的 307 redirect 时可以重发 Body。环境变量与本地启动RETRIEVE_DRIVERdoris DORIS_ADDRdoris-fe:9030 # FE MySQL 协议地址 DORIS_HTTP_PORT8030 # FE HTTP 端口Stream Load DORIS_DATABASEweknora # 目标库 DORIS_USERNAMEroot DORIS_PASSWORD DORIS_TABLE_PREFIXweknora_embeddings注意各环境变量在注册代码中都有默认值DORIS_ADDR默认doris-fe:9030docker-compose 服务名、DORIS_DATABASE默认weknora、DORIS_USERNAME默认root、DORIS_HTTP_PORT默认 8030见 container.go#L1346-L1366。本地启动 Dorisdocker compose --profile doris up -d docker exec -it WeKnora-doris-fe mysql -h 127.0.0.1 -P 9030 -uroot \ -e CREATE DATABASE IF NOT EXISTS weknora;仓库根目录的 docker-compose.yml第 713 行起为--profile doris定义了 FE BE 单实例 standalone 部署FE 使用apache/doris:fe-4.1.0镜像、BE 使用apache/doris:be-4.1.0镜像数据持久化在doris_fe_meta/doris_fe_log/doris_be_storage/doris_be_log四个命名卷中。启动后运行 WeKnora 后端知识库写入即会按维度自动建表。Tencent VectorDB 集成解析WeKnora 内置 Tencent VectorDB 适配器驱动名为tencent_vectordb实现在internal/application/repository/retriever/tencentvectordb/。该适配器支持向量检索、基于 BM25 sparse vector 的关键词检索和索引管理可参与 WeKnora 上层混合检索。环境变量RETRIEVE_DRIVERtencent_vectordb TENCENT_VECTORDB_ADDRhttp://your-instance.tencentvectordb.com TENCENT_VECTORDB_USERNAMEroot TENCENT_VECTORDB_API_KEYyour_tencent_vectordb_api_key TENCENT_VECTORDB_DATABASEweknora TENCENT_VECTORDB_COLLECTIONweknora_embeddings TENCENT_VECTORDB_REPLICA_NUMBER1从注册代码container.go#L1393-L1423可以看到客户端通过tcvectordb.NewRpcClient(addr, username, apiKey, ...)创建 RPC 客户端并配置了ReadConsistency: EventualConsistency最终一致性读与 10 秒超时ADDR、USERNAME、API_KEY三者缺一不可缺失会直接报 Missing Tencent VectorDB configuration。维度分集合与副本数TENCENT_VECTORDB_COLLECTION是集合名前缀。WeKnora 会按向量维度创建实际集合例如weknora_embeddings_768用于隔离不同 embedding 模型维度的数据。集合名解析逻辑在 repository.go#L38-L46优先使用IndexConfig中的配置否则读取环境变量再回退到默认值。TENCENT_VECTORDB_REPLICA_NUMBER是创建集合时使用的副本数。resolveReplicaNumber的解析优先级为IndexConfig.ReplicaNumber 环境变量需 ≥ 0 默认值 1见 repository.go#L49-L60。单节点 QA 环境可设为0生产环境可按 Tencent VectorDB 集群规模调整。此外还有分片数shardsNum默认 1同样可通过IndexConfig覆盖。sparse vector 关键词检索关键词检索依赖 Tencent VectorDB 的 sparse vector 索引新建集合会自动创建sparse_vector索引适配器的Support()返回[keywords, vector]见 repository.go#L66-L68。注意旧版本已创建的向量集合如果没有该索引需要重建集合并重新导入知识库数据后才能启用关键词检索。写入时BatchSave会按 embedding 维度分组同时构造 dense vector 与 BM25 sparse vector 数据写入集合。扩展开发模式的延伸阅读向量数据库集成遵循的接口实现 注册 DI 依赖注入模式在 WeKnora 中同样适用于网络搜索引擎等扩展点添加网络搜索引擎 — 同类扩展开发模式接口实现 注册 DI知识图谱 — 知识图谱功能依赖 Neo4j 而非向量数据库常见问题 — Embedding 模型配置与向量维度相关版本路线图 — 路线图中的检索能力扩展方向开发指南 — 本地开发环境与调试方式Home — Wiki 首页导航掌握了本指南的接口体系与六步流程即可将任意具备向量检索能力的数据源接入 WeKnora 的 RAG、Agent 与 Wiki 检索链路享受上层混合检索、维度分表、索引管理等开箱即用的能力。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考