传统 LLM 调用:  用户问题 → LLM → 答案（依赖模型内部知识）RAG 模式:       用户问题 → 检索器 → 相关知识 + 问题 → LLM → 基于事实的答案

graph LR    A[用户查询] --> B[检索阶段]    B --> C[检索结果]    C --> D[生成阶段]    D --> E[最终答案]    subgraph 索引管线（离线）        F[原始文档] --> G[文档分割]        G --> H[Embedding]        H --> I[(向量数据库)]    end    I -.-> B

Spring AI RAG 组件层次┌─────────────────────────────────────────────┐│                 应用层                         ││   ChatClient / StreamingChatClient           │├─────────────────────────────────────────────┤│                 增强层                         ││   QuestionAnswerAdvisor                      ││   RetrievalAugmentationAdvisor               │├─────────────────────────────────────────────┤│                 检索层                         ││   VectorStore (PGVector / Pinecone / Redis)  ││   DocumentRetriever                          │├─────────────────────────────────────────────┤│                 处理层                         ││   DocumentReader / DocumentTransformer       ││   TokenTextSplitter / ContentFormatter       │├─────────────────────────────────────────────┤│                 基础设施层                      ││   EmbeddingModel (OpenAI / Ollama / BAAI)    ││   ChatModel / StreamingChatModel             │└─────────────────────────────────────────────┘

// 文档表示public class Document {    private String id;    private String content;          // 文档文本内容    private Metadata metadata;       // 元数据（来源、时间、类型等）    private List<Double> embedding;  // 向量表示}// 向量存储抽象public interface VectorStore {    void add(List<Document> documents);    void delete(List<String> idList);    List<Document> similaritySearch(SearchRequest request);}// 检索增强建议器（核心 RAG 组件）public interface RetrievalAugmentationAdvisor {    ChatResponse advise(ChatRequest request);}// 文档检索器public interface DocumentRetriever {    List<Document> retrieve(RetrievalRequest request);}

@Beanpublic VectorStore vectorStore(EmbeddingModel embeddingModel) {    return new PgVectorStore(jdbcTemplate, embeddingModel);}@Servicepublic class RagService {    private final ChatClient chatClient;    public RagService(ChatClient.Builder builder, VectorStore vectorStore) {        this.chatClient = builder            .defaultSystem("""                你是一个专业的AI助手。请基于提供的上下文信息回答问题。                如果上下文信息不足以回答问题，请明确说明，不要编造答案。                回答时请引用信息来源。                """)            .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore))            .build();    }    public String ask(String question) {        return chatClient.prompt()            .user(question)            .call()            .content();    }}

// 读取 PDFDocumentReader pdfReader = new PdfDocumentReader(    new FileSystemResource("document.pdf"));// 读取 JSONDocumentReader jsonReader = new JsonDocumentReader(    new ClassPathResource("data.json"));// 读取 MarkdownDocumentReader mdReader = new MarkdownDocumentReader(    new FileSystemResource("README.md"));// 读取 CSVDocumentReader csvReader = new CsvDocumentReader(    new FileSystemResource("data.csv"));// 读取 HTMLDocumentReader htmlReader = new HtmlDocumentReader(    new UrlResource("https://example.com"));

// 原生 PDF（文本可选中）DocumentReader reader = new PdfDocumentReader(resource);// 扫描版 PDF（需先 OCR 处理）// Spring AI 本身不内置 OCR，可以结合 Tesseract 预处理// 或者使用 AWS Textract、Azure Document Intelligence 等云服务

Document doc = new Document("content");doc.getMetadata().put("source", "financial-report-2026-q1.pdf");doc.getMetadata().put("page", 42);doc.getMetadata().put("category", "quarterly");doc.getMetadata().put("created_at", "2026-04-15");doc.getMetadata().put("author", "finance-team");

太细（句子级）        ←→        太粗（章节级）  检索精度高                         上下文完整  上下文碎片化                       检索噪声大  丢失跨句关系                       可能含无关内容

// 基于 Token 的分割（推荐）DocumentTransformer splitter = TokenTextSplitter.builder()    .defaultMaxTokenSize(500)        // 每个分割块最多 500 token    .minChunkSizeChars(350)          // 最小字符数    .minOverlap(50)                  // 块间重叠（保持上下文连续性）    .build();List<Document> chunks = splitter.apply(originalDocuments);

