Spring AI 进阶：RAG 技术原理拆解与本地知识库检索落地

Weiz-SpringAI-RAG/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── weizspringai/
│   │   │               ├── WeizSpringAiRAGApplication.java
│   │   │               ├── controller/
│   │   │               └── service/
│   │   └── resources/
│   │       ├── application.properties
│   └── test/
└── pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>Weiz-SpringAI</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </parent>
    <artifactId>Weiz-SpringAI-RAG</artifactId>
    <name>Weiz-SpringAI-RAG</name>
    <description>Weiz-SpringAI-RAG</description>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-zhipuai</artifactId>
        </dependency>

        <!-- spring-ai-client-chat 中包括 TokenTextSplitter、TextReader、Document 等工具 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-client-chat</artifactId>
            <version>${spring-ai.version}</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

    </dependencies>
</project>

# 应用名称
spring.application.name=Weiz-SpringAI-RAG
# 服务端口
server.port=8080
# 智普 AI 基础配置
spring.ai.zhipuai.api-key=你的智普 AI API Key
spring.ai.zhipuai.base-url=https://open.bigmodel.cn/api/paas
# Embedding 模型配置（用于文本向量化）
spring.ai.zhipuai.embedding.options.model=embedding-2
# Chat 模型配置（用于生成回答）
spring.ai.zhipuai.chat.options.model=GLM-4-Flash

