人工智能AI AgentAgent 框架工具調(diào)用Agent 工作流RAGMCP Clients強(qiáng)化學(xué)習(xí)【免費(fèi)下載鏈接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent開發(fā)、運(yùn)行、調(diào)優(yōu)與演進(jìn)相關(guān)的全套SDK能力。項(xiàng)目地址https://gitcode.com/openJiuwen/agent-core-java點(diǎn)擊查看免費(fèi)下載PGVectorField是 openJiuwen agent-core JavaopenJiuwen Core 的 Java 版本中面向 PostgreSQL pgvector 后端的向量索引配置對(duì)象負(fù)責(zé)承載 HNSW / IVFFlat 索引的參數(shù)、向量字段名以及附加搜索選項(xiàng)。本文以該類的 API 文檔為主體結(jié)合倉(cāng)庫(kù)源碼與測(cè)試用例系統(tǒng)講解其字段語(yǔ)義、參數(shù)校驗(yàn)規(guī)則、按階段導(dǎo)出機(jī)制以及它在PGVectorStore檢索鏈路中的真實(shí)消費(fèi)方式。讀完本文你將掌握如何在知識(shí)庫(kù)檢索場(chǎng)景中為 pgvector 后端精確配置向量索引參數(shù)并理解這些參數(shù)最終如何落地為 PostgreSQL 的建表與建索引語(yǔ)句。一、類定位pgvector 后端的索引配置載體PGVectorField位于com.openjiuwen.core.foundation.store.vector_fields包是抽象基類 VectorField 的一個(gè)具體實(shí)現(xiàn)對(duì)應(yīng)文檔路徑 documents/zh/2.開發(fā)指南/API文檔/com.openjiuwen.core/foundation/store/vector_fields/PGVectorField.md。public class PGVectorField extends VectorField該類是 PGVector 索引配置對(duì)象與同一包下的ChromaVectorField、MilvusVectorField含MilvusHNSW、MilvusIVF、MilvusFLAT等平級(jí)共同構(gòu)成 vector_fields 中面向不同后端的向量索引配置對(duì)象體系。它的存在意義在于把 pgvector 索引的全部調(diào)優(yōu)參數(shù)集中在一個(gè)類型安全的 Java 對(duì)象里由上層檢索組件統(tǒng)一讀取并翻譯成后端 DDL。從源碼注釋可以看到該類鏡像了 Python 版本openjiuwen/core/foundation/store/vector_fields/pg_fields.py中的PGVectorField因此參數(shù)命名、默認(rèn)值與行為與 Python 側(cè)保持一致便于多語(yǔ)言 SDK 對(duì)齊。二、核心字段與默認(rèn)值文檔中定義了 8 個(gè)字段完整繼承如下字段類型默認(rèn)值說(shuō)明vectorFieldStringembedding向量字段名。indexTypeStringhnsw索引類型支持hnsw與ivfflat。mint16HNSW 鄰接參數(shù)。efConstructionint64構(gòu)建參數(shù)。efSearchint40搜索參數(shù)。listsint100IVF 列表數(shù)。probesint1IVF 探測(cè)數(shù)。extraSearchMapString, Object{}附加搜索參數(shù)。各字段語(yǔ)義補(bǔ)充說(shuō)明依據(jù) PGVectorField.java 源碼vectorField實(shí)際由基類 VectorField.java 持有默認(rèn)embedding。在PGVectorStore中它會(huì)被requireIdentifier校驗(yàn)后用作建表時(shí)的向量列名vector(dimension)列。vector_fields包的 README 也明確說(shuō)明默認(rèn)向量字段名統(tǒng)一為embedding除非調(diào)用方顯式覆蓋。indexTypehnsw與ivfflat二選一二者分別對(duì)應(yīng) pgvector 的兩類索引算法。默認(rèn)hnsw。m/efConstruction僅對(duì) HNSW 索引生效對(duì)應(yīng) pgvector 建索引語(yǔ)句WITH (m ..., ef_construction ...)中的參數(shù)。efSearchHNSW 索引查詢時(shí)的動(dòng)態(tài)搜索寬度對(duì)應(yīng)查詢階段參數(shù)。lists/probes僅對(duì) IVFFlat 索引生效lists對(duì)應(yīng)建索引時(shí)的分區(qū)數(shù)probes對(duì)應(yīng)查詢時(shí)探測(cè)的分區(qū)數(shù)。extraSearch附加搜索參數(shù)集合。從測(cè)試用例看實(shí)際可放入distance_metric如cosine、target_listsIVFFlat 查詢時(shí)的目標(biāo)列表數(shù)等鍵值在導(dǎo)出階段會(huì)被解包平鋪。三、公開方法 API文檔公開方法表完整繼承如下簽名說(shuō)明public String getDatabaseType()返回?cái)?shù)據(jù)庫(kù)類型pg。public String getIndexType()返回索引類型。public void setIndexType(String indexType)設(shè)置索引類型。public int getM()返回m。public void setM(int m)設(shè)置m。public int getEfConstruction()返回構(gòu)建參數(shù)。public void setEfConstruction(int efConstruction)設(shè)置構(gòu)建參數(shù)。public int getEfSearch()返回搜索參數(shù)。public void setEfSearch(int efSearch)設(shè)置搜索參數(shù)。public int getLists()返回lists。public void setLists(int lists)設(shè)置lists。public int getProbes()返回probes。public MapString, Object getExtraSearch()返回附加搜索參數(shù)。public void setExtraSearch(MapString, Object extraSearch)設(shè)置附加搜索參數(shù)。public MapString, Object toDict(String stage)按階段導(dǎo)出參數(shù)。其中g(shù)etDatabaseType()是基類聲明的抽象方法PGVectorField固定返回字符串pg這是該配置對(duì)象被識(shí)別為 pgvector 后端的標(biāo)識(shí)。四、參數(shù)校驗(yàn)規(guī)則源碼級(jí)約束與普通 POJO 不同PGVectorField的每個(gè) setter 都內(nèi)置了防御性校驗(yàn)非法值會(huì)直接拋出IllegalArgumentException。依據(jù) PGVectorField.java 源碼整理如下設(shè)置方法校驗(yàn)規(guī)則違規(guī)提示setIndexType僅允許hnsw、ivfflatindexType must be one of: hnsw, ivfflatsetMm必須在[2, 2000]區(qū)間m must be in range [2, 2000]setEfConstructionefConstruction 1efConstruction must be 1setEfSearchefSearch 1efSearch must be 1setListslists 1lists must be 1setProbesprobes 1probes must be 1這些校驗(yàn)規(guī)則與單元測(cè)試 PGVectorFieldTest.java 一一對(duì)應(yīng)測(cè)試validatorsRejectOutOfRangeValues分別對(duì)setIndexType(flat)、setM(1)、setEfConstruction(0)、setEfSearch(0)、setLists(0)、setProbes(0)斷言拋出含對(duì)應(yīng)參數(shù)名的IllegalArgumentException。因此在實(shí)際編碼時(shí)應(yīng)優(yōu)先通過(guò) setter 賦值以盡早暴露配置錯(cuò)誤。此外getExtraSearch()返回的是內(nèi)部LinkedHashMap的副本防御性拷貝setExtraSearch也會(huì)對(duì)入?yún)⒆隹截惗侵苯映钟幸帽苊馔獠考媳灰馔夤蚕硇薷倪@一細(xì)節(jié)保證了配置對(duì)象在并發(fā)或復(fù)用場(chǎng)景下的安全隔離。五、按階段導(dǎo)出機(jī)制toDict(stage) 的兩種形態(tài)toDict(String stage)是VectorField基類聲明的抽象方法其設(shè)計(jì)意圖在 vector_fields 包 README 中有明確說(shuō)明toDict(String stage)一般按construct與search兩個(gè)階段輸出后端參數(shù)。兩個(gè)階段常量定義在基類 VectorField.javaSTAGE_CONSTRUCT construct建索引階段STAGE_SEARCH search查詢階段。PGVectorField對(duì)兩個(gè)階段的導(dǎo)出內(nèi)容如下來(lái)自 PGVectorField.java 的toDict實(shí)現(xiàn)階段導(dǎo)出的鍵constructindex_type、m、ef_construction、listssearchef_search、probes、extra_search導(dǎo)出后基類finalizeDict還會(huì)做一層后處理移除database_type、index_type、vector_field、variant等標(biāo)識(shí)性鍵把extra_{stage}中的鍵值對(duì)解包平鋪到結(jié)果 Map 頂層例如extra_search中的distance_metric、target_lists直接成為結(jié)果鍵剔除值為null的條目。由此實(shí)現(xiàn)了構(gòu)造參數(shù)與搜索參數(shù)的物理隔離——建索引時(shí)只關(guān)心m/ef_construction/lists查詢時(shí)只關(guān)心ef_search/probes/附加參數(shù)。測(cè)試constructStageExportsOnlyPgBuildParameters驗(yàn)證了默認(rèn)配置在 construct 階段僅導(dǎo)出{m16, ef_construction64, lists100}index_type被剝離測(cè)試searchStageExportsSearchParametersAndUnpacksExtraSearch則驗(yàn)證在設(shè)置extraSearch為{distance_metric: cosine, target_lists: 8}后search 階段導(dǎo)出{ef_search40, probes1, distance_metriccosine, target_lists8}附加參數(shù)確實(shí)被解包。六、在檢索鏈路中的實(shí)際消費(fèi)PGVectorStore 與 VectorStoreFactoryPGVectorField并不是一個(gè)孤立的配置類它在知識(shí)庫(kù)檢索鏈路中扮演關(guān)鍵角色。6.1 PGVectorStore 如何消費(fèi)配置PGVectorStore.java 是使用 pgvector 的向量存儲(chǔ)實(shí)現(xiàn)鏡像 Python 的PGVectorStore它持有PGVectorField vectorFieldConfig成員并在建表/建索引時(shí)直接讀取配置構(gòu)造時(shí)通過(guò)vectorFieldConfig.getVectorField()得到向量列名經(jīng)requireIdentifier校驗(yàn)后作為建表列名vector(dimension)列g(shù)etOrCreateTable中先執(zhí)行CREATE EXTENSION IF NOT EXISTS vector創(chuàng)建擴(kuò)展再執(zhí)行CREATE TABLE IF NOT EXISTS建表當(dāng)indexType為hnsw時(shí)追加執(zhí)行 HNSW 索引語(yǔ)句m與ef_construction被直接拼入WITH (m ..., ef_construction ...)子句ivfflat類型則不會(huì)自動(dòng)建索引從getOrCreateTable的分支邏輯可以推斷IVFFlat 場(chǎng)景需要調(diào)用方按需自行處理向量維度上限為 2000超過(guò)時(shí)拋出RETRIEVAL_KB_DATABASE_CONFIG_INVALID錯(cuò)誤提示pgvector only supports vector dimensions up to 2000距離度量cosine/euclidean/dot決定 SQL 中使用的操作符、-、#與索引操作符類vector_cosine_ops、vector_l2_ops、vector_ip_ops。對(duì)應(yīng)測(cè)試 PGVectorStoreTest.java 中addBootstrapsTableAndBatchesUpserts驗(yàn)證了建表過(guò)程中依次執(zhí)行CREATE EXTENSION IF NOT EXISTS vector、CREATE TABLE IF NOT EXISTS與USING hnsw三類 DDL且批量寫入按 batchSize 分批提交。6.2 通過(guò) VectorStoreFactory 接入VectorStoreFactory.java 的createVectorStore根據(jù) VectorStoreConfig.java 中的storeProvider分發(fā)當(dāng)為 StoreType.java 中的PGVECTOR(pgvector)時(shí)走createPgVectorStore此時(shí)若 kwargs 中vector_field傳入的是PGVectorField實(shí)例則直接以其構(gòu)造PGVectorStore否則按字符串向量字段名構(gòu)造默認(rèn)配置。測(cè)試 VectorStoreFactoryTest.java 驗(yàn)證了將PGVectorFieldsetVectorField(embedding_vec)作為vector_field傳入后返回的PGVectorStore能正確讀取embedding_vec作為向量列名。VectorStoreConfig中與 pgvector 場(chǎng)景相關(guān)的頂層配置包括storeProvider必填、databaseName匹配^[A-Za-z0-9_]*$、collectionName必填、distanceMetric取值cosine、euclidean、dot默認(rèn)cosine。6.3 默認(rèn) schema 輔助包內(nèi)工具類 PgFields.java 提供defaultSchema(int dimension)內(nèi)部委托 BaseVectorFields.java 生成 pgvector 兼容的默認(rèn) CollectionSchema包含id主鍵 VARCHAR、embeddingFLOAT_VECTOR維度由調(diào)用方指定、textVARCHAR 65535、metadataJSON四個(gè)字段與PGVectorStore的建表結(jié)構(gòu)id、text、metadata、vector 列保持一致。七、實(shí)戰(zhàn)示例配置 pgvector 向量索引綜合以上內(nèi)容一個(gè)典型的 pgvector 檢索接入流程如下示例代碼基于源碼構(gòu)造方式與測(cè)試用例整理實(shí)際運(yùn)行時(shí)需自行管理 DataSource 與連接配置// 1. 配置頂層向量庫(kù)參數(shù) VectorStoreConfig config VectorStoreConfig.builder() .storeProvider(StoreType.PGVECTOR) .databaseName(kb_db) .collectionName(kb_chunks) .distanceMetric(cosine) // cosine / euclidean / dot .build(); // 2. 定制 PGVectorField 索引參數(shù) PGVectorField field new PGVectorField(); field.setVectorField(embedding); // 向量列名默認(rèn)即可 field.setIndexType(hnsw); // 或 ivfflat field.setM(16); // HNSW 鄰接參數(shù)范圍 [2, 2000] field.setEfConstruction(64); // 構(gòu)建參數(shù) 1 field.setEfSearch(40); // 搜索參數(shù) 1 field.setLists(100); // IVFFlat 列表數(shù) 1 field.setProbes(1); // IVFFlat 探測(cè)數(shù) 1 MapString, Object extra new LinkedHashMap(); extra.put(distance_metric, cosine); // 附加搜索參數(shù) extra.put(target_lists, 8); field.setExtraSearch(extra); // 3. 通過(guò)工廠創(chuàng)建 pgvector 存儲(chǔ) MapString, Object kwargs new LinkedHashMap(); kwargs.put(pg_uri, postgresqlasyncpg://user:passlocalhost/db); kwargs.put(vector_field, field); // 傳入 PGVectorField 實(shí)例 VectorStore store VectorStoreFactory.createVectorStore(config, kwargs); // 4. 階段導(dǎo)出驗(yàn)證可選調(diào)試 MapString, Object constructParams field.toDict(VectorField.STAGE_CONSTRUCT); MapString, Object searchParams field.toDict(VectorField.STAGE_SEARCH);寫入數(shù)據(jù)時(shí)PGVectorStore會(huì)根據(jù)首條數(shù)據(jù)推斷向量維度自動(dòng)完成建表與 HNSW 索引創(chuàng)建隨后按默認(rèn) 128 的批大小分批 upsert查詢時(shí)則使用ef_search、probes與解包后的附加搜索參數(shù)。整個(gè)流程中PGVectorField提供的校驗(yàn)與分階段導(dǎo)出能力保證了索引參數(shù)在構(gòu)建與搜索兩個(gè)生命周期中各司其職。八、小結(jié)PGVectorField是 openJiuwen agent-core Java 中 pgvector 后端向量索引配置的唯一入口8 個(gè)字段覆蓋 HNSWm、efConstruction、efSearch與 IVFFlatlists、probes兩類索引的全部核心調(diào)優(yōu)參數(shù)默認(rèn)值開箱即用setter 級(jí)參數(shù)校驗(yàn)在配置階段攔截非法值配合 PGVectorFieldTest.java 可驗(yàn)證邊界行為toDict(stage)兩階段導(dǎo)出把構(gòu)建參數(shù)與搜索參數(shù)物理隔離并通過(guò)extraSearch解包機(jī)制支持distance_metric、target_lists等附加選項(xiàng)在 PGVectorStore.java 與 VectorStoreFactory.java 中它被直接翻譯為 PostgreSQL 的CREATE EXTENSION、CREATE TABLE與USING hnswDDL是連接 Java 配置層與 pgvector 后端的橋梁。如需進(jìn)一步了解同體系的 Milvus / Chroma 索引配置可參閱 vector_fields.README.md。贊分享人工智能AI AgentAgent 框架工具調(diào)用Agent 工作流RAGMCP Clients強(qiáng)化學(xué)習(xí)【免費(fèi)下載鏈接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent開發(fā)、運(yùn)行、調(diào)優(yōu)與演進(jìn)相關(guān)的全套SDK能力。項(xiàng)目地址https://gitcode.com/openJiuwen/agent-core-java點(diǎn)擊查看免費(fèi)下載相關(guān)推薦openJiuwen agent-core-java 向量索引配置指南vector_fields 包的類體系與雙階段參數(shù)導(dǎo)出機(jī)制openJiuwen agent core java 向量索引配置指南vector_fields 包的類體系與雙階段參數(shù)導(dǎo)出機(jī)制 com.openjiuwen人工智能AI AgentAgent 框架工具調(diào)用Agent 工作流RAGMCP Clients強(qiáng)化學(xué)習(xí)openJiuwen agent-core 向量字段索引配置指南vector_fields 模塊深度解析openJiuwen agent core 向量字段索引配置指南vector_fields 模塊深度解析 openjiuwen.core.foundation人工智能AI AgentAgent 框架大模型工具調(diào)用RAG提示工程強(qiáng)化學(xué)習(xí)openJiuwen agent-core Milvus 向量索引配置指南從 FLAT 到 HNSW 的 vector_fields 全解析openJiuwen agent core Milvus 向量索引配置指南從 FLAT 到 HNSW 的 vector_fields 全解析 導(dǎo)讀 本文聚焦于人工智能AI AgentAgent 框架大模型工具調(diào)用RAG提示工程強(qiáng)化學(xué)習(xí)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考