• 人工智能
• AI Agent
• Agent 框架
• 工具调用
• Agent 工作流
• RAG
• MCP Clients
• 强化学习

在 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 枚举值与底层字符串值

需要说明两点与 API 文档的差异（以当前仓库源码为准）：

• API 文档的枚举值表仅列出MILVUS/CHROMA/PGVECTOR三项，而当前源码中已包含第四项ELASTICSEARCH，它是通过 SPI 扩展层接入的提供方（见 ElasticsearchVectorStoreProvider.java，typeName()返回"elasticsearch"）；
• API 文档将取值方法写作public String value()，当前源码中的实际签名为public String getValue()，并带有@JsonValue注解（见 StoreType.java）。

1.2 两个核心方法

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_provider

StoreType并不是孤立存在的，它最主要的消费方是同包的 VectorStoreConfig.java（API 文档见 VectorStoreConfig.md）。该类持有四个字段：

其中storeProvider字段标注@JsonProperty("store_provider")，并且 setter 直接走枚举解析（见 VectorStoreConfig.java）：

public 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.java），storeProvider同时接受枚举与字符串两种入参：

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, Map<String, Object> kwargs)读取config.getStoreProvider()后按枚举常量分支：

三个后端的具体实现类分别位于 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, Map<String, Object> options)，按字符串类型名创建BaseVectorStore，并委托给 SPI 工厂；
• SPI 的具体实现通过 Java ServiceLoader 机制注册，服务文件 com.openjiuwen.spi.store.vector.VectorStoreProvider 内置了四个 provider：ChromaVectorStoreProvider、MilvusVectorStoreProvider、PGVectorStoreProvider、ElasticsearchVectorStoreProvider；
• VectorStoreRegistry.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现场重建一份VectorStoreConfig（collection 名缺省兜底"default"、距离度量缺省兜底"cosine"）来构造MilvusIndexer；其余向量库实例则统一回退为InMemoryIndexer。这说明 Milvus 是唯一拥有独立 Indexer 实现的提供方，其余后端的索引维护由内存侧承担；
• 知识库层的 KnowledgeBaseConfig.java 通过index_type（hybrid/bm25/vector，默认hybrid）决定检索模式。结合 retrieval.README.md 的说明，SimpleKnowledgeBase会据此在向量、BM25 与混合检索间自动选择——而向量通道落到哪个后端，最终由VectorStoreConfig.store_provider（即StoreType）说了算。

6. 常见错误与排查

结合源码中的校验与异常路径，StoreType相关的典型报错有四类：

7. 选型与参考资料

• 选型上，三个由VectorStoreFactory直连的后端对应不同部署形态：Chroma 适合本地/轻量开发（chroma_path指向本地目录即可），Milvus 面向独立部署的向量数据库（milvus_uri+milvus_token），PGVector 复用既有 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 Agent
• Agent 框架
• 工具调用
• Agent 工作流
• RAG
• MCP Clients
• 强化学习