RAG 重排序技术详解：Spring Boot 4 + LangChain4j 1.13.1 实战指南

// ScoringModel 核心方法
public interface ScoringModel {

    // 对单个文本段打分
    Response<Double> score(TextSegment segment, String query);

    // 批量打分（推荐使用，一次推理多条）
    Response<List<Double>> scoreAll(List<TextSegment> segments, String query);
}

// DashScopeScoringModel.java
package com.example.rag.model;

import com.fasterxml.jackson.databind.ObjectMapper;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.output.Response;
import dev.langchain4j.model.scoring.ScoringModel;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

public class DashScopeScoringModel implements ScoringModel {

    private final String apiKey;
    private final String modelName;
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    private static final String API_URL = "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank";

    public DashScopeScoringModel(String apiKey, String modelName) {
        this.apiKey = apiKey;
        this.modelName = modelName;
        this.httpClient = HttpClient.newHttpClient();
        this.objectMapper = new ObjectMapper();
    }

    @Override
    public Response<Double> score(TextSegment textSegment, String query) {
        return Response.from(scoreAll(List.of(textSegment), query).content().get(0));
    }

    @Override
    public Response<List<Double>> scoreAll(List<TextSegment> textSegments, String query) {
        try {
            List<String> docs = textSegments.stream().map(TextSegment::text).collect(Collectors.toList());

            Map<String, Object> input = new HashMap<>();
            input.put("query", query);
            input.put("documents", docs);

            Map<String, Object> requestBody = new HashMap<>();
            requestBody.put("model", this.modelName);
            requestBody.put("input", input);

            String jsonBody = objectMapper.writeValueAsString(requestBody);

            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(API_URL))
                    .header("Authorization", "Bearer " + apiKey)
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                    .build();

            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() != 200) {
                throw new RuntimeException("DashScope API call failed: " + response.body());
            }

            Map<String, Object> responseMap = objectMapper.readValue(response.body(), Map.class);
            Map<String, Object> output = (Map<String, Object>) responseMap.get("output");
            List<Map<String, Object>> results = (List<Map<String, Object>>) output.get("results");

            Double[] scores = new Double[docs.size()];
            for (Map<String, Object> res : results) {
                int index = (Integer) res.get("index");
                double score = (Double) res.get("relevance_score");
                scores[index] = score;
            }

            return Response.from(List.of(scores));
        } catch (Exception e) {
            throw new RuntimeException("Failed to score texts with DashScope API", e);
        }
    }
}

// RerankingConfig.java
package com.example.rag.config;

import com.example.rag.model.DashScopeScoringModel;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.embedding.onnx.bgesmallenv15q.BgeSmallEnV15QuantizedEmbeddingModel;
import dev.langchain4j.model.scoring.ScoringModel;
import dev.langchain4j.rag.DefaultRetrievalAugmentor;
import dev.langchain4j.rag.RetrievalAugmentor;
import dev.langchain4j.rag.content.aggregator.ContentAggregator;
import dev.langchain4j.rag.content.aggregator.ReRankingContentAggregator;
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 dev.langchain4j.data.segment.TextSegment;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * RAG 重排序核心配置类（纯 Java 风格，不依赖 langchain4j-spring 自动装配）
 *
 * <p>配置了完整的两阶段检索流水线：
 * <ol>
 *   <li>粗排：EmbeddingStoreContentRetriever 向量检索 Top-20</li>
 *   <li>精排：ReRankingContentAggregator 交叉编码器重排序，取 Top-3</li>
 * </ol>
 * </p>
 */
@Configuration
public class RerankingConfig {

    // 阿里云百炼 API Key，从 application.properties 注入
    @Value("${dashscope.api.key}")
    private String apiKey;

    /**
     * 云端重排序模型 Bean
     *
     * <p>使用自定义的 DashScopeScoringModel 对接百炼 gte-rerank 模型
     * </p>
     */
    @Bean
    public ScoringModel scoringModel() {
        return new DashScopeScoringModel(apiKey, "gte-rerank");
    }

    /**
     * 嵌入模型 Bean（用于向量化文档和查询）
     *
     * <p>bge-small-en-v1.5 量化版，24MB，内置于 JAR 中，纯本地推理，无需手动下载。</p>
     */
    @Bean
    public EmbeddingModel embeddingModel() {
        return new BgeSmallEnV15QuantizedEmbeddingModel();
    }