// 自定义语义分割器示例（概念）List<Document> semanticChunks = documents.stream()    .flatMap(doc -> splitByMarkdownHeaders(doc).stream())    .flatMap(doc -> splitByParagraphs(doc).stream())    .collect(Collectors.toList());

// 递归分割：先按 ## 分割，再按段落分割，最后按句子分割// Spring AI 的 TokenTextSplitter 内置了类似递归逻辑

"苹果发布了新款手机"      [0.23, -0.45, 0.78, ...]   ←→"iPhone 16 正式发布"      [0.21, -0.42, 0.80, ...]   ← 语义相近，向量距离小"天气预报说明天下雨"      [0.67, 0.12, -0.34, ...]   ← 语义无关，向量距离大

public interface EmbeddingModel {    // 单条文本 embedding    EmbeddingResponse embed(EmbeddingRequest request);    // 批量 embedding（通常有优化）    List<EmbeddingResponse> embed(List<EmbeddingRequest> requests);    // 获取向量维度    int dimensions();}

// 中文推荐：使用 BAAI/bge 系列或 Qwen Embeddings@Beanpublic EmbeddingModel embeddingModel() {    // 方案1：本地部署（Ollama）    return new OllamaEmbeddingModel(ollamaApi)        .withModel("bge-m3");  // 支持中英文    // 方案2：阿里通义千问    return new TongyiEmbeddingModel(tongyiApi);    // 方案3：OpenAI（英文为主场景）    return new OpenAiEmbeddingModel(openAiApi)        .withModel("text-embedding-3-small");}

// 批量处理优于逐条处理（大多数模型支持 batch）List<Document> batch = chunkedDocuments;List<List<Double>> embeddings = embeddingModel.embed(batch); // 一次调用// 缓存 embedding 结果（避免重复计算）// 向量数据库通常会自动处理缓存

public interface VectorStore {    void add(List<Document> documents);    void delete(List<String> idList);    List<Document> similaritySearch(SearchRequest request);}

// 开发环境：Chroma（零配置嵌入式）@Beanpublic VectorStore chromaVectorStore(EmbeddingModel embeddingModel) {    return new ChromaVectorStore(chromaApi, embeddingModel, "collection_name");}// 中小规模生产：PGVector（复用 PostgreSQL 基础设施）@Beanpublic VectorStore pgVectorStore(EmbeddingModel embeddingModel,                                   JdbcTemplate jdbcTemplate) {    return new PgVectorStore(jdbcTemplate, embeddingModel,         PgVectorStore.PgDistanceType.COSINE_DISTANCE,         PgIndexType.HNSW,  // HNSW 索引，支持 ANN 搜索        false);             // 不移除现有文档}// 大规模生产：Pinecone（全托管）@Beanpublic VectorStore pineconeVectorStore(PineconeApi api,                                        EmbeddingModel embeddingModel) {    return new PineconeVectorStore(api, embeddingModel,         "my-index", PineconeVectorStore.MetadataFields.NONE);}

// Spring AI 中实现带过滤的检索SearchRequest request = SearchRequest.builder()    .query("2026年第一季度财报数据")     // 查询文本    .topK(10)                                // 返回前10条    .similarityThreshold(0.75)               // 相似度阈值    .filterExpression("category == 'quarterly' && created_at > '2026-01-01'")    .build();List<Document> results = vectorStore.similaritySearch(request);

// 余弦距离：1 - cos(A, B)// 值域 [0, 2]，越小越相似PgVectorStore.PgDistanceType.COSINE_DISTANCE// 内积距离：常用于归一化向量// 值域 [-1, 1]，越大越相似PgVectorStore.PgDistanceType.NEGATIVE_INNER_PRODUCT// 欧几里得距离：适合低维向量PgVectorStore.PgDistanceType.EUCLIDEAN_DISTANCE

// K 值的影响K = 1-3:   高精度，低召回（严谨问答场景）K = 5-10:  适中（通用知识问答）K = 10-20: 高召回，低精度（摘要、综合分析场景）

// 概念：问题越复杂，需要的上下文越多int dynamicTopK(String question) {    int words = question.split(" ").length;    int tokens = estimateTokens(question);    if (tokens < 10) return 3;    // 简单问题    if (tokens < 50) return 5;    // 一般问题    return 10;                     // 复杂问题}

SearchRequest request = SearchRequest.builder()    .query(question)    .topK(20)    .similarityThreshold(0.7)  // 低于 0.7 的结果将被丢弃    .build();

// 1. QuestionAnswerAdvisor：最简单的 RAG// 自动执行检索并将结果注入 Prompt.defaultAdvisors(new QuestionAnswerAdvisor(vectorStore))// 2. RetrievalAugmentationAdvisor：更灵活的配置.defaultAdvisors(RetrievalAugmentationAdvisor.builder()    .documentRetriever(DefaultDocumentRetriever.builder()        .vectorStore(vectorStore)        .similarityThreshold(0.75)        .topK(5)        .build())    .contentFormatter(DefaultContentFormatter.builder()        .withTemplate("""            上下文信息：            ------------            {documents}            ------------            请基于上述上下文回答以下问题。            """)        .build())    .build())

用户问题: "去年的营收怎么样？"重写后: "2025年公司年度营收数据"

用户问题: "苹果和微软2025年的营收对比"子问题1: "苹果公司2025年营收是多少"子问题2: "微软公司2025年营收是多少"

用户问题: "什么是量子计算？"假设文档: "量子计算是一种利用量子力学原理进行信息处理的计算方式..."检索: 用假设文档的 embedding 去匹配真实文档

// 自定义上下文模板ContentFormatter formatter = DefaultContentFormatter.builder()    .withTemplate("""        你是一个专业的AI助手。        ## 上下文信息        以下是与你需要回答的问题相关的参考信息。请仔细阅读这些信息，        它们来自我们公司的知识库：        {% for document in documents %}        [来源：{{ document.metadata.source }}]        {{ document.content }}        {% endfor %}        ## 回答要求        1. 如果上下文信息充分，请基于上下文给出准确、详细的回答        2. 如果上下文信息不足，请明确说明"根据现有信息无法回答"        3. 回答时请在句末标注信息来源：[[来源：xxx]]        4. 不要编造上下文之外的信息        5. 使用专业、清晰的语言        ## 用户问题        {{ userInput }}        """)    .build();

1. 接收用户请求2. 调用 VectorStore.similaritySearch() 检索相关文档3. 将检索结果注入 Prompt（通过 ContentFormatter）4. 构造增强后的 Prompt：   System: [原始 System Message + 检索到的上下文]   User: [用户问题]5. 调用 ChatModel6. 返回基于上下文的回答

// 流式 RAG 响应@Beanpublic ChatClient streamingChatClient(ChatClient.Builder builder) {    return builder        .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore))        .build();}// Controller@GetMapping("/chat/stream")public Flux<String> streamChat(@RequestParam String question) {    return streamingChatClient.prompt()        .user(question)        .stream()        .content();}

// 在 Prompt 中要求标注来源// 同时在后处理中解析引用@Servicepublic class CitedRagService {    public AnswerWithSources answer(String question) {        String response = chatClient.prompt()            .user(question)            .call()            .content();        // 解析引用来源（从元数据中提取）        List<String> sources = extractSources(response);        return new AnswerWithSources(response, sources);    }    private List<String> extractSources(String response) {        // 从 LLM 输出中解析 [[来源: xxx]] 格式的引用        Pattern pattern = Pattern.compile("\\[\\[来源：(.+?)\\]\\]");        Matcher matcher = pattern.matcher(response);        return matcher.results()            .map(r -> r.group(1))            .distinct()            .collect(Collectors.toList());    }}public record AnswerWithSources(    String answer,    List<String> sources) {}

用户： "什么是量子计算？"助手： "量子计算是..."用户： "它和传统计算有什么区别？"      ↑ 这里的"它"指的是量子计算，需要从对话历史推断

// 在检索前，将对话历史压缩为最新的上下文// 或者让 LLM 将用户问题补全为独立问题@Componentpublic class ContextualQueryEnricher {    public String enrichQuery(String currentQuestion,                                List<Message> history) {        if (history.isEmpty()) {            return currentQuestion;        }        // 使用 LLM 将问题补全        String enriched = chatClient.prompt()            .system("""                根据对话历史，将用户的最后一句话改写为可以独立检索的查询。                只需要返回改写后的查询，不要有其他内容。                """)            .user("""                历史对话：                %s                用户最新问题：%s                """.formatted(formatHistory(history), currentQuestion))            .call()            .content();        return enriched != null ? enriched : currentQuestion;    }}

用户问题    │    ├──→ 向量检索（语义匹配）    ├──→ 关键词检索（精确匹配，如 Elasticsearch）    ├──→ 图检索（实体关系，如 Neo4j）    └──→ SQL 查询（结构化数据）            │            └──→ 融合排序 → 最终上下文

@Componentpublic class HybridRetriever {    private final VectorStore vectorStore;    private final ElasticsearchRestClient esClient;    public List<Document> retrieve(String query, int topK) {        // 1. 向量检索        List<Document> vectorResults = vectorStore.similaritySearch(            SearchRequest.builder().query(query).topK(topK).build());        // 2. 关键词检索        List<Document> keywordResults = keywordSearch(query, topK);        // 3. 融合排序（Reciprocal Rank Fusion）        return reciprocalRankFusion(vectorResults, keywordResults, topK);    }    private List<Document> reciprocalRankFusion(            List<Document>... rankings) {        // RRF: score = Σ 1/(k + rank)        // 融合多路检索结果，被多路都命中的文档排名更高        // ...    }}

