RAG 混合检索深度解析：BM25 + 向量检索 + RRF 算法，让 AI 真正"找到"你要的内容

import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.rag.content.Content;
import dev.langchain4j.rag.content.retriever.ContentRetriever;
import dev.langchain4j.rag.query.Query;

import java.util.*;
import java.util.stream.Collectors;

/**
 * 基于 BM25 算法的内存关键词检索器
 * <p>
 * langchain4j 1.x 未内置 BM25 ContentRetriever，此类手动实现。
 * 中文场景建议将 tokenize() 替换为 jieba 或 HanLP 分词器。
 * 若已集成 Elasticsearch，可直接调用其 BM25 接口替换本类。
 */
public class BM25ContentRetriever implements ContentRetriever {

    private static final double K1 = 1.5;   // 词频饱和参数
    private static final double B  = 0.75;  // 文档长度归一化系数

    private final List<TextSegment> corpus = new ArrayList<>();
    private final int topK;

    public BM25ContentRetriever(int topK) {
        this.topK = topK;
    }

    /**
     * 向 BM25 索引注册文档（文档入库时同步调用）
     */
    public void index(TextSegment segment) {
        corpus.add(segment);
    }

    @Override
    public List<Content> retrieve(Query query) {
        if (corpus.isEmpty()) return Collections.emptyList();

        String[] queryTerms = tokenize(query.text());
        double avgdl = corpus.stream()
                .mapToInt(s -> tokenize(s.text()).length)
                .average()
                .orElse(1.0);

        return corpus.stream()
                .map(seg -> Map.entry(seg, bm25Score(queryTerms, seg.text(), avgdl)))
                .filter(e -> e.getValue() > 0)
                .sorted(Map.Entry.<TextSegment, Double>comparingByValue().reversed())
                .limit(topK)
                .map(e -> Content.from(e.getKey()))
                .collect(Collectors.toList());
    }

    private double bm25Score(String[] queryTerms, String docText, double avgdl) {
        String[] docTerms = tokenize(docText);
        Map<String, Long> tf = Arrays.stream(docTerms)
                .collect(Collectors.groupingBy(t -> t, Collectors.counting()));

        double score = 0.0;
        int N = corpus.size();

        for (String term : queryTerms) {
            long df = corpus.stream()
                    .filter(s -> s.text().toLowerCase().contains(term))
                    .count();
            if (df == 0) continue;

            // IDF：文档频率越低，辨别力越强
            double idf = Math.log((N - df + 0.5) / (df + 0.5) + 1);

            // TF 饱和：词频越高加分越慢，防止词语堆砌
            double termFreq = tf.getOrDefault(term, 0L);
            double numerator   = termFreq * (K1 + 1);
            double denominator = termFreq + K1 * (1 - B + B * (docTerms.length / avgdl));

            score += idf * (numerator / denominator);
        }
        return score;
    }

    /** 简单空格/标点分词；中文场景请替换为 jieba / HanLP */
    private String[] tokenize(String text) {
        return text.toLowerCase().split("[\\s\\p{Punct}]+");
    }
}

import dev.langchain4j.rag.content.Content;
import dev.langchain4j.rag.content.retriever.ContentRetriever;
import dev.langchain4j.rag.query.Query;

import java.util.*;
import java.util.stream.Collectors;

/**
 * RRF（倒数排名融合）多路检索融合器
 * <p>
 * 对任意数量的 ContentRetriever 结果按排名加权融合，不依赖原始分数。
 * RRF 得分公式：score(d) = Σ 1 / (rrfK + rank_r(d))
 */
public class RrfFusionContentRetriever implements ContentRetriever {

    private final List<ContentRetriever> retrievers;
    private final int rrfK; // 平滑常数，业界标准值 60

    /**
     * @param retrievers 多路检索器列表（如 BM25 + 向量）
     * @param rrfK       RRF 平滑常数（值越大，低排名文档贡献越平稳）
     */
    public RrfFusionContentRetriever(List<ContentRetriever> retrievers, int rrfK) {
        this.retrievers = retrievers;
        this.rrfK = rrfK;
    }

    @Override
    public List<Content> retrieve(Query query) {
        // 1. 依次调用各路检索器
        List<List<Content>> allResults = retrievers.stream()
                .map(r -> r.retrieve(query))
                .collect(Collectors.toList());

        // 2. 以文本内容为 Key，计算并累加 RRF 得分
        Map<String, Double>  rrfScores  = new LinkedHashMap<>();
        Map<String, Content> contentMap = new LinkedHashMap<>();

        for (List<Content> results : allResults) {
            for (int rank = 0; rank < results.size(); rank++) {
                Content content = results.get(rank);
                String  key     = content.textSegment().text(); // 文本去重
                double  score   = 1.0 / (rrfK + rank + 1);     // rank 从 0 开始

                rrfScores.merge(key, score, Double::sum);
                contentMap.putIfAbsent(key, content);
            }
        }

        // 3. 按 RRF 得分降序返回融合结果
        return rrfScores.entrySet().stream()
                .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
                .map(e -> contentMap.get(e.getKey()))
                .collect(Collectors.toList());
    }
}

import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.embedding.onnx.allminilml6v2.AllMiniLmL6V2EmbeddingModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.rag.content.retriever.ContentRetriever;
import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.List;

@Configuration
public class HybridRetrieverConfig {