    /**
     * 内存向量库（生产环境替换为 Milvus / Qdrant / PgVector 等）
     */
    @Bean
    public EmbeddingStore<TextSegment> embeddingStore() {
        return new InMemoryEmbeddingStore<>();
    }

    /**
     * 向量检索器：粗排阶段，从库中捞出 Top-20 候选
     *
     * <p>maxResults(20) 故意设大，给重排序提供足够候选；minScore(0.4) 适当放宽，
     * 避免错过语义相关的文档。</p>
     */
    @Bean
    public ContentRetriever contentRetriever(
            EmbeddingStore<TextSegment> embeddingStore,
            EmbeddingModel embeddingModel) {
        return EmbeddingStoreContentRetriever.builder()
                .embeddingStore(embeddingStore)
                .embeddingModel(embeddingModel)
                .maxResults(20)          // 粗排多捞，给精排留余量
                .minScore(0.4)           // 粗排阈值适当放宽
                .build();
    }

    /**
     * 重排序内容聚合器：精排阶段，从 Top-20 中取最优 Top-3
     *
     * <p>
     * minScore(0.7)：过滤掉精排后分数仍低的结果，防止低质量上下文污染 LLM<br>
     * maxResults(3)：最终只保留 3 条最相关的内容送给 LLM
     * </p>
     */
    @Bean
    public ContentAggregator contentAggregator(ScoringModel scoringModel) {
        return ReRankingContentAggregator.builder()
                .scoringModel(scoringModel)
                .minScore(0.7)   // 精排分数阈值（0~1），低于此值的结果被丢弃
                .maxResults(3)   // 最终送给 LLM 的最大结果数
                .build();
    }

    /**
     * RAG 检索增强器：将粗排 + 精排串联为完整流水线
     */
    @Bean
    public RetrievalAugmentor retrievalAugmentor(
            ContentRetriever contentRetriever,
            ContentAggregator contentAggregator) {
        return DefaultRetrievalAugmentor.builder()
                .contentRetriever(contentRetriever)
                .contentAggregator(contentAggregator)
                .build();
    }
}

// StandaloneRerankingService.java
package com.example.rag.service;

import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.output.Response;
import dev.langchain4j.model.scoring.ScoringModel;
import org.springframework.stereotype.Service;

import java.util.Comparator;
import java.util.List;
import java.util.stream.IntStream;

/**
 * 独立重排序服务（不与完整 RAG 流水线耦合）
 *
 * <p>当只需要对自定义候选列表做重排序，而不需要完整 RAG 流水线时使用此服务。
 * 直接调用 {@link ScoringModel#scoreAll(List, String)} 进行批量打分。
 * </p>
 */
@Service
public class StandaloneRerankingService {

    private final ScoringModel scoringModel;

    public StandaloneRerankingService(ScoringModel scoringModel) {
        this.scoringModel = scoringModel;
    }

    /**
     * 对候选文本列表按照与 query 的相关性重排序，返回 topK 条
     *
     * @param query      用户查询
     * @param candidates 粗排阶段返回的候选文本列表
     * @param topK       精排后保留的最大数量
     * @return 按相关性降序排列的 topK 结果
     */
    public List<ScoredText> rerank(String query, List<String> candidates, int topK) {
        // 将字符串包装为 TextSegment（LangChain4j 的文本段类型）
        List<TextSegment> segments = candidates.stream()
                .map(TextSegment::from)
                .toList();

        // 批量打分：一次推理为所有候选文本评分（比逐条调用效率高得多）
        Response<List<Double>> response = scoringModel.scoreAll(segments, query);
        List<Double> scores = response.content();

        // 将文本与分数绑定，按分数降序排列，取 topK
        return IntStream.range(0, candidates.size())
                .mapToObj(i -> new ScoredText(candidates.get(i), scores.get(i)))
                .sorted(Comparator.comparingDouble(ScoredText::score).reversed())
                .limit(topK)
                .toList();
    }

    /**
     * 打分结果封装（文本 + 相关性分数）
     */
    public record ScoredText(String text, double score) {}
}

// RagServiceFactory.java
package com.example.rag.service;

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.rag.RetrievalAugmentor;
import dev.langchain4j.service.AiServices;
import org.springframework.stereotype.Component;

