現(xiàn)語義搜索：文檔智能檢索全鏈路實(shí)戰(zhàn))
在AI應(yīng)用和知識(shí)庫項(xiàng)目里摸爬滾打了一段時(shí)間后我越來越確認(rèn)一個(gè)事情傳統(tǒng)的數(shù)據(jù)庫檢索方式在面對(duì)語義搜索和文檔智能問答這類需求時(shí)是真的不夠用。你光靠關(guān)鍵詞匹配和SQL的LIKE查詢永遠(yuǎn)解決不了用戶搜蘋果但文檔里寫的是iPhone這種級(jí)別的語義問題。于是我把目光投向了向量數(shù)據(jù)庫。之前網(wǎng)上搜資料90%的教程都是Python示例Java的完整實(shí)踐案例少得可憐而且很多Demo代碼根本跑不通。這篇就把我踩過坑、填過土之后的完整方案寫出來講清楚Java怎么接向量數(shù)據(jù)庫、文檔怎么切分、向量怎么生成、檢索怎么實(shí)現(xiàn)以及一系列工程化細(xì)節(jié)。項(xiàng)目核心是解決文檔檢索與語義搜索這個(gè)場景適合正在搞RAG、智能客服、企業(yè)知識(shí)庫的后端Java開發(fā)同學(xué)直接參考。1. 項(xiàng)目整體思路為什么Java后端需要一個(gè)向量層1.1 從關(guān)鍵詞匹配到語義檢索差的不是算法而是數(shù)據(jù)組織方式先講個(gè)背景。我之前在做一個(gè)企業(yè)合同知識(shí)庫倉庫里有幾百份PDF和Word文檔。業(yè)務(wù)方的需求很樸素員工輸入去年和華為簽的采購合同里違約金比例是多少系統(tǒng)要快速給出答案。用傳統(tǒng)的ES方案我只能做分詞和倒排索引。違約金比例這種詞如果合同原文寫的是違約賠償金那ES的精確分詞基本就廢了搜出來一堆不相關(guān)的東西。要想讓系統(tǒng)懂語義核心思路是把文本變成高維向量然后在向量空間里計(jì)算距離和相似度。蘋果和iPhone這兩個(gè)詞的文本形式差了十萬八千里但它們的語義向量在空間里距離很近。這個(gè)能力不是靠算法而是靠預(yù)訓(xùn)練的Embedding模型和海量語料訓(xùn)練得到的。向量數(shù)據(jù)庫干的事情就是把生成后的向量存起來并提供高效的近鄰檢索能力也就是ANNApproximate Nearest Neighbor。所以這個(gè)項(xiàng)目的架構(gòu)其實(shí)很清晰文檔進(jìn)來之后先做切割切出來的每一段文本都過一遍Embedding模型生成一個(gè)幾百維的Float數(shù)組然后連同原文和元數(shù)據(jù)一起寫入向量數(shù)據(jù)庫。查詢的時(shí)候用戶的問題同樣過一遍Embedding模型再拿這個(gè)查詢向量去庫里做相似度搜索取TopK結(jié)果返回。整個(gè)過程Java這邊全程參與不依賴任何Python微服務(wù)這也是這個(gè)項(xiàng)目最有價(jià)值的地方。1.2 技術(shù)棧選型與整體架構(gòu)這個(gè)項(xiàng)目我用了Spring Boot 3.x Java 17作為基礎(chǔ)后端框架向量數(shù)據(jù)庫選了Milvus向量化模型選用本地部署的ONNX格式中文Embedding模型。之所以不選在線API是因?yàn)槠髽I(yè)級(jí)知識(shí)庫對(duì)數(shù)據(jù)出域很敏感合同、醫(yī)療、客服對(duì)話這類數(shù)據(jù)不適合直接提交給第三方API做詞向量轉(zhuǎn)換。本地化部署雖然要花一些時(shí)間配置環(huán)境但數(shù)據(jù)安全性可控而且調(diào)用延遲更低QPS起來了之后在線API的成本會(huì)很高本地模型更劃算。整體流程分兩條鏈路。寫入鏈路解析文檔 - 清洗文本 - 文檔切分 - 生成向量 - 寫入Milvus。查詢鏈路接收用戶問題 - 生成查詢向量 - Milvus向量檢索 - 按元數(shù)據(jù)過濾 - 結(jié)果重排 - 返回給上層業(yè)務(wù)。這兩條鏈路在Java服務(wù)內(nèi)完全閉環(huán)Milvus只負(fù)責(zé)當(dāng)向量存儲(chǔ)和檢索引擎不承擔(dān)任何業(yè)務(wù)邏輯。2. 向量數(shù)據(jù)庫選型Java生態(tài)里最務(wù)實(shí)的幾個(gè)選項(xiàng)2.1 主流向量數(shù)據(jù)庫橫向?qū)Ρ葦?shù)據(jù)庫部署復(fù)雜度Java SDK成熟度混合檢索支持適用場景Milvus中依賴K8s或Docker官方Java SDK接口完整支持Meta過濾大規(guī)模向量檢索、RAG專用Elasticsearch中自帶集群能力原生Java客戶端完善全文檢索向量已有ES需要兼顧全文搜索Redis低官方Java客戶端很成熟較弱小規(guī)模原型驗(yàn)證、緩存場景PostgreSQL pgvector低JDBC即可一般SQL靈活已有PG業(yè)務(wù)需要統(tǒng)一存儲(chǔ)我最終選擇了Milvus主要原因有三點(diǎn)。第一它是純正的向量數(shù)據(jù)庫對(duì)ANN算法、內(nèi)存索引、分片策略的優(yōu)化非常深入單機(jī)集群模式下千萬級(jí)向量檢索的延遲都能壓在100毫秒左右。第二它的Java SDK不是社區(qū)熱情產(chǎn)物而是官方維護(hù)的milvus-sdk-java接口設(shè)計(jì)思路和REST API差不多用起來比較順手。第三它支持標(biāo)量字段過濾我可以把合同ID、文檔分類、上傳時(shí)間這些業(yè)務(wù)屬性存成標(biāo)量字段檢索時(shí)先過濾再搜大幅縮小向量搜索范圍實(shí)用性非常強(qiáng)。2.2 為什么沒選Elasticsearch和RedisES其實(shí)是很多團(tuán)隊(duì)的第一直覺畢竟大部分后端項(xiàng)目里ES已經(jīng)在了再復(fù)用豈不是省事。但我在對(duì)比測試中發(fā)現(xiàn)了問題ES的向量檢索kNN search在數(shù)據(jù)量超過百萬級(jí)之后性能曲線下降得很明顯而且ES的內(nèi)存存儲(chǔ)結(jié)構(gòu)不如Milvus這種為向量設(shè)計(jì)的系統(tǒng)高效。另外一個(gè)問題是ES的向量能力在開源版本中支持得不夠靈活一些高級(jí)參數(shù)如efConstruction、M需要配置深度調(diào)優(yōu)對(duì)普通業(yè)務(wù)開發(fā)者來說門檻偏高。當(dāng)然如果你的項(xiàng)目本身已經(jīng)重度使用ES做全文檢索而且數(shù)據(jù)量不大直接升級(jí)版本用ES的向量檢索能力也完全合理這屬于已有基礎(chǔ)設(shè)施優(yōu)先的策略。Redis做過一輪測試結(jié)論是僅適合Demo階段或幾百條數(shù)據(jù)的在線測試原因是它的向量模塊是基于內(nèi)存哈希結(jié)構(gòu)的簡單實(shí)現(xiàn)沒有Milvus那樣完善的索引和分段存儲(chǔ)機(jī)制查詢延遲雖然低但召回率不穩(wěn)定。我在本地用一萬條隨機(jī)向量測過Redis的搜索召回率在80%左右Milvus在90%以上差距還是很明顯的。3. 環(huán)境準(zhǔn)備Milvus部署與Java工程搭建3.1 Docker方式快速部署Milvus Standalone很多教程一上來就推薦Milvus集群模式需要部署etcd、Pulsar、MinIO等一大堆組件直接把新人嚇退。其實(shí)單機(jī)環(huán)境或者測試環(huán)境用Standalone模式就足夠了Docker Compose一條命令就能把Milvus跑起來。我本地開發(fā)環(huán)境的docker-compose.yml關(guān)鍵部分是這樣寫的version: 3.5 services: etcd: image: quay.io/coreos/etcd:v3.5.5 environment: - ETCD_AUTO_COMPACTION_MODErevision - ETCD_AUTO_COMPACTION_RETENTION1000 - ETCD_QUOTA_BACKEND_BYTES4294967296 - ETCD_SNAPSHOT_COUNT50000 command: etcd -advertise-client-urlshttp://127.0.0.1:2379 -listen-client-urlshttp://0.0.0.0:2379 minio: image: minio/minio:RELEASE.2023-03-20T20-16-18Z environment: MINIO_ACCESS_KEY: minioadmin MINIO_SECRET_KEY: minioadmin command: minio server /minio_data --console-address :9001 milvus: image: milvusdb/milvus:v2.3.4 command: [milvus, run, standalone] environment: ETCD_ENDPOINTS: etcd:2379 MINIO_ADDRESS: minio:9000 ports: - 19530:19530 - 9091:9091 depends_on: - etcd - minio跑起來之后Milvus默認(rèn)監(jiān)聽19530端口這就是gRPC通信的入口。Java SDK連接的就是這個(gè)端口。這里我踩過一個(gè)大坑Docker Desktop的版本如果太老etcd和minio這兩個(gè)依賴容器的健康檢查會(huì)一直不通過導(dǎo)致Milvus啟動(dòng)后連不上。解決方式是先把Docker Desktop升級(jí)到最新版然后用docker compose up -d依次啟動(dòng)最后用docker logs milvus看日志確認(rèn)milvus started successfully再繼續(xù)開發(fā)。3.2 Java工程引入Milvus SDK與連接工具類Maven里引入SDK非常簡單需要注意版本號(hào)要對(duì)應(yīng)你的Milvus服務(wù)端版本。我用的Milvus 2.3.4服務(wù)端對(duì)應(yīng)的Java SDK版本是2.3.x。過新或過舊的客戶端版本在gRPC協(xié)議對(duì)接時(shí)可能出現(xiàn)method not found或者屬性字段不兼容的問題。dependency groupIdio.milvus/groupId artifactIdmilvus-sdk-java/artifactId version2.3.4/version /dependency連接Milvus這步網(wǎng)上很多老教程用的是MilvusServiceClient這個(gè)類在2.3.x版本中還是主流。我封裝了一個(gè)Milvus配置類把連接參數(shù)放到application.yml里這樣多環(huán)境切換比較省事Component public class MilvusClientFactory { private static MilvusServiceClient client; Value(${milvus.host:localhost}) private String host; Value(${milvus.port:19530}) private int port; PostConstruct public void init() { ConnectParam connectParam ConnectParam.newBuilder() .withHost(host) .withPort(port) .build(); client new MilvusServiceClient(connectParam); } public static MilvusServiceClient getClient() { return client; } }這里有個(gè)實(shí)際經(jīng)驗(yàn)值得說一下MilvusServiceClient本身是線程安全的也就是說我可以在Service層直接通過靜態(tài)方法獲取實(shí)例然后用同一個(gè)實(shí)例并發(fā)查詢不需要為每個(gè)請(qǐng)求新建連接。新建連接的開銷很大每個(gè)連接底層都會(huì)創(chuàng)建gRPC Channel連接數(shù)一多Milvus服務(wù)端會(huì)報(bào)too many channels的錯(cuò)誤。4. 文檔預(yù)處理文本切分與向量生成4.1 文檔切分策略固定窗口還是語義邊界很多第一次做向量檢索的同學(xué)會(huì)忽略文檔切分直接把一整篇幾千字甚至幾萬字的合同文檔丟給Embedding模型生成向量。這會(huì)導(dǎo)致兩個(gè)問題一是模型對(duì)超長文本的編碼能力有限超過512個(gè)token之后后面的內(nèi)容信息會(huì)被嚴(yán)重稀釋語義向量幾乎全是噪音二是檢索的粒度太粗用戶問違約金的計(jì)算基數(shù)是多少返回的是一整篇合同向量后端根本不知道應(yīng)該拿哪一段去再加工和回答。所以切分是必須的這是所有RAG管道里最影響檢索質(zhì)量的步驟之一。我實(shí)踐下來中文場景最穩(wěn)妥的策略是分層切分先按語義結(jié)構(gòu)切出章節(jié)塊比如按二級(jí)標(biāo)題、按空行分出來的段落如果某個(gè)語義塊仍然超過設(shè)定的最大長度再按固定窗口二次切分同時(shí)保留一定的重疊區(qū)域。固定窗口的大小設(shè)置要考慮Embedding模型的上下文長度我用的是BGE-small-zh它的最大長度是512個(gè)token中文場景下我通常把窗口設(shè)為200到300個(gè)字重疊區(qū)域設(shè)為50個(gè)字左右。過長會(huì)導(dǎo)致語義信息截?cái)噙^短會(huì)導(dǎo)致塊與塊之間上下文斷裂。切分代碼我用Java實(shí)現(xiàn)了一個(gè)簡單的DocumentSplitter核心邏輯是按\n\n先分段落再根據(jù)長度決定是否二次切分public ListDocChunk split(String text, int maxLength, int overlap) { ListDocChunk chunks new ArrayList(); String[] sections text.split(\\n\\n); for (String section : sections) { section section.trim(); if (section.isEmpty()) continue; if (section.length() maxLength) { chunks.add(new DocChunk(section)); } else { int start 0; int end Math.min(start maxLength, section.length()); while (start section.length()) { String chunkText section.substring(start, end); chunks.add(new DocChunk(chunkText)); if (end section.length()) break; start Math.max(0, end - overlap); end Math.min(start maxLength, section.length()); } } } return chunks; }實(shí)際項(xiàng)目中文本清洗很重要常見要做的處理包括去掉PDF解析產(chǎn)生的多余換行符、把全角標(biāo)點(diǎn)統(tǒng)一成半角、把空白字符正則替換、識(shí)別并剔除頁眉頁腳。這些不做切出來的塊經(jīng)常是一半正文一半頁腳向量檢索效果會(huì)大打折扣。我個(gè)人曾經(jīng)因?yàn)槁┑繇撁记謇韺?dǎo)致檢索結(jié)果里高頻出現(xiàn)某個(gè)固定公司名一度以為模型出了問題排查半天才意識(shí)到是頁眉污染了向量。4.2 Embedding模型選擇與Java端加載向量生成是整個(gè)鏈路中的核心計(jì)算環(huán)節(jié)。最開始我想偷懶直接調(diào)云端API但考慮到數(shù)據(jù)合規(guī)和延遲最終采用本地部署ONNX模型。Java端做推理我選了ONNX Runtime它對(duì)Java的支持比較完善而且不需要額外開啟Python環(huán)境的依賴。模型我用的是BGE-small-zh-v1.5它對(duì)中文語義檢索的效果在同等體積模型里表現(xiàn)很好輸出維度是512維。下載下來之后會(huì)得到一個(gè).onnx文件和一個(gè)vocab.txt詞表。加載模型和生成向量的核心代碼是這個(gè)樣子public class EmbeddingService { private OrtSession session; private OrtEnvironment env; private BertTokenizer tokenizer; public void loadModel(String modelPath) throws OrtException { env OrtEnvironment.getEnvironment(); OrtSession.SessionOptions options new OrtSession.SessionOptions(); options.setOptimizationLevel(OrtSession.SessionOptions.OptLevel.ALL_OPT); session env.createSession(modelPath, options); tokenizer new BertTokenizer(vocab.txt); } public float[] embed(String text) throws OrtException { ListString tokens tokenizer.tokenize(text); // 對(duì)BGE模型需要添加 [CLS] 和 [SEP] 標(biāo)記 long[] inputIds new long[tokens.size()]; long[] attentionMask new long[tokens.size()]; // 填充inputIds... OnnxTensor inputIdsTensor OnnxTensor.createTensor(env, inputIds, new long[]{1, tokens.size()}); OnnxTensor attentionMaskTensor OnnxTensor.createTensor(env, attentionMask, new long[]{1, tokens.size()}); MapString, OnnxTensor inputs new HashMap(); inputs.put(input_ids, inputIdsTensor); inputs.put(attention_mask, attentionMaskTensor); OrtSession.Result results session.run(inputs); // 獲取last_hidden_state取[CLS]位置的向量 } }這段代碼只是核心邏輯的示意實(shí)際用的時(shí)候有很多細(xì)節(jié)尤其是分詞和Tensor的shape轉(zhuǎn)換。但我要強(qiáng)調(diào)一個(gè)更關(guān)鍵的坑BGE系列模型在檢索場景下必須添加指令前綴中文對(duì)應(yīng)的前綴是為這個(gè)句子生成表示以用于檢索相關(guān)文章查詢側(cè)和文檔側(cè)都要加上否則檢索效果會(huì)退化得非常明顯。我一開始沒加前綴測試的時(shí)候Top5的命中率只有30%加了之后直接到85%以上差距非?？鋸?。如果你不想在Java里折騰ONNX Runtime的tokenizer也可以用另一種務(wù)實(shí)方案單獨(dú)寫一個(gè)Python小服務(wù)部署Embedding模型Java通過gRPC或HTTP調(diào)用。但這樣架構(gòu)上多了一個(gè)服務(wù)部署復(fù)雜度上升而且Python服務(wù)的守護(hù)、重啟、版本管理都成了新的問題。我后來還是走回了Java直接加載ONNX模型的路線雖然技術(shù)棧稍微硬核一點(diǎn)但一勞永逸部署就一套Java服務(wù)。5. 核心實(shí)現(xiàn)Collection定義、數(shù)據(jù)寫入與語義檢索5.1 Milvus集合定義與文檔寫入鏈路Milvus里的Collection可以理解成關(guān)系型數(shù)據(jù)庫里的表字段定義好了之后寫入向量就必須嚴(yán)格按照字段來。我的集合設(shè)計(jì)是這樣的字段名類型說明idInt64自增主鍵docIdVarChar原始文檔的唯一標(biāo)識(shí)contentVarChar當(dāng)前chunk的純文本內(nèi)容categoryVarChar文檔分類用于標(biāo)量過濾embeddingFloatVector(512)語義向量創(chuàng)建Collection代碼如下public void createCollection(String collectionName) { FieldType idField FieldType.newBuilder() .withName(id).withDataType(DataType.Int64) .withPrimaryKey(true).withAutoID(true).build(); FieldType docIdField FieldType.newBuilder() .withName(docId).withDataType(DataType.VarChar).withMaxLength(256).build(); FieldType contentField FieldType.newBuilder() .withName(content).withDataType(DataType.VarChar).withMaxLength(65535).build(); FieldType categoryField FieldType.newBuilder() .withName(category).withDataType(DataType.VarChar).withMaxLength(128).build(); FieldType embeddingField FieldType.newBuilder() .withName(embedding).withDataType(DataType.FloatVector).withDimension(512).build(); CreateCollectionParam createParam CreateCollectionParam.newBuilder() .withCollectionName(collectionName) .withDescription(知識(shí)庫文檔向量集合) .addFieldType(idField) .addFieldType(docIdField) .addFieldType(contentField) .addFieldType(categoryField) .addFieldType(embeddingField) .build(); milvusClient.createCollection(createParam); }字段維度這個(gè)細(xì)節(jié)特別容易出錯(cuò)模型的輸出維度、創(chuàng)建Collection時(shí)指定的維度、以及實(shí)際寫入向量的長度三者必須完全一致。我在項(xiàng)目里遇到過一把情況是模型輸出的實(shí)際維度是512但我創(chuàng)建Collection時(shí)誤寫成了768插入的時(shí)候報(bào)float vector dim check failed排查了快一個(gè)小時(shí)才意識(shí)到是字段定義寫錯(cuò)了。建議你在代碼里把維度定義成常量不要散落在各處。寫入鏈路我建議用批量插入Milvus對(duì)大批量寫入的吞吐性能遠(yuǎn)好于逐條插入。我封裝好的批量寫入邏輯是把一組文檔chunk的向量和元數(shù)據(jù)都組裝好一次性提交public void upsertChunks(ListDocChunk chunks, String docId, String category) { ListListFloat vectors new ArrayList(); ListString contents new ArrayList(); ListString docIds new ArrayList(); ListString categories new ArrayList(); for (DocChunk chunk : chunks) { float[] vector embeddingService.embed(chunk.getText()); vectors.add(toFloatList(vector)); contents.add(chunk.getText()); docIds.add(docId); categories.add(category); } InsertParam insertParam InsertParam.newBuilder() .withCollectionName(COLLECTION_NAME) .withFields(Map.of( docId, docIds, content, contents, category, categories, embedding, vectors )) .build(); RMutationResult response milvusClient.insert(insertParam); if (response.getStatus() ! R.Status.Success.getCode()) { throw new RuntimeException(Milvus insert failed: response.getMessage()); } }這里面有個(gè)性能相關(guān)的經(jīng)驗(yàn)批量插入時(shí)一次插多少個(gè)合適我的建議是500到1000條chunk為一批太少會(huì)頻繁觸發(fā)網(wǎng)絡(luò)往返和Milvus內(nèi)部的數(shù)據(jù)落盤太多則容易導(dǎo)致內(nèi)存峰值和請(qǐng)求超時(shí)。我實(shí)際測過1000條512維向量單次插入耗時(shí)大概200毫秒左右吞吐足夠了。5.2 語義檢索API與混合檢索方案寫入完成之后查詢才是真正見真章的地方。查詢側(cè)處理流程沒那么復(fù)雜核心就是把用戶輸入的問題用同一個(gè)Embedding模型轉(zhuǎn)成向量然后調(diào)用Milvus的search接口搜TopK但有幾個(gè)容易被忽略的工程細(xì)節(jié)要做好。我實(shí)現(xiàn)了一個(gè)searchSimilarDocs方法支持按分類過濾和TopK配置public ListSearchResult searchSimilarDocs(String query, String category, int topK) { float[] queryVector embeddingService.embed(query); SearchParam searchParam SearchParam.newBuilder() .withCollectionName(COLLECTION_NAME) .withVector(queryVector) .withTopK(topK) .withOutputFields(List.of(docId, content, category)) .build(); if (category ! null !category.isEmpty()) { searchParam.getSearchParams().put(category, category); // Milvus支持在搜索時(shí)用過濾表達(dá)式例如 category 合同 searchParam.setExpr(category \ category \); } RSearchResults response milvusClient.search(searchParam); SearchResults data response.getData(); ListSearchResult results new ArrayList(); for (SearchResults.SearchResult hit : data.getResults()) { SearchResult sr new SearchResult(); sr.setScore(hit.getScore()); sr.setContent((String) hit.getFieldData(content)); sr.setDocId((String) hit.getFieldData(docId)); results.add(sr); } // 按分?jǐn)?shù)排序并返回 results.sort((a, b) - Float.compare(b.getScore(), a.getScore())); return results; }這里有幾個(gè)要點(diǎn)。第一個(gè)是相似度度量的選擇BGE模型推薦用CosineMilvus創(chuàng)建Collection和索引時(shí)都要設(shè)置成MetricType.COSINE這樣才能保證檢索分?jǐn)?shù)語義正確。第二個(gè)是過濾表達(dá)式如果業(yè)務(wù)上允許按分類過濾一定要先過濾再檢索不要拿全量向量撞一次再在業(yè)務(wù)層過濾那樣又慢又浪費(fèi)算力。第三個(gè)是搜索結(jié)果的排序Milvus返回的結(jié)果本身是有序的但我在代碼里還是做了一次排序兜底保證邏輯清晰。另外如果你要做的不是單純的向量檢索而是全文語義混合檢索那Milvus也支持在同一個(gè)Collection上做標(biāo)量過濾和向量搜索的組合。但如果你想同時(shí)做BM25關(guān)鍵詞召回和向量召回那需要自己寫一部分邏輯把ES的BM25分?jǐn)?shù)和Milvus的向量分?jǐn)?shù)做加權(quán)融合。我在項(xiàng)目中做過的方案是ES做關(guān)鍵詞召回Milvus做向量召回兩條結(jié)果按rank fusion算法合并這個(gè)效果在長尾query上會(huì)明顯好于單一檢索方式。不過為了控制篇幅混合檢索的細(xì)節(jié)這次不展開講后面單獨(dú)開一篇來寫。6. 上線之后踩過的坑索引、性能與工程化細(xì)節(jié)6.1 忘記建索引導(dǎo)致的百萬級(jí)數(shù)據(jù)全表掃描這是我在Milvus上踩過最疼的坑。一開始我只創(chuàng)建了Collection并寫入數(shù)據(jù)沒有單獨(dú)建索引結(jié)果查詢速度一開始還行數(shù)據(jù)量到幾十萬之后單條查詢耗時(shí)直接飆到3秒以上。Milvus如果不對(duì)向量字段建索引搜索就會(huì)退化成暴力掃描本質(zhì)上就是全量計(jì)算相似度數(shù)據(jù)量越大越慢。后來我把索引改成HNSW建索引的代碼如下public void createIndex(String collectionName) { CreateIndexParam indexParam CreateIndexParam.newBuilder() .withCollectionName(collectionName) .withFieldName(embedding) .withIndexType(IndexType.HNSW) .withMetricType(MetricType.COSINE) .withExtraParam({\M\: 16, \efConstruction\: 200}) .build(); RRpcStatus response milvusClient.createIndex(indexParam); }HNSW索引的兩個(gè)核心參數(shù)是M和efConstruction。M代表每個(gè)節(jié)點(diǎn)的最大連接數(shù)M越大表示圖越密集召回率越高但內(nèi)存和索引構(gòu)建時(shí)間也會(huì)增加一般取16或32。efConstruction是構(gòu)建時(shí)的動(dòng)態(tài)列表長度越大索引質(zhì)量越高但構(gòu)建越慢200是一個(gè)比較平衡的選擇。查詢時(shí)還有一個(gè)ef參數(shù)我會(huì)在SearchParam里單獨(dú)配置它控制查詢時(shí)的搜索范圍越大召回越高但延遲越高。我的建議是召回優(yōu)先場景ef設(shè)64或128延遲敏感場景設(shè)32。關(guān)于建索引還有一個(gè)坑如果你先寫入數(shù)據(jù)再建索引當(dāng)數(shù)據(jù)量很大的時(shí)候建索引過程非常耗內(nèi)存和CPU生產(chǎn)環(huán)境最好在Collection創(chuàng)建好之后就立即建索引然后再灌數(shù)據(jù)。Milvus是支持在寫入過程中增量構(gòu)建索引的但如果先灌數(shù)據(jù)再觸發(fā)建索引遇到大數(shù)據(jù)量會(huì)產(chǎn)生明顯的IO抖動(dòng)。6.2 Java工程化里的數(shù)據(jù)一致性、并發(fā)與超時(shí)問題在實(shí)際接入過程中數(shù)據(jù)處理鏈路長不像單表CRUD那么簡單有幾點(diǎn)工程化細(xì)節(jié)值得單獨(dú)記一筆。首先是寫入一致性的保障。我的場景是從消息隊(duì)列里消費(fèi)到文檔后先解析、切分、向量化再寫入Milvus。如果向量化或?qū)懭脒^程中服務(wù)重啟了那這條文檔數(shù)據(jù)就丟了。為了避免這個(gè)問題我加了一個(gè)文檔狀態(tài)表用MySQL記錄每個(gè)文檔的切分?jǐn)?shù)量、向量化狀態(tài)和寫入狀態(tài)。流程是接收文檔 - 創(chuàng)建狀態(tài)記錄PENDING - 切分向量化 - 寫Milvus - 更新狀態(tài)為SUCCESS。下一次啟動(dòng)時(shí)掃描狀態(tài)為PENDING的文檔重新處理一遍這樣既保證了最終一致性又不會(huì)重復(fù)寫入大量數(shù)據(jù)。其次是并發(fā)問題。Java這邊用了線程池并發(fā)處理文檔切分和向量化但在調(diào)用ONNX模型做推理時(shí)OrtSession不是線程安全的并發(fā)推理需要做同步或者用線程局部變量。我的土辦法是每線程一個(gè)Session實(shí)例這樣既避免了鎖競爭又充分利用了多核CPU。MilvusClient倒是線程安全的可以直接并發(fā)調(diào)用但要注意控制并發(fā)度我壓測下來8到16個(gè)并發(fā)寫入或查詢線程都比較穩(wěn)定再高容易觸發(fā)Milvus端的連接池瓶頸。最后是超時(shí)和重試。Milvus的網(wǎng)絡(luò)交互是gRPC超時(shí)時(shí)間默認(rèn)比較長但業(yè)務(wù)接口不能讓用戶等太久。我給檢索接口設(shè)置了一個(gè)超時(shí)器超過2秒就暫時(shí)返回服務(wù)繁忙或走降級(jí)策略避免把連接池拖死。同時(shí)每次寫入操作都加了失敗重試邏輯重試三次間隔指數(shù)退避。這里我踩過的一個(gè)小坑是Milvus的insert操作不是冪等的如果客戶端寫超時(shí)后重試服務(wù)端可能已經(jīng)寫入成功導(dǎo)致同一條chunk插了兩遍。解決方法是插入前生成一個(gè)業(yè)務(wù)側(cè)唯一ID寫入時(shí)用這個(gè)ID作為主鍵靠autoID就不行要自己指定ID這樣重復(fù)插入就能被主鍵沖突擋住。6.3 檢索效果調(diào)優(yōu)從糟糕結(jié)果到可用狀態(tài)項(xiàng)目上線之后我調(diào)了一段時(shí)間的檢索效果。要知道向量檢索不是接完就完事的效果好壞受切分粒度、向量模型、查詢側(cè)文本處理、TopK參數(shù)等多重因素影響。這里把幾個(gè)性價(jià)比最高的優(yōu)化手段按優(yōu)先級(jí)列一下優(yōu)化項(xiàng)具體操作效果提升切分窗口從500字降到200到300字中檢索粒度更精準(zhǔn)添加指令前綴BGE模型查詢和文檔側(cè)都加前綴極大命中率翻倍元數(shù)據(jù)過濾檢索時(shí)優(yōu)先按category過濾高縮小搜索范圍結(jié)果重排序Top10召回后按原文輕量rerank高最后一條內(nèi)容質(zhì)量決定用戶體驗(yàn)去掉停用詞查詢文本清理的、了、呢小但穩(wěn)定重排序這步我很推薦做。最簡單的方式是Milvus先招回Top20然后把這20條chunk的文本和用戶問題再做一次余弦相似度重算取更精確的Top5返回給上游做答案生成。因?yàn)镸ilvus的ANN搜索本身是近似的Top20的精度可能不如Top5但重排序能把這部分誤差糾回來。我實(shí)際體驗(yàn)下來重排序后的結(jié)果比直接Top5的滿意度要高不少而且實(shí)現(xiàn)成本很低幾十行代碼的事。有個(gè)建議是把重排序邏輯和Milvus搜索解耦獨(dú)立成一個(gè)RerankService方便后續(xù)升級(jí)成CrossEncoder模型而不是每次都做余弦重算。如果你有精力做CrossEncoder的重排序會(huì)更專業(yè)模型效果相比普通余弦相似度有明顯代差。6.4 快速排錯(cuò)速查表最后把這段時(shí)間遇到的典型問題整理成一個(gè)速查表方便大家少走彎路現(xiàn)象大概率原因解決方式milvus connect failDocker依賴容器etcd/minio沒起用docker compose up -d全部拉起確認(rèn)健康狀態(tài)創(chuàng)建Collection報(bào)維度錯(cuò)誤模型輸出維度與Collection定義不一致打印模型輸出shape與字段dimension對(duì)齊查詢結(jié)果為空沒有寫入數(shù)據(jù)或expr過濾條件太嚴(yán)格先去掉過濾條件測試再用collection stats驗(yàn)證數(shù)據(jù)量查詢速度突然變慢向量字段沒建索引創(chuàng)建HNSW或IVF索引等待索引就緒插入時(shí)返回主鍵沖突自增ID被關(guān)閉且業(yè)務(wù)側(cè)指定了重復(fù)ID檢查ID生成邏輯或改用autoIDJava進(jìn)程內(nèi)存溢出批量插入數(shù)據(jù)量過大每次插入控制在1000條以內(nèi)及時(shí)釋放list結(jié)果語義相關(guān)性差沒加BGE指令前綴或切分窗口過大按上文添加前綴縮短切分窗口還有一個(gè)小細(xì)節(jié)Milvus的collection如果刪除重建之前的數(shù)據(jù)就徹底沒了所以生產(chǎn)環(huán)境一定不要在生產(chǎn)connection上隨便執(zhí)行dropCollection。我在開發(fā)環(huán)境就手滑過一次結(jié)果整個(gè)知識(shí)庫的向量數(shù)據(jù)全部清空重新跑了一遍全量入庫流程白白浪費(fèi)了一個(gè)下午。結(jié)尾分享這套Java接向量數(shù)據(jù)庫的方案已經(jīng)在我的知識(shí)庫項(xiàng)目里穩(wěn)定跑了兩個(gè)多月文檔入庫量累計(jì)超過20萬條chunk單次查詢平均耗時(shí)120毫秒左右數(shù)據(jù)安全性也因?yàn)槿镜鼗Ｐ投玫搅吮Ｕ稀Ｎ覀€(gè)人實(shí)操中的體會(huì)是向量數(shù)據(jù)庫本身不難接難的是把文檔怎么切、向量怎么生成、檢索怎么調(diào)優(yōu)這套鏈路想明白。如果你也在做類似項(xiàng)目建議先拿一個(gè)小數(shù)據(jù)集從切分和模型的前綴效果開始做起把每一步的結(jié)果都打印出來看一眼不要等到全鏈路完成再一起調(diào)試那是災(zāi)難。最后再分享一個(gè)小技巧每次修改切分策略或模型后別急著全量更新索引先選一個(gè)真實(shí)用戶查詢用新方案跑一遍對(duì)比一下返回的Top5結(jié)果效率最高。 Java接入Milvus實(shí)現(xiàn)語義搜索：文檔智能檢索全鏈路實(shí)戰(zhàn)
在AI應(yīng)用和知識(shí)庫項(xiàng)目里摸爬滾打了一段時(shí)間后我越來越確認(rèn)一個(gè)事情傳統(tǒng)的數(shù)據(jù)庫檢索方式在面對(duì)語義搜索和文檔智能問答這類需求時(shí)是真的不夠用。你光靠關(guān)鍵詞匹配和SQL的LIKE查詢永遠(yuǎn)解決不了用戶搜蘋果但文檔里寫的是iPhone這種級(jí)別的語義問題。于是我把目光投向了向量數(shù)據(jù)庫。之前網(wǎng)上搜資料90%的教程都是Python示例Java的完整實(shí)踐案例少得可憐而且很多Demo代碼根本跑不通。這篇就把我踩過坑、填過土之后的完整方案寫出來講清楚Java怎么接向量數(shù)據(jù)庫、文檔怎么切分、向量怎么生成、檢索怎么實(shí)現(xiàn)以及一系列工程化細(xì)節(jié)。項(xiàng)目核心是解決文檔檢索與語義搜索這個(gè)場景適合正在搞RAG、智能客服、企業(yè)知識(shí)庫的后端Java開發(fā)同學(xué)直接參考。1. 項(xiàng)目整體思路為什么Java后端需要一個(gè)向量層1.1 從關(guān)鍵詞匹配到語義檢索差的不是算法而是數(shù)據(jù)組織方式先講個(gè)背景。我之前在做一個(gè)企業(yè)合同知識(shí)庫倉庫里有幾百份PDF和Word文檔。業(yè)務(wù)方的需求很樸素員工輸入去年和華為簽的采購合同里違約金比例是多少系統(tǒng)要快速給出答案。用傳統(tǒng)的ES方案我只能做分詞和倒排索引。違約金比例這種詞如果合同原文寫的是違約賠償金那ES的精確分詞基本就廢了搜出來一堆不相關(guān)的東西。要想讓系統(tǒng)懂語義核心思路是把文本變成高維向量然后在向量空間里計(jì)算距離和相似度。蘋果和iPhone這兩個(gè)詞的文本形式差了十萬八千里但它們的語義向量在空間里距離很近。這個(gè)能力不是靠算法而是靠預(yù)訓(xùn)練的Embedding模型和海量語料訓(xùn)練得到的。向量數(shù)據(jù)庫干的事情就是把生成后的向量存起來并提供高效的近鄰檢索能力也就是ANNApproximate Nearest Neighbor。所以這個(gè)項(xiàng)目的架構(gòu)其實(shí)很清晰文檔進(jìn)來之后先做切割切出來的每一段文本都過一遍Embedding模型生成一個(gè)幾百維的Float數(shù)組然后連同原文和元數(shù)據(jù)一起寫入向量數(shù)據(jù)庫。查詢的時(shí)候用戶的問題同樣過一遍Embedding模型再拿這個(gè)查詢向量去庫里做相似度搜索取TopK結(jié)果返回。整個(gè)過程Java這邊全程參與不依賴任何Python微服務(wù)這也是這個(gè)項(xiàng)目最有價(jià)值的地方。1.2 技術(shù)棧選型與整體架構(gòu)這個(gè)項(xiàng)目我用了Spring Boot 3.x Java 17作為基礎(chǔ)后端框架向量數(shù)據(jù)庫選了Milvus向量化模型選用本地部署的ONNX格式中文Embedding模型。之所以不選在線API是因?yàn)槠髽I(yè)級(jí)知識(shí)庫對(duì)數(shù)據(jù)出域很敏感合同、醫(yī)療、客服對(duì)話這類數(shù)據(jù)不適合直接提交給第三方API做詞向量轉(zhuǎn)換。本地化部署雖然要花一些時(shí)間配置環(huán)境但數(shù)據(jù)安全性可控而且調(diào)用延遲更低QPS起來了之后在線API的成本會(huì)很高本地模型更劃算。整體流程分兩條鏈路。寫入鏈路解析文檔 - 清洗文本 - 文檔切分 - 生成向量 - 寫入Milvus。查詢鏈路接收用戶問題 - 生成查詢向量 - Milvus向量檢索 - 按元數(shù)據(jù)過濾 - 結(jié)果重排 - 返回給上層業(yè)務(wù)。這兩條鏈路在Java服務(wù)內(nèi)完全閉環(huán)Milvus只負(fù)責(zé)當(dāng)向量存儲(chǔ)和檢索引擎不承擔(dān)任何業(yè)務(wù)邏輯。2. 向量數(shù)據(jù)庫選型Java生態(tài)里最務(wù)實(shí)的幾個(gè)選項(xiàng)2.1 主流向量數(shù)據(jù)庫橫向?qū)Ρ葦?shù)據(jù)庫部署復(fù)雜度Java SDK成熟度混合檢索支持適用場景Milvus中依賴K8s或Docker官方Java SDK接口完整支持Meta過濾大規(guī)模向量檢索、RAG專用Elasticsearch中自帶集群能力原生Java客戶端完善全文檢索向量已有ES需要兼顧全文搜索Redis低官方Java客戶端很成熟較弱小規(guī)模原型驗(yàn)證、緩存場景PostgreSQL pgvector低JDBC即可一般SQL靈活已有PG業(yè)務(wù)需要統(tǒng)一存儲(chǔ)我最終選擇了Milvus主要原因有三點(diǎn)。第一它是純正的向量數(shù)據(jù)庫對(duì)ANN算法、內(nèi)存索引、分片策略的優(yōu)化非常深入單機(jī)集群模式下千萬級(jí)向量檢索的延遲都能壓在100毫秒左右。第二它的Java SDK不是社區(qū)熱情產(chǎn)物而是官方維護(hù)的milvus-sdk-java接口設(shè)計(jì)思路和REST API差不多用起來比較順手。第三它支持標(biāo)量字段過濾我可以把合同ID、文檔分類、上傳時(shí)間這些業(yè)務(wù)屬性存成標(biāo)量字段檢索時(shí)先過濾再搜大幅縮小向量搜索范圍實(shí)用性非常強(qiáng)。2.2 為什么沒選Elasticsearch和RedisES其實(shí)是很多團(tuán)隊(duì)的第一直覺畢竟大部分后端項(xiàng)目里ES已經(jīng)在了再復(fù)用豈不是省事。但我在對(duì)比測試中發(fā)現(xiàn)了問題ES的向量檢索kNN search在數(shù)據(jù)量超過百萬級(jí)之后性能曲線下降得很明顯而且ES的內(nèi)存存儲(chǔ)結(jié)構(gòu)不如Milvus這種為向量設(shè)計(jì)的系統(tǒng)高效。另外一個(gè)問題是ES的向量能力在開源版本中支持得不夠靈活一些高級(jí)參數(shù)如efConstruction、M需要配置深度調(diào)優(yōu)對(duì)普通業(yè)務(wù)開發(fā)者來說門檻偏高。當(dāng)然如果你的項(xiàng)目本身已經(jīng)重度使用ES做全文檢索而且數(shù)據(jù)量不大直接升級(jí)版本用ES的向量檢索能力也完全合理這屬于已有基礎(chǔ)設(shè)施優(yōu)先的策略。Redis做過一輪測試結(jié)論是僅適合Demo階段或幾百條數(shù)據(jù)的在線測試原因是它的向量模塊是基于內(nèi)存哈希結(jié)構(gòu)的簡單實(shí)現(xiàn)沒有Milvus那樣完善的索引和分段存儲(chǔ)機(jī)制查詢延遲雖然低但召回率不穩(wěn)定。我在本地用一萬條隨機(jī)向量測過Redis的搜索召回率在80%左右Milvus在90%以上差距還是很明顯的。3. 環(huán)境準(zhǔn)備Milvus部署與Java工程搭建3.1 Docker方式快速部署Milvus Standalone很多教程一上來就推薦Milvus集群模式需要部署etcd、Pulsar、MinIO等一大堆組件直接把新人嚇退。其實(shí)單機(jī)環(huán)境或者測試環(huán)境用Standalone模式就足夠了Docker Compose一條命令就能把Milvus跑起來。我本地開發(fā)環(huán)境的docker-compose.yml關(guān)鍵部分是這樣寫的version: 3.5 services: etcd: image: quay.io/coreos/etcd:v3.5.5 environment: - ETCD_AUTO_COMPACTION_MODErevision - ETCD_AUTO_COMPACTION_RETENTION1000 - ETCD_QUOTA_BACKEND_BYTES4294967296 - ETCD_SNAPSHOT_COUNT50000 command: etcd -advertise-client-urlshttp://127.0.0.1:2379 -listen-client-urlshttp://0.0.0.0:2379 minio: image: minio/minio:RELEASE.2023-03-20T20-16-18Z environment: MINIO_ACCESS_KEY: minioadmin MINIO_SECRET_KEY: minioadmin command: minio server /minio_data --console-address :9001 milvus: image: milvusdb/milvus:v2.3.4 command: [milvus, run, standalone] environment: ETCD_ENDPOINTS: etcd:2379 MINIO_ADDRESS: minio:9000 ports: - 19530:19530 - 9091:9091 depends_on: - etcd - minio跑起來之后Milvus默認(rèn)監(jiān)聽19530端口這就是gRPC通信的入口。Java SDK連接的就是這個(gè)端口。這里我踩過一個(gè)大坑Docker Desktop的版本如果太老etcd和minio這兩個(gè)依賴容器的健康檢查會(huì)一直不通過導(dǎo)致Milvus啟動(dòng)后連不上。解決方式是先把Docker Desktop升級(jí)到最新版然后用docker compose up -d依次啟動(dòng)最后用docker logs milvus看日志確認(rèn)milvus started successfully再繼續(xù)開發(fā)。3.2 Java工程引入Milvus SDK與連接工具類Maven里引入SDK非常簡單需要注意版本號(hào)要對(duì)應(yīng)你的Milvus服務(wù)端版本。我用的Milvus 2.3.4服務(wù)端對(duì)應(yīng)的Java SDK版本是2.3.x。過新或過舊的客戶端版本在gRPC協(xié)議對(duì)接時(shí)可能出現(xiàn)method not found或者屬性字段不兼容的問題。dependency groupIdio.milvus/groupId artifactIdmilvus-sdk-java/artifactId version2.3.4/version /dependency連接Milvus這步網(wǎng)上很多老教程用的是MilvusServiceClient這個(gè)類在2.3.x版本中還是主流。我封裝了一個(gè)Milvus配置類把連接參數(shù)放到application.yml里這樣多環(huán)境切換比較省事Component public class MilvusClientFactory { private static MilvusServiceClient client; Value(${milvus.host:localhost}) private String host; Value(${milvus.port:19530}) private int port; PostConstruct public void init() { ConnectParam connectParam ConnectParam.newBuilder() .withHost(host) .withPort(port) .build(); client new MilvusServiceClient(connectParam); } public static MilvusServiceClient getClient() { return client; } }這里有個(gè)實(shí)際經(jīng)驗(yàn)值得說一下MilvusServiceClient本身是線程安全的也就是說我可以在Service層直接通過靜態(tài)方法獲取實(shí)例然后用同一個(gè)實(shí)例并發(fā)查詢不需要為每個(gè)請(qǐng)求新建連接。新建連接的開銷很大每個(gè)連接底層都會(huì)創(chuàng)建gRPC Channel連接數(shù)一多Milvus服務(wù)端會(huì)報(bào)too many channels的錯(cuò)誤。4. 文檔預(yù)處理文本切分與向量生成4.1 文檔切分策略固定窗口還是語義邊界很多第一次做向量檢索的同學(xué)會(huì)忽略文檔切分直接把一整篇幾千字甚至幾萬字的合同文檔丟給Embedding模型生成向量。這會(huì)導(dǎo)致兩個(gè)問題一是模型對(duì)超長文本的編碼能力有限超過512個(gè)token之后后面的內(nèi)容信息會(huì)被嚴(yán)重稀釋語義向量幾乎全是噪音二是檢索的粒度太粗用戶問違約金的計(jì)算基數(shù)是多少返回的是一整篇合同向量后端根本不知道應(yīng)該拿哪一段去再加工和回答。所以切分是必須的這是所有RAG管道里最影響檢索質(zhì)量的步驟之一。我實(shí)踐下來中文場景最穩(wěn)妥的策略是分層切分先按語義結(jié)構(gòu)切出章節(jié)塊比如按二級(jí)標(biāo)題、按空行分出來的段落如果某個(gè)語義塊仍然超過設(shè)定的最大長度再按固定窗口二次切分同時(shí)保留一定的重疊區(qū)域。固定窗口的大小設(shè)置要考慮Embedding模型的上下文長度我用的是BGE-small-zh它的最大長度是512個(gè)token中文場景下我通常把窗口設(shè)為200到300個(gè)字重疊區(qū)域設(shè)為50個(gè)字左右。過長會(huì)導(dǎo)致語義信息截?cái)噙^短會(huì)導(dǎo)致塊與塊之間上下文斷裂。切分代碼我用Java實(shí)現(xiàn)了一個(gè)簡單的DocumentSplitter核心邏輯是按\n\n先分段落再根據(jù)長度決定是否二次切分public ListDocChunk split(String text, int maxLength, int overlap) { ListDocChunk chunks new ArrayList(); String[] sections text.split(\\n\\n); for (String section : sections) { section section.trim(); if (section.isEmpty()) continue; if (section.length() maxLength) { chunks.add(new DocChunk(section)); } else { int start 0; int end Math.min(start maxLength, section.length()); while (start section.length()) { String chunkText section.substring(start, end); chunks.add(new DocChunk(chunkText)); if (end section.length()) break; start Math.max(0, end - overlap); end Math.min(start maxLength, section.length()); } } } return chunks; }實(shí)際項(xiàng)目中文本清洗很重要常見要做的處理包括去掉PDF解析產(chǎn)生的多余換行符、把全角標(biāo)點(diǎn)統(tǒng)一成半角、把空白字符正則替換、識(shí)別并剔除頁眉頁腳。這些不做切出來的塊經(jīng)常是一半正文一半頁腳向量檢索效果會(huì)大打折扣。我個(gè)人曾經(jīng)因?yàn)槁┑繇撁记謇韺?dǎo)致檢索結(jié)果里高頻出現(xiàn)某個(gè)固定公司名一度以為模型出了問題排查半天才意識(shí)到是頁眉污染了向量。4.2 Embedding模型選擇與Java端加載向量生成是整個(gè)鏈路中的核心計(jì)算環(huán)節(jié)。最開始我想偷懶直接調(diào)云端API但考慮到數(shù)據(jù)合規(guī)和延遲最終采用本地部署ONNX模型。Java端做推理我選了ONNX Runtime它對(duì)Java的支持比較完善而且不需要額外開啟Python環(huán)境的依賴。模型我用的是BGE-small-zh-v1.5它對(duì)中文語義檢索的效果在同等體積模型里表現(xiàn)很好輸出維度是512維。下載下來之后會(huì)得到一個(gè).onnx文件和一個(gè)vocab.txt詞表。加載模型和生成向量的核心代碼是這個(gè)樣子public class EmbeddingService { private OrtSession session; private OrtEnvironment env; private BertTokenizer tokenizer; public void loadModel(String modelPath) throws OrtException { env OrtEnvironment.getEnvironment(); OrtSession.SessionOptions options new OrtSession.SessionOptions(); options.setOptimizationLevel(OrtSession.SessionOptions.OptLevel.ALL_OPT); session env.createSession(modelPath, options); tokenizer new BertTokenizer(vocab.txt); } public float[] embed(String text) throws OrtException { ListString tokens tokenizer.tokenize(text); // 對(duì)BGE模型需要添加 [CLS] 和 [SEP] 標(biāo)記 long[] inputIds new long[tokens.size()]; long[] attentionMask new long[tokens.size()]; // 填充inputIds... OnnxTensor inputIdsTensor OnnxTensor.createTensor(env, inputIds, new long[]{1, tokens.size()}); OnnxTensor attentionMaskTensor OnnxTensor.createTensor(env, attentionMask, new long[]{1, tokens.size()}); MapString, OnnxTensor inputs new HashMap(); inputs.put(input_ids, inputIdsTensor); inputs.put(attention_mask, attentionMaskTensor); OrtSession.Result results session.run(inputs); // 獲取last_hidden_state取[CLS]位置的向量 } }這段代碼只是核心邏輯的示意實(shí)際用的時(shí)候有很多細(xì)節(jié)尤其是分詞和Tensor的shape轉(zhuǎn)換。但我要強(qiáng)調(diào)一個(gè)更關(guān)鍵的坑BGE系列模型在檢索場景下必須添加指令前綴中文對(duì)應(yīng)的前綴是為這個(gè)句子生成表示以用于檢索相關(guān)文章查詢側(cè)和文檔側(cè)都要加上否則檢索效果會(huì)退化得非常明顯。我一開始沒加前綴測試的時(shí)候Top5的命中率只有30%加了之后直接到85%以上差距非?？鋸?。如果你不想在Java里折騰ONNX Runtime的tokenizer也可以用另一種務(wù)實(shí)方案單獨(dú)寫一個(gè)Python小服務(wù)部署Embedding模型Java通過gRPC或HTTP調(diào)用。但這樣架構(gòu)上多了一個(gè)服務(wù)部署復(fù)雜度上升而且Python服務(wù)的守護(hù)、重啟、版本管理都成了新的問題。我后來還是走回了Java直接加載ONNX模型的路線雖然技術(shù)棧稍微硬核一點(diǎn)但一勞永逸部署就一套Java服務(wù)。5. 核心實(shí)現(xiàn)Collection定義、數(shù)據(jù)寫入與語義檢索5.1 Milvus集合定義與文檔寫入鏈路Milvus里的Collection可以理解成關(guān)系型數(shù)據(jù)庫里的表字段定義好了之后寫入向量就必須嚴(yán)格按照字段來。我的集合設(shè)計(jì)是這樣的字段名類型說明idInt64自增主鍵docIdVarChar原始文檔的唯一標(biāo)識(shí)contentVarChar當(dāng)前chunk的純文本內(nèi)容categoryVarChar文檔分類用于標(biāo)量過濾embeddingFloatVector(512)語義向量創(chuàng)建Collection代碼如下public void createCollection(String collectionName) { FieldType idField FieldType.newBuilder() .withName(id).withDataType(DataType.Int64) .withPrimaryKey(true).withAutoID(true).build(); FieldType docIdField FieldType.newBuilder() .withName(docId).withDataType(DataType.VarChar).withMaxLength(256).build(); FieldType contentField FieldType.newBuilder() .withName(content).withDataType(DataType.VarChar).withMaxLength(65535).build(); FieldType categoryField FieldType.newBuilder() .withName(category).withDataType(DataType.VarChar).withMaxLength(128).build(); FieldType embeddingField FieldType.newBuilder() .withName(embedding).withDataType(DataType.FloatVector).withDimension(512).build(); CreateCollectionParam createParam CreateCollectionParam.newBuilder() .withCollectionName(collectionName) .withDescription(知識(shí)庫文檔向量集合) .addFieldType(idField) .addFieldType(docIdField) .addFieldType(contentField) .addFieldType(categoryField) .addFieldType(embeddingField) .build(); milvusClient.createCollection(createParam); }字段維度這個(gè)細(xì)節(jié)特別容易出錯(cuò)模型的輸出維度、創(chuàng)建Collection時(shí)指定的維度、以及實(shí)際寫入向量的長度三者必須完全一致。我在項(xiàng)目里遇到過一把情況是模型輸出的實(shí)際維度是512但我創(chuàng)建Collection時(shí)誤寫成了768插入的時(shí)候報(bào)float vector dim check failed排查了快一個(gè)小時(shí)才意識(shí)到是字段定義寫錯(cuò)了。建議你在代碼里把維度定義成常量不要散落在各處。寫入鏈路我建議用批量插入Milvus對(duì)大批量寫入的吞吐性能遠(yuǎn)好于逐條插入。我封裝好的批量寫入邏輯是把一組文檔chunk的向量和元數(shù)據(jù)都組裝好一次性提交public void upsertChunks(ListDocChunk chunks, String docId, String category) { ListListFloat vectors new ArrayList(); ListString contents new ArrayList(); ListString docIds new ArrayList(); ListString categories new ArrayList(); for (DocChunk chunk : chunks) { float[] vector embeddingService.embed(chunk.getText()); vectors.add(toFloatList(vector)); contents.add(chunk.getText()); docIds.add(docId); categories.add(category); } InsertParam insertParam InsertParam.newBuilder() .withCollectionName(COLLECTION_NAME) .withFields(Map.of( docId, docIds, content, contents, category, categories, embedding, vectors )) .build(); RMutationResult response milvusClient.insert(insertParam); if (response.getStatus() ! R.Status.Success.getCode()) { throw new RuntimeException(Milvus insert failed: response.getMessage()); } }這里面有個(gè)性能相關(guān)的經(jīng)驗(yàn)批量插入時(shí)一次插多少個(gè)合適我的建議是500到1000條chunk為一批太少會(huì)頻繁觸發(fā)網(wǎng)絡(luò)往返和Milvus內(nèi)部的數(shù)據(jù)落盤太多則容易導(dǎo)致內(nèi)存峰值和請(qǐng)求超時(shí)。我實(shí)際測過1000條512維向量單次插入耗時(shí)大概200毫秒左右吞吐足夠了。5.2 語義檢索API與混合檢索方案寫入完成之后查詢才是真正見真章的地方。查詢側(cè)處理流程沒那么復(fù)雜核心就是把用戶輸入的問題用同一個(gè)Embedding模型轉(zhuǎn)成向量然后調(diào)用Milvus的search接口搜TopK但有幾個(gè)容易被忽略的工程細(xì)節(jié)要做好。我實(shí)現(xiàn)了一個(gè)searchSimilarDocs方法支持按分類過濾和TopK配置public ListSearchResult searchSimilarDocs(String query, String category, int topK) { float[] queryVector embeddingService.embed(query); SearchParam searchParam SearchParam.newBuilder() .withCollectionName(COLLECTION_NAME) .withVector(queryVector) .withTopK(topK) .withOutputFields(List.of(docId, content, category)) .build(); if (category ! null !category.isEmpty()) { searchParam.getSearchParams().put(category, category); // Milvus支持在搜索時(shí)用過濾表達(dá)式例如 category 合同 searchParam.setExpr(category \ category \); } RSearchResults response milvusClient.search(searchParam); SearchResults data response.getData(); ListSearchResult results new ArrayList(); for (SearchResults.SearchResult hit : data.getResults()) { SearchResult sr new SearchResult(); sr.setScore(hit.getScore()); sr.setContent((String) hit.getFieldData(content)); sr.setDocId((String) hit.getFieldData(docId)); results.add(sr); } // 按分?jǐn)?shù)排序并返回 results.sort((a, b) - Float.compare(b.getScore(), a.getScore())); return results; }這里有幾個(gè)要點(diǎn)。第一個(gè)是相似度度量的選擇BGE模型推薦用CosineMilvus創(chuàng)建Collection和索引時(shí)都要設(shè)置成MetricType.COSINE這樣才能保證檢索分?jǐn)?shù)語義正確。第二個(gè)是過濾表達(dá)式如果業(yè)務(wù)上允許按分類過濾一定要先過濾再檢索不要拿全量向量撞一次再在業(yè)務(wù)層過濾那樣又慢又浪費(fèi)算力。第三個(gè)是搜索結(jié)果的排序Milvus返回的結(jié)果本身是有序的但我在代碼里還是做了一次排序兜底保證邏輯清晰。另外如果你要做的不是單純的向量檢索而是全文語義混合檢索那Milvus也支持在同一個(gè)Collection上做標(biāo)量過濾和向量搜索的組合。但如果你想同時(shí)做BM25關(guān)鍵詞召回和向量召回那需要自己寫一部分邏輯把ES的BM25分?jǐn)?shù)和Milvus的向量分?jǐn)?shù)做加權(quán)融合。我在項(xiàng)目中做過的方案是ES做關(guān)鍵詞召回Milvus做向量召回兩條結(jié)果按rank fusion算法合并這個(gè)效果在長尾query上會(huì)明顯好于單一檢索方式。不過為了控制篇幅混合檢索的細(xì)節(jié)這次不展開講后面單獨(dú)開一篇來寫。6. 上線之后踩過的坑索引、性能與工程化細(xì)節(jié)6.1 忘記建索引導(dǎo)致的百萬級(jí)數(shù)據(jù)全表掃描這是我在Milvus上踩過最疼的坑。一開始我只創(chuàng)建了Collection并寫入數(shù)據(jù)沒有單獨(dú)建索引結(jié)果查詢速度一開始還行數(shù)據(jù)量到幾十萬之后單條查詢耗時(shí)直接飆到3秒以上。Milvus如果不對(duì)向量字段建索引搜索就會(huì)退化成暴力掃描本質(zhì)上就是全量計(jì)算相似度數(shù)據(jù)量越大越慢。后來我把索引改成HNSW建索引的代碼如下public void createIndex(String collectionName) { CreateIndexParam indexParam CreateIndexParam.newBuilder() .withCollectionName(collectionName) .withFieldName(embedding) .withIndexType(IndexType.HNSW) .withMetricType(MetricType.COSINE) .withExtraParam({\M\: 16, \efConstruction\: 200}) .build(); RRpcStatus response milvusClient.createIndex(indexParam); }HNSW索引的兩個(gè)核心參數(shù)是M和efConstruction。M代表每個(gè)節(jié)點(diǎn)的最大連接數(shù)M越大表示圖越密集召回率越高但內(nèi)存和索引構(gòu)建時(shí)間也會(huì)增加一般取16或32。efConstruction是構(gòu)建時(shí)的動(dòng)態(tài)列表長度越大索引質(zhì)量越高但構(gòu)建越慢200是一個(gè)比較平衡的選擇。查詢時(shí)還有一個(gè)ef參數(shù)我會(huì)在SearchParam里單獨(dú)配置它控制查詢時(shí)的搜索范圍越大召回越高但延遲越高。我的建議是召回優(yōu)先場景ef設(shè)64或128延遲敏感場景設(shè)32。關(guān)于建索引還有一個(gè)坑如果你先寫入數(shù)據(jù)再建索引當(dāng)數(shù)據(jù)量很大的時(shí)候建索引過程非常耗內(nèi)存和CPU生產(chǎn)環(huán)境最好在Collection創(chuàng)建好之后就立即建索引然后再灌數(shù)據(jù)。Milvus是支持在寫入過程中增量構(gòu)建索引的但如果先灌數(shù)據(jù)再觸發(fā)建索引遇到大數(shù)據(jù)量會(huì)產(chǎn)生明顯的IO抖動(dòng)。6.2 Java工程化里的數(shù)據(jù)一致性、并發(fā)與超時(shí)問題在實(shí)際接入過程中數(shù)據(jù)處理鏈路長不像單表CRUD那么簡單有幾點(diǎn)工程化細(xì)節(jié)值得單獨(dú)記一筆。首先是寫入一致性的保障。我的場景是從消息隊(duì)列里消費(fèi)到文檔后先解析、切分、向量化再寫入Milvus。如果向量化或?qū)懭脒^程中服務(wù)重啟了那這條文檔數(shù)據(jù)就丟了。為了避免這個(gè)問題我加了一個(gè)文檔狀態(tài)表用MySQL記錄每個(gè)文檔的切分?jǐn)?shù)量、向量化狀態(tài)和寫入狀態(tài)。流程是接收文檔 - 創(chuàng)建狀態(tài)記錄PENDING - 切分向量化 - 寫Milvus - 更新狀態(tài)為SUCCESS。下一次啟動(dòng)時(shí)掃描狀態(tài)為PENDING的文檔重新處理一遍這樣既保證了最終一致性又不會(huì)重復(fù)寫入大量數(shù)據(jù)。其次是并發(fā)問題。Java這邊用了線程池并發(fā)處理文檔切分和向量化但在調(diào)用ONNX模型做推理時(shí)OrtSession不是線程安全的并發(fā)推理需要做同步或者用線程局部變量。我的土辦法是每線程一個(gè)Session實(shí)例這樣既避免了鎖競爭又充分利用了多核CPU。MilvusClient倒是線程安全的可以直接并發(fā)調(diào)用但要注意控制并發(fā)度我壓測下來8到16個(gè)并發(fā)寫入或查詢線程都比較穩(wěn)定再高容易觸發(fā)Milvus端的連接池瓶頸。最后是超時(shí)和重試。Milvus的網(wǎng)絡(luò)交互是gRPC超時(shí)時(shí)間默認(rèn)比較長但業(yè)務(wù)接口不能讓用戶等太久。我給檢索接口設(shè)置了一個(gè)超時(shí)器超過2秒就暫時(shí)返回服務(wù)繁忙或走降級(jí)策略避免把連接池拖死。同時(shí)每次寫入操作都加了失敗重試邏輯重試三次間隔指數(shù)退避。這里我踩過的一個(gè)小坑是Milvus的insert操作不是冪等的如果客戶端寫超時(shí)后重試服務(wù)端可能已經(jīng)寫入成功導(dǎo)致同一條chunk插了兩遍。解決方法是插入前生成一個(gè)業(yè)務(wù)側(cè)唯一ID寫入時(shí)用這個(gè)ID作為主鍵靠autoID就不行要自己指定ID這樣重復(fù)插入就能被主鍵沖突擋住。6.3 檢索效果調(diào)優(yōu)從糟糕結(jié)果到可用狀態(tài)項(xiàng)目上線之后我調(diào)了一段時(shí)間的檢索效果。要知道向量檢索不是接完就完事的效果好壞受切分粒度、向量模型、查詢側(cè)文本處理、TopK參數(shù)等多重因素影響。這里把幾個(gè)性價(jià)比最高的優(yōu)化手段按優(yōu)先級(jí)列一下優(yōu)化項(xiàng)具體操作效果提升切分窗口從500字降到200到300字中檢索粒度更精準(zhǔn)添加指令前綴BGE模型查詢和文檔側(cè)都加前綴極大命中率翻倍元數(shù)據(jù)過濾檢索時(shí)優(yōu)先按category過濾高縮小搜索范圍結(jié)果重排序Top10召回后按原文輕量rerank高最后一條內(nèi)容質(zhì)量決定用戶體驗(yàn)去掉停用詞查詢文本清理的、了、呢小但穩(wěn)定重排序這步我很推薦做。最簡單的方式是Milvus先招回Top20然后把這20條chunk的文本和用戶問題再做一次余弦相似度重算取更精確的Top5返回給上游做答案生成。因?yàn)镸ilvus的ANN搜索本身是近似的Top20的精度可能不如Top5但重排序能把這部分誤差糾回來。我實(shí)際體驗(yàn)下來重排序后的結(jié)果比直接Top5的滿意度要高不少而且實(shí)現(xiàn)成本很低幾十行代碼的事。有個(gè)建議是把重排序邏輯和Milvus搜索解耦獨(dú)立成一個(gè)RerankService方便后續(xù)升級(jí)成CrossEncoder模型而不是每次都做余弦重算。如果你有精力做CrossEncoder的重排序會(huì)更專業(yè)模型效果相比普通余弦相似度有明顯代差。6.4 快速排錯(cuò)速查表最后把這段時(shí)間遇到的典型問題整理成一個(gè)速查表方便大家少走彎路現(xiàn)象大概率原因解決方式milvus connect failDocker依賴容器etcd/minio沒起用docker compose up -d全部拉起確認(rèn)健康狀態(tài)創(chuàng)建Collection報(bào)維度錯(cuò)誤模型輸出維度與Collection定義不一致打印模型輸出shape與字段dimension對(duì)齊查詢結(jié)果為空沒有寫入數(shù)據(jù)或expr過濾條件太嚴(yán)格先去掉過濾條件測試再用collection stats驗(yàn)證數(shù)據(jù)量查詢速度突然變慢向量字段沒建索引創(chuàng)建HNSW或IVF索引等待索引就緒插入時(shí)返回主鍵沖突自增ID被關(guān)閉且業(yè)務(wù)側(cè)指定了重復(fù)ID檢查ID生成邏輯或改用autoIDJava進(jìn)程內(nèi)存溢出批量插入數(shù)據(jù)量過大每次插入控制在1000條以內(nèi)及時(shí)釋放list結(jié)果語義相關(guān)性差沒加BGE指令前綴或切分窗口過大按上文添加前綴縮短切分窗口還有一個(gè)小細(xì)節(jié)Milvus的collection如果刪除重建之前的數(shù)據(jù)就徹底沒了所以生產(chǎn)環(huán)境一定不要在生產(chǎn)connection上隨便執(zhí)行dropCollection。我在開發(fā)環(huán)境就手滑過一次結(jié)果整個(gè)知識(shí)庫的向量數(shù)據(jù)全部清空重新跑了一遍全量入庫流程白白浪費(fèi)了一個(gè)下午。結(jié)尾分享這套Java接向量數(shù)據(jù)庫的方案已經(jīng)在我的知識(shí)庫項(xiàng)目里穩(wěn)定跑了兩個(gè)多月文檔入庫量累計(jì)超過20萬條chunk單次查詢平均耗時(shí)120毫秒左右數(shù)據(jù)安全性也因?yàn)槿镜鼗Ｐ投玫搅吮Ｕ稀Ｎ覀€(gè)人實(shí)操中的體會(huì)是向量數(shù)據(jù)庫本身不難接難的是把文檔怎么切、向量怎么生成、檢索怎么調(diào)優(yōu)這套鏈路想明白。如果你也在做類似項(xiàng)目建議先拿一個(gè)小數(shù)據(jù)集從切分和模型的前綴效果開始做起把每一步的結(jié)果都打印出來看一眼不要等到全鏈路完成再一起調(diào)試那是災(zāi)難。最后再分享一個(gè)小技巧每次修改切分策略或模型后別急著全量更新索引先選一個(gè)真實(shí)用戶查詢用新方案跑一遍對(duì)比一下返回的Top5結(jié)果效率最高。