基于 SpringAI 与 RAG 的知识库问答机器人实战

2.2.2 应用配置

在 application.yml 中配置 API 密钥和相关参数。

spring:
  ai:
    zhipuai:
      api-key: ${zhipuai-api-key}
    chat:
      options:
        model: GLM-4-Flash
        temperature: 0.1
  thymeleaf:
    cache: false
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 50MB
logging:
  level:
    org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor: debug
    org.springframework.ai.chat.client: DEBUG
server:
  port: 8080

2.3 自定义向量存储实现

通常 RAG 会使用 Pinecone、Weaviate 等成熟向量数据库，但考虑到环境成本，我们可以实现一个基础的自定义文本向量库 TextBasedVectorStore，基于内存实现，无需外部依赖，适合快速原型开发。

Spring AI 原生提供了 SimpleVectorStore，依赖向量模型。如果没有渠道使用向量模型，可以参考下面的自定义实现，它提供了一套不依赖向量模型的解决方案。

2.3.1 TextBasedVectorStore - 文本匹配向量存储

重点实现了两个方法：doAdd（文档保存）和 doSimilaritySearch（相似度搜索）。注意：文档向量化与搜索时的向量化需采用同一套方案。

public class TextBasedVectorStore extends AbstractObservationVectorStore {
    @Getter
    protected Map<String, SimpleVectorStoreContent> store = new ConcurrentHashMap<>();
    private Set<String> persistMd5 = new CopyOnWriteArraySet<>();

    @Override
    public void doAdd(List<Document> documents) {
        if (CollectionUtils.isEmpty(documents)) return;
        List<Document> mutableDocuments = new ArrayList<>();
        for (Document document : documents) {
            if (!persistMd5.contains((String) document.getMetadata().get("md5"))) {
                mutableDocuments.add(document);
            }
        }
        if (CollectionUtils.isEmpty(mutableDocuments)) return;

        // 文档分片
        List<Document> chunkers = DocumentChunker.DEFAULT_CHUNKER.chunkDocuments(mutableDocuments);
        chunkers.forEach(document -> {
            float[] embedding = DocumentQuantizer.quantizeDocument(document);
            if (embedding.length == 0) return;
            SimpleVectorStoreContent storeContent = new SimpleVectorStoreContent(
                document.getId(), document.getText(), document.getMetadata(), embedding
            );
            this.store.put(document.getId(), storeContent);
        });
        mutableDocuments.forEach(document -> 
            persistMd5.add((String) document.getMetadata().get("md5"))
        );
    }

    @Override
    public List<Document> doSimilaritySearch(SearchRequest request) {
        Predicate<SimpleVectorStoreContent> documentFilterPredicate = this.doFilterPredicate(request);
        final float[] userQueryEmbedding = this.getUserQueryEmbedding(request.getQuery());
        return this.store.values().stream()
            .filter(documentFilterPredicate)
            .map(content -> content.toDocument(
                DocumentQuantizer.calculateCosineSimilarity(userQueryEmbedding, content.getEmbedding())
            ))
            .filter(document -> document.getScore() >= request.getSimilarityThreshold())
            .sorted(Comparator.comparing(Document::getScore).reversed())
            .limit((long) request.getTopK())
            .toList();
    }

    private float[] getUserQueryEmbedding(String query) {
        return DocumentQuantizer.quantizeQuery(query);
    }
}

2.3.2 DocumentChunker - 文档分块器

合理分块是 RAG 的关键。固定尺寸、语义拆分、结构化拆分都是常见方案。这里采用优先在语义边界处分割的方案。

public class DocumentChunker {
    private final int maxChunkSize;
    private final int overlapSize;

    public DocumentChunker() {
        this(500, 50); // 默认最大块 500 字符，重叠 50 字符
    }

    public List<Document> chunkDocument(Document document) {
        String content = document.getText();
        if (content == null || content.trim().isEmpty()) return List.of(document);
        List<String> chunks = splitText(content);
        List<Document> chunkedDocuments = new ArrayList<>();
        for (int i = 0; i < chunks.size(); i++) {
            String chunk = chunks.get(i);
            String chunkId = document.getId() + "_chunk_" + i;
            Document chunkDoc = new Document(chunkId, chunk, new HashMap<>(document.getMetadata()));
            chunkDoc.getMetadata().put("chunk_index", i);
            chunkDoc.getMetadata().put("total_chunks", chunks.size());
            chunkDoc.getMetadata().put("original_document_id", document.getId());
            chunkedDocuments.add(chunkDoc);
        }
        return chunkedDocuments;
    }

    private List<String> splitText(String text) {
        List<String> chunks = new ArrayList<>();
        String[] sentences = text.split("(?<=。)|(?<=！)|(?<=!)|(?<=？)|(?<=\\?)|(?<=\\n\\n)");
        StringBuilder currentChunk = new StringBuilder();
        for (String sentence : sentences) {
            if (sentence.trim().isEmpty()) continue;
            if (currentChunk.length() + sentence.length() <= maxChunkSize) {
                if (currentChunk.length() > 0) currentChunk.append(sentence);
                else currentChunk.append(sentence);
            } else {
                if (currentChunk.length() == 0) {
                    List<String> subChunks = forceSplit(sentence, maxChunkSize);
                    for (int i = 0; i < subChunks.size(); i++) {
                        String subChunk = subChunks.get(i);
                        if (i < subChunks.size() - 1) chunks.add(subChunk);
                        else currentChunk.append(subChunk);
                    }
                } else {
                    chunks.add(currentChunk.toString());
                    currentChunk = new StringBuilder();
                    if (sentence.length() > overlapSize) {
                        String overlap = sentence.substring(Math.max(0, sentence.length() - overlapSize));
                        currentChunk.append(overlap).append(sentence);
                    } else {
                        currentChunk.append(sentence);
                    }
                }
            }
        }
        if (currentChunk.length() > 0) chunks.add(currentChunk.toString());
        return chunks;
    }
    // forceSplit 方法略...
}

2.3.3 DocumentQuantizer - 文档量化器

使用 HanLP 进行中文分词，实现简单的文档向量化。虽然效果不如 EmbeddingModel，但用于学习体验 RAG 足够。

public class DocumentQuantizer {
    private static final Segment SEGMENT = HanLP.newSegment();

    public static float[] quantizeText(String text) {
        if (text == null || text.trim().isEmpty()) return new float[0];
        String[] words = preprocessText(text);
        Map<String, Integer> wordFreq = countWordFrequency(words);
        return generateFixedLengthVector(wordFreq, 128);
    }

    private static String[] preprocessText(String text) {
        List<Term> termList = SEGMENT.seg(text);
        return termList.stream()
            .filter(term -> !isStopWord(term.word))
            .filter(term -> !term.nature.toString().startsWith("w"))
            .map(term -> term.word.toLowerCase())
            .toArray(String[]::new);
    }

    private static float[] generateFixedLengthVector(Map<String, Integer> wordFreq, int length) {
        float[] vector = new float[length];
        List<Map.Entry<String, Integer>> sortedEntries = wordFreq.entrySet().stream()
            .sorted(Map.Entry.<String, Integer>comparingByValue().reversed())
            .limit(length)
            .collect(Collectors.toList());
        for (int i = 0; i < Math.min(sortedEntries.size(), length); i++) {
            vector[i] = sortedEntries.get(i).getValue();
        }
        return vector;
    }

    public static double calculateCosineSimilarity(float[] vectorA, float[] vectorB) {
        if (vectorA == null || vectorB == null || vectorA.length == 0 || vectorB.length == 0) return 0.0;
        int minLength = Math.min(vectorA.length, vectorB.length);
        float[] adjustedA = Arrays.copyOf(vectorA, minLength);
        float[] adjustedB = Arrays.copyOf(vectorB, minLength);
        double dotProduct = 0.0, normA = 0.0, normB = 0.0;
        for (int i = 0; i < minLength; i++) {
            dotProduct += adjustedA[i] * adjustedB[i];
            normA += Math.pow(adjustedA[i], 2);
            normB += Math.pow(adjustedB[i], 2);
        }
        normA = Math.sqrt(normA);
        normB = Math.sqrt(normB);
        if (normA == 0 || normB == 0) return 0.0;
        return dotProduct / (normA * normB);
    }
}

2.3.4 注册向量库

在配置类或启动类中添加 Bean 声明即可。

@Bean
public VectorStore vectorStore() {
    return TextBasedVectorStore.builder().build();
}

若可直接使用大模型厂家的向量模型，则忽略上述自定义实现，直接使用：

@Bean
public VectorStore vectorStore(EmbeddingModel embeddingModel) {
    return SimpleVectorStore.builder(embeddingModel).build();
}

2.4 问答服务实现

2.4.1 QaBoltService - 核心问答服务

问答服务流程分为两步：文档向量化（数据准备）和问答（应用层响应）。

第一步：文档向量化 包含数据提取、文本分割、向量化。

第二步：问答 响应用户提问，检索相似文档，注入提示词，访问大模型获取答案。

实际使用中，用户上传附件会同时触发这两个步骤。

Step 1: 初始化 ChatClient 参照官方教程，通过 Advisor 初始化支持 RAG 的 ChatClient。

@Service
public class QaBoltService {
    private final ChatClient chatClient;
    private final ChatMemory chatMemory;
    private final VectorStore vectorStore;
    @Value("classpath:/prompts/qa-prompts.pt")
    private Resource boltPrompts;

    public QaBoltService(ChatClient.Builder builder, VectorStore vectorStore, ChatMemory chatMemory) {
        this.vectorStore = vectorStore;
        this.chatMemory = chatMemory;
        this.chatClient = builder.defaultAdvisors(
            new SimpleLoggerAdvisor(ModelOptionsUtils::toJsonStringPrettyPrinter, ModelOptionsUtils::toJsonStringPrettyPrinter, 0),
            MessageChatMemoryAdvisor.builder(chatMemory).build(),
            RetrievalAugmentationAdvisor.builder()
                .queryTransformers(RewriteQueryTransformer.builder().chatClientBuilder(builder.build().mutate()).build())
                .queryAugmenter(ContextualQueryAugmenter.builder().allowEmptyContext(true).build())
                .documentRetriever(VectorStoreDocumentRetriever.builder()
                    .similarityThreshold(0.50).vectorStore(vectorStore).build())
                .build()
        ).build();
    }
}

Step 2: 文档处理 处理用户上传的附件，解析、切分、向量化、保存。利用元数据中的 MD5 去重。

private ProceedInfo processFiles(String chatId, Collection<MultipartFile> files) {
    StringBuilder context = new StringBuilder("\n\n");
    List<Media> mediaList = new ArrayList<>();
    files.forEach(file -> {
        try {
            var data = new ByteArrayResource(file.getBytes());
            var md5 = calculateHash(chatId, file.getBytes());
            MimeTypemime = MimeType.valueOf(file.getContentType());
            if (mime.equalsTypeAndSubtype(MediaType.APPLICATION_PDF)) {
                PagePdfDocumentReader pdfReader = new PagePdfDocumentReader(data,
                    PdfDocumentReaderConfig.builder()
                        .withPageTopMargin(0)
                        .withPageExtractedTextFormatter(ExtractedTextFormatter.builder()
                            .withNumberOfTopTextLinesToDelete(0).build())
                        .withPagesPerDocument(1).build());
                List<Document> documents = pdfReader.read();
                documents.forEach(document -> {
                    document.getMetadata().put("md5", md5);
                    if (document.getMetadata().containsKey("file_name") && document.getMetadata().get("file_name") == null) {
                        document.getMetadata().put("file_name", file.getName());
                    }
                });
                vectorStore.add(documents);
                var content = String.join("\n", documents.stream().map(Document::getText).toList());
                context.append(String.format(ATTACHMENT_TEMPLATE, file.getName(), content));
            } else if ("text".equalsIgnoreCase(mime.getType())) {
                List<Document> documents = new TikaDocumentReader(data).read();
                documents.forEach(document -> document.getMetadata().put("md5", md5));
                vectorStore.add(documents);
                var content = String.join("\n", documents.stream().map(Document::getText).toList());
                context.append(String.format(ATTACHMENT_TEMPLATE, file.getName(), content));
            }
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    });
    return new ProceedInfo(context.toString(), mediaList);
}

Step 3: 问答实现 借助 QuestionAnswerAdvisor 封装 RAG 信息，使用自定义提示词模板。

public Flux<String> ask(String chatId, String question, Collection<MultipartFile> files) {
    processFiles(chatId, files);
    PromptTemplate customPromptTemplate = PromptTemplate.builder()
        .renderer(StTemplateRenderer.builder().startDelimiterToken('<').endDelimiterToken('>').build())
        .template("""
            <query> Context information is below.
            ---------------------
            <question_answer_context>
            ---------------------
            Given the context information and no prior knowledge, answer the query.
            Follow these rules:
            1. If the answer is not in the context, just say that you don't know.
            2. Avoid statements like "Based on the context..." or "The provided information...".
            """).build();
    var qaAdvisor = QuestionAnswerAdvisor.builder(vectorStore)
        .searchRequest(SearchRequest.builder().similarityThreshold(0.5d).topK(3).build())
        .promptTemplate(customPromptTemplate)
        .build();
    var requestSpec = chatClient.prompt()
        .system(boltPrompts)
        .user(question)
        .advisors(qaAdvisor)
        .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, chatId));
    return requestSpec.stream().content().map(s -> s.replaceAll("\n", "<br/>"));
}

2.4.2 控制器实现

@RestController
@RequestMapping("/api")
public class QaApiController {
    @Autowired
    private QaBoltService qaBolt;

    @GetMapping(path = "/chat/{chatId}", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> qaGet(@PathVariable("chatId") String chatId, @RequestParam("question") String question) {
        return qaBolt.ask(chatId, question, Collections.emptyList());
    }

    @PostMapping(path = "/chat/{chatId}", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> qaPost(@PathVariable("chatId") String chatId, @RequestParam("question") String question, 
                               @RequestParam(value = "files", required = false) Collection<MultipartFile> files) {
        if (files == null) files = Collections.emptyList();
        return qaBolt.ask(chatId, question, files);
    }
}

三、体验与小结

3.1 启动类

@SpringBootApplication
public class D05Application {
    @Bean
    public VectorStore vectorStore() {
        return TextBasedVectorStore.builder().build();
    }

    public static void main(String[] args) {
        SpringApplication.run(D05Application.class, args);
        System.out.println("启动成功，前端测试访问地址：http://localhost:8080/chat");
    }
}

3.2 问答提示词

在 resources/prompts/qa-prompts.pt 中维护系统提示词。

## 角色设定
你是一个智能问答助手，专门负责根据用户提供的文档内容进行准确的回答和信息提取。

## 核心任务
- 仔细阅读并理解用户上传的文档内容
- 基于文档中的信息回答用户的问题
- 提供准确、相关且基于文档的答案
- 当问题超出文档范围时，明确告知用户该信息未在文档中提及

## 工作流程
1. 首先分析用户上传的文档，提取关键信息
2. 理解用户提出的问题
3. 在文档中查找与问题相关的信息
4. 整合相关信息并形成结构化答案
5. 如无法从文档中找到相关信息，则说明情况

## 回答规范
- 严格基于文档内容作答，不得编造信息
- 引用文档中的具体信息时，请保持原文准确性
- 如果问题涉及多个知识点，在答案中清晰分点说明
- 对于不确定的内容，应诚实表达不确定性，而非猜测
- 保持回答简洁明了，同时确保信息完整

## 注意事项
- 不得脱离文档内容进行回答
- 遇到模糊或不明确的问题时，可以请求用户提供更详细的信息
- 如果文档中没有相关内容，必须明确告知用户
- 保持专业、礼貌的沟通态度

3.3 运行与测试

1. 启动应用：运行 D05Application 主类。
2. 访问页面：打开 http://localhost:8080/chat。
3. 上传文档：选择 PDF、Word 或文本文件。
4. 提问测试：输入关于文档的问题。

启动时可在参数中指定大模型 ApiKey，或直接修改 application.yml。

3.4 核心技术要点小结

1. RAG 工作流程：检索阶段将问题转为向量查找相似文档；生成阶段结合文档内容与问题输入大模型。
2. 文档处理优化：使用 HanLP 精确中文分词；合理分块保持语义完整性；通过 MD5 哈希去重。
3. 性能优化：余弦相似度计算文本相似度；缓存已处理文档；SSE 流式返回提升体验。