企业官网建设流程全解析

LangChain4j 集成 Jina Reranker：在 Java RAG 管线中实现语义重排

【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j

本文以 LangChain4j 的langchain4j-jina集成模块为核心，介绍如何将 Jina Reranker 评分模型接入 Java RAG 应用：从 Maven 依赖引入、JinaScoringModel构建与参数配置，到通过ReRankingContentAggregator把重排器嵌入DefaultRetrievalAugmentor的完整检索增强管线。读完本文，你将掌握在 Spring Boot / Quarkus 等 Java 生态中落地"召回-重排"两阶段 RAG 的实战方案，并理解其底层的 API 调用与源码实现原理。

什么是重排器（Reranker）

在 RAG（检索增强生成）架构中，初检阶段通常由 embedding（向量）检索或基于 token 的关键词检索完成，负责从海量文档中快速召回一个"可能相关"的候选集。由于初检只做表层匹配，召回结果中往往混入大量与用户真实意图偏差较大的片段。

重排器（Reranker）正是一类针对这一缺陷设计的精排模型：它接收初检得到的候选结果集，将用户查询（query）与每篇文档的内容进行深度交互建模，而非停留在词汇层面的匹配，从而重新评估每条候选与用户意图的契合度，输出一个相关性得分，最终按得分对结果重新排序。

在 LangChain4j 中，重排能力通过ScoringModel（评分模型）抽象暴露，而 Jina Reranker 就是其中一个开箱即用的实现，对应模块为langchain4j-jina，核心类为JinaScoringModel（源码位于 JinaScoringModel.java）。

添加 Maven 依赖

在项目的pom.xml中引入：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-jina</artifactId> <version>1.20.0-beta30</version> </dependency>

其中langchain4j-jina模块内部依赖langchain4j-core（其pom.xml中对langchain4j-core的版本引用见 pom.xml），因此无需额外引入核心包即可使用ScoringModel、RAG 等基础 API。当前仓库主干的版本号已演进为1.21.0-beta31-SNAPSHOT，正式发布后请以 Maven Central 上的最新 Release 版本为准。

快速开始：构建 JinaScoringModel

JinaScoringModel实现了dev.langchain4j.model.scoring.ScoringModel接口，通过 Builder 模式创建。最简用法如下：

ScoringModel scoringModel = JinaScoringModel.builder() .apiKey(System.getenv("JINA_API_KEY")) .modelName("jina-reranker-v2-base-multilingual") .build();

• apiKey：必填项，Jina AI 平台颁发的 API Key，推荐通过环境变量注入，避免硬编码泄露。
• modelName：必填项，指定使用的 Jina Reranker 模型名称，常用模型如jina-reranker-v2-base-multilingual（多语言基础版）与jina-reranker-v3（更新版本）。

JinaScoringModel的score(String text, String query)与scoreAll(List<TextSegment> segments, String query)两个核心方法由ScoringModel接口定义：score单文本评分是scoreAll在单元素列表上的默认实现（见 ScoringModel.java），返回的Response<Double>中封装了评分值、Token 用量与结束原因。单文本评分的典型场景是快速验证一个查询与某段文本的相关性。

Builder 配置参数详解

JinaScoringModel.JinaScoringModelBuilder提供的完整可配置参数如下表（均来自 JinaScoringModel.java 源码）：

需要注意：toString()方法会对apiKey做脱敏处理，输出为apiKey=********而非明文，这一行为有专门测试用例验证（见 JinaScoringModelBuilderTest.java），因此将模型对象打印到日志时不会泄露密钥。

底层原理：scoreAll 是如何调用 Jina API 的

从源码看，JinaScoringModel.scoreAll的执行链路分为三步：

1. 组装请求体。将查询与待评分的TextSegment列表转换为JinaRerankingRequest，其字段为model、query、documents（各文档文本）、returnDocuments（见 JinaRerankingRequest.java）：

JinaRerankingRequest request = JinaRerankingRequest.builder() .model(modelName) .query(query) .documents(segments.stream().map(TextSegment::text).collect(toList())) .returnDocuments(false) // 减小响应体积，响应中不携带文档文本 .build();

2. 发起 HTTP 调用。通过JinaClient.rerank(request)向POST /v1/rerank端点发送请求（见 JinaClient.java），并借助withRetryMappingExceptions在失败时按maxRetries自动重试。

3. 解析响应并排序。响应JinaRerankingResponse包含model、results、usage三部分；每个JinaRerankingResult携带index（原始文档下标）与relevanceScore（相关性得分，见 JinaRerankingResult.java）。源码将结果按index升序排序后再提取得分，从而保证返回的分数列表顺序与传入的segments顺序一一对应：

List<Double> scores = response.results.stream() .sorted(comparingInt(result -> result.index)) .map(result -> result.relevanceScore) .collect(toList());

同时，JinaUsage中的promptTokens与totalTokens会被封装进TokenUsage（见 JinaUsage.java），调用方可通过response.tokenUsage()获取本次重排消耗的 Token 数，用于成本统计与监控。

将 Jina Reranker 接入 RAG 管线

单独的评分模型价值有限，langchain4j-jina文档给出的标准用法是将其接入 RAG 的**内容聚合（ContentAggregation）**阶段，与 LangChain4j 的RetrievalAugmentor配合使用：

// 1. 构建评分模型（Jina Reranker） ScoringModel scoringModel = JinaScoringModel.builder() .apiKey(System.getenv("JINA_API_KEY")) .modelName("jina-reranker-v2-base-multilingual") .build(); // 2. 创建基于重排的内容聚合器 ContentAggregator contentAggregator = ReRankingContentAggregator.builder() .scoringModel(scoringModel) // 可选：.minScore(0.3) 低于该阈值的片段将被过滤 // 可选：.maxResults(5) 最多保留的重排结果数 // 可选：.querySelector(...) 多查询场景下选择用于重排的查询 .build(); // 3. 将聚合器挂到检索增强器上 RetrievalAugmentor retrievalAugmentor = DefaultRetrievalAugmentor.builder() // ... .contentRetriever(...) .contentAggregator(contentAggregator) .build(); // 4. 构建带 RAG 能力的 AI 服务 return AiServices.builder(Assistant.class) .chatModel(...) .retrievalAugmentor(retrievalAugmentor) .build();

ReRankingContentAggregator 的内部流程

ReRankingContentAggregator是 LangChain4j 官方提供的ContentAggregator实现（源码位于 ReRankingContentAggregator.java），其aggregate方法按如下流水线工作：

1. 查询选择：若输入只有单个Query，直接使用；若存在多个查询（例如使用了ExpandingQueryTransformer展开查询），必须显式提供querySelector指定用哪个查询对所有内容重排，否则默认选择器会抛出异常提示重排存在歧义。
2. 内容融合：对同一查询从不同检索源召回的片段，先按ReciprocalRankFuser（倒数排名融合）合并去重。
3. 重排与过滤：将融合后的全部片段一次性交给ScoringModel评分，然后按得分降序排序，过滤掉低于minScore阈值的片段，并截断到maxResults条。
4. 元数据写入：每个保留的片段会附带RERANKED_SCORE元数据，下游 Prompt 组装或日志输出时可读取该得分。

此外，该类还提供aggregateAsync异步版本：融合过程在 CPU 上同步完成，仅将真正的评分 I/O 调用scoreAsync异步化，并将取消信号回传到进行中的网络请求，适配非阻塞 RAG 场景（详见 docs/docs/tutorials/non-blocking.md）。

完整的 Runnable 示例

将上述片段组合为一个可直接运行的 RAG 服务：

import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.jina.JinaScoringModel; import dev.langchain4j.model.scoring.ScoringModel; 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.service.AiServices; import java.time.Duration; public class JinaRerankRagExample { interface Assistant { String chat(String userMessage); } public static void main(String[] args) { // 1. Jina Reranker 评分模型 ScoringModel scoringModel = JinaScoringModel.builder() .apiKey(System.getenv("JINA_API_KEY")) .modelName("jina-reranker-v2-base-multilingual") .timeout(Duration.ofSeconds(30)) .maxRetries(2) .build(); // 2. 初检检索器（embedding 向量检索，返回候选片段） ContentRetriever contentRetriever = EmbeddingStoreContentRetriever.builder() .embeddingStore(...) .embeddingModel(...) .maxResults(20) // 召回更多候选，交给重排器精排 .build(); // 3. 重排聚合器：只保留得分 >= 0.3 且排序最靠前的 5 条 ContentAggregator contentAggregator = ReRankingContentAggregator.builder() .scoringModel(scoringModel) .minScore(0.3) .maxResults(5) .build(); // 4. 检索增强器 RetrievalAugmentor retrievalAugmentor = DefaultRetrievalAugmentor.builder() .contentRetriever(contentRetriever) .contentAggregator(contentAggregator) .build(); // 5. 组装 AI 服务 Assistant assistant = AiServices.builder(Assistant.class) .chatModel(...) .retrievalAugmentor(retrievalAugmentor) .build(); System.out.println(assistant.chat("tell me about dogs")); } }

实战中的经典调优手法是：初检阶段（EmbeddingStoreContentRetriever）适当提高maxResults召回更多候选，再让重排器精排筛选，从而在召回率与精读成本之间取得平衡。

测试用例验证

仓库中的集成测试 JinaScoringModelIT.java 直观展示了两个验证场景：

• 单文本评分：对文本"labrador retriever"与查询"tell me about dogs"调用score，断言得分约为0.1（允许 10% 误差），且totalTokenCount为 14——说明该查询确实命中了"狗"的语义相关主题，验证了重排器具备语义理解而非简单关键词匹配的能力。
• 多片段评分：对["sunny cloudy rainy", "sunny cloudy rainy", "cat dog bird"]三个片段以查询"animal"调用scoreAll，断言动物相关片段（下标 2）得分显著高于天气片段（下标 0、1），且 Token 用量为正。这一用例同时使用了timeout(10s)与logResponses(true)配置。

两个测试都用@EnabledIfEnvironmentVariable(named = "JINA_API_KEY", matches = ".+")注解，仅在设置了JINA_API_KEY环境变量时才会执行，因此不会污染 CI 的常规构建。

总结与注意事项

通过langchain4j-jina模块，LangChain4j 将 Jina Reranker 无缝封装为标准的ScoringModel，一行 Builder 即可创建，再配合ReRankingContentAggregator与DefaultRetrievalAugmentor，即可为 Java RAG 应用补上"召回-重排"中至关重要的精排环节，显著提升送入 LLM 的上下文质量。

使用时的关键注意点：

• apiKey与modelName为必填项，务必通过环境变量等方式安全管理密钥；
• 默认baseUrl指向 Jina 官方 API（https://api.jina.ai/v1/），自建网关或代理时可通过baseUrl覆盖；
• 多查询场景下使用ReRankingContentAggregator必须配置querySelector，否则会抛异常；
• 模型名需与 Jina 平台当前提供的 Reranker 版本保持一致，如jina-reranker-v2-base-multilingual、jina-reranker-v3；
• 评分结果顺序与传入片段顺序一一对应，得分可通过RERANKED_SCORE元数据在下游读取。

更完整的 RAG 概念与调优指南可参考 docs/docs/tutorials/rag.md 及同目录下的其他评分模型集成文档（如 cohere.md、voyage-ai.md）。

【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j