openJiuwen agent-core-java 知识检索中的 StoreType 枚举：向量库提供方的定义、校验与工厂路由

人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载在 agent-core-java 的知识检索retrieval体系中StoreType枚举是“选择哪种向量库”的唯一配置入口它以小写字符串标识 Milvus、Chroma、PGVector、Elasticsearch 四类提供方贯穿VectorStoreConfig配置校验、VectorStoreFactory工厂实例化以及 SPI 插件路由三层链路。读完本篇你可以掌握StoreType的取值与解析规则、它在 JSON 配置中的序列化形式以及如何根据该枚举正确创建对应的向量库实例并排查“提供方不可用”类错误。1. StoreType向量库提供方枚举StoreType定义在 core 模块的com.openjiuwen.core.retrieval.common包中对应源文件为 StoreType.java。其 Javadoc 明确说明该枚举镜像自 Python 版openjiuwen/core/retrieval/common/config.py中的同名StoreType即它是 Java 版 openJiuwen Core 与 Python 版 API 对齐的一部分。API 文档 StoreType.md 将其概括为“向量库提供方枚举”。以当前仓库源码为准完整枚举定义如下public enum StoreType { MILVUS(milvus), CHROMA(chroma), PGVECTOR(pgvector), ELASTICSEARCH(elasticsearch); private final String value; ... }1.1 枚举值与底层字符串值枚举常量value()底层字符串说明MILVUSmilvusMilvus 向量库CHROMAchromaChroma 向量库PGVECTORpgvectorPostgreSQL pgvector 向量库ELASTICSEARCHelasticsearchElasticsearch 向量库依赖 dense vector 能力需要说明两点与 API 文档的差异以当前仓库源码为准API 文档的枚举值表仅列出MILVUS/CHROMA/PGVECTOR三项而当前源码中已包含第四项ELASTICSEARCH它是通过 SPI 扩展层接入的提供方见 ElasticsearchVectorStoreProvider.javatypeName()返回elasticsearchAPI 文档将取值方法写作public String value()当前源码中的实际签名为public String getValue()并带有JsonValue注解见 StoreType.java。1.2 两个核心方法签名说明public String getValue()返回底层字符串值如MILVUS.getValue()得到milvus标注JsonValue用于 Jackson 序列化public static StoreType fromValue(String value)从字符串解析枚举值标注JsonCreator用于 Jackson 反序列化fromValue的解析逻辑是对values()逐个做equals比对区分大小写未匹配时直接抛出参数异常JsonCreator public static StoreType fromValue(String value) { for (StoreType type : values()) { if (type.value.equals(value)) { return type; } } throw new IllegalArgumentException(Unsupported store provider: value); }因此Milvus首字母大写或es这类字符串都会触发IllegalArgumentException: Unsupported store provider: ...。测试 RetrievalCommonConfigTest.java 中有对应的正常解析断言assertThat(StoreType.fromValue(milvus)).isEqualTo(StoreType.MILVUS);JsonValue与JsonCreator这一对注解决定了StoreType在配置文件中始终是小写字符串而非枚举名这也是后文 JSON 配置示例的由来。2. StoreType 参与配置VectorStoreConfig 中的 store_providerStoreType并不是孤立存在的它最主要的消费方是同包的 VectorStoreConfig.javaAPI 文档见 VectorStoreConfig.md。该类持有四个字段JSON 字段Java 字段默认值约束store_providerStoreType storeProvider无必填缺失时validate()抛出store_provider is requireddatabase_nameString databaseName必须匹配^[A-Za-z0-9_]*$collection_nameString collectionName无非 CHROMA 场景必填为null时抛collection_name is requireddistance_metricString distanceMetriccosine仅允许cosine、euclidean、dot其中storeProvider字段标注JsonProperty(store_provider)并且 setter 直接走枚举解析见 VectorStoreConfig.javapublic void setStoreProvider(String storeProvider) { this.storeProvider StoreType.fromValue(storeProvider); }这意味着无论通过 Jackson 反序列化还是通过字符串构造器VectorStoreConfig(Object storeProvider, ...)内部调用toStoreType非枚举对象会先String.valueOf再走fromValue非法提供方字符串都会在配置阶段就报错而不是拖到运行时建连才失败。2.1 JSON 配置形态由于序列化走getValue()/fromValue一个 Milvus 知识库配置对象序列化为{ store_provider: milvus, database_name: db_01, collection_name: collection-a, distance_metric: cosine }反序列化时milvus经JsonCreator fromValue还原为StoreType.MILVUS。2.2 Builder 用法VectorStoreConfig提供静态 Builder见 VectorStoreConfig.javastoreProvider同时接受枚举与字符串两种入参VectorStoreConfig config VectorStoreConfig.builder() .storeProvider(StoreType.MILVUS) // 等价写法.storeProvider(milvus) .databaseName(db_01) .collectionName(collection-a) .distanceMetric(cosine) .build();Builder 中有一个值得注意的分支build()时若collectionName为null且提供方是StoreType.CHROMA会把集合名兜底为空串后再构造CHROMA 本地持久化不依赖显式集合名语义其余提供方则仍会触发collection_name is required校验。测试 ConfigTest.java 与 RetrievalCommonConfigTest.java 分别覆盖了CHROMA正常构造、非法distance_metric抛错等场景。3. 工厂路由StoreType 如何决定向量库实例StoreType的第二大消费方是 retrieval 模块的 VectorStoreFactory.java。createVectorStore(VectorStoreConfig config, MapString, Object kwargs)读取config.getStoreProvider()后按枚举常量分支提供方创建结果关键 kwargs含默认值MILVUSMilvusVectorStore支持注入外部MilvusClientFacademilvus_uri、milvus_token、text_fieldcontent、vector_fieldembedding、sparse_vector_fieldsparse_vector、metadata_fieldmetadata、doc_id_fielddocument_id、milvus_alias、milvus_clientCHROMAChromaVectorStorechroma_path以及同上的text_field/vector_field/sparse_vector_field/metadata_field/doc_id_field默认值PGVECTORPGVectorStorevector_field可为PGVectorField对象pg_uri其余字段默认值同上其他含ELASTICSEARCH抛出StatusCode.RETRIEVAL_VECTOR_STORE_PROVIDER_INVALID错误错误信息为unavailable vector store provider: ...并附StoreType.values()全量列表三个后端的具体实现类分别位于 MilvusVectorStore.java、ChromaVectorStore.java、PGVectorStore.java。它们统一实现 core 模块的 VectorStore.java 接口提供add、search稠密向量检索、sparseSearch稀疏/BM25 检索、hybridSearch混合检索带alpha权重以及delete、tableExists、deleteTable等能力并以VectorStoreFilter/DeleteFilter封装过滤条件。一个完整的创建示例// 1. 构造配置store_provider chroma VectorStoreConfig config VectorStoreConfig.builder() .storeProvider(StoreType.CHROMA) .collectionName(demo_kb) .distanceMetric(cosine) .build(); // 2. 通过工厂创建向量库实例 VectorStore store VectorStoreFactory.createVectorStore(config, Map.of( chroma_path, ./chroma_data, text_field, content, vector_field, embedding));这里有一个从源码结构看可以推断出的细节异常分支中“available providers”是通过遍历StoreType.values()拼出来的因此错误提示里会列出全部四个字符串值含elasticsearch但工厂自身只分支处理三个elasticsearch实际由扩展 SPI 层承接下一节。兼容性测试 StoreExtensionCompatibilityTest.java 中的retrievalVectorStoreFactoryShouldRejectUnsupportedStoreType用例正是验证了这一点用new VectorStoreConfig(elasticsearch, demo_collection)构造配置后调用VectorStoreFactory.createVectorStore断言抛出异常。4. SPI 扩展层elasticsearch 提供方如何接入StoreType.ELASTICSEARCH虽然存在于配置层却不走VectorStoreFactory的硬编码分支而是走 foundation 层的插件化路由StoreFactory.java 提供createVectorStore(String storeType, MapString, Object options)按字符串类型名创建BaseVectorStore并委托给 SPI 工厂SPI 的具体实现通过 Java ServiceLoader 机制注册服务文件 com.openjiuwen.spi.store.vector.VectorStoreProvider 内置了四个 providerChromaVectorStoreProvider、MilvusVectorStoreProvider、PGVectorStoreProvider、ElasticsearchVectorStoreProviderVectorStoreRegistry.java 维护了三层解析顺序内置名称集合chroma、milvus、gaussvector→ 运行时registerVectorStore(name, factory)注册的自定义工厂 →ServiceLoader加载的 provider找不到时记录告警并返回null同时提供register_vector_store等 Python 风格别名以兼容原实现。对应测试用例演示了 elasticsearch 的正确入口Object store StoreFactory.createVectorStore(elasticsearch, Map.of( collection_name, demo_collection)); assertThat(store).isInstanceOf(ElasticsearchVectorStore.class);examples/store/README.md 也说明了当前 Java 侧extensions.store基线已暴露ElasticsearchVectorStore等实现且其适配器属于“兼容性优先”阶段。换言之若你的知识库配置是store_provider: elasticsearch应通过StoreFactory/SPI 路径创建实例而不是 retrieval 模块的VectorStoreFactory。5. 下游消费IndexerFactory 与知识库检索模式StoreType的影响还延伸到了索引与知识库层面IndexerFactory.java 的createIndexer(VectorStore)会对MilvusVectorStore做类型判断并用StoreType.MILVUS现场重建一份VectorStoreConfigcollection 名缺省兜底default、距离度量缺省兜底cosine来构造MilvusIndexer其余向量库实例则统一回退为InMemoryIndexer。这说明 Milvus 是唯一拥有独立 Indexer 实现的提供方其余后端的索引维护由内存侧承担知识库层的 KnowledgeBaseConfig.java 通过index_typehybrid/bm25/vector默认hybrid决定检索模式。结合 retrieval.README.md 的说明SimpleKnowledgeBase会据此在向量、BM25 与混合检索间自动选择——而向量通道落到哪个后端最终由VectorStoreConfig.store_provider即StoreType说了算。6. 常见错误与排查结合源码中的校验与异常路径StoreType相关的典型报错有四类错误信息触发位置排查方向Unsupported store provider: xxxStoreType.fromValue配置字符串非四个合法小写值之一注意大小写与拼写unavailable vector store provider: elasticsearch, ...VectorStoreFactory.createVectorStore想用 Elasticsearch 时应改走StoreFactory/SPI 路径database_name must match ^[A-Za-z0-9_]*$VectorStoreConfig.setDatabaseName库名含-、.等非法字符distance_metric must be one of cosine, euclidean, dotVectorStoreConfig.setDistanceMetric距离度量只支持这三种取值7. 选型与参考资料选型上三个由VectorStoreFactory直连的后端对应不同部署形态Chroma 适合本地/轻量开发chroma_path指向本地目录即可Milvus 面向独立部署的向量数据库milvus_urimilvus_tokenPGVector 复用既有 PostgreSQL 实例pg_uri且支持传入PGVectorField对象精细控制向量列Elasticsearch 则通过 SPI 扩展接入适合已有 ES 集群的场景。相关 API 文档可继续参阅 StoreType.md、VectorStoreConfig.md 与 retrieval 包 README。验证本文结论的测试入口RetrievalCommonConfigTest.java、ConfigTest.java、StoreExtensionCompatibilityTest.java、MilvusIndexerTest.java、ChromaIndexerTest.java。适用前提本文基于当前仓库源码core 与 retrieval 模块配置字段与默认值以VectorStoreConfig、VectorStoreFactory的实际实现为准若你对照的是 API 文档中的旧枚举表仅三项或旧方法签名value()请以 StoreType.java 当前实现为准。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐agent-core-java 中 KnowledgeBaseConfig 知识库配置全解字段语义、校验规则与在检索链路中的落地agent core java 中 KnowledgeBaseConfig 知识库配置全解字段语义、校验规则与在检索链路中的落地 KnowledgeBaseC人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen agent-core-java 中 ControllerType 枚举详解控制器类型标识、JSON 序列化与运行时校验openJiuwen agent core java 中 ControllerType 枚举详解控制器类型标识、JSON 序列化与运行时校验 Controll人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen agent-core-java 记忆类型枚举 MemoryType 解析从枚举值到记忆引擎路由的完整指南openJiuwen agent core java 记忆类型枚举 MemoryType 解析从枚举值到记忆引擎路由的完整指南 com.openjiuwen.人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习上一篇cc-skills-golang 是什么42个Golang AI Agent技能完整解析为什么它能让AI写出少40%错误的Go代码下一篇拆解 Metapi 源码OpenAI⇄Claude 格式转换与 SSE 流式代理引擎是如何工作的创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考