            ┌─────────────┐            │ 全局摘要      │  ← Level 2（最抽象）            └──────┬──────┘                   │         ┌─────────┼─────────┐         │         │         │   ┌────┴───┐ ┌───┴────┐ ┌──┴────┐   │摘要集群A │ │摘要集群B │ │摘要集群C │  ← Level 1   └────┬───┘ └───┬────┘ └───┬───┘        │         │          │   ┌────┴───┐    ...         ...   │原始块A1 │   │原始块A2 │   └────────┘                   ← Level 0（原始文档块）

1. 检索：根据问题检索相关文档2. 评估：判断检索到的文档是否与问题相关   - 相关 → 基于文档生成答案   - 不相关 → 拒绝回答或请求补充信息3. 事实核查：检查生成的答案是否基于检索到的文档4. 最终输出：如果有冲突，修正或标注不确定性

// 索引管线（IndexingPipeline）@Configurationpublic class IndexingPipelineConfig {    private final EmbeddingModel embeddingModel;    private final VectorStore vectorStore;    @Bean    public CommandLineRunner indexDocuments(            @Value("${documents.path}") String docPath) {        return args -> {            // 1. 扫描文档            List<File> files = scanDocuments(docPath);            for (File file : files) {                // 2. 文档加载                DocumentReader reader = createReader(file);                List<Document> documents = reader.read();                // 3. 文档分割                DocumentTransformer splitter = TokenTextSplitter.builder()                    .defaultMaxTokenSize(500)                    .minOverlap(50)                    .build();                List<Document> chunks = splitter.apply(documents);                // 4. 向量化并存储                vectorStore.add(chunks);                log.info("Indexed: {} ({} chunks)", file.getName(), chunks.size());            }        };    }    private DocumentReader createReader(File file) {        String name = file.getName().toLowerCase();        Resource resource = new FileSystemResource(file);        if (name.endsWith(".pdf")) return new PdfDocumentReader(resource);        if (name.endsWith(".md"))  return new MarkdownDocumentReader(resource);        if (name.endsWith(".csv")) return new CsvDocumentReader(resource);        // 扩展更多格式        throw new UnsupportedOperationException("Unsupported format: " + name);    }}

@Servicepublic class IncrementalIndexingService {    private final VectorStore vectorStore;    private final DocumentIdStrategy idStrategy;    // 文档更新时调用    public void updateDocument(String docId, String newContent) {        // 1. 删除旧索引        vectorStore.delete(List.of(docId));        // 2. 重新分割和索引        Document doc = Document.builder()            .id(docId)            .content(newContent)            .metadata(Map.of("updated_at", Instant.now().toString()))            .build();        List<Document> chunks = splitter.apply(List.of(doc));        vectorStore.add(chunks);    }    // 监听文件变化（适用于本地文件）    @EventListener    public void onFileChange(FileChangeEvent event) {        updateDocument(event.getFileId(), event.getContent());    }}

@Configurationpublic class RagCacheConfig {    @Bean    public CacheManager ragCacheManager() {        // 使用 Caffeine 作为本地缓存        CaffeineCacheManager cacheManager = new CaffeineCacheManager("rag-cache");        cacheManager.setCaffeine(Caffeine.newBuilder()            .maximumSize(1000)            .expireAfterWrite(1, TimeUnit.HOURS)            .recordStats());        return cacheManager;    }    @Bean    public ChatClient cachedChatClient(ChatClient.Builder builder) {        return builder            .defaultAdvisors(new QuestionAnswerAdvisor(vectorStore))            .build();    }}@Servicepublic class CachedRagService {    @Cacheable(value = "rag-cache", key = "#question")    public String ask(String question) {        return chatClient.prompt()            .user(question)            .call()            .content();    }}

@Servicepublic class AsyncIndexingService {    private final Executor executor = Executors.newVirtualThreadPerTaskExecutor();    @Async    public CompletableFuture<Void> indexDocumentAsync(MultipartFile file) {        return CompletableFuture.runAsync(() -> {            // 异步处理文档索引            indexDocument(file);        }, executor);    }    // 批量索引    public void batchIndex(List<File> files) {        List<CompletableFuture<Void>> futures = files.stream()            .map(file -> CompletableFuture.runAsync(() -> indexDocument(file), executor))            .toList();        // 等待所有完成        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))            .join();    }}

@RestController@RequestMapping("/api/rag")public class RagController {    private final RagService ragService;    // 标准问答    @PostMapping("/ask")    public ResponseEntity<RagResponse> ask(@RequestBody @Valid RagRequest request) {        RagResponse response = ragService.ask(request);        return ResponseEntity.ok(response);    }    // 流式问答    @PostMapping(value = "/ask/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)    public Flux<ServerSentEvent<String>> askStream(@RequestBody RagRequest request) {        return ragService.askStream(request)            .map(content -> ServerSentEvent.<String>builder()                .data(content)                .build());    }    // 带引用来源的问答    @PostMapping("/ask/cited")    public ResponseEntity<CitedResponse> askWithCitations(            @RequestBody @Valid RagRequest request) {        CitedResponse response = ragService.askWithCitations(request);        return ResponseEntity.ok(response);    }    // 文档上传和索引    @PostMapping("/documents/upload")    public ResponseEntity<Void> uploadDocument(            @RequestParam("file") MultipartFile file) {        ragService.indexDocument(file);        return ResponseEntity.accepted().build();    }}public record RagRequest(    @NotBlank String question,    @Min(1) @Max(20) Integer topK,    Double similarityThreshold,    String filterExpression) {}public record RagResponse(    String answer,    long processingTimeMs) {}public record CitedResponse(    String answer,    List<Source> sources,    long processingTimeMs) {    public record Source(String title, String content, double score) {}}

@Componentpublic class RagMetricsCollector {    private final MeterRegistry meterRegistry;    public void recordQuery(String question, RagResponse response) {        // 记录查询延迟        meterRegistry.timer("rag.query.latency")            .record(response.processingTimeMs(), TimeUnit.MILLISECONDS);        // 记录检索结果数量        meterRegistry.gauge("rag.retrieval.topk", response.sources().size());        // 记录平均相似度分数        double avgScore = response.sources().stream()            .mapToDouble(Source::score)            .average()            .orElse(0.0);        meterRegistry.gauge("rag.retrieval.avg_score", avgScore);    }}

失败模式              表现形式                    解决方案───────              ────────                    ────────检索失败              返回了完全不相关的文档        调整分割策略、embedding模型、检索参数上下文窗口溢出          Token 使用超过限制          减小 Top-K、压缩上下文幻觉                  答案包含检索结果中没有的信息   优化 Prompt、增加 faithfulness 检查引用错误               标注了错误的来源              加强引用解析逻辑更新延迟               文档已修改但索引未更新         实现增量索引机制冷启动问题              新知识库没有高质量检索结果     预置种子数据，逐步优化嵌入