簡(jiǎn)介面向 Java 開(kāi)發(fā)者的 RAG 增強(qiáng)檢索生成實(shí)戰(zhàn)項(xiàng)目完整展示如何將知識(shí)庫(kù)與語(yǔ)義檢索能力集成到可運(yùn)行的系統(tǒng)中適合希望掌握 RAG 落地路徑、需要企業(yè)級(jí)檢索場(chǎng)景參考的開(kāi)發(fā)者。壓縮包共 266 個(gè)文件以 231 個(gè) Java 源碼文件為主輔以 XML 配置、YML 環(huán)境配置、Dockerfile、SQL 腳本和 JAR 依賴等整體僅 14.32MB結(jié)構(gòu)清晰便于快速部署與二次開(kāi)發(fā)。已有 1651 人學(xué)習(xí)下載。項(xiàng)目不僅包含可運(yùn)行源碼還提供流程教程從知識(shí)庫(kù)構(gòu)建、向量存儲(chǔ)、檢索服務(wù)到 LLM 調(diào)用均有完整實(shí)現(xiàn)同時(shí)覆蓋用戶管理、圖片生成等擴(kuò)展能力可直接移植到企業(yè)內(nèi)部知識(shí)庫(kù)、在線問(wèn)答等場(chǎng)景中使用。1. RAG 與 Java 的結(jié)合點(diǎn)為什么說(shuō)這是增強(qiáng)檢索最值得先跑通的項(xiàng)目先拋一個(gè)反直覺(jué)的結(jié)論很多團(tuán)隊(duì)把 RAG 做成「簡(jiǎn)歷級(jí) Demo」只需要一個(gè)周末但生產(chǎn)可用卻卡在知識(shí)庫(kù)切分和檢索召回這兩步上跟用什么語(yǔ)言寫大模型調(diào)用反而關(guān)系不大。這個(gè)基于 Java 實(shí)現(xiàn)的 RAG 項(xiàng)目恰好把這兩塊做成了完整閉環(huán)——自帶知識(shí)庫(kù)模塊、文檔解析與切分、向量化檢索、Top-K 召回最后才是與大模型的 Prompt 組裝。也就是說(shuō)你拿到的不是一條「調(diào)接口」的腳本而是一套從文檔入庫(kù)到答案生成都能在本地跑通的工程骨架。適合誰(shuí)首先是在 Java 技術(shù)棧里做內(nèi)部知識(shí)庫(kù)問(wèn)答的團(tuán)隊(duì)其次是想理解 RAG 全鏈路、但不想從零開(kāi)始寫分詞和向量檢索的工程師。項(xiàng)目源碼里把流程教程也帶上了這意味著你既能當(dāng)項(xiàng)目抄也能當(dāng)教材拆。下面按我拆這類項(xiàng)目的習(xí)慣從知識(shí)庫(kù)構(gòu)建、檢索鏈路、生成接入、坑點(diǎn)排查一路講到參數(shù)調(diào)優(yōu)。2. 項(xiàng)目骨架與知識(shí)庫(kù)構(gòu)建從原始文檔到可檢索的語(yǔ)料2.1 模塊劃分與啟動(dòng)入口拿到源碼后第一件事不是看代碼而是先把模塊邊界理清楚。這個(gè)項(xiàng)目按 RAG 的標(biāo)準(zhǔn)三段式組織ingestion負(fù)責(zé)文檔加載與切分retriever負(fù)責(zé)向量化和召回generator負(fù)責(zé)與大模型交互。另外有一個(gè)獨(dú)立的config包存放知識(shí)庫(kù)路徑、模型地址、閾值參數(shù)全部收斂在application.yml。git clone 項(xiàng)目地址 rag-java cd rag-java mvn clean package -DskipTests java -jar target/rag-demo.jar --spring.profiles.activedev啟動(dòng)之后留意控制臺(tái)日志正常會(huì)打印「知識(shí)庫(kù)加載完成」和「向量索引初始化完成」兩行。如果只看到前者說(shuō)明檢索組件沒(méi)起來(lái)多數(shù)情況是向量模型路徑配置錯(cuò)了后面避坑章節(jié)會(huì)細(xì)說(shuō)。2.2 文檔解析與切分策略知識(shí)庫(kù)最常見(jiàn)的數(shù)據(jù)來(lái)源是 Word、PDF、Markdown 和純文本這個(gè)項(xiàng)目里統(tǒng)一走DocumentParser接口再按擴(kuò)展名分發(fā)到具體實(shí)現(xiàn)。切分策略是整條流水線里最影響檢索質(zhì)量的一環(huán)——切得太粗一段文本里混入多個(gè)主題召回噪聲大切得太細(xì)語(yǔ)義被割裂很多片段單獨(dú)拿出來(lái)根本讀不通。// TextSplitter.java 核心片段 public ListTextChunk split(String content, SplitConfig config) { int chunkSize config.getChunkSize(); // 單塊字?jǐn)?shù)默認(rèn) 400 int overlapSize config.getOverlapSize(); // 相鄰塊重疊字?jǐn)?shù)默認(rèn) 80 ListString sentences splitIntoSentences(content, config.getLanguage()); ListTextChunk chunks new ArrayList(); StringBuilder buffer new StringBuilder(); for (String sentence : sentences) { if (buffer.length() sentence.length() chunkSize buffer.length() 0) { chunks.add(new TextChunk(buffer.toString())); int overlapStart Math.max(0, buffer.length() - overlapSize); buffer.setLength(0); buffer.append(buffer.substring(overlapStart)); } buffer.append(sentence); } if (buffer.length() 0) { chunks.add(new TextChunk(buffer.toString())); } return chunks; }邏輯說(shuō)明按句切分而不是按固定長(zhǎng)度硬切是為了避免一句話被攔腰截?cái)喑^(guò)chunkSize的句子會(huì)單獨(dú)成塊保證每塊都有相對(duì)完整的語(yǔ)義單元。overlapStart的取值是關(guān)鍵它把上一塊的尾部 80 字帶到下一塊開(kāi)頭讓跨塊引用的信息能同時(shí)出現(xiàn)在兩個(gè) chunk 里。參數(shù)建議內(nèi)部文檔以術(shù)語(yǔ)密集為特點(diǎn)chunkSize可以降到 300overlapSize保持 80如果是對(duì)話記錄或新聞?wù)Z料chunkSize調(diào)到 500 效果更好。切忌把 overlap 設(shè)得比 chunk 的一半還大那會(huì)造成同一段內(nèi)容被多次索引檢索結(jié)果千篇一律。2.3 知識(shí)庫(kù)存儲(chǔ)結(jié)構(gòu)設(shè)計(jì)這個(gè)項(xiàng)目把切分后的 chunk 存進(jìn)內(nèi)置的 Lucene 索引目錄同時(shí)把每個(gè) chunk 對(duì)應(yīng)的原始文檔路徑當(dāng)成元數(shù)據(jù)一并存儲(chǔ)。這樣做的直接好處是檢索命中之后你能立刻知道答案來(lái)自哪份文檔的哪個(gè)位置對(duì)后續(xù)人工校驗(yàn)非常重要。-- 索引結(jié)構(gòu)示意實(shí)際為 Lucene Document 字段 -- doc_id: 唯一標(biāo)識(shí) -- content: 切分后的文本塊 -- source: 原始文件名 頁(yè)碼 -- chunk_seq: 塊在文檔中的序號(hào) -- embed: 768 維向量由 EmbeddingService 生成如果你打算改成 MySQL 存儲(chǔ)建議不要省掉chunk_seq這個(gè)字段。之前我有一次排查「同一段答案反復(fù)出現(xiàn)」的問(wèn)題最后發(fā)現(xiàn)是檢索時(shí)只按相似度排序沒(méi)有按文檔內(nèi)順序約束導(dǎo)致匹配到的塊都是同一篇文章里最相似的段落。加上chunk_seq做二次排序體驗(yàn)立刻正常。3. 檢索層實(shí)現(xiàn)向量召回與關(guān)鍵詞召回的雙路策略3.1 文本向量化與模型接入向量化是 RAG 與普通全文檢索的分水嶺。這個(gè)項(xiàng)目里的EmbeddingService預(yù)留了兩種接入方式本地加載 ONNX 格式的 Embedding 模型以及遠(yuǎn)程調(diào)用 HTTP 接口。生產(chǎn)環(huán)境我一般推薦遠(yuǎn)程接口因?yàn)楸镜啬Ｐ偷膬?nèi)存開(kāi)銷遠(yuǎn)比想象中大但項(xiàng)目默認(rèn)走本地加載方便離線調(diào)試。// EmbeddingService.java public float[] embed(String text) { // 1. 文本標(biāo)準(zhǔn)化去除多余空格、統(tǒng)一全半角 String normalized normalize(text); // 2. 調(diào)用本地 ONNX 模型或遠(yuǎn)程接口 if (localMode) { return localEmbedder.embed(normalized); } // 3. 遠(yuǎn)程模式需要設(shè)置超時(shí)避免檢索鏈路被外部拖死 return remoteEmbedder.embedWithTimeout(normalized, 3000); }這里有一個(gè)非常容易被忽略的細(xì)節(jié)查詢語(yǔ)句和知識(shí)庫(kù)文本必須走同一個(gè)預(yù)處理函數(shù)。如果你在入庫(kù)時(shí)做了全角轉(zhuǎn)半角檢索時(shí)不轉(zhuǎn)向量就會(huì)產(chǎn)生偏差。這個(gè)項(xiàng)目把normalize放在embed內(nèi)部保證所有入?yún)⒍歼^(guò)一遍算是比很多開(kāi)源實(shí)現(xiàn)嚴(yán)謹(jǐn)?shù)牡胤健?.2 相似度計(jì)算與 Top-K 選擇向量檢索的相似度計(jì)算項(xiàng)目里同時(shí)實(shí)現(xiàn)了余弦相似度和內(nèi)積兩種方式。默認(rèn)用余弦相似度因?yàn)樗皇芟蛄磕ｉL(zhǎng)影響對(duì) Embedding 模型的直接輸出更友好。內(nèi)積適合已歸一化的向量計(jì)算速度略快但語(yǔ)義區(qū)分度稍弱。// VectorSearch.java public ListSearchHit search(float[] queryVector, int topK) { PriorityQueueSearchHit queue new PriorityQueue(topK); for (VectorDoc doc : vectorStore.getAll()) { double score cosineSimilarity(queryVector, doc.getVector()); queue.offer(new SearchHit(doc.getDocId(), doc.getSource(), score)); if (queue.size() topK) { queue.poll(); // 淘汰最小分 } } ListSearchHit result new ArrayList(queue); result.sort(Comparator.comparingDouble(SearchHit::getScore).reversed()); return result; }邏輯說(shuō)明用小頂堆做 Top-K 而不是全量排序后取前 K是工程上的常規(guī)優(yōu)化——當(dāng)知識(shí)庫(kù)有幾萬(wàn)條文本時(shí)全量排序的內(nèi)存和耗時(shí)都不可接受。堆的大小固定為topK每次插入新元素后彈出最小分保證堆內(nèi)始終是當(dāng)前最大的 K 個(gè)。參數(shù)選擇topK建議在 310 之間。知識(shí)庫(kù)越大單塊信息密度越低topK可以適當(dāng)調(diào)大。但不要一上來(lái)就設(shè) 20召回太多塊塞進(jìn) Prompt大模型的注意力會(huì)被稀釋回答反而變差。3.3 混合檢索的融合排序純粹靠向量檢索有兩個(gè)典型短板專業(yè)縮寫詞比如「RAG」本身就是縮寫的向量表達(dá)不穩(wěn)定以及精確 ID 號(hào)、工單編號(hào)這類場(chǎng)景向量相似度遠(yuǎn)不如字符串匹配可靠。這個(gè)項(xiàng)目在檢索模塊里實(shí)現(xiàn)了關(guān)鍵詞檢索與向量檢索的加權(quán)融合。// HybridRetriever.java public ListSearchHit hybridSearch(String query, int topK, double vectorWeight) { ListSearchHit vectorHits vectorSearcher.search(query, topK * 2); ListSearchHit keywordHits keywordSearcher.search(query, topK * 2); MapString, SearchHit merged new LinkedHashMap(); for (SearchHit hit : vectorHits) { hit.setScore(hit.getScore() * vectorWeight); merged.put(hit.getDocId(), hit); } for (SearchHit hit : keywordHits) { merged.merge(hit.getDocId(), hit, (oldHit, newHit) - new SearchHit(hit.getDocId(), hit.getSource(), oldHit.getScore() hit.getScore() * (1 - vectorWeight))); } return merged.values().stream() .sorted(Comparator.comparingDouble(SearchHit::getScore).reversed()) .limit(topK) .collect(Collectors.toList()); }邏輯說(shuō)明兩次召回都取了topK * 2的候選目的是給融合排序留出緩沖避免單路召回漏掉關(guān)鍵結(jié)果后直接沒(méi)得可融。合并時(shí)同一個(gè)docId會(huì)累加兩路得分這相當(dāng)于給「既被向量命中又被關(guān)鍵詞命中」的文本加權(quán)實(shí)際檢索效果比單路穩(wěn)定很多。vectorWeight的默認(rèn)值可以設(shè) 0.7即向量召回為主、關(guān)鍵詞兜底。如果知識(shí)庫(kù)里有大量代碼片段、報(bào)錯(cuò)日志這類文本的關(guān)鍵詞特征遠(yuǎn)比語(yǔ)義特征明顯把權(quán)重調(diào)到 0.5 以下會(huì)更合理。4. 生成鏈路把檢索結(jié)果安全地送給大模型4.1 Prompt 組裝與上下文窗口控制檢索只是手段答案生成才是用戶能感知的結(jié)果。這個(gè)項(xiàng)目在generator模塊里把檢索到的文本塊組裝成帶編號(hào)的上下文再拼上用戶問(wèn)題一次交給大模型。組裝順序不是簡(jiǎn)單的拼接而是按文本塊的得分從高到低排列保證模型最先看到最相關(guān)的證據(jù)。// PromptBuilder.java public String build(SearchRequest request, ListSearchHit hits) { StringBuilder context new StringBuilder(); context.append(請(qǐng)基于以下資料回答問(wèn)題如果你不確定答案請(qǐng)直接說(shuō)明。\n\n); for (int i 0; i hits.size(); i) { SearchHit hit hits.get(i); context.append(【資料).append(i 1).append(】) .append(來(lái)源).append(hit.getSource()).append(\n) .append(hit.getContent()).append(\n\n); } context.append(問(wèn)題).append(request.getQuestion()); return context.toString(); }這段代碼里有三個(gè)容易被忽視的細(xì)節(jié)。一是「來(lái)源」字段被強(qiáng)行帶進(jìn) Prompt讓模型在回答時(shí)可以引用出處二是「不確定就說(shuō)明」這句限定語(yǔ)能顯著降低模型編造答案的概率三是資料數(shù)控制在 5 條以內(nèi)避免上下文過(guò)長(zhǎng)。4.2 上下文窗口與 Token 預(yù)算上下文窗口控制是生成鏈路里最容易翻車的環(huán)節(jié)。很多模型對(duì)外宣稱支持 8K 甚至更大的上下文但實(shí)際效果在超過(guò)一定長(zhǎng)度后急劇下降。項(xiàng)目里給出了一個(gè)ContextWindowGuard工具類核心邏輯很簡(jiǎn)單估算每個(gè)文本塊的 Token 數(shù)超出預(yù)算直接丟棄得分最低的塊。// ContextWindowGuard.java public ListSearchHit fitToWindow(ListSearchHit hits, int maxTokens) { ListSearchHit filtered new ArrayList(); int used 0; for (SearchHit hit : hits) { int tokens estimateTokens(hit.getContent()); if (used tokens maxTokens) { break; } filtered.add(hit); used tokens; } return filtered; }為什么必須丟棄而不是截?cái)嘁驗(yàn)榻財(cái)鄷?huì)恰好切在某個(gè)文本塊的中間大模型看到的是一段語(yǔ)義殘缺的文字比不看這段還糟糕。丟棄低分塊至少保證接進(jìn)來(lái)的內(nèi)容都是完整的。另一個(gè)相關(guān)部門是請(qǐng)求超時(shí)。調(diào)用大模型接口時(shí)生成速度受輸入長(zhǎng)度影響很大這個(gè)項(xiàng)目把連接超時(shí)設(shè)為 3 秒、讀取超時(shí)設(shè)為 30 秒。如果你接入的是本地部署的模型讀取超時(shí)可以放寬到 60 秒但連接超時(shí)建議保持短避免模型服務(wù)掛了之后請(qǐng)求一直掛著。5. 避坑與排查RAG 在 Java 工程里的常見(jiàn)問(wèn)題5.1 中文亂碼導(dǎo)致檢索結(jié)果「仿佛失憶」現(xiàn)象知識(shí)庫(kù)能加載但無(wú)論怎么搜都召不回正確的文本塊甚至檢索結(jié)果一片空白。原因Windows 環(huán)境下默認(rèn)字符集是 GBK項(xiàng)目里讀文件用的是Files.readAllLines且沒(méi)指定 charset中文文本入庫(kù)時(shí)就變成亂碼向量化出來(lái)的向量也是錯(cuò)亂的。解決把讀文件的地方統(tǒng)一改成顯式指定 UTF-8Files.readAllLines(path, StandardCharsets.UTF_8)。我在接手任何 Java 項(xiàng)目時(shí)第一步就是全局搜readAllLines和FileReader看到?jīng)]帶 charset 的一律改掉。5.2 向量化耗時(shí)過(guò)長(zhǎng)接口超時(shí)現(xiàn)象第一次啟動(dòng)時(shí)建索引可以接受但運(yùn)行期間每來(lái)一個(gè)查詢都要等好幾秒才能返回。原因Embedding 服務(wù)是同步調(diào)用的查詢請(qǐng)求里把「問(wèn)題向量化」和「知識(shí)庫(kù)文本向量化」串行執(zhí)行了。更隱蔽的是有些實(shí)現(xiàn)會(huì)在每次查詢時(shí)重新計(jì)算整個(gè)知識(shí)庫(kù)的向量而不是復(fù)用啟動(dòng)時(shí)構(gòu)建的索引。解決把向量索引的構(gòu)建放到啟動(dòng)階段查詢階段只做「問(wèn)題向量化 索引搜索」。如果你改造成異步接口記得給 Embedding 調(diào)用加緩存——同一個(gè)問(wèn)題短時(shí)間內(nèi)重復(fù)查詢沒(méi)必要重新向量化。5.3 上下文溢出直接報(bào)錯(cuò)現(xiàn)象知識(shí)庫(kù)單塊字?jǐn)?shù)設(shè)置過(guò)大檢索命中的幾塊加起來(lái)超過(guò)模型輸入限制調(diào)用時(shí)報(bào)context length exceeded之類錯(cuò)誤。原因chunkSize設(shè)得太大比如超過(guò) 1000 字再加上 5 塊一起注入Token 數(shù)輕松破萬(wàn)。責(zé)任不在模型在切分參數(shù)。解決把chunkSize降到 400 以下把ContextWindowGuard的maxTokens設(shè)成模型上限的 80%。留出 20% 余量因?yàn)?Prompt 模板本身、問(wèn)題文本、系統(tǒng)提示也都要吃 Token。5.4 檢索結(jié)果順序不穩(wěn)定現(xiàn)象同樣的查詢兩次運(yùn)行命中的內(nèi)容差不多但排序不同導(dǎo)致生成答案的文字組織方式有差異。原因許多 Embedding 模型在計(jì)算文本向量時(shí)引入了隨機(jī)性或者向量索引的排序沒(méi)對(duì)得分相同的文本塊做二次穩(wěn)定排序。解決在hit.getScore()相同的情況下按docId升序排列。代價(jià)是結(jié)果順序確定用戶感知一致性明顯提升。6. 檢索效果自檢三個(gè)硬指標(biāo)和一套壓測(cè)流程這個(gè)項(xiàng)目跑通并不代表它「好用」。我一般會(huì)在交付前做一輪檢索質(zhì)量自檢三個(gè)指標(biāo)就能暴露大部分問(wèn)題。第一個(gè)是召回準(zhǔn)確率從知識(shí)庫(kù)里挑 30 個(gè)有明確答案的問(wèn)題人工標(biāo)注正確答案所在的文本塊跑一遍檢索鏈路看前 5 條召回里是否包含標(biāo)注塊低于 80% 就得調(diào)整切分參數(shù)或檢查向量化質(zhì)量。第二個(gè)是答案可溯源比例讓大模型生成的答案必須帶出「來(lái)源文檔」字段統(tǒng)計(jì)能正確命中的比例。第三個(gè)是響應(yīng)耗時(shí)從查詢到達(dá)服務(wù)到答案完全生成這個(gè)值決定了你能不能把接口對(duì)外放出。# 壓測(cè)腳本片段模擬查詢并發(fā) seq 1 50 | xargs -P 10 -I {} curl -s -X POST http://localhost:8080/api/rag/query \ -H Content-Type: application/json \ -d {question:什么是RAG增強(qiáng)檢索} \ -o /tmp/response_{}.json壓測(cè)之后重點(diǎn)看 P95 耗時(shí)而不是平均值——平均值會(huì)被少數(shù)慢請(qǐng)求拉高P95 更接近普通用戶的真實(shí)體驗(yàn)。如果 P95 超過(guò) 5 秒優(yōu)先檢查 Embedding 服務(wù)的耗時(shí)如果模型生成占大頭考慮降低topK或把ContextWindowGuard的預(yù)算收緊。我個(gè)人的習(xí)慣是每換一次知識(shí)庫(kù)語(yǔ)料類型就強(qiáng)制走一遍上述流程并且把每一輪的自檢結(jié)果提交到項(xiàng)目倉(cāng)庫(kù)里。這樣做的好處是團(tuán)隊(duì)里任何人改過(guò)參數(shù)之后都能對(duì)比前后兩輪的召回指標(biāo)而不是靠感覺(jué)判斷「好像變好了」。從那以后我每次接觸新的 RAG 項(xiàng)目都會(huì)先問(wèn)一句你的評(píng)估集在哪沒(méi)有評(píng)估集的檢索系統(tǒng)就是裸奔。這個(gè) Java 項(xiàng)目把流程教程和源碼都備齊了希望幫你在正式上線前把這一步補(bǔ)上。本文還有配套的精品資源點(diǎn)擊獲取