SpringBoot 3.5 + AI RAG實戰：從向量檢索到智能問答的6種生產模式
AI与大数据
Java開發者的AI困境：會寫代碼，卻不會讓代碼「懂知識」
你花了三個月訓練了一個企業知識庫大模型，上線第一天用戶就問了個模型沒見過的內部術語，模型一本正經地胡說八道。
這不是段子，這是2026年Java團隊做AI落地的真實寫照。大模型有推理能力，但沒有你的企業數據；你的數據庫有數據，但沒有推理能力。 RAG（檢索增強生成）就是連接兩者的橋樑。
但問題來了——Python生態的RAG教程滿天飛，Java生態卻幾乎一片空白。Spring AI雖然1.0已GA，但文檔裡的RAG示例還停留在「Hello World」級別。生產級RAG需要什麼？向量存儲選型、文檔分塊策略、混合檢索、對話記憶、流水線編排、監控告警——缺一不可。
本文基於SpringBoot 3.5 + Spring AI 1.0，給出6種可直接用於生產的RAG模式，每種模式附帶完整可運行的Java代碼。
核心收穫
- 掌握Spring AI + PgVector向量存儲的完整集成方案
- 理解文檔分塊與嵌入生成的最佳實踐與性能調優
- 實現向量+關鍵詞混合檢索，召回率提升40%+
- 構建帶對話記憶的多輪問答系統
- 學會RAG流水線編排與生產環境部署監控
- 避開5個最常見的RAG落地陷阱
目錄
- RAG架構全景
- 模式一：Spring AI + PgVector向量存儲集成
- 模式二：文檔分塊與嵌入生成
- 模式三：混合檢索（向量+關鍵詞）
- 模式四：對話記憶與多輪問答
- 模式五：RAG流水線編排
- 模式六：生產環境部署與監控
- 5個常見坑及解決方案
- 10個常見報錯排查
- 進階優化技巧
- 對比分析：3種向量數據庫方案
- 在線工具推薦
RAG架構全景
RAG不是簡單的「先搜後答」，而是一條完整的知識處理流水線：
┌─────────────────────────────────────────────────────────────────────┐
│ RAG 完整架構 (SpringBoot 3.5) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 離線索引階段 │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ 文檔加載 │───▶│ 文檔分塊 │───▶│ 嵌入生成 │───▶│ 向量存儲 │ │
│ │ PDF/DOCX │ │ Chunking │ │ Embedding│ │ PgVector │ │
│ │ Markdown │ │ 512token │ │ OpenAI │ │ Milvus │ │
│ │ HTML │ │ 重疊64 │ │ BGE │ │ Chroma │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 在線查詢階段 │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ 用戶提問 │───▶│ 混合檢索 │───▶│ 上下文組裝│───▶│ LLM生成 │ │
│ │ Query │ │ 向量+BM25│ │ Prompt │ │ GPT-4o │ │
│ │ │ │ Rerank │ │ Template │ │ DeepSeek │ │
│ │ │ │ │ │ │ │ Qwen │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ │ ┌──────────┐ │ │
│ └─────────────▶│ 對話記憶 │◀───────────────────┘ │
│ │ Redis │ │
│ │ Window │ │
│ └──────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 可觀測性 & 治理層 │ │
│ │ OpenTelemetry · Prometheus · 告警 · 限流 · 熔斷 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
為什麼選擇SpringBoot 3.5做RAG
| 特性 | SpringBoot 3.5 | Python FastAPI |
|---|---|---|
| 虛擬線程 | 原生支持，IO密集型吞吐提升5x | 不支持 |
| 向量存儲抽象 | VectorStore統一接口 | 各庫API不統一 |
| 依賴注入 | 自動裝配，零樣板代碼 | 手動管理生命週期 |
| 流式響應 | WebFlux + Flux | SSE手動實現 |
| 企業安全 | Spring Security集成 | 需額外中間件 |
| 監控 | Actuator + Micrometer | 需自行集成 |
模式一：Spring AI + PgVector向量存儲集成
PgVector是PostgreSQL的向量擴展，對Java團隊來說最大的優勢是運維零學習成本——你已有的PG實例加個擴展就能跑。
1.1 環境準備
-- 在PostgreSQL中啟用pgvector擴展
CREATE EXTENSION IF NOT EXISTS vector;
-- 創建向量存儲表（Spring AI可自動創建，這裡展示表結構）
CREATE TABLE vector_store (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
content TEXT NOT NULL,
metadata JSONB DEFAULT '{}',
embedding VECTOR(1536) -- OpenAI text-embedding-3-small維度
);
-- 創建HNSW索引（比IVFFlat更適合生產）
CREATE INDEX ON vector_store
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
1.2 Maven依賴配置
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
</dependency>
</dependencies>
1.3 應用配置
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
base-url: ${OPENAI_BASE_URL:https://api.openai.com}
embedding:
options:
model: text-embedding-3-small
vectorstore:
pgvector:
index-type: HNSW
distance-type: COSINE
dimensions: 1536
initialize-schema: true
datasource:
url: jdbc:postgresql://localhost:5432/rag_db
username: ${PG_USERNAME}
password: ${PG_PASSWORD}
hikari:
maximum-pool-size: 20
minimum-idle: 5
1.4 向量存儲服務
@Service
public class VectorStoreService {
private final VectorStore vectorStore;
private final EmbeddingModel embeddingModel;
public VectorStoreService(VectorStore vectorStore, EmbeddingModel embeddingModel) {
this.vectorStore = vectorStore;
this.embeddingModel = embeddingModel;
}
public void indexDocument(String content, Map<String, Object> metadata) {
Document document = new Document(content, metadata);
vectorStore.add(List.of(document));
}
public void indexDocuments(List<Document> documents) {
vectorStore.add(documents);
}
public List<Document> search(String query, int topK) {
return vectorStore.similaritySearch(
SearchRequest.builder()
.query(query)
.topK(topK)
.similarityThreshold(0.7)
.build()
);
}
public List<Document> searchWithFilter(String query, int topK, String filterExpression) {
return vectorStore.similaritySearch(
SearchRequest.builder()
.query(query)
.topK(topK)
.similarityThreshold(0.7)
.filterExpression(filterExpression)
.build()
);
}
public void deleteDocuments(List<String> ids) {
vectorStore.delete(ids);
}
}
1.5 REST API暴露
@RestController
@RequestMapping("/api/v1/vectors")
public class VectorStoreController {
private final VectorStoreService vectorStoreService;
public VectorStoreController(VectorStoreService vectorStoreService) {
this.vectorStoreService = vectorStoreService;
}
@PostMapping("/index")
public ResponseEntity<String> indexDocument(@RequestBody IndexRequest request) {
vectorStoreService.indexDocument(request.content(), request.metadata());
return ResponseEntity.ok("Document indexed successfully");
}
@PostMapping("/search")
public ResponseEntity<List<SearchResult>> search(@RequestBody SearchRequestDto request) {
List<Document> results = vectorStoreService.search(request.query(), request.topK());
List<SearchResult> searchResults = results.stream()
.map(doc -> new SearchResult(
doc.getId(),
doc.getText(),
doc.getMetadata(),
(Double) doc.getMetadata().get("distance")
))
.toList();
return ResponseEntity.ok(searchResults);
}
@PostMapping("/search/filtered")
public ResponseEntity<List<SearchResult>> searchWithFilter(
@RequestBody FilteredSearchRequest request) {
List<Document> results = vectorStoreService.searchWithFilter(
request.query(), request.topK(), request.filterExpression()
);
List<SearchResult> searchResults = results.stream()
.map(doc -> new SearchResult(
doc.getId(),
doc.getText(),
doc.getMetadata(),
(Double) doc.getMetadata().get("distance")
))
.toList();
return ResponseEntity.ok(searchResults);
}
@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteDocument(@PathVariable String id) {
vectorStoreService.deleteDocuments(List.of(id));
return ResponseEntity.noContent().build();
}
}
record IndexRequest(String content, Map<String, Object> metadata) {}
record SearchRequestDto(String query, int topK) {}
record FilteredSearchRequest(String query, int topK, String filterExpression) {}
record SearchResult(String id, String content, Map<String, Object> metadata, Double distance) {}
1.6 元數據過濾實戰
Spring AI支持SQL風格的元數據過濾，這在多租戶場景下非常關鍵：
@Service
public class MetadataFilterService {
private final VectorStore vectorStore;
public MetadataFilterService(VectorStore vectorStore) {
this.vectorStore = vectorStore;
}
public List<Document> searchByTenant(String query, String tenantId) {
return vectorStore.similaritySearch(
SearchRequest.builder()
.query(query)
.topK(5)
.filterExpression("tenantId == '" + tenantId + "'")
.build()
);
}
public List<Document> searchByDepartmentAndDate(
String query, String department, String dateAfter) {
return vectorStore.similaritySearch(
SearchRequest.builder()
.query(query)
.topK(5)
.filterExpression(
"department == '" + department + "' && createdAt >= '" + dateAfter + "'"
)
.build()
);
}
public List<Document> searchByTags(String query, List<String> tags) {
String tagFilter = tags.stream()
.map(tag -> "tags.contains('" + tag + "')")
.collect(Collectors.joining(" || "));
return vectorStore.similaritySearch(
SearchRequest.builder()
.query(query)
.topK(5)
.filterExpression(tagFilter)
.build()
);
}
}
模式二：文檔分塊與嵌入生成
分塊策略直接決定RAG效果的上限。分塊太大，檢索噪聲多；分塊太小，語義不完整。
2.1 分塊策略對比
| 策略 | 適用場景 | 優點 | 缺點 |
|---|---|---|---|
| 固定大小分塊 | 通用文檔 | 實現簡單，性能穩定 | 可能切斷語義 |
| 遞歸字符分塊 | Markdown/代碼 | 保留結構邊界 | 需要調參 |
| 語義分塊 | 高質量文檔 | 語義完整性最好 | 計算成本高 |
| 句子窗口分塊 | 精確問答 | 上下文豐富 | 存儲開銷大 |
2.2 Spring AI文檔處理流水線
@Configuration
public class DocumentProcessingConfig {
@Bean
public DocumentTransformer documentTransformer() {
return new TokenTextSplitter(
512, // defaultChunkSize
64, // minChunkSizeChars
64, // maxNumChunks
true, // keepSeparator
null // separators 自定義分隔符
);
}
@Bean
public DocumentReader markdownReader() {
return new MarkdownDocumentReader(
new ClassPathResource("docs/knowledge-base.md"),
MarkdownDocumentReaderConfig.builder()
.withHorizontalRuleCreateDocument(true)
.withIncludeCodeBlock(true)
.withIncludeBlockquote(true)
.withAdditionalMetadata("source", "knowledge-base")
.build()
);
}
}
2.3 自定義分塊策略
@Service
public class CustomChunkingService {
private final EmbeddingModel embeddingModel;
public CustomChunkingService(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
}
public List<Document> chunkWithOverlap(String content, int chunkSize, int overlap) {
List<Document> chunks = new ArrayList<>();
int start = 0;
int chunkIndex = 0;
while (start < content.length()) {
int end = Math.min(start + chunkSize, content.length());
String chunkText = content.substring(start, end);
Map<String, Object> metadata = new HashMap<>();
metadata.put("chunkIndex", chunkIndex);
metadata.put("startOffset", start);
metadata.put("endOffset", end);
metadata.put("totalChunks", (content.length() + chunkSize - 1) / chunkSize);
chunks.add(new Document(chunkText, metadata));
start += chunkSize - overlap;
chunkIndex++;
}
return chunks;
}
public List<Document> chunkMarkdownByHeaders(String markdownContent) {
List<Document> chunks = new ArrayList<>();
String[] sections = markdownContent.split("(?=^#{1,6}\\s)");
for (String section : sections) {
if (section.isBlank()) continue;
String[] lines = section.split("\n", 2);
String header = lines[0].trim();
String body = lines.length > 1 ? lines[1].trim() : "";
if (body.length() > 512) {
List<Document> subChunks = chunkWithOverlap(body, 512, 64);
for (Document subChunk : subChunks) {
subChunk.getMetadata().put("sectionHeader", header);
chunks.add(subChunk);
}
} else if (!body.isEmpty()) {
Map<String, Object> metadata = new HashMap<>();
metadata.put("sectionHeader", header);
chunks.add(new Document(body, metadata));
}
}
return chunks;
}
public List<Document> chunkWithSemanticBoundary(String text, int maxChunkSize) {
String[] sentences = text.split("(?<=[。！？.!?])");
List<Document> chunks = new ArrayList<>();
StringBuilder currentChunk = new StringBuilder();
for (String sentence : sentences) {
if (currentChunk.length() + sentence.length() > maxChunkSize
&& currentChunk.length() > 0) {
Map<String, Object> metadata = new HashMap<>();
metadata.put("chunkStrategy", "semantic");
metadata.put("sentenceCount", countSentences(currentChunk.toString()));
chunks.add(new Document(currentChunk.toString().trim(), metadata));
currentChunk = new StringBuilder();
}
currentChunk.append(sentence);
}
if (currentChunk.length() > 0) {
Map<String, Object> metadata = new HashMap<>();
metadata.put("chunkStrategy", "semantic");
chunks.add(new Document(currentChunk.toString().trim(), metadata));
}
return chunks;
}
private int countSentences(String text) {
return text.split("[。！？.!?]").length;
}
}
2.4 批量嵌入生成與索引
@Service
public class EmbeddingIndexService {
private static final int BATCH_SIZE = 100;
private final VectorStore vectorStore;
private final DocumentTransformer textSplitter;
private final CustomChunkingService customChunkingService;
public EmbeddingIndexService(
VectorStore vectorStore,
DocumentTransformer textSplitter,
CustomChunkingService customChunkingService) {
this.vectorStore = vectorStore;
this.textSplitter = textSplitter;
this.customChunkingService = customChunkingService;
}
@Async
public CompletableFuture<Integer> indexFile(Resource resource, String source) {
try {
DocumentReader reader = createReader(resource, source);
List<Document> documents = reader.get();
List<Document> splitDocuments = textSplitter.apply(documents);
for (int i = 0; i < splitDocuments.size(); i += BATCH_SIZE) {
List<Document> batch = splitDocuments.subList(
i, Math.min(i + BATCH_SIZE, splitDocuments.size())
);
vectorStore.add(batch);
}
return CompletableFuture.completedFuture(splitDocuments.size());
} catch (Exception e) {
return CompletableFuture.failedFuture(e);
}
}
public int indexMarkdownContent(String content, String source) {
List<Document> chunks = customChunkingService.chunkMarkdownByHeaders(content);
chunks.forEach(doc -> doc.getMetadata().putIfAbsent("source", source));
for (int i = 0; i < chunks.size(); i += BATCH_SIZE) {
List<Document> batch = chunks.subList(
i, Math.min(i + BATCH_SIZE, chunks.size())
);
vectorStore.add(batch);
}
return chunks.size();
}
public int reindexAll(List<Resource> resources) {
return resources.parallelStream()
.mapToInt(resource -> {
try {
DocumentReader reader = createReader(resource, resource.getFilename());
List<Document> documents = reader.get();
List<Document> splitDocuments = textSplitter.apply(documents);
vectorStore.add(splitDocuments);
return splitDocuments.size();
} catch (Exception e) {
return 0;
}
})
.sum();
}
private DocumentReader createReader(Resource resource, String source) {
String filename = resource.getFilename();
if (filename != null && filename.endsWith(".md")) {
return new MarkdownDocumentReader(
resource,
MarkdownDocumentReaderConfig.builder()
.withAdditionalMetadata("source", source)
.build()
);
}
return new TextReader(resource);
}
}
2.5 嵌入模型性能對比
| 模型 | 維度 | 速度(tokens/s) | 質量(MTEB) | 價格(/1M tokens) |
|---|---|---|---|---|
| text-embedding-3-small | 1536 | 15000 | 62.3% | $0.02 |
| text-embedding-3-large | 3072 | 8000 | 64.5% | $0.13 |
| BGE-M3 | 1024 | 12000 | 63.1% | 免費(自部署) |
| bge-large-zh-v1.5 | 1024 | 10000 | 64.2%(中文) | 免費(自部署) |
模式三：混合檢索（向量+關鍵詞）
純向量檢索在專有名詞、產品編號等精確匹配場景下表現不佳，混合檢索是生產環境的必選項。
3.1 混合檢索架構
┌─────────────┐
│ 用戶查詢 │
└──────┬──────┘
│
├──────────────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ 向量檢索 │ │ 關鍵詞檢索 │
│ PgVector │ │ Full-Text │
│ 語義相似度 │ │ BM25 │
│ topK=10 │ │ topK=10 │
└──────┬───────┘ └──────┬───────┘
│ │
▼ ▼
┌─────────────────────────────────┐
│ 結果融合 & Rerank │
│ Reciprocal Rank Fusion (RRF) │
│ 或 Cohere Rerank API │
└──────────────┬──────────────────┘
│
▼
┌──────────────┐
│ Top-N 結果 │
└──────────────┘
3.2 混合檢索實現
@Service
public class HybridSearchService {
private final VectorStore vectorStore;
private final JdbcTemplate jdbcTemplate;
private final ChatModel chatModel;
public HybridSearchService(
VectorStore vectorStore,
JdbcTemplate jdbcTemplate,
ChatModel chatModel) {
this.vectorStore = vectorStore;
this.jdbcTemplate = jdbcTemplate;
this.chatModel = chatModel;
}
public List<ScoredDocument> hybridSearch(String query, int topK) {
List<ScoredDocument> vectorResults = vectorSearch(query, topK * 2);
List<ScoredDocument> keywordResults = keywordSearch(query, topK * 2);
List<ScoredDocument> fused = reciprocalRankFusion(vectorResults, keywordResults);
return fused.stream().limit(topK).toList();
}
private List<ScoredDocument> vectorSearch(String query, int topK) {
List<Document> docs = vectorStore.similaritySearch(
SearchRequest.builder()
.query(query)
.topK(topK)
.similarityThreshold(0.5)
.build()
);
return docs.stream()
.map(doc -> new ScoredDocument(
doc.getId(),
doc.getText(),
doc.getMetadata(),
1.0 - (Double) doc.getMetadata().getOrDefault("distance", 1.0)
))
.toList();
}
private List<ScoredDocument> keywordSearch(String query, int topK) {
String sql = """
SELECT id, content, metadata,
ts_rank_cd(to_tsvector('simple', content),
plainto_tsquery('simple', ?)) AS rank
FROM vector_store
WHERE to_tsvector('simple', content) @@ plainto_tsquery('simple', ?)
ORDER BY rank DESC
LIMIT ?
""";
return jdbcTemplate.query(sql, (rs, rowNum) -> {
Map<String, Object> metadata = new HashMap<>();
try {
String metadataJson = rs.getString("metadata");
metadata = new ObjectMapper().readValue(metadataJson, new TypeReference<>() {});
} catch (Exception ignored) {}
return new ScoredDocument(
rs.getString("id"),
rs.getString("content"),
metadata,
rs.getDouble("rank")
);
}, query, query, topK);
}
private List<ScoredDocument> reciprocalRankFusion(
List<ScoredDocument> vectorResults,
List<ScoredDocument> keywordResults) {
int k = 60;
Map<String, ScoredDocument> docMap = new LinkedHashMap<>();
Map<String, Double> scoreMap = new HashMap<>();
for (int i = 0; i < vectorResults.size(); i++) {
ScoredDocument doc = vectorResults.get(i);
scoreMap.merge(doc.id(), 1.0 / (k + i + 1), Double::sum);
docMap.putIfAbsent(doc.id(), doc);
}
for (int i = 0; i < keywordResults.size(); i++) {
ScoredDocument doc = keywordResults.get(i);
scoreMap.merge(doc.id(), 1.0 / (k + i + 1), Double::sum);
docMap.putIfAbsent(doc.id(), doc);
}
return scoreMap.entrySet().stream()
.sorted(Map.Entry.<String, Double>comparingByValue().reversed())
.map(entry -> {
ScoredDocument doc = docMap.get(entry.getKey());
return new ScoredDocument(doc.id(), doc.text(), doc.metadata(), entry.getValue());
})
.toList();
}
public String askWithHybridSearch(String question) {
List<ScoredDocument> results = hybridSearch(question, 5);
String context = results.stream()
.map(ScoredDocument::text)
.collect(Collectors.joining("\n\n---\n\n"));
String prompt = """
基於以下參考資料回答用戶問題。如果參考資料中沒有相關信息，請明確說明。
參考資料：
%s
用戶問題：%s
請給出準確、完整的回答，並標註信息來源。
""".formatted(context, question);
return chatModel.call(prompt);
}
}
record ScoredDocument(String id, String text, Map<String, Object> metadata, double score) {}
3.3 全文檢索索引配置
-- 為PgVector表添加全文檢索支持
ALTER TABLE vector_store ADD COLUMN IF NOT EXISTS tsv tsvector
GENERATED ALWAYS AS (to_tsvector('simple', content)) STORED;
CREATE INDEX IF NOT EXISTS idx_vector_store_tsv ON vector_store USING GIN(tsv);
-- 中文全文檢索需要zhparser擴展
CREATE EXTENSION IF NOT EXISTS zhparser;
CREATE TEXT SEARCH CONFIGURATION chinese_zh (PARSER = zhparser);
ALTER TEXT SEARCH CONFIGURATION chinese_zh ADD MAPPING FOR n,v,a,i,e,l WITH simple;
3.4 查詢重寫增強召回
@Service
public class QueryRewriteService {
private final ChatModel chatModel;
public QueryRewriteService(ChatModel chatModel) {
this.chatModel = chatModel;
}
public List<String> rewriteQuery(String originalQuery) {
String rewritePrompt = """
用戶提出了以下問題，請生成3個語義相同但表達不同的改寫版本，
用於提高檢索召回率。每行一個改寫，不要編號。
原始問題：%s
""".formatted(originalQuery);
String response = chatModel.call(rewritePrompt);
List<String> rewrites = Arrays.stream(response.split("\n"))
.map(String::trim)
.filter(line -> !line.isEmpty())
.toList();
List<String> allQueries = new ArrayList<>();
allQueries.add(originalQuery);
allQueries.addAll(rewrites);
return allQueries;
}
public String expandWithSynonyms(String query) {
String synonymPrompt = """
為以下查詢提取關鍵實體和同義詞，用於擴展檢索範圍。
格式：每行一個關鍵詞或同義詞。
查詢：%s
""".formatted(query);
return chatModel.call(synonymPrompt);
}
}
模式四：對話記憶與多輪問答
單輪問答只是玩具，生產級RAG必須支持多輪對話，理解上下文中的指代和省略。
4.1 對話記憶架構
┌──────────┐ ┌──────────────┐ ┌──────────┐
│ 用戶消息 │────▶│ 上下文管理器 │────▶│ LLM │
│ 第N輪 │ │ 窗口/摘要 │ │ 生成 │
└──────────┘ └──────────────┘ └──────────┘
▲ │
│ ▼
┌──────────────────┐
│ 對話歷史存儲 │
│ Redis / PG │
└──────────────────┘
4.2 基於Redis的對話記憶
@Configuration
public class ChatMemoryConfig {
@Bean
public ChatMemory chatMemory(RedisTemplate<String, String> redisTemplate) {
return new RedisChatMemory(redisTemplate, 20);
}
}
public class RedisChatMemory implements ChatMemory {
private static final String KEY_PREFIX = "chat:memory:";
private final RedisTemplate<String, String> redisTemplate;
private final int maxMessages;
public RedisChatMemory(RedisTemplate<String, String> redisTemplate, int maxMessages) {
this.redisTemplate = redisTemplate;
this.maxMessages = maxMessages;
}
@Override
public void add(String conversationId, List<Message> messages) {
String key = KEY_PREFIX + conversationId;
for (Message message : messages) {
String serialized = serializeMessage(message);
redisTemplate.opsForList().rightPush(key, serialized);
}
redisTemplate.opsForList().trim(key, -maxMessages, -1);
redisTemplate.expire(key, Duration.ofHours(24));
}
@Override
public List<Message> get(String conversationId, int lastN) {
String key = KEY_PREFIX + conversationId;
List<String> rawMessages = redisTemplate.opsForList().range(key, -lastN, -1);
if (rawMessages == null || rawMessages.isEmpty()) {
return List.of();
}
return rawMessages.stream()
.map(this::deserializeMessage)
.toList();
}
@Override
public void clear(String conversationId) {
redisTemplate.delete(KEY_PREFIX + conversationId);
}
private String serializeMessage(Message message) {
try {
Map<String, String> map = Map.of(
"role", message.getMessageType().getValue(),
"content", message.getText()
);
return new ObjectMapper().writeValueAsString(map);
} catch (Exception e) {
throw new RuntimeException("Failed to serialize message", e);
}
}
private Message deserializeMessage(String json) {
try {
Map<String, String> map = new ObjectMapper().readValue(json, new TypeReference<>() {});
return switch (map.get("role")) {
case "user" -> new UserMessage(map.get("content"));
case "assistant" -> new AssistantMessage(map.get("content"));
case "system" -> new SystemMessage(map.get("content"));
default -> new UserMessage(map.get("content"));
};
} catch (Exception e) {
throw new RuntimeException("Failed to deserialize message", e);
}
}
}
4.3 多輪RAG問答服務
@Service
public class ConversationalRagService {
private final ChatClient chatClient;
private final VectorStore vectorStore;
private final ChatMemory chatMemory;
public ConversationalRagService(
ChatClient chatClient,
VectorStore vectorStore,
ChatMemory chatMemory) {
this.chatClient = chatClient;
this.vectorStore = vectorStore;
this.chatMemory = chatMemory;
}
public String chat(String conversationId, String userMessage) {
List<Message> history = chatMemory.get(conversationId, 10);
String contextualizedQuery = buildContextualizedQuery(userMessage, history);
List<Document> relevantDocs = vectorStore.similaritySearch(
SearchRequest.builder()
.query(contextualizedQuery)
.topK(5)
.similarityThreshold(0.6)
.build()
);
String context = relevantDocs.stream()
.map(Document::getText)
.collect(Collectors.joining("\n\n"));
String systemPrompt = """
你是一個專業的知識庫助手。基於提供的參考資料回答用戶問題。
規則：
1. 只基於參考資料回答，不要編造信息
2. 如果參考資料不足以回答問題，明確告知用戶
3. 引用具體的參考來源
4. 保持回答簡潔準確
參考資料：
%s
""".formatted(context);
String response = chatClient.prompt()
.system(systemPrompt)
.messages(history)
.user(userMessage)
.call()
.content();
chatMemory.add(conversationId, List.of(
new UserMessage(userMessage),
new AssistantMessage(response)
));
return response;
}
private String buildContextualizedQuery(String currentQuery, List<Message> history) {
if (history.isEmpty()) {
return currentQuery;
}
String historySummary = history.stream()
.map(msg -> msg.getMessageType().getValue() + ": " + msg.getText())
.collect(Collectors.joining("\n"));
String condensePrompt = """
基於對話歷史和當前問題，生成一個獨立的、包含完整上下文的查詢。
只輸出改寫後的查詢，不要解釋。
對話歷史：
%s
當前問題：%s
""".formatted(historySummary, currentQuery);
return chatClient.prompt()
.user(condensePrompt)
.call()
.content();
}
}
4.4 流式多輪對話
@RestController
@RequestMapping("/api/v1/chat")
public class StreamingChatController {
private final StreamingRagService streamingRagService;
public StreamingChatController(StreamingRagService streamingRagService) {
this.streamingRagService = streamingRagService;
}
@PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> streamChat(@RequestBody ChatRequest request) {
return streamingRagService.streamChat(request.conversationId(), request.message());
}
}
@Service
public class StreamingRagService {
private final ChatClient chatClient;
private final VectorStore vectorStore;
public StreamingRagService(ChatClient chatClient, VectorStore vectorStore) {
this.chatClient = chatClient;
this.vectorStore = vectorStore;
}
public Flux<String> streamChat(String conversationId, String userMessage) {
List<Document> docs = vectorStore.similaritySearch(
SearchRequest.builder()
.query(userMessage)
.topK(5)
.similarityThreshold(0.6)
.build()
);
String context = docs.stream()
.map(Document::getText)
.collect(Collectors.joining("\n\n"));
return chatClient.prompt()
.system("基於以下參考資料回答：\n" + context)
.user(userMessage)
.stream()
.content();
}
}
模式五：RAG流水線編排
生產級RAG不是單一接口調用，而是一條可編排、可觀測、可降級的流水線。
5.1 流水線架構
┌──────────────────────────────────────────────────────────────┐
│ RAG Pipeline Orchestration │
│ │
│ Query ──▶ [Rewrite] ──▶ [Retrieve] ──▶ [Rerank] ──▶ [Generate] │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ [Cache] [Fallback] [Score] [Guard] │
│ │ │ │ │ │
│ └──────────────┴─────────────┴────────────┘ │
│ │ │
│ ▼ │
│ [Observability] │
│ Tracing · Metrics · Logging │
└──────────────────────────────────────────────────────────────┘
5.2 流水線定義與執行
public interface RagPipelineStep {
String getName();
StepResult execute(StepContext context);
default int getOrder() { return 0; }
default boolean isEnabled() { return true; }
}
public record StepResult(boolean success, Map<String, Object> data, String error) {
public static StepResult success(Map<String, Object> data) {
return new StepResult(true, data, null);
}
public static StepResult failure(String error) {
return new StepResult(false, Map.of(), error);
}
}
public class StepContext {
private final Map<String, Object> data = new ConcurrentHashMap<>();
private String originalQuery;
private String rewrittenQuery;
private List<Document> retrievedDocuments;
private List<ScoredDocument> rerankedDocuments;
private String generatedAnswer;
private long startTimeMs;
public StepContext(String query) {
this.originalQuery = query;
this.startTimeMs = System.currentTimeMillis();
}
public Map<String, Object> getData() { return data; }
public String getOriginalQuery() { return originalQuery; }
public void setRewrittenQuery(String q) { this.rewrittenQuery = q; }
public String getEffectiveQuery() { return rewrittenQuery != null ? rewrittenQuery : originalQuery; }
public void setRetrievedDocuments(List<Document> docs) { this.retrievedDocuments = docs; }
public List<Document> getRetrievedDocuments() { return retrievedDocuments; }
public void setRerankedDocuments(List<ScoredDocument> docs) { this.rerankedDocuments = docs; }
public List<ScoredDocument> getRerankedDocuments() { return rerankedDocuments; }
public void setGeneratedAnswer(String answer) { this.generatedAnswer = answer; }
public String getGeneratedAnswer() { return generatedAnswer; }
public long getElapsedTimeMs() { return System.currentTimeMillis() - startTimeMs; }
}
5.3 具體步驟實現
@Component
public class QueryRewriteStep implements RagPipelineStep {
private final ChatModel chatModel;
public QueryRewriteStep(ChatModel chatModel) {
this.chatModel = chatModel;
}
@Override
public String getName() { return "query-rewrite"; }
@Override
public int getOrder() { return 1; }
@Override
public StepResult execute(StepContext context) {
String query = context.getOriginalQuery();
String rewritePrompt = """
將以下查詢改寫為更適合檢索的形式，保留核心語義，補充必要的上下文。
只輸出改寫後的查詢。
原始查詢：%s
""".formatted(query);
String rewritten = chatModel.call(rewritePrompt);
context.setRewrittenQuery(rewritten.trim());
return StepResult.success(Map.of(
"originalQuery", query,
"rewrittenQuery", rewritten.trim()
));
}
}
@Component
public class VectorRetrieveStep implements RagPipelineStep {
private final VectorStore vectorStore;
public VectorRetrieveStep(VectorStore vectorStore) {
this.vectorStore = vectorStore;
}
@Override
public String getName() { return "vector-retrieve"; }
@Override
public int getOrder() { return 2; }
@Override
public StepResult execute(StepContext context) {
List<Document> docs = vectorStore.similaritySearch(
SearchRequest.builder()
.query(context.getEffectiveQuery())
.topK(10)
.similarityThreshold(0.5)
.build()
);
context.setRetrievedDocuments(docs);
return StepResult.success(Map.of(
"documentCount", docs.size(),
"query", context.getEffectiveQuery()
));
}
}
@Component
public class RerankStep implements RagPipelineStep {
private final ChatModel chatModel;
public RerankStep(ChatModel chatModel) {
this.chatModel = chatModel;
}
@Override
public String getName() { return "rerank"; }
@Override
public int getOrder() { return 3; }
@Override
public StepResult execute(StepContext context) {
List<Document> docs = context.getRetrievedDocuments();
if (docs == null || docs.isEmpty()) {
return StepResult.failure("No documents to rerank");
}
String query = context.getEffectiveQuery();
List<ScoredDocument> scored = docs.stream()
.map(doc -> {
double relevanceScore = computeRelevance(query, doc.getText());
return new ScoredDocument(doc.getId(), doc.getText(), doc.getMetadata(), relevanceScore);
})
.sorted(Comparator.comparingDouble(ScoredDocument::score).reversed())
.limit(5)
.toList();
context.setRerankedDocuments(scored);
return StepResult.success(Map.of("rerankedCount", scored.size()));
}
private double computeRelevance(String query, String documentText) {
Set<String> queryTerms = Arrays.stream(query.toLowerCase().split("\\s+"))
.collect(Collectors.toSet());
Set<String> docTerms = Arrays.stream(documentText.toLowerCase().split("\\s+"))
.collect(Collectors.toSet());
long overlap = queryTerms.stream().filter(docTerms::contains).count();
return (double) overlap / queryTerms.size();
}
}
@Component
public class GenerateStep implements RagPipelineStep {
private final ChatClient chatClient;
public GenerateStep(ChatClient chatClient) {
this.chatClient = chatClient;
}
@Override
public String getName() { return "generate"; }
@Override
public int getOrder() { return 4; }
@Override
public StepResult execute(StepContext context) {
List<ScoredDocument> docs = context.getRerankedDocuments();
if (docs == null || docs.isEmpty()) {
return StepResult.failure("No documents available for generation");
}
String contextText = docs.stream()
.map(ScoredDocument::text)
.collect(Collectors.joining("\n\n---\n\n"));
String answer = chatClient.prompt()
.system("""
你是一個專業的知識庫助手。基於參考資料回答問題。
如果資料不足，明確說明。引用具體來源。
參考資料：
%s
""".formatted(contextText))
.user(context.getOriginalQuery())
.call()
.content();
context.setGeneratedAnswer(answer);
return StepResult.success(Map.of("answerLength", answer.length()));
}
}
5.4 流水線編排器
@Service
public class RagPipelineOrchestrator {
private final List<RagPipelineStep> steps;
private final MeterRegistry meterRegistry;
public RagPipelineOrchestrator(
List<RagPipelineStep> steps,
MeterRegistry meterRegistry) {
this.steps = steps.stream()
.filter(RagPipelineStep::isEnabled)
.sorted(Comparator.comparingInt(RagPipelineStep::getOrder))
.toList();
this.meterRegistry = meterRegistry;
}
public RagPipelineResult execute(String query) {
StepContext context = new StepContext(query);
List<StepExecutionRecord> records = new ArrayList<>();
for (RagPipelineStep step : steps) {
long stepStart = System.currentTimeMillis();
try {
StepResult result = step.execute(context);
long stepDuration = System.currentTimeMillis() - stepStart;
records.add(new StepExecutionRecord(
step.getName(), true, stepDuration, result.error()
));
meterRegistry.counter("rag.pipeline.step.success",
"step", step.getName()).increment();
meterRegistry.timer("rag.pipeline.step.duration",
"step", step.getName())
.record(stepDuration, TimeUnit.MILLISECONDS);
if (!result.success()) {
break;
}
} catch (Exception e) {
long stepDuration = System.currentTimeMillis() - stepStart;
records.add(new StepExecutionRecord(
step.getName(), false, stepDuration, e.getMessage()
));
meterRegistry.counter("rag.pipeline.step.failure",
"step", step.getName()).increment();
break;
}
}
return new RagPipelineResult(
context.getGeneratedAnswer(),
context.getElapsedTimeMs(),
records
);
}
}
record StepExecutionRecord(String stepName, boolean success, long durationMs, String error) {}
record RagPipelineResult(String answer, long totalDurationMs, List<StepExecutionRecord> steps) {}
模式六：生產環境部署與監控
RAG應用上線後的運維複雜度遠超普通CRUD服務，需要專門的監控和降級策略。
6.1 Docker Compose部署
version: '3.8'
services:
app:
build:
context: .
dockerfile: Dockerfile
ports:
- "8080:8080"
environment:
- SPRING_PROFILES_ACTIVE=prod
- OPENAI_API_KEY=${OPENAI_API_KEY}
- SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/rag_db
- SPRING_DATASOURCE_USERNAME=rag_user
- SPRING_DATASOURCE_PASSWORD=${PG_PASSWORD}
- SPRING_DATA_REDIS_HOST=redis
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
interval: 30s
timeout: 10s
retries: 3
deploy:
resources:
limits:
memory: 1G
cpus: '2'
postgres:
image: pgvector/pgvector:pg16
environment:
- POSTGRES_DB=rag_db
- POSTGRES_USER=rag_user
- POSTGRES_PASSWORD=${PG_PASSWORD}
volumes:
- pgdata:/var/lib/postgresql/data
- ./init.sql:/docker-entrypoint-initdb.d/init.sql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U rag_user -d rag_db"]
interval: 10s
timeout: 5s
retries: 5
redis:
image: redis:7-alpine
command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 5
prometheus:
image: prom/prometheus:latest
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
grafana:
image: grafana/grafana:latest
ports:
- "3000:3000"
environment:
- GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
volumes:
pgdata:
6.2 RAG專用監控指標
@Configuration
public class RagMetricsConfig {
@Bean
public MeterRegistryCustomizer<MeterRegistry> ragMetrics() {
return registry -> registry.config()
.meterFilter(MeterFilter.deny(id ->
id.getName().startsWith("jvm.") || id.getName().startsWith("process.")
));
}
}
@Service
public class RagMetricsService {
private final MeterRegistry meterRegistry;
public RagMetricsService(MeterRegistry meterRegistry) {
this.meterRegistry = meterRegistry;
}
public void recordRetrievalLatency(long durationMs, String storeType) {
meterRegistry.timer("rag.retrieval.latency", "store", storeType)
.record(durationMs, TimeUnit.MILLISECONDS);
}
public void recordEmbeddingLatency(long durationMs, int tokenCount) {
meterRegistry.timer("rag.embedding.latency")
.record(durationMs, TimeUnit.MILLISECONDS);
meterRegistry.counter("rag.embedding.tokens").increment(tokenCount);
}
public void recordGenerationLatency(long durationMs, int inputTokens, int outputTokens) {
meterRegistry.timer("rag.generation.latency")
.record(durationMs, TimeUnit.MILLISECONDS);
meterRegistry.counter("rag.generation.input.tokens").increment(inputTokens);
meterRegistry.counter("rag.generation.output.tokens").increment(outputTokens);
}
public void recordRetrievalQuality(int retrievedCount, double avgSimilarity) {
meterRegistry.gauge("rag.retrieval.document.count", retrievedCount);
meterRegistry.gauge("rag.retrieval.avg.similarity", avgSimilarity);
}
public void recordCacheHit(boolean hit) {
meterRegistry.counter("rag.cache",
"result", hit ? "hit" : "miss").increment();
}
}
6.3 降級與熔斷
@Configuration
public class ResilienceConfig {
@Bean
public CircuitBreaker ragCircuitBreaker() {
CircuitBreakerConfig config = CircuitBreakerConfig.custom()
.failureRateThreshold(50)
.waitDurationInOpenState(Duration.ofSeconds(30))
.slidingWindowSize(10)
.slidingWindowType(CircuitBreakerConfig.SlidingWindowType.COUNT_BASED)
.build();
return CircuitBreaker.of("ragCircuitBreaker", config);
}
}
@Service
public class ResilientRagService {
private final VectorStore vectorStore;
private final ChatClient chatClient;
private final CircuitBreaker circuitBreaker;
private final RagMetricsService metricsService;
public ResilientRagService(
VectorStore vectorStore,
ChatClient chatClient,
CircuitBreaker circuitBreaker,
RagMetricsService metricsService) {
this.vectorStore = vectorStore;
this.chatClient = chatClient;
this.circuitBreaker = circuitBreaker;
this.metricsService = metricsService;
}
public String ask(String question) {
return circuitBreaker.executeSupplier(() -> {
try {
long start = System.currentTimeMillis();
List<Document> docs = vectorStore.similaritySearch(
SearchRequest.builder()
.query(question)
.topK(5)
.similarityThreshold(0.6)
.build()
);
metricsService.recordRetrievalLatency(
System.currentTimeMillis() - start, "pgvector"
);
if (docs.isEmpty()) {
return "抱歉，知識庫中沒有找到與您問題相關的信息。請嘗試換一種方式提問。";
}
String context = docs.stream()
.map(Document::getText)
.collect(Collectors.joining("\n\n"));
long genStart = System.currentTimeMillis();
String answer = chatClient.prompt()
.system("基於參考資料回答：\n" + context)
.user(question)
.call()
.content();
metricsService.recordGenerationLatency(
System.currentTimeMillis() - genStart, 0, 0
);
return answer;
} catch (Exception e) {
metricsService.recordRetrievalLatency(-1, "error");
return getFallbackAnswer(question);
}
});
}
private String getFallbackAnswer(String question) {
return """
抱歉，AI服務暫時不可用。這可能是由於：
1. 向量數據庫連接超時
2. LLM服務過載
3. 網絡波動
請稍後重試，或聯繫技術支持。
""";
}
}
6.4 Prometheus告警規則
groups:
- name: rag-alerts
rules:
- alert: RAGRetrievalLatencyHigh
expr: histogram_quantile(0.95, rag_retrieval_latency_seconds) > 2
for: 5m
labels:
severity: warning
annotations:
summary: "RAG檢索延遲過高"
description: "95分位檢索延遲超過2秒，當前值: {{ $value }}s"
- alert: RAGGenerationLatencyHigh
expr: histogram_quantile(0.95, rag_generation_latency_seconds) > 10
for: 5m
labels:
severity: warning
annotations:
summary: "RAG生成延遲過高"
description: "95分位生成延遲超過10秒"
- alert: RAGCircuitBreakerOpen
expr: resilience4j_circuitbreaker_state{name="ragCircuitBreaker",state="open"} == 1
for: 1m
labels:
severity: critical
annotations:
summary: "RAG熔斷器已打開"
description: "RAG服務熔斷器處於OPEN狀態，所有請求將走降級路徑"
- alert: RAGEmbeddingErrorRateHigh
expr: rate(rag_pipeline_step_failure_total{step="vector-retrieve"}[5m]) > 0.1
for: 3m
labels:
severity: critical
annotations:
summary: "向量檢索錯誤率過高"
6.5 K8s部署配置
apiVersion: apps/v1
kind: Deployment
metadata:
name: rag-service
labels:
app: rag-service
spec:
replicas: 3
selector:
matchLabels:
app: rag-service
template:
metadata:
labels:
app: rag-service
spec:
containers:
- name: rag-service
image: registry.example.com/rag-service:latest
ports:
- containerPort: 8080
env:
- name: SPRING_PROFILES_ACTIVE
value: "prod"
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: rag-secrets
key: openai-api-key
resources:
requests:
memory: "512Mi"
cpu: "500m"
limits:
memory: "1Gi"
cpu: "2000m"
livenessProbe:
httpGet:
path: /actuator/health/liveness
port: 8080
initialDelaySeconds: 60
periodSeconds: 30
readinessProbe:
httpGet:
path: /actuator/health/readiness
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
name: rag-service
spec:
selector:
app: rag-service
ports:
- port: 80
targetPort: 8080
type: ClusterIP
5個常見坑及解決方案
坑1：嵌入維度不匹配
現象：ERROR: expected 1536 dimensions, not 768
原因：切換了嵌入模型但未更新向量表維度配置
解決方案：
@Configuration
public class EmbeddingDimensionGuard {
@Value("${spring.ai.openai.embedding.options.model:text-embedding-3-small}")
private String embeddingModel;
@Bean
public ApplicationRunner validateDimensions(JdbcTemplate jdbcTemplate) {
return args -> {
int expectedDim = getExpectedDimension(embeddingModel);
Integer actualDim = jdbcTemplate.queryForObject(
"SELECT atttypmod FROM pg_attribute WHERE attrelid = 'vector_store'::regclass AND attname = 'embedding'",
Integer.class
);
if (actualDim != null && actualDim != expectedDim + 4) {
throw new IllegalStateException(
"Embedding dimension mismatch! Expected: " + expectedDim +
", Actual: " + (actualDim - 4)
);
}
};
}
private int getExpectedDimension(String model) {
return switch (model) {
case "text-embedding-3-small" -> 1536;
case "text-embedding-3-large" -> 3072;
case "text-embedding-ada-002" -> 1536;
default -> 1536;
};
}
}
坑2：大文檔OOM
現象：加載100MB的PDF時JVM直接OOM
原因：DocumentReader一次性將整個文檔加載到內存
解決方案：
@Service
public class SafeDocumentLoader {
private static final long MAX_FILE_SIZE = 50 * 1024 * 1024;
public List<Document> loadSafely(Resource resource) {
try {
if (resource.contentLength() > MAX_FILE_SIZE) {
return loadInChunks(resource);
}
DocumentReader reader = new TextReader(resource);
return reader.get();
} catch (IOException e) {
throw new RuntimeException("Failed to load document", e);
}
}
private List<Document> loadInChunks(Resource resource) {
try (BufferedReader reader = new BufferedReader(
new InputStreamReader(resource.getInputStream(), StandardCharsets.UTF_8))) {
List<Document> allChunks = new ArrayList<>();
StringBuilder buffer = new StringBuilder();
String line;
while ((line = reader.readLine()) != null) {
buffer.append(line).append("\n");
if (buffer.length() > 100000) {
Map<String, Object> metadata = Map.of(
"source", resource.getFilename(),
"chunkStrategy", "streaming"
);
allChunks.add(new Document(buffer.toString(), metadata));
buffer = new StringBuilder();
}
}
if (buffer.length() > 0) {
allChunks.add(new Document(buffer.toString(),
Map.of("source", resource.getFilename())));
}
return allChunks;
} catch (IOException e) {
throw new RuntimeException("Failed to stream document", e);
}
}
}
坑3：檢索結果全是無關內容
現象：相似度閾值0.7以下返回了大量噪聲
原因：閾值設置不合理 + 嵌入模型對中文支持差
解決方案：
spring:
ai:
vectorstore:
pgvector:
distance-type: COSINE
@Service
public class AdaptiveThresholdService {
private final VectorStore vectorStore;
public AdaptiveThresholdService(VectorStore vectorStore) {
this.vectorStore = vectorStore;
}
public List<Document> searchWithAdaptiveThreshold(String query, int topK) {
double[] thresholds = {0.8, 0.7, 0.6, 0.5};
for (double threshold : thresholds) {
List<Document> results = vectorStore.similaritySearch(
SearchRequest.builder()
.query(query)
.topK(topK)
.similarityThreshold(threshold)
.build()
);
if (!results.isEmpty()) {
return results;
}
}
return List.of();
}
}
坑4：並發索引導致重複向量
現象：同一個文檔被索引了多次，檢索結果出現重複
原因：缺少冪等性保障
解決方案：
@Service
public class IdempotentIndexService {
private final VectorStore vectorStore;
private final JdbcTemplate jdbcTemplate;
public IdempotentIndexService(VectorStore vectorStore, JdbcTemplate jdbcTemplate) {
this.vectorStore = vectorStore;
this.jdbcTemplate = jdbcTemplate;
}
@Transactional
public void indexWithDedup(List<Document> documents, String sourceId) {
jdbcTemplate.update(
"DELETE FROM vector_store WHERE metadata->>'sourceId' = ?",
sourceId
);
documents.forEach(doc ->
doc.getMetadata().put("sourceId", sourceId)
);
vectorStore.add(documents);
}
}
坑5：LLM幻覺無法控制
現象：模型在知識庫沒有相關信息時仍然編造答案
原因：System Prompt約束不夠強 + 缺少Grounding驗證
解決方案：
@Service
public class GroundedRagService {
private final ChatClient chatClient;
private final VectorStore vectorStore;
public GroundedRagService(ChatClient chatClient, VectorStore vectorStore) {
this.chatClient = chatClient;
this.vectorStore = vectorStore;
}
public GroundedAnswer askWithGrounding(String question) {
List<Document> docs = vectorStore.similaritySearch(
SearchRequest.builder()
.query(question)
.topK(5)
.similarityThreshold(0.65)
.build()
);
if (docs.isEmpty()) {
return new GroundedAnswer(
"知識庫中沒有找到相關信息，無法回答該問題。",
false,
List.of()
);
}
String context = docs.stream()
.map(doc -> "[來源:" + doc.getMetadata().get("source") + "]\n" + doc.getText())
.collect(Collectors.joining("\n\n"));
String systemPrompt = """
嚴格規則：
1. 只基於提供的參考資料回答
2. 每個事實陳述必須標註來源編號[來源:xxx]
3. 如果參考資料不足以完整回答，明確指出哪些部分缺乏依據
4. 絕不編造參考資料中沒有的信息
參考資料：
%s
""".formatted(context);
String answer = chatClient.prompt()
.system(systemPrompt)
.user(question)
.call()
.content();
boolean isGrounded = validateGrounding(answer, docs);
return new GroundedAnswer(answer, isGrounded,
docs.stream().map(d -> (String) d.getMetadata().get("source")).toList());
}
private boolean validateGrounding(String answer, List<Document> sources) {
String sourceTexts = sources.stream()
.map(Document::getText)
.collect(Collectors.joining(" "));
String validationPrompt = """
判斷以下回答是否完全基於給定的參考資料。
只回答 YES 或 NO。
參考資料：%s
回答：%s
""".formatted(sourceTexts.substring(0, Math.min(2000, sourceTexts.length())),
answer);
String result = chatClient.prompt()
.user(validationPrompt)
.call()
.content();
return result.trim().toUpperCase().startsWith("YES");
}
}
record GroundedAnswer(String answer, boolean isGrounded, List<String> sources) {}
10個常見報錯排查
| # | 報錯信息 | 原因 | 解決方案 |
|---|---|---|---|
| 1 | ERROR: operator does not exist: vector <=> vector |
pgvector擴展未安裝 | CREATE EXTENSION vector; 並重啟應用 |
| 2 | EmbeddingModel bean not found |
缺少embedding starter依賴 | 添加spring-ai-openai-spring-boot-starter |
| 3 | Connection refused: localhost:5432 |
PostgreSQL未啟動 | docker compose up -d postgres |
| 4 | 429 Too Many Requests |
OpenAI API限流 | 添加限流器，降低並發，使用本地模型 |
| 5 | expected 1536 dimensions, not 768 |
嵌入模型維度不匹配 | 統一embedding模型或重建向量表 |
| 6 | OutOfMemoryError: Java heap space |
大文檔一次性加載 | 使用流式加載，限制單文件大小 |
| 7 | CircuitBreaker 'ragCircuitBreaker' is OPEN |
下游服務持續故障 | 檢查LLM/向量庫連通性，等待熔斷恢復 |
| 8 | RedisConnectionFailureException |
Redis不可用 | 檢查Redis健康狀態，降級為內存記憶 |
| 9 | Empty search results for threshold 0.8 |
相似度閾值過高 | 降低閾值或使用自適應閾值策略 |
| 10 | JsonProcessingException: metadata |
元數據JSON格式錯誤 | 檢查metadata字段，確保可序列化 |
進階優化技巧
1. 緩存層：減少重複嵌入計算
@Service
public class EmbeddingCacheService {
private final Cache<String, float[]> embeddingCache;
private final EmbeddingModel embeddingModel;
public EmbeddingCacheService(EmbeddingModel embeddingModel) {
this.embeddingModel = embeddingModel;
this.embeddingCache = Caffeine.newBuilder()
.maximumSize(10000)
.expireAfterWrite(Duration.ofHours(24))
.build();
}
public float[] getEmbedding(String text) {
String cacheKey = DigestUtils.md5Hex(text);
return embeddingCache.get(cacheKey, key -> {
float[] embedding = embeddingModel.embed(text);
return embedding;
});
}
public void preloadCache(List<String> texts) {
texts.parallelStream().forEach(text -> {
String cacheKey = DigestUtils.md5Hex(text);
embeddingCache.put(cacheKey, embeddingModel.embed(text));
});
}
}
2. 異步索引：不阻塞主流程
@Service
public class AsyncIndexingService {
private final VectorStore vectorStore;
private final DocumentTransformer textSplitter;
private final TaskExecutor indexExecutor;
public AsyncIndexingService(
VectorStore vectorStore,
DocumentTransformer textSplitter) {
this.vectorStore = vectorStore;
this.textSplitter = textSplitter;
this.indexExecutor = Executors.newVirtualThreadPerTaskExecutor();
}
@Async("indexExecutor")
public CompletableFuture<IndexResult> indexAsync(Resource resource, String sourceId) {
long start = System.currentTimeMillis();
try {
DocumentReader reader = new TextReader(resource);
List<Document> documents = reader.get();
List<Document> split = textSplitter.apply(documents);
split.forEach(doc -> doc.getMetadata().put("sourceId", sourceId));
vectorStore.add(split);
return CompletableFuture.completedFuture(
new IndexResult(true, split.size(), System.currentTimeMillis() - start, null)
);
} catch (Exception e) {
return CompletableFuture.completedFuture(
new IndexResult(false, 0, System.currentTimeMillis() - start, e.getMessage())
);
}
}
}
record IndexResult(boolean success, int documentCount, long durationMs, String error) {}
3. 多模型路由：成本與質量平衡
@Service
public class ModelRoutingService {
private final Map<String, ChatModel> models;
private final MeterRegistry meterRegistry;
public ModelRoutingService(
@Qualifier("openAiChatModel") ChatModel openAiModel,
@Qualifier("deepseekChatModel") ChatModel deepseekModel,
@Qualifier("qwenChatModel") ChatModel qwenModel,
MeterRegistry meterRegistry) {
this.models = Map.of(
"gpt-4o", openAiModel,
"deepseek-v3", deepseekModel,
"qwen-max", qwenModel
);
this.meterRegistry = meterRegistry;
}
public String routeAndChat(String question, String priority) {
ChatModel selectedModel = switch (priority) {
case "quality" -> models.get("gpt-4o");
case "cost" -> models.get("deepseek-v3");
case "chinese" -> models.get("qwen-max");
default -> models.get("deepseek-v3");
};
meterRegistry.counter("rag.model.routing",
"model", getModelName(selectedModel)).increment();
return selectedModel.call(question);
}
private String getModelName(ChatModel model) {
for (Map.Entry<String, ChatModel> entry : models.entrySet()) {
if (entry.getValue().equals(model)) {
return entry.getKey();
}
}
return "unknown";
}
}
對比分析：3種向量數據庫方案
| 維度 | PgVector | Milvus | Chroma |
|---|---|---|---|
| 部署方式 | PG擴展，零額外運維 | 獨立集群，需Zookeeper | 嵌入式/Server兩種模式 |
| 適用規模 | <100萬向量 | 億級向量 | <50萬向量 |
| 索引類型 | HNSW/IVFFlat | HNSW/IVF_FLAT/IVF_PQ8 | HNSW |
| 查詢延遲(P99) | 50-200ms | 10-50ms | 30-100ms |
| 過濾查詢 | SQL原生支持 | 表達式引擎 | 元數據過濾 |
| 事務支持 | ACID | 最終一致 | 無 |
| Java生態 | Spring AI原生 | Spring AI + Milvus SDK | Spring AI原生 |
| 運維複雜度 | 低(復用PG) | 高(分佈式集群) | 低(嵌入式) |
| 成本 | 低(復用PG實例) | 中(需獨立集群) | 低(嵌入式免費) |
| 推薦場景 | 企業已有PG，中小規模 | 大規模向量檢索 | 原型驗證，小規模 |
選型建議：
- 已有PostgreSQL的企業 → PgVector，運維零成本
- 向量規模超500萬 → Milvus，分佈式擴展
- 快速原型驗證 → Chroma，5分鐘跑通
更多向量數據庫對比可參考 向量數據庫語義檢索實戰。
在線工具推薦
構建RAG應用過程中，以下在線工具可以大幅提升效率：
| 工具 | 用途 | 鏈接 |
|---|---|---|
| JSON格式化 | 處理向量存儲的metadata JSON | JSON格式化 |
| Hash計算 | 生成文檔指紋用於緩存和去重 | Hash計算 |
| Curl轉代碼 | 快速生成LLM API調用代碼 | Curl轉代碼 |
| Base64編解碼 | 處理文檔內容的編碼轉換 | Base64編解碼 |
| 正則表達式測試 | 驗證文檔分塊的正則規則 | 正則測試 |
總結
SpringBoot 3.5 + Spring AI讓Java開發者終於有了生產級RAG的完整解決方案。6種模式覆蓋了從向量存儲到智能問答的全鏈路：PgVector集成是基礎設施，文檔分塊決定效果上限，混合檢索提升召回率，對話記憶讓問答更智能，流水線編排保障可靠性，監控降級守護生產穩定。記住：RAG不是銀彈，但它是2026年Java AI落地最務實的路徑。
相關閱讀
- Spring Boot 3 AI大模型整合全攻略 — Spring AI vs LangChain4j框架選型與AI Agent構建
- Python AI生產部署實戰 — Python側AI模型部署與運維經驗
- RAG評估與優化 — RAG效果評估指標與優化方法論
- PostgreSQL PgVector RAG實戰 — PgVector深度配置與性能調優
本站提供瀏覽器本地工具，免註冊即可試用 →
#SpringBoot#Spring AI#RAG#向量数据库#Java#大模型集成#2026#AI与大数据