ARTICLE DETAIL

建站实战干货

来自一线的建站与推广经验沉淀，每一条都经过真实交付验证。

首页 / 资讯中心 / 正文

Conductor 向量数据库配置指南：多实例编排、参数详解与故障排查

2026/9/10 12:44:50 拓冰建站 浏览量
Conductor 向量数据库配置指南：多实例编排、参数详解与故障排查 Conductor 向量数据库配置指南多实例编排、参数详解与故障排查【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor本指南系统讲解 Conductor事件驱动的 Agentic 工作流引擎中向量数据库Vector Database的配置体系。文章以 ai/VECTORDB_CONFIGURATION.md 为骨架深入结合ai模块源码覆盖 PostgreSQLpgvector、MongoDBAtlas Vector Search、Pinecone 三种提供方的多命名实例配置格式、工作流引用方式、参数表、旧配置迁移与最佳实践。读完本文你将能够为 RAG检索增强生成与语义搜索类工作流正确配置多套向量库实例并能够独立排查常见故障。概述为什么需要可配置的向量数据库Conductor 的 AI 能力如LLM_STORE_EMBEDDINGS、LLM_SEARCH_EMBEDDINGS等系统任务需要持久化与检索文本的向量表示embeddings。这些向量数据存储在独立的向量数据库中而不同业务场景文档索引、语义搜索、推荐召回对环境、模型维度、延迟的要求各不相同。为此Conductor 采用多命名实例multiple named instances的配置方式允许同时配置同一类型的多套数据库以实现同类型多实例例如同时连接多套 PostgreSQL 实例环境隔离分别连接生产prod、开发dev、预发staging用例分离按用途拆分 embeddings 存储、搜索、推荐等不同向量库。从源码来看这一设计体现在 VectorDBInstanceConfig.java 中配置类以ConfigurationProperties(prefix conductor.vectordb)绑定外部配置将每个命名实例按其type分派到对应的数据库实现最终在 VectorDBProvider.java 中以ConcurrentHashMapString, VectorDB按名称注册供工作流任务按名称查找。支持的向量数据库当前仓库支持以下三类向量数据库提供方类型标识type数据库扩展/服务postgresPostgreSQLpgvector 扩展mongodbMongoDBAtlas Vector SearchpineconePinecone托管向量数据库服务配置格式conductor.vectordb.instances所有向量数据库统一使用列表list式配置位于conductor.vectordb.instances前缀之下。基础模板如下conductor: vectordb: instances: - name: instance-name # 该实例的唯一标识 type: database-type # 类型postgres / mongodb / pinecone type-specific-config: # 与该数据库类型对应的配置块 # ... 类型专属属性每个列表元素对应一个独立实例包含三个字段name实例唯一名称工作流任务通过它引用实例要求与工作流中的vectorDB参数完全一致type数据库类型标识决定实例化哪个实现类类型专属配置块按type对应postgres、mongodb或pinecone键提供该类型的具体参数。在源码中VectorDBInstanceConfig.VectorDBInstance 正是这样建模的每个实例同时持有name、type以及三种类型的可选配置对象createVectorDB 根据type大小写不敏感分派创建对应数据库实例。若类型未知或对应的配置块缺失该实例会被记录错误日志并跳过。配置示例单个 PostgreSQL 实例conductor: vectordb: instances: - name: postgres-main type: postgres postgres: datasourceURL: jdbc:postgresql://localhost:5432/vectors user: conductor password: secret dimensions: 1536 connectionPoolSize: 10 indexingMethod: hnsw # 可选hnsw, ivfflat distanceMetric: cosine # 可选l2, cosine, inner_product tablePrefix: conductor多个 PostgreSQL 实例同一类型可配置多个实例便于区分生产与开发环境注意二者维度不同需与各自使用的嵌入模型匹配conductor: vectordb: instances: - name: postgres-prod type: postgres postgres: datasourceURL: jdbc:postgresql://prod-db:5432/vectors user: conductor password: prod-secret dimensions: 1536 - name: postgres-dev type: postgres postgres: datasourceURL: jdbc:postgresql://dev-db:5432/vectors user: conductor password: dev-secret dimensions: 768MongoDB Atlas Vector Searchconductor: vectordb: instances: - name: mongodb-embeddings type: mongodb mongodb: connectionString: mongodbsrv://user:passcluster.mongodb.net/ database: conductor collection: embeddings numCandidates: 100Pineconeconductor: vectordb: instances: - name: pinecone-search type: pinecone pinecone: apiKey: your-pinecone-api-key混合配置多种类型并存三种类型可以在同一个instances列表中任意混用适合生产检索 嵌入存储 缓存的分工conductor: vectordb: instances: - name: postgres-prod type: postgres postgres: datasourceURL: jdbc:postgresql://prod:5432/vectors user: conductor password: secret dimensions: 1536 - name: pinecone-embeddings type: pinecone pinecone: apiKey: pk-xxx - name: mongodb-cache type: mongodb mongodb: connectionString: mongodb://localhost:27017 database: conductor使用 properties 文件配置等价写法除 YAML 外也可以使用标准的application.properties索引式写法。仓库文档 docs/devguide/cookbook/ai-llm.md 给出了一个可直接用于 RAG 示例的配置conductor.vectordb.instances[0].namepostgres-prod conductor.vectordb.instances[0].typepostgres conductor.vectordb.instances[0].postgres.datasourceURLjdbc:postgresql://localhost:5432/vectors conductor.vectordb.instances[0].postgres.userconductor conductor.vectordb.instances[0].postgres.passwordsecret conductor.vectordb.instances[0].postgres.dimensions1536两种写法最终都会被ConfigurationProperties(prefix conductor.vectordb)绑定到同一套配置模型。在工作流中使用向量数据库实例工作流中的向量数据库系统任务通过inputParameters.vectorDB按配置的实例名称引用实例。以LLM_STORE_EMBEDDINGS为例原文档 示例{ name: store_embeddings, taskReferenceName: store_embeddings_ref, type: LLM_STORE_EMBEDDINGS, inputParameters: { vectorDB: postgres-prod, index: documents, namespace: my_namespace, embeddings: ${embedding_task.output.embeddings}, metadata: { documentId: ${workflow.input.docId} } } }从源码看这一引用链路的实现位于 VectorDBWorkers.javaLLM_STORE_EMBEDDINGS把embeddings写入指定实例的index/namespaceLLM_SEARCH_EMBEDDINGS基于查询向量检索相似文档返回IndexedDoc列表输入字段定义在 VectorDBInput.javavectorDB、index、namespace、embeddings、query、metadata、maxResults等两个任务最终都经由 VectorDBs.java 调用VectorDBProvider.get(vectorDBName, context)按名称取出实例若实例不存在会抛出NonRetryableException(VectorDB not found: name)任务将直接失败而不会重试。另外还有LLM_INDEX_TEXT自动为文本生成嵌入并索引见 VectorDBWorkers.java以及LLM_SEARCH_INDEX、LLM_GET_EMBEDDINGS已标记Deprecated内部转发到新方法等任务。详细的 AI 工作流示例可参考 ai/examples 目录如05-semantic-search.json、06-rag-basic.json、07-rag-complete.json。PostgreSQL 配置选项属性类型默认值说明datasourceURLString必填JDBC 连接 URLuserString必填数据库用户名passwordString必填数据库密码dimensionsInteger256向量维度connectionPoolSizeInteger5连接池大小indexingMethodStringhnsw索引方法hnsw 或 ivfflatdistanceMetricStringl2距离度量l2、cosine、inner_productinvertedListCountInteger100IVFFlat 索引参数tablePrefixStringnull表名前缀这些默认值在 PostgresConfig.java 中直接定义。结合 PostgresVectorDB.java 实现有几个值得注意的底层行为连接池connectionPoolSize最终作用于 HikariCPHikariDataSource的maximumPoolSize并设置idleTimeout为 60 秒连接池启动时会等待其就绪最长 5 秒见 PostgresVectorDB.java。维度校验写入时会校验dimensions与传入向量的长度一致不一致会直接抛出RuntimeExceptionEmbeddings must be of dimensions: ...。因此dimensions必须与嵌入模型输出的维度一致否则运行时必然报错。命名空间与表结构namespace与indexName必须匹配正则[a-zA-Z0-9_-]否则抛 Invalid namespace/index name 异常表名由tablePrefix若设置与namespace拼接而成tablePrefix _ namespace表不存在时自动创建。索引与写入写入前会自动创建向量表与向量索引插入采用ON CONFLICT (id) DO UPDATE的 upsert 语义doc文本会经过TextUtils.sanitizeForPostgres清洗metadata以 JSON 形式存储。连接复用DataSource 以datasourceURL为键缓存在 Guava Cache 中最多 100 个、空闲 60 秒后过期并关闭底层连接池见 PostgresVectorDB.java。MongoDB 配置选项属性类型默认值说明connectionStringString必填MongoDB 连接串databaseString必填数据库名collectionString可选集合名numCandidatesInteger可选向量搜索参数候选数字段定义位于 MongoDBConfig.java实际实现见 MongoVectorDB.java其测试用例位于 MongoVectorDBTest.java。需要特别说明向量搜索依赖 MongoDB Atlas 或 MongoDB 6.0 的 Atlas Search 能力本地 MongoDB 容器不支持向量搜索且必须先在集合上创建向量搜索索引。Pinecone 配置选项属性类型默认值说明apiKeyString必填Pinecone API Key字段定义位于 PineconeConfig.java实现见 PineconeDB.java。使用前需确保 Pinecone 账号中已存在目标 index且 API Key 具有相应权限。从旧配置迁移旧格式每类型单实例在引入命名实例之前配置采用单实例平铺结构conductor: vectordb: postgres: datasourceURL: jdbc:postgresql://localhost:5432/vectors user: conductor password: secret新格式命名实例conductor: vectordb: instances: - name: pgvectordb # 使用旧类型名以保持向后兼容 type: postgres postgres: datasourceURL: jdbc:postgresql://localhost:5432/vectors user: conductor password: secret类型标识已简化pgvectordb→postgresmongovectordb→mongodbpineconedb→pinecone不过为了向后兼容旧类型名仍然可用——只需将实例命名为对应旧类型名即可。这一点在源码中有直接印证createVectorDB 的 switch 分支同时接受postgres/pgvectordb、mongodb/mongovectordb、pinecone/pineconedb两套写法大小写不敏感。最佳实践使用描述性名称实例名应清晰表达用途如postgres-prod、pinecone-embeddings-search便于在日志与工作流中识别。隔离环境生产、开发、预发使用不同实例避免数据意外混写。优化维度dimensions必须与嵌入模型输出维度一致否则运行时抛错PostgreSQL 实现会在写入时严格校验。连接池调优根据工作负载与数据库容量调整connectionPoolSize过高会压垮数据库过低会导致高并发下排队。索引选型hnsw默认查询性能更好适合在线检索ivfflat建索引更快适合写入密集、查询规模可控的场景可通过invertedListCount调节其质量。距离度量选型cosine适合归一化后的嵌入绝大多数现代嵌入模型的默认场景l2欧氏距离适合需要绝对距离语义的场景inner_product用于点积相似度。所选度量应与训练/索引时一致。故障排查实例找不到Instance Not Found出现Vector DB instance not found: xyz之类的错误时依次检查工作流inputParameters.vectorDB中的名称与配置中的name完全一致区分大小写、无多余空格实例确实已写入application.yml/application.properties注意conductor.vectordb.instances前缀是否正确配置修改后是否已重启应用——VectorDBProvider在启动阶段一次性完成实例注册见 VectorDBProvider.java运行期修改配置不会生效。另外可留意服务启动日志注册成功会打印Initialized vector DB instance: name (type: type)失败则打印Failed to initialize vector DB instance: ...及原因VectorDBProvider启动时也会打印全部可用实例清单方便核对名称。PostgreSQL 连接问题确保已安装 pgvector 扩展CREATE EXTENSION vector;核对 JDBC URL 格式与网络连通性源码要求连接串非空否则抛 Missing connection URL 异常检查数据库用户权限建表、建索引、读写目标 schema 的权限。MongoDB 向量搜索问题向量搜索需要 MongoDB Atlas 或 MongoDB 6.0 的 Atlas Search 能力确保已在集合上创建向量搜索索引否则查询会失败本地 MongoDB 容器不支持向量搜索请使用 Atlas 或兼容实例。Pinecone 问题验证 API Key 有效且具备必要权限确保目标 index 已存在于 Pinecone 账号中再于工作流中引用。小结Conductor 的向量数据库配置围绕conductor.vectordb.instances这一统一列表展开通过name type 类型专属配置块的结构同时支持 PostgreSQL、MongoDB 与 Pinecone 的多实例与混合部署工作流侧以实例名解耦存储位置与业务逻辑底层由VectorDBProvider统一注册、按名查找。理解本文中的参数语义、旧配置迁移路径与排查要点后你即可为 RAG、语义搜索等 AI 工作流搭建稳定、可扩展的向量存储层。更多端到端示例可继续阅读 ai/examples 与 docs/devguide/cookbook/ai-llm.md。【免费下载链接】conductorConductor is an event driven agentic workflow engine providing durable and highly resilient execution engine for applications and AI Agents项目地址: https://gitcode.com/GitHub_Trending/co/conductor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考