/**
 * RAG 服务工厂（不使用 langchain4j-spring 自动装配）
 *
 * <p>使用 LangChain4j 原生的 {@link AiServices} API 手动构建 RAG 服务，
 * 保持对流水线的完整控制，不依赖 {@code @AiService} 注解。
 * </p>
 */
@Component
public class RagServiceFactory {

    /**
     * 使用原始 AiServices API 手动构建 RAG 服务
     *
     * <p>这里不用 langchain4j-spring 的 @AiService 注解，保持对流水线的完整控制。</p>
     *
     * @param chatModel          对话语言模型（如 OpenAI GPT、Ollama 本地模型等）
     * @param retrievalAugmentor 带重排序的 RAG 检索增强器
     * @return 具备 RAG 能力的 Assistant 代理实例
     */
    public Assistant createAssistant(
            ChatModel chatModel,
            RetrievalAugmentor retrievalAugmentor) {

        return AiServices.builder(Assistant.class)
                .chatModel(chatModel)
                .retrievalAugmentor(retrievalAugmentor)  // 注入带重排序的增强器
                .build();
    }

    /**
     * AI 服务接口（由 AiServices 动态代理实现）
     *
     * <p>LangChain4j 会在运行时生成代理实现，自动处理 RAG 检索与 LLM 调用。</p>
     */
    public interface Assistant {
        String chat(String userMessage);
    }
}

// RerankingTest.java
package com.example.rag;

import com.example.rag.model.DashScopeScoringModel;
import dev.langchain4j.data.document.Document;
import dev.langchain4j.data.document.DocumentSplitter;
import dev.langchain4j.data.document.splitter.DocumentSplitters;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.embedding.onnx.bgesmallenv15q.BgeSmallEnV15QuantizedEmbeddingModel;
import dev.langchain4j.model.scoring.ScoringModel;
import dev.langchain4j.rag.content.Content;
import dev.langchain4j.rag.content.retriever.ContentRetriever;
import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever;
import dev.langchain4j.rag.query.Query;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.EmbeddingStoreIngestor;
import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import java.util.List;
import java.util.stream.IntStream;

import static org.assertj.core.api.Assertions.assertThat;
import static org.junit.jupiter.api.Assumptions.assumeTrue;

/**
 * 重排序功能集成测试
 *
 * <p><strong>运行前提：</strong></p>
 * <ol>
 *   <li>拥有阿里云百炼（DashScope）API Key</li>
 *   <li>设置环境变量 DASHSCOPE_API_KEY</li>
 * </ol>
 */
class RerankingTest {

    // ⚠️ 从环境变量获取你的 API Key
    private static final String API_KEY = System.getenv().getOrDefault("DASHSCOPE_API_KEY", "your-api-key");

    private static EmbeddingModel      embeddingModel;
    private static EmbeddingStore<TextSegment> embeddingStore;
    private static ContentRetriever    contentRetriever;

    @BeforeAll
    static void setUp() {
        // 初始化嵌入模型（本地 ONNX，内置于 JAR，无需下载）
        embeddingModel = new BgeSmallEnV15QuantizedEmbeddingModel();
        embeddingStore = new InMemoryEmbeddingStore<>();

        // 准备知识库：写入几条故意设计的"相似但相关性不同"的文本
        List<Document> docs = List.of(
            Document.from("Java 线程池的 shutdown() 方法会平滑地关闭线程池，等待已提交的任务全部完成后再终止。"),
            Document.from("Python 的 ThreadPoolExecutor 可以通过 shutdown(wait=True) 关闭线程池。"),
            Document.from("Java 线程池 shutdownNow() 方法会立即尝试停止所有活跃任务，并返回等待中的任务列表。"),
            Document.from("Java 线程池最佳实践：使用 try-finally 确保 shutdown() 总是被调用，避免资源泄漏。"),
            Document.from("线程池的核心参数：corePoolSize、maximumPoolSize、keepAliveTime 和 BlockingQueue。"),
            Document.from("Redis 缓存穿透可以通过布隆过滤器（Bloom Filter）在数据库查询前过滤掉不存在的 key。")
        );

        // 使用 EmbeddingStoreIngestor 批量向量化并存入内存库
        DocumentSplitter splitter = DocumentSplitters.recursive(200, 20);
        EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
                .documentSplitter(splitter)
                .embeddingModel(embeddingModel)
                .embeddingStore(embeddingStore)
                .build();
        docs.forEach(ingestor::ingest);

        // 粗排检索器：最多返回 10 条候选
        contentRetriever = EmbeddingStoreContentRetriever.builder()
                .embeddingStore(embeddingStore)
                .embeddingModel(embeddingModel)
                .maxResults(10)
                .build();
    }

    @Test
    @DisplayName("嵌入模型初始化验证：BgeSmallEnV15QuantizedEmbeddingModel 应可正常加载")
    void testEmbeddingModelInit() {
        // 验证嵌入模型（内置于 JAR，无需手动下载）可以正常工作
        assertThat(embeddingModel).isNotNull();

        // 执行一次实际嵌入，确认模型可推理
        var response = embeddingModel.embed("Java 线程池关闭方法");
        assertThat(response).isNotNull();
        assertThat(response.content()).isNotNull();
        assertThat(response.content().vector().length).isGreaterThan(0);

        System.out.println("✅ 嵌入模型初始化成功，向量维度：" + response.content().vector().length);
    }

    @Test
    @DisplayName("内存向量库入库验证：知识库文档应正确入库")
    void testEmbeddingStoreIngest() {
        // 验证向量库有内容
        assertThat(embeddingStore).isNotNull();

        // 执行检索验证入库
        List<Content> results = contentRetriever.retrieve(Query.from("Java 线程池"));
        assertThat(results).isNotEmpty();

        System.out.println("✅ 向量库入库成功，检索到 " + results.size() + " 条候选结果：");
        results.forEach(c -> System.out.println("  · " + c.textSegment().text()));
    }

    @Test
    @DisplayName("对比：有无重排序的检索结果差异（使用百炼 API）")
    void testRerankingVsNoReranking() {
        // 如果没有配置真正的 API KEY，为了避免测试失败影响打包，可以跳过
        assumeTrue(!API_KEY.equals("your-api-key"), "⏭️ 跳过：请设置 DASHSCOPE_API_KEY 环境变量");

        String query = "Java 如何安全地关闭线程池？";

        // ─── 场景 A：无重排序，直接取向量检索 Top-3 ───
        List<Content> rawResults = contentRetriever.retrieve(Query.from(query));

        System.out.println("=== 无重排序结果（向量相似度排序，取前 3）===");
        rawResults.stream().limit(3).forEach(c ->
                System.out.println("  · " + c.textSegment().text()));

        // ─── 场景 B：有重排序，用 ScoringModel 对向量检索结果精排 ───
        ScoringModel scoringModel = new DashScopeScoringModel(API_KEY, "gte-rerank");

        // 提取文本段列表
        List<TextSegment> candidates = rawResults.stream()
                .map(Content::textSegment)
                .toList();

        // 批量打分
        List<Double> scores = scoringModel.scoreAll(candidates, query).content();

        // 按分数降序排列，过滤 minScore < 0.1 的结果，取 Top-3
        List<String> rerankResults = IntStream.range(0, candidates.size())
                .boxed()
                .filter(i -> scores.get(i) >= 0.1)          // minScore 过滤
                .sorted((a, b) -> Double.compare(scores.get(b), scores.get(a)))
                .limit(3)
                .map(i -> String.format("[%.4f] %s", scores.get(i), candidates.get(i).text()))
                .toList();

        System.out.println("=== 有重排序结果（交叉编码器精排，minScore=0.1）===");
        rerankResults.forEach(r -> System.out.println("  · " + r));

        // 验证：重排序后结果数量不超过 3
        assertThat(rerankResults.size()).isLessThanOrEqualTo(3);

        // 验证：重排序后第一条结果的分数应高于 0.1
        if (!rerankResults.isEmpty()) {
            assertThat(rerankResults.get(0)).contains("Java");
        }
    }

    @Test
    @DisplayName("直接使用 ScoringModel 打分验证（使用百炼 API）")
    void testScoringModelDirectly() {
        assumeTrue(!API_KEY.equals("your-api-key"), "⏭️ 跳过：请设置 DASHSCOPE_API_KEY 环境变量");

        ScoringModel scoringModel = new DashScopeScoringModel(API_KEY, "gte-rerank");

        String query = "Java 如何安全地关闭线程池？";
        List<TextSegment> candidates = List.of(
            TextSegment.from("Java 线程池的 shutdown() 方法会平滑地关闭线程池。"),     // 高度相关
            TextSegment.from("Python 的 ThreadPoolExecutor 可以通过 shutdown() 关闭。"), // 语言不符
            TextSegment.from("Redis 缓存穿透的解决方案是使用布隆过滤器。")                // 完全不相关
        );

        // 批量打分
        List<Double> scores = scoringModel.scoreAll(candidates, query).content();

        System.out.println("=== 相关性打分结果 ===");
        for (int i = 0; i < candidates.size(); i++) {
            System.out.printf("  分数: %.4f | %s%n",
                    scores.get(i), candidates.get(i).text());
        }

        // 验证：Java 线程池关闭的文本分数应明显高于 Python 和 Redis
        double javaScore   = scores.get(0);
        double pythonScore = scores.get(1);
        double redisScore  = scores.get(2);

        assertThat(javaScore).isGreaterThan(pythonScore);
        assertThat(javaScore).isGreaterThan(redisScore);
    }
}

// MockScoringModelTest.java
package com.example.rag;

import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.output.Response;
import dev.langchain4j.model.scoring.ScoringModel;
import dev.langchain4j.rag.content.aggregator.ContentAggregator;
import dev.langchain4j.rag.content.aggregator.ReRankingContentAggregator;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import java.util.List;
import java.util.Map;

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

/**
 * 使用 Mock ScoringModel 验证重排序逻辑（无需真实模型文件）
 *
 * <p>此测试类不加载 Spring 容器，也不依赖任何 ONNX 模型文件，可以直接运行。
 * 主要验证：
 * <ol>
 *   <li>ReRankingContentAggregator 能否正确构建</li>
 *   <li>Mock ScoringModel 打分逻辑是否正确</li>
 *   <li>minScore 过滤行为是否符合预期</li>
 * </ol>
 * </p>
 *
 * <p>运行命令：{@code mvn test -Dtest=MockScoringModelTest}</p>
 */
class MockScoringModelTest {

    @Test
    @DisplayName("使用 Mock ScoringModel 验证重排序聚合逻辑")
    void testWithMockScoringModel() {
        // Mock ScoringModel：根据文本内容返回预设分数（不调用真实模型）
        Map<String, Double> mockScores = Map.of(
            "Java shutdown() 关闭线程池", 0.95,
            "Python 关闭线程池",          0.40,
            "Redis 缓存穿透解决方案",      0.10
        );

        ScoringModel mockScoringModel = new ScoringModel() {
            @Override
            public Response<Double> score(TextSegment segment, String query) {
                double score = mockScores.getOrDefault(segment.text(), 0.5);
                return Response.from(score);
            }

            @Override
            public Response<List<Double>> scoreAll(List<TextSegment> segments, String query) {
                List<Double> scores = segments.stream()
                        .map(s -> mockScores.getOrDefault(s.text(), 0.5))
                        .toList();
                return Response.from(scores);
            }
        };

        // 构建 ReRankingContentAggregator，minScore=0.6 会过滤掉 Python 和 Redis 相关内容
        ContentAggregator aggregator = ReRankingContentAggregator.builder()
                .scoringModel(mockScoringModel)
                .minScore(0.6)
                .maxResults(2)
                .build();

        // 验证 aggregator 已正确创建（实际内容聚合需要配合 RetrievalAugmentor 使用）
        assertThat(aggregator).isNotNull();

        // 直接测试打分逻辑
        List<TextSegment> candidates = List.of(
            TextSegment.from("Java shutdown() 关闭线程池"),
            TextSegment.from("Python 关闭线程池"),
            TextSegment.from("Redis 缓存穿透解决方案")
        );

        List<Double> scores = mockScoringModel.scoreAll(candidates, "Java 关闭线程池").content();

        System.out.println("=== Mock ScoringModel 打分结果 ===");
        for (int i = 0; i < candidates.size(); i++) {
            System.out.printf("  分数: %.2f | %s%n", scores.get(i), candidates.get(i).text());
        }

        // 验证分数排序符合预期
        assertThat(scores.get(0)).isGreaterThan(scores.get(1)); // Java > Python
        assertThat(scores.get(0)).isGreaterThan(scores.get(2)); // Java > Redis
        assertThat(scores.get(0)).isGreaterThanOrEqualTo(0.6);  // Java 通过阈值
        assertThat(scores.get(1)).isLessThan(0.6);              // Python 被过滤
        assertThat(scores.get(2)).isLessThan(0.6);              // Redis 被过滤
    }

    @Test
    @DisplayName("验证 ScoringModel 接口：批量打分 scoreAll() 返回类型正确")
    void testScoringModelReturnType() {
        // 验证文档中对 ScoringModel 接口返回类型的描述是否正确
        // 文档声称：scoreAll() 返回 Response<List<Double>>
        ScoringModel model = new ScoringModel() {
            @Override
            public Response<Double> score(TextSegment segment, String query) {
                return Response.from(0.8);
            }

            @Override
            public Response<List<Double>> scoreAll(List<TextSegment> segments, String query) {
                return Response.from(segments.stream().mapToDouble(s -> 0.5).boxed().toList());
            }
        };

        List<TextSegment> segments = List.of(
            TextSegment.from("文本 A"),
            TextSegment.from("文本 B")
        );

        // 验证 scoreAll 返回类型
        Response<List<Double>> response = model.scoreAll(segments, "查询");
        assertThat(response).isNotNull();
        assertThat(response.content()).hasSize(2);
        assertThat(response.content().get(0)).isEqualTo(0.5);

        // 验证 score 返回类型
        Response<Double> singleResponse = model.score(segments.get(0), "查询");
        assertThat(singleResponse).isNotNull();
        assertThat(singleResponse.content()).isEqualTo(0.8);

        System.out.println("✅ ScoringModel 接口验证通过：scoreAll() 返回 Response<List<Double>>，score() 返回 Response<Double>");
    }

    @Test
    @DisplayName("验证 ReRankingContentAggregator 构建器 API（minScore + maxResults）")
    void testReRankingContentAggregatorBuilderApi() {
        // 验证文档中的构建器 API 是否正确
        // 文档声称：builder() 支持 scoringModel()、minScore()、maxResults()

        ScoringModel dummyModel = new ScoringModel() {
            @Override
            public Response<Double> score(TextSegment segment, String query) {
                return Response.from(0.9);
            }

            @Override
            public Response<List<Double>> scoreAll(List<TextSegment> segments, String query) {
                return Response.from(segments.stream().map(s -> 0.9).toList());
            }
        };

        // 正确配置（文档 7.1 节的 ✅ 做法）
        ContentAggregator aggregator = ReRankingContentAggregator.builder()
                .scoringModel(dummyModel)
                .maxResults(3)    // 精排严格，只取最优 3 条送 LLM
                .minScore(0.7)    // 精排阈值严格，过滤低质量上下文
                .build();

        assertThat(aggregator).isNotNull();
        System.out.println("✅ ReRankingContentAggregator.builder() API 验证通过");
    }
}

// ❌ 错误做法：粗排和精排的 maxResults 设置相同
ContentRetriever retriever = EmbeddingStoreContentRetriever.builder()
        .maxResults(3)    // 粗排只捞 3 条
        .build();
ContentAggregator aggregator = ReRankingContentAggregator.builder()
        .maxResults(3)    // 精排也要 3 条，等于没有过滤
        .build();

// ✅ 正确做法：粗排多捞，精排严格过滤
ContentRetriever retriever = EmbeddingStoreContentRetriever.builder()
        .maxResults(20)   // 粗排宽松召回，给精排足够候选
        .minScore(0.4)    // 粗排阈值适当放宽，避免错过相关结果
        .build();
ContentAggregator aggregator = ReRankingContentAggregator.builder()
        .scoringModel(scoringModel)
        .maxResults(3)    // 精排严格，只取最优 3 条送 LLM
        .minScore(0.7)    // 精排阈值严格，过滤低质量上下文
        .build();

// 从阿里云百炼切换到 Cohere 云端 API，只需换这一个 Bean
// （需要添加 langchain4j-cohere 依赖）
@Bean
public ScoringModel scoringModel() {
    return CohereScoringModel.builder()
            .apiKey(System.getenv("COHERE_API_KEY"))
            .modelName("rerank-multilingual-v3.0")
            .build();
}