人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载PGVectorField是 openJiuwen agent-core JavaopenJiuwen Core 的 Java 版本中面向 PostgreSQL pgvector 后端的向量索引配置对象负责承载 HNSW / IVFFlat 索引的参数、向量字段名以及附加搜索选项。本文以该类的 API 文档为主体结合仓库源码与测试用例系统讲解其字段语义、参数校验规则、按阶段导出机制以及它在PGVectorStore检索链路中的真实消费方式。读完本文你将掌握如何在知识库检索场景中为 pgvector 后端精确配置向量索引参数并理解这些参数最终如何落地为 PostgreSQL 的建表与建索引语句。一、类定位pgvector 后端的索引配置载体PGVectorField位于com.openjiuwen.core.foundation.store.vector_fields包是抽象基类 VectorField 的一个具体实现对应文档路径 documents/zh/2.开发指南/API文档/com.openjiuwen.core/foundation/store/vector_fields/PGVectorField.md。public class PGVectorField extends VectorField该类是 PGVector 索引配置对象与同一包下的ChromaVectorField、MilvusVectorField含MilvusHNSW、MilvusIVF、MilvusFLAT等平级共同构成 vector_fields 中面向不同后端的向量索引配置对象体系。它的存在意义在于把 pgvector 索引的全部调优参数集中在一个类型安全的 Java 对象里由上层检索组件统一读取并翻译成后端 DDL。从源码注释可以看到该类镜像了 Python 版本openjiuwen/core/foundation/store/vector_fields/pg_fields.py中的PGVectorField因此参数命名、默认值与行为与 Python 侧保持一致便于多语言 SDK 对齐。二、核心字段与默认值文档中定义了 8 个字段完整继承如下字段类型默认值说明vectorFieldStringembedding向量字段名。indexTypeStringhnsw索引类型支持hnsw与ivfflat。mint16HNSW 邻接参数。efConstructionint64构建参数。efSearchint40搜索参数。listsint100IVF 列表数。probesint1IVF 探测数。extraSearchMapString, Object{}附加搜索参数。各字段语义补充说明依据 PGVectorField.java 源码vectorField实际由基类 VectorField.java 持有默认embedding。在PGVectorStore中它会被requireIdentifier校验后用作建表时的向量列名vector(dimension)列。vector_fields包的 README 也明确说明默认向量字段名统一为embedding除非调用方显式覆盖。indexTypehnsw与ivfflat二选一二者分别对应 pgvector 的两类索引算法。默认hnsw。m/efConstruction仅对 HNSW 索引生效对应 pgvector 建索引语句WITH (m ..., ef_construction ...)中的参数。efSearchHNSW 索引查询时的动态搜索宽度对应查询阶段参数。lists/probes仅对 IVFFlat 索引生效lists对应建索引时的分区数probes对应查询时探测的分区数。extraSearch附加搜索参数集合。从测试用例看实际可放入distance_metric如cosine、target_listsIVFFlat 查询时的目标列表数等键值在导出阶段会被解包平铺。三、公开方法 API文档公开方法表完整继承如下签名说明public String getDatabaseType()返回数据库类型pg。public String getIndexType()返回索引类型。public void setIndexType(String indexType)设置索引类型。public int getM()返回m。public void setM(int m)设置m。public int getEfConstruction()返回构建参数。public void setEfConstruction(int efConstruction)设置构建参数。public int getEfSearch()返回搜索参数。public void setEfSearch(int efSearch)设置搜索参数。public int getLists()返回lists。public void setLists(int lists)设置lists。public int getProbes()返回probes。public MapString, Object getExtraSearch()返回附加搜索参数。public void setExtraSearch(MapString, Object extraSearch)设置附加搜索参数。public MapString, Object toDict(String stage)按阶段导出参数。其中getDatabaseType()是基类声明的抽象方法PGVectorField固定返回字符串pg这是该配置对象被识别为 pgvector 后端的标识。四、参数校验规则源码级约束与普通 POJO 不同PGVectorField的每个 setter 都内置了防御性校验非法值会直接抛出IllegalArgumentException。依据 PGVectorField.java 源码整理如下设置方法校验规则违规提示setIndexType仅允许hnsw、ivfflatindexType must be one of: hnsw, ivfflatsetMm必须在[2, 2000]区间m must be in range [2, 2000]setEfConstructionefConstruction 1efConstruction must be 1setEfSearchefSearch 1efSearch must be 1setListslists 1lists must be 1setProbesprobes 1probes must be 1这些校验规则与单元测试 PGVectorFieldTest.java 一一对应测试validatorsRejectOutOfRangeValues分别对setIndexType(flat)、setM(1)、setEfConstruction(0)、setEfSearch(0)、setLists(0)、setProbes(0)断言抛出含对应参数名的IllegalArgumentException。因此在实际编码时应优先通过 setter 赋值以尽早暴露配置错误。此外getExtraSearch()返回的是内部LinkedHashMap的副本防御性拷贝setExtraSearch也会对入参做拷贝而非直接持有引用避免外部集合被意外共享修改这一细节保证了配置对象在并发或复用场景下的安全隔离。五、按阶段导出机制toDict(stage) 的两种形态toDict(String stage)是VectorField基类声明的抽象方法其设计意图在 vector_fields 包 README 中有明确说明toDict(String stage)一般按construct与search两个阶段输出后端参数。两个阶段常量定义在基类 VectorField.javaSTAGE_CONSTRUCT construct建索引阶段STAGE_SEARCH search查询阶段。PGVectorField对两个阶段的导出内容如下来自 PGVectorField.java 的toDict实现阶段导出的键constructindex_type、m、ef_construction、listssearchef_search、probes、extra_search导出后基类finalizeDict还会做一层后处理移除database_type、index_type、vector_field、variant等标识性键把extra_{stage}中的键值对解包平铺到结果 Map 顶层例如extra_search中的distance_metric、target_lists直接成为结果键剔除值为null的条目。由此实现了构造参数与搜索参数的物理隔离——建索引时只关心m/ef_construction/lists查询时只关心ef_search/probes/附加参数。测试constructStageExportsOnlyPgBuildParameters验证了默认配置在 construct 阶段仅导出{m16, ef_construction64, lists100}index_type被剥离测试searchStageExportsSearchParametersAndUnpacksExtraSearch则验证在设置extraSearch为{distance_metric: cosine, target_lists: 8}后search 阶段导出{ef_search40, probes1, distance_metriccosine, target_lists8}附加参数确实被解包。六、在检索链路中的实际消费PGVectorStore 与 VectorStoreFactoryPGVectorField并不是一个孤立的配置类它在知识库检索链路中扮演关键角色。6.1 PGVectorStore 如何消费配置PGVectorStore.java 是使用 pgvector 的向量存储实现镜像 Python 的PGVectorStore它持有PGVectorField vectorFieldConfig成员并在建表/建索引时直接读取配置构造时通过vectorFieldConfig.getVectorField()得到向量列名经requireIdentifier校验后作为建表列名vector(dimension)列getOrCreateTable中先执行CREATE EXTENSION IF NOT EXISTS vector创建扩展再执行CREATE TABLE IF NOT EXISTS建表当indexType为hnsw时追加执行 HNSW 索引语句m与ef_construction被直接拼入WITH (m ..., ef_construction ...)子句ivfflat类型则不会自动建索引从getOrCreateTable的分支逻辑可以推断IVFFlat 场景需要调用方按需自行处理向量维度上限为 2000超过时抛出RETRIEVAL_KB_DATABASE_CONFIG_INVALID错误提示pgvector only supports vector dimensions up to 2000距离度量cosine/euclidean/dot决定 SQL 中使用的操作符、-、#与索引操作符类vector_cosine_ops、vector_l2_ops、vector_ip_ops。对应测试 PGVectorStoreTest.java 中addBootstrapsTableAndBatchesUpserts验证了建表过程中依次执行CREATE EXTENSION IF NOT EXISTS vector、CREATE TABLE IF NOT EXISTS与USING hnsw三类 DDL且批量写入按 batchSize 分批提交。6.2 通过 VectorStoreFactory 接入VectorStoreFactory.java 的createVectorStore根据 VectorStoreConfig.java 中的storeProvider分发当为 StoreType.java 中的PGVECTOR(pgvector)时走createPgVectorStore此时若 kwargs 中vector_field传入的是PGVectorField实例则直接以其构造PGVectorStore否则按字符串向量字段名构造默认配置。测试 VectorStoreFactoryTest.java 验证了将PGVectorFieldsetVectorField(embedding_vec)作为vector_field传入后返回的PGVectorStore能正确读取embedding_vec作为向量列名。VectorStoreConfig中与 pgvector 场景相关的顶层配置包括storeProvider必填、databaseName匹配^[A-Za-z0-9_]*$、collectionName必填、distanceMetric取值cosine、euclidean、dot默认cosine。6.3 默认 schema 辅助包内工具类 PgFields.java 提供defaultSchema(int dimension)内部委托 BaseVectorFields.java 生成 pgvector 兼容的默认 CollectionSchema包含id主键 VARCHAR、embeddingFLOAT_VECTOR维度由调用方指定、textVARCHAR 65535、metadataJSON四个字段与PGVectorStore的建表结构id、text、metadata、vector 列保持一致。七、实战示例配置 pgvector 向量索引综合以上内容一个典型的 pgvector 检索接入流程如下示例代码基于源码构造方式与测试用例整理实际运行时需自行管理 DataSource 与连接配置// 1. 配置顶层向量库参数 VectorStoreConfig config VectorStoreConfig.builder() .storeProvider(StoreType.PGVECTOR) .databaseName(kb_db) .collectionName(kb_chunks) .distanceMetric(cosine) // cosine / euclidean / dot .build(); // 2. 定制 PGVectorField 索引参数 PGVectorField field new PGVectorField(); field.setVectorField(embedding); // 向量列名默认即可 field.setIndexType(hnsw); // 或 ivfflat field.setM(16); // HNSW 邻接参数范围 [2, 2000] field.setEfConstruction(64); // 构建参数 1 field.setEfSearch(40); // 搜索参数 1 field.setLists(100); // IVFFlat 列表数 1 field.setProbes(1); // IVFFlat 探测数 1 MapString, Object extra new LinkedHashMap(); extra.put(distance_metric, cosine); // 附加搜索参数 extra.put(target_lists, 8); field.setExtraSearch(extra); // 3. 通过工厂创建 pgvector 存储 MapString, Object kwargs new LinkedHashMap(); kwargs.put(pg_uri, postgresqlasyncpg://user:passlocalhost/db); kwargs.put(vector_field, field); // 传入 PGVectorField 实例 VectorStore store VectorStoreFactory.createVectorStore(config, kwargs); // 4. 阶段导出验证可选调试 MapString, Object constructParams field.toDict(VectorField.STAGE_CONSTRUCT); MapString, Object searchParams field.toDict(VectorField.STAGE_SEARCH);写入数据时PGVectorStore会根据首条数据推断向量维度自动完成建表与 HNSW 索引创建随后按默认 128 的批大小分批 upsert查询时则使用ef_search、probes与解包后的附加搜索参数。整个流程中PGVectorField提供的校验与分阶段导出能力保证了索引参数在构建与搜索两个生命周期中各司其职。八、小结PGVectorField是 openJiuwen agent-core Java 中 pgvector 后端向量索引配置的唯一入口8 个字段覆盖 HNSWm、efConstruction、efSearch与 IVFFlatlists、probes两类索引的全部核心调优参数默认值开箱即用setter 级参数校验在配置阶段拦截非法值配合 PGVectorFieldTest.java 可验证边界行为toDict(stage)两阶段导出把构建参数与搜索参数物理隔离并通过extraSearch解包机制支持distance_metric、target_lists等附加选项在 PGVectorStore.java 与 VectorStoreFactory.java 中它被直接翻译为 PostgreSQL 的CREATE EXTENSION、CREATE TABLE与USING hnswDDL是连接 Java 配置层与 pgvector 后端的桥梁。如需进一步了解同体系的 Milvus / Chroma 索引配置可参阅 vector_fields.README.md。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐openJiuwen agent-core-java 向量索引配置指南vector_fields 包的类体系与双阶段参数导出机制openJiuwen agent core java 向量索引配置指南vector_fields 包的类体系与双阶段参数导出机制 com.openjiuwen人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen agent-core 向量字段索引配置指南vector_fields 模块深度解析openJiuwen agent core 向量字段索引配置指南vector_fields 模块深度解析 openjiuwen.core.foundation人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core Milvus 向量索引配置指南从 FLAT 到 HNSW 的 vector_fields 全解析openJiuwen agent core Milvus 向量索引配置指南从 FLAT 到 HNSW 的 vector_fields 全解析 导读 本文聚焦于人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考