户外旅行安全指南
----
1．露营安全
- 选址：避开低洼积水区、陡坡和可能落石的区域，优先选择平坦硬质地面。
- 防火：远离干草、枯枝等易燃物，使用炉具时保持通风，睡前彻底熄灭明火。
- 防虫：携带驱蚊液、防虫网，避免在草丛密集处搭建帐篷，睡前检查帐篷内是否有虫类。
- 应急：随身携带手电筒、急救包和足够的饮用水，提前下载离线地图。
----
2．徒步安全
- 路线规划：提前查询路线难度、天气情况，选择与自身体能匹配的路线，告知亲友行程。
- 装备要求：必须穿防滑登山鞋、戴防晒帽，携带充足食物和水，配备登山杖和护膝。
- 环境应对：遇到暴雨立即寻找高地躲避，避免涉险过河；遭遇野生动物保持冷静，切勿投喂或驱赶。
- 体能管理：保持匀速前进，每小时休息 10-15 分钟，避免过度疲劳。
----
3．城市漫游安全
- 交通：骑行遵守交通规则，不逆行、不闯红灯，佩戴安全头盔；乘坐公共交通保管好个人财物。
- 选址：避开偏僻小巷和治安较差区域，优先选择人流密集的商业街区和景点。
- 应急：保存当地派出所、医院的联系方式，携带少量现金备用，手机保持电量充足。

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.core.io.ClassPathResource;
import org.springframework.core.io.Resource;
import org.springframework.stereotype.Service;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
@Service
public class RagService {
    // Embedding 模型（文本向量化）
    private final EmbeddingModel embeddingModel;
    // Chat 模型（生成回答）
    private final ChatClient chatClient;
    // 本地知识库文本片段
    private final List<String> docChunks = new ArrayList<>();
    // 文本片段对应的向量
    private final List<float[]> docVectors = new ArrayList<>();
    // 相似度算法（默认余弦相似度，可根据需求修改）
    private final EmbeddingService.SimilarityAlgorithm similarityAlgorithm = EmbeddingService.SimilarityAlgorithm.COSINE;
    // 构造方法注入依赖，初始化知识库（索引阶段）
    public RagService(EmbeddingModel embeddingModel, ChatClient.Builder chatClientBuilder) throws IOException {
        this.embeddingModel = embeddingModel;
        this.chatClient = chatClientBuilder.build();
        // 加载本地知识库文件并切分片段
        loadAndSplitDocument();
    }
    /**
     * 加载本地知识库文件，切分为文本片段（索引阶段第一步）
     */
    private void loadAndSplitDocument() throws IOException {
        // 读取 resources 目录下的知识库文件
        Resource resource = new ClassPathResource("户外旅行安全指南.txt");
        String content = new String(resource.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
        // 按 "----" 切分文本（根据文件格式自定义切分规则）
        String[] chunks = content.split("----");
        for (String chunk : chunks) {
            String cleanChunk = chunk.strip();
            if (!cleanChunk.isBlank()) {
                docChunks.add(cleanChunk);
                // 文本片段向量化并缓存（索引阶段第二步、第三步）
                docVectors.add(embeddingModel.embed(cleanChunk));
            }
        }
    }
    /**
     * 处理用户提问，返回 RAG 增强后的回答（检索+生成阶段）
     * @param question 用户问题
     * @return 大模型生成的回答
     */
    public String answer(String question) {
        // 1. 用户问题向量化（检索阶段第一步）
        float[] questionVector = embeddingModel.embed(question);
        // 2. 检索 Top2 最相似的文本片段（检索阶段第二步、第三步）
        List<String> topRelevantChunks = retrieveTopRelevantChunks(questionVector, 2);
        // 3. 构建上下文（生成阶段第一步）
        String context = String.join("\n---\n", topRelevantChunks);
        // 4. 构建提示词（生成阶段第二步）
        String prompt = String.format(
                "以下是户外旅行安全指南的知识：\n%s\n请基于上述知识，简洁明了地回答问题：%s",
                context, question
        );
        // 5. 调用 Chat 模型生成回答（生成阶段第三步）
        return chatClient.prompt()
                .system("你是户外旅行安全助手，仅基于提供的上下文回答问题，不添加额外信息。")
                .user(prompt)
                .call()
                .content();
    }
    /**
     * 检索 TopK 最相似的文本片段（检索阶段核心逻辑）
     * @param questionVector 用户问题向量
     * @param topK 返回前 K 个相似片段
     * @return TopK 相似文本片段
     */
    private List<String> retrieveTopRelevantChunks(float[] questionVector, int topK) {
        List<ChunkSimilarity> similarityList = new ArrayList<>();
        // 计算问题向量与所有文本片段向量的相似度（使用指定算法）
        for (int i = 0; i < docVectors.size(); i++) {
            double sim = calculateSimilarity(questionVector, docVectors.get(i));
            similarityList.add(new ChunkSimilarity(i, sim));
        }
        // 按相似度降序排序，取前 topK 个
        similarityList.sort((a, b) -> Double.compare(b.similarity, a.similarity));
        return similarityList.stream()
                .limit(topK)
                .map(item -> docChunks.get(item.index))
                .toList();
    }
    /**
     * 相似度计算（调用工具类，支持算法切换）
     */
    private double calculateSimilarity(float[] a, float[] b) {
        return switch (similarityAlgorithm) {
            case COSINE -> SimilarityCalculator.cosineSimilarity(a, b);
            case EUCLIDEAN -> SimilarityCalculator.euclideanSimilarity(a, b);
            case PEARSON -> SimilarityCalculator.pearsonCorrelation(a, b);
            case MANHATTAN -> SimilarityCalculator.manhattanSimilarity(a, b);
            default -> SimilarityCalculator.cosineSimilarity(a, b); // 默认 fallback 到余弦相似度
        };
    }
    /**
     * 辅助类：存储文本片段索引与相似度
     */
    private static class ChunkSimilarity {
        int index;
        double similarity;
        ChunkSimilarity(int index, double similarity) {
            this.index = index;
            this.similarity = similarity;
        }
    }
}

import com.example.springaiembedding.service.RagService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
@RestController
@RequestMapping("/rag")
public class RagController {
    @Autowired
    private RagService ragService;
    /**
     * RAG 本地知识库检索接口
     * @param question 用户问题
     * @return 包含问题与回答的响应
     */
    @GetMapping("/ask")
    public Map<String, String> ask(@RequestParam("question") String question) {
        String answer = ragService.answer(question);
        return Map.of(
                "question", question,
                "answer", answer
        );
    }
}

{
  "question": "露营选址有什么安全要求？",
  "answer": "露营选址需避开低洼积水区、陡坡和可能落石的区域，优先选择平坦硬质地面，同时要远离干草、枯枝等易燃物，避免在草丛密集处搭建帐篷。"
}

{
  "question": "徒步时遇到暴雨该怎么办？",
  "answer": "徒步遇到暴雨时，应立即寻找高地躲避，避免涉险过河，同时注意远离陡坡和可能落石的区域，确保自身安全。"
}