    private static final int BM25_TOP_K   = 20;
    private static final int VECTOR_TOP_K = 20;
    private static final int RRF_K        = 60;

    @Value("${langchain4j.open-ai.api-key:demo}")
    private String apiKey;

    /**
     * 手动定义 ChatModel Bean（非 Starter 模式）
     */
    @Bean
    public ChatModel chatModel() {
        return OpenAiChatModel.builder()
                .apiKey(apiKey)
                .build();
    }

    /**
     * 手动定义 EmbeddingModel Bean（本地模型）
     */
    @Bean
    public EmbeddingModel embeddingModel() {
        return new AllMiniLmL6V2EmbeddingModel();
    }

    /**
     * 手动定义 EmbeddingStore Bean（内存存储）
     */
    @Bean
    public EmbeddingStore<TextSegment> embeddingStore() {
        return new InMemoryEmbeddingStore<>();
    }

    /**
     * 构建混合检索器（BM25 + 向量语义 + RRF 融合）
     * <p>
     * langchain4j 1.x 已移除 HybridRetriever，
     * 改为手动组合两路 ContentRetriever 并通过 RrfFusionContentRetriever 融合。
     *
     * @param embeddingModel 向量化模型（将文本转为语义向量）
     * @param embeddingStore 向量数据库（存储 & 检索向量）
     */
    @Bean
    public ContentRetriever hybridContentRetriever(
            EmbeddingModel embeddingModel,
            EmbeddingStore<TextSegment> embeddingStore) {

        // ── 向量语义检索器 ─────────────────────────────
        // EmbeddingStoreContentRetriever 是 langchain4j 1.x 的标准向量检索实现
        ContentRetriever vectorRetriever = EmbeddingStoreContentRetriever.builder()
                .embeddingStore(embeddingStore)
                .embeddingModel(embeddingModel)
                .maxResults(VECTOR_TOP_K)    // 向量侧召回 Top-20 候选
                .build();

        // ── BM25 关键词检索器 ──────────────────────────
        // langchain4j 1.x 不内置 BM25，使用自定义实现
        // 文档入库时需同步调用 bm25Retriever.index(segment) 建立索引
        BM25ContentRetriever bm25Retriever = new BM25ContentRetriever(BM25_TOP_K);

        // ── RRF 融合：统一暴露为 ContentRetriever Bean ─
        // RrfFusionContentRetriever 内部完成：
        //   1. 并发调用两路检索器
        //   2. 按排名倒数加权（公式：1 / (rrfK + rank)）
        //   3. 去重 + 降序排列，返回最终候选列表
        return new RrfFusionContentRetriever(
                List.of(bm25Retriever, vectorRetriever),
                RRF_K
        );
    }
}

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.rag.content.retriever.ContentRetriever;
import dev.langchain4j.service.AiServices;
import org.springframework.stereotype.Service;

@Service
public class KnowledgeBaseService {

    private final KnowledgeAssistant assistant;

    /**
     * langchain4j 1.13.1+：使用 ChatModel 替代 ChatLanguageModel
     */
    public KnowledgeBaseService(
            ChatModel chatModel,
            ContentRetriever hybridContentRetriever) {

        this.assistant = AiServices.builder(KnowledgeAssistant.class)
                .chatModel(chatModel)
                .contentRetriever(hybridContentRetriever)
                .build();
    }

    /**
     * 知识库问答入口
     * @param userQuestion 用户问题
     * @return AI 生成的答案（基于混合检索的上下文）
     */
    public String ask(String userQuestion) {
        return assistant.answer(userQuestion);
    }
}

import dev.langchain4j.service.SystemMessage;

/**
 * 知识库问答 AI Service
 * LangChain4j 会自动将混合检索结果注入为上下文
 */
public interface KnowledgeAssistant {

    @SystemMessage("""
            你是一个专业的知识库问答助手。
            请严格根据提供的上下文内容来回答用户问题。
            如果上下文中没有相关信息，请直接告知用户，不要编造答案。
            """)
    String answer(String userQuestion);
}

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/knowledge")
public class KnowledgeController {

    private final KnowledgeBaseService knowledgeBaseService;

    public KnowledgeController(KnowledgeBaseService knowledgeBaseService) {
        this.knowledgeBaseService = knowledgeBaseService;
    }

    /**
     * 问答接口
     * POST /api/knowledge/ask
     * Body: {"question": "苹果14的屏幕分辨率是多少？"}
     */
    @PostMapping("/ask")
    public AnswerResponse ask(@RequestBody QuestionRequest request) {
        String answer = knowledgeBaseService.ask(request.question());
        return new AnswerResponse(answer);
    }

    // 请求/响应 DTO（Java 16+ record）
    record QuestionRequest(String question) {}
    record AnswerResponse(String answer) {}
}

// ❌ 错误：两路各 20 条，合并后 40 条全塞给大模型
List<TextSegment> bm25Results = bm25.retrieve(query);
List<TextSegment> vectorResults = vector.retrieve(query);
List<TextSegment> combined = new ArrayList<>();
combined.addAll(bm25Results);
combined.addAll(vectorResults); // 可能包含大量重复文档，且未按质量排序

// ✅ 正确：hybridContentRetriever 内部完成两路召回 + RRF 融合 + 去重
List<Content> results = hybridContentRetriever.retrieve(Query.from(userQuery));
// results 已按 RRF 分数降序排列，无重复文档