5. 第一个 RAG 应用

package com.albertstack.rag.config;

import com.albertstack.rag.service.IngestionService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.vectorstore.QuestionAnswerAdvisor;
import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.vectorstore.SimpleVectorStore;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;

import java.util.List;

@Slf4j
@Configuration
public class AiConfig {

    // 内存向量存储，开发阶段够用，后续会替换为 Qdrant
    @Bean
    public VectorStore vectorStore(EmbeddingModel embeddingModel) {
        return SimpleVectorStore.builder(embeddingModel).build();
    }

    // 基础 ChatClient，不带任何 Advisor
    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder.build();
    }

    // 带 RAG 能力的 ChatClient
    @Bean
    public ChatClient ragChatClient(ChatClient.Builder builder, VectorStore vectorStore) {
        return builder
            .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore)
                .searchRequest(SearchRequest.builder()
                    .topK(5)
                    .build())
                .build())
            .build();
    }

    // 启动时自动摄入知识库
    @Bean
    public CommandLineRunner ingestDocuments(IngestionService ingestionService) {
        return args -> {
            // 这里列出要摄入的文档路径，可以根据需要添加更多文件
            List<String> files = List.of(
                "docs/spring-ai-intro.txt",
                "docs/rag-concepts.txt",
                "docs/ollama-guide.txt"
            );

            for (String file : files) {
                var resource = new ClassPathResource(file);
                int chunks = ingestionService.ingest(resource);
                log.info("已摄入: {} -> {} 个分块", file, chunks);
            }
        };
    }
}

RAG（Retrieval-Augmented Generation）是一种将信息检索与文本生成相结合的技术。它的核心思想是：在生成回答之前，先从外部知识库中检索相关信息，然后将这些信息作为上下文提供给语言模型。

RAG 系统的关键组件包括：

1. 文档摄入管道：负责将原始文档处理成可检索的格式。这包括文档读取、文本分块、向量化和存储四个步骤。

2. 向量数据库：存储文档的向量表示。常见的向量数据库包括 PGVector、Qdrant、Chroma、Milvus、Pinecone 等。向量数据库支持基于语义相似度的快速检索。

3. Embedding 模型：将文本转换为高维向量。好的 Embedding 模型能够捕捉文本的语义信息，使得语义相近的文本在向量空间中距离更近。

4. 检索策略：决定如何从向量数据库中获取最相关的文档。包括 Top-K 检索、相似度阈值过滤、元数据过滤等策略。

5. Prompt 工程：将检索到的文档与用户问题组合成有效的 Prompt。好的 Prompt 模板能显著提升回答质量。

RAG 相比直接使用 LLM 的优势：
- 知识实时更新：只需更新知识库，无需重新训练模型
- 减少幻觉：回答基于真实文档，而非模型的参数记忆
- 可追溯：可以标注回答的来源文档
- 成本低：不需要微调模型，普通硬件即可运行

Ollama 是一个本地运行大语言模型的工具，让你无需云端 API 就能在自己的电脑上使用 LLM。

Ollama 的主要特点：

1. 简单易用：一条命令即可下载并运行模型。例如 ollama run llama3 就能启动 Meta 的 LLaMA 3 模型进行对话。
2. 模型丰富：支持 LLaMA 3、Mistral、Gemma、Qwen 等主流开源模型，以及 qwen3-embedding、nomic-embed-text 等 Embedding 模型。
3. API 兼容：提供 REST API 接口，兼容 OpenAI API 格式，方便集成到各种应用中。默认运行在 http://localhost:11434。
4. 资源管理：根据模型大小自动分配 CPU 或 GPU 资源。支持 Apple Silicon 的 Metal 加速和 NVIDIA CUDA 加速。
5. 模型自定义：通过 Modelfile 可以自定义模型参数、系统提示词等。

在 Spring AI 中使用 Ollama 非常简单，只需要在配置文件中指定模型名称和服务地址即可。Spring AI 的 Ollama 集成支持 Chat 和 Embedding 两种模型类型。

package com.albertstack.rag.service;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Flux;

@Service
public class RagService {

    private final ChatClient ragChatClient;

    public RagService(@Qualifier("ragChatClient") ChatClient ragChatClient) {
        this.ragChatClient = ragChatClient;
    }

    /**
     * 同步问答：等待完整回答后一次性返回
     */
    public String chat(String question) {
        return ragChatClient.prompt()
            .user(question)
            .call()
            .content();
    }

    /**
     * 流式问答：逐 Token 返回纯文本，适合 SSE 接口
     */
    public Flux<String> chatStream(String question) {
        return ragChatClient.prompt()
            .user(question)
            .stream()
            .content();
    }

    /**
     * 流式问答（详细版）：返回完整的 ChatResponse，可提取思考过程和元数据
     */
    public Flux<ChatResponse> chatStreamDetail(String question) {
        return ragChatClient.prompt()
            .user(question)
            .stream()
            .chatResponse();
    }
}

package com.albertstack.rag.controller;

import com.albertstack.rag.service.RagService;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;

import java.util.Map;

@RestController
@RequestMapping("/api/rag")
public class RagController {

    private final RagService ragService;

    public RagController(RagService ragService) {
        this.ragService = ragService;
    }

    @PostMapping("/chat")
    public Map<String, String> chat(@RequestBody Map<String, String> request) {
        String question = request.get("question");
        String answer = ragService.chat(question);
        return Map.of("question", question, "answer", answer);
    }

    @GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> chatStream(@RequestParam String question) {
        return ragService.chatStream(question);
    }
}

package com.albertstack.rag;

import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.boot.test.context.SpringBootTest;

import static org.assertj.core.api.Assertions.assertThat;

@Slf4j
@SpringBootTest
class RagCompareTest {

    @Autowired
    private ChatClient chatClient; // 基础版，无 Advisor

    @Autowired
    @Qualifier("ragChatClient")
    private ChatClient ragChatClient; // 带 QuestionAnswerAdvisor

    @Test
    void compareWithAndWithoutRag() {
        String question = "Spring AI 支持哪些向量数据库？";

        // 无 RAG：模型凭训练数据回答，可能不准确
        String plainAnswer = chatClient.prompt()
            .user(question)
            .call()
            .content();
        log.info("无 RAG 回答：\n{}", plainAnswer);

        // 有 RAG：基于知识库文档回答
        String ragAnswer = ragChatClient.prompt()
            .user(question)
            .call()
            .content();
        log.info("有 RAG 回答：\n{}", ragAnswer);

        // RAG 版本应该包含知识库中的具体内容
        assertThat(ragAnswer).satisfiesAnyOf(
            a -> assertThat(a).containsIgnoringCase("SimpleVectorStore"),
            a -> assertThat(a).containsIgnoringCase("PGVector"),
            a -> assertThat(a).containsIgnoringCase("Chroma")
        );
    }

    @Test
    void ragShouldAnswerSpecificFacts() {
        // 知识库中明确写了 http://localhost:11434
        String answer = ragChatClient.prompt()
            .user("Ollama 默认运行在哪个端口？")
            .call()
            .content();
        log.info("回答：{}", answer);

        assertThat(answer).contains("11434");
    }
}

// topK = 1：只检索最相关的 1 个文档块
SearchRequest.builder().topK(1).build()

// topK = 10：检索最相关的 10 个文档块
SearchRequest.builder().topK(10).build()

// 低阈值：宽松匹配
SearchRequest.builder().similarityThreshold(0.5).build()

// 高阈值：严格匹配
SearchRequest.builder().similarityThreshold(0.9).build()

@Bean
public ChatClient ragChatClient(ChatClient.Builder builder, VectorStore vectorStore) {
    return builder
        .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore)
            .searchRequest(SearchRequest.builder()
                .topK(5)
                .similarityThreshold(0.7)
                .build())
            .promptTemplate(new PromptTemplate("""
                基于以下上下文信息回答用户的问题。
                如果上下文中没有相关信息，请明确告知用户"根据现有资料无法回答该问题"，不要编造答案。
                回答时请引用相关的上下文内容来支持你的观点。

                上下文：
                {question_answer_context}

                用户问题：{query}
                """))
            .build())
        .build();
}

package com.albertstack.rag.service;

import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

import static org.assertj.core.api.Assertions.assertThat;

@Slf4j
@SpringBootTest
class RagServiceTest {

    // AiConfig 中的 CommandLineRunner 会在测试启动时自动摄入知识库

    @Autowired
    private RagService ragService;

    @Test
    void shouldAnswerFromKnowledgeBase() {
        String question = "Spring AI 支持哪些向量数据库？";
        String answer = ragService.chat(question);

        log.info("问题：{}", question);
        log.info("回答：{}", answer);

        assertThat(answer).satisfiesAnyOf(
                a -> assertThat(a).containsIgnoringCase("PGVector"),
                a -> assertThat(a).containsIgnoringCase("SimpleVectorStore"),
                a -> assertThat(a).containsIgnoringCase("Chroma")
        );
    }

    @Test
    void shouldAnswerAboutOllama() {
        String question = "Ollama 支持哪些模型？";
        String answer = ragService.chat(question);

        log.info("问题：{}", question);
        log.info("回答：{}", answer);

        assertThat(answer).satisfiesAnyOf(
                a -> assertThat(a).containsIgnoringCase("LLaMA"),
                a -> assertThat(a).containsIgnoringCase("Mistral"),
                a -> assertThat(a).containsIgnoringCase("Qwen")
        );
    }

    @Test
    void shouldStreamWithThinking() {
        String question = "RAG 的核心组件有哪些？";
        log.info("问题：{}", question);

        var thinkingText = new StringBuilder();
        var contentText = new StringBuilder();

        ragService.chatStreamDetail(question)
                .doOnNext(chunk -> {
                    var result = chunk.getResult();
                    if (result == null || result.getOutput() == null) return;

                    // 思考过程在 Generation metadata 的 "thinking" 字段中
                    Object thinking = result.getMetadata().get("thinking");
                    if (thinking != null && !thinking.toString().isEmpty()) {
                        thinkingText.append(thinking);
                        System.out.print(thinking);
                        return;
                    }

                    // 回答内容
                    String text = result.getOutput().getText();
                    if (text != null && !text.isEmpty()) {
                        contentText.append(text);
                        System.out.print(text);
                    }
                })
                .doOnComplete(System.out::println)
                .blockLast();

        log.info("思考过程：{} 字符", thinkingText.length());
        log.info("回答内容：{} 字符", contentText.length());

        assertThat(contentText.toString()).isNotBlank();
    }
}