企业官网建设流程全解析

LangChain4j 集成 Cohere 重排序模型：CohereScoringModel 实现 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

Cohere 的 Rerank API 是业界成熟的语义相关性重排序服务，LangChain4j 通过langchain4j-cohere模块将其封装为标准的ScoringModel，与检索增强生成（RAG）流水线无缝衔接。本文以仓库中的 官方集成文档 为主体骨架，结合 langchain4j-cohere 模块源码 与 集成测试用例，完整讲解 Maven 依赖配置、模型构建、同步/异步评分调用、Builder 全参数说明与底层 Rerank 调用链，帮助你在 Java 应用中直接落地"召回 → 重排 → 精排"的 RAG 检索流程。

为什么需要 Cohere 重排序评分模型

在典型的 RAG 场景中，向量检索（如 EmbeddingStore 相似度搜索）先"宽召回"出大量候选片段，但向量相似度并不总能精确反映语义相关性，粗排结果中可能混入低质量片段。此时需要重排序（Re-ranking）：用一个专门的交叉编码（cross-encoder）模型，把用户查询与每个候选片段逐对打分，再按相关性分数重新排序，从而显著提升送入 LLM 的上下文质量。

LangChain4j 在 langchain4j-core 中抽象出 ScoringModel 接口，其 Javadoc 明确指出：该接口"用于针对同一查询对多个文本进行相关性评分，可服务于重排序用途"。CohereScoringModel正是该接口的官方 Cohere 实现，对应的官方文档即 cohere.md。

添加 Maven 依赖

按照官方文档，在项目中引入langchain4j-cohere依赖：

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

从仓库中 langchain4j-cohere/pom.xml 可以看到该模块的依赖结构：它声明依赖langchain4j-core（提供ScoringModel等核心抽象）与langchain4j-http-client（LangChain4j 统一 HTTP 客户端抽象），并将langchain4j-http-client-jdk以runtime作用域引入，即默认使用 JDK 内置HttpClient发送请求，无需额外配置传输层实现。若你的项目已引入其他langchain4j-http-client-*实现（如 Apache、OkHttp），可以通过自定义HttpClientBuilder替换默认实现。

认识 CohereScoringModel

官方文档列出了该模块提供的评分模型：

• CohereScoringModel

它是 CohereScoringModel.java 中对ScoringModel的完整实现，底层调用 Cohere Rerank API（POST https://api.cohere.ai/v1/rerank）。模块内其余类均为内部支撑：CohereClient（HTTP 客户端封装）、RerankRequest/RerankResponse（请求/响应 DTO）、Result（单条评分结果）、BilledUnits（计费单元统计）等。

快速上手：构建模型并完成评分

1. 构建评分模型

推荐使用builder()方式构建：

import dev.langchain4j.model.cohere.CohereScoringModel; import dev.langchain4j.model.scoring.ScoringModel; ScoringModel model = CohereScoringModel.builder() .apiKey(System.getenv("COHERE_API_KEY")) // 从环境变量读取，切勿硬编码 .modelName("rerank-english-v3.0") .build();

从源码可见，builder()返回 CohereScoringModelBuilder，build()时对apiKey做了ensureNotBlank非空校验；不传apiKey会直接抛出校验异常。

2. 单条文本评分

ScoringModel提供score(String text, String query)与score(TextSegment segment, String query)两个便捷方法，返回Response<Double>：

Response<Double> response = model.score("labrador retriever", "tell me about dogs"); Double score = response.content(); // 相关性分数（0~1 之间的小数）

3. 多条文本批量评分

scoreAll(List<TextSegment> segments, String query)是重排序场景的核心入口，返回与输入片段顺序一一对应的分数列表：

import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.output.Response; import java.util.List; List<TextSegment> segments = List.of( TextSegment.from("maine coon"), // 猫，与"狗"相关度低 TextSegment.from("labrador retriever") // 狗，与"狗"相关度高 ); Response<List<Double>> response = model.scoreAll(segments, "tell me about dogs"); List<Double> scores = response.content(); // 输出顺序与输入顺序一致：第一个分数应明显低于第二个

这一行为有源码与测试双重印证：

• CohereScoringModel.scoreAll() 将每个TextSegment的文本收集为RerankRequest.documents，调用 Cohere Rerank API 后，按Result::getIndex对结果排序，保证输出分数顺序与输入片段顺序严格一致；
• CohereScoringModelIT 中的should_score_multiple_segments_with_all_parameters用例验证了"猫"片段分数低于"狗"片段，且响应中tokenUsage().totalTokenCount()为 1（对应 Cohere 计费单元searchUnits）。

拿到分数列表后，即可对候选片段按分数降序重排，截取 Top-K 作为最终送入 LLM 的上下文。

Builder 配置参数详解

结合 CohereScoringModel.CohereScoringModelBuilder 源码，完整参数如下：

全部参数就位的完整示例（与集成测试中的用法一致）：

ScoringModel model = CohereScoringModel.builder() .baseUrl("https://api.cohere.ai/v1/") .apiKey(System.getenv("COHERE_API_KEY")) .modelName("rerank-english-v3.0") .timeout(Duration.ofSeconds(30)) .maxRetries(2) .logRequests(true) .logResponses(true) .build();

注意：源码中标有@Deprecated(forRemoval = true, since = "1.4.0")的全参构造器以及withApiKey(String)静态工厂方法均已废弃，官方推荐一律使用builder()。

底层原理：Rerank 请求调用链

CohereScoringModel的每次评分都走如下调用链：

1. 组装请求：scoreAll将modelName、query、各片段文本组装为 RerankRequest（内部类RerankRequestBuilder负责构建），结构为model+query+documents；
2. 发送 HTTP 请求：CohereClient.rerank() 构造POST {baseUrl}rerank请求，携带Content-Type: application/json、Accept: application/json与Authorization: Bearer <apiKey>头，请求体为RerankRequest的 JSON 序列化结果；
3. 解析响应：响应体反序列化为 RerankResponse，其中results为 Result 列表（含index与relevanceScore），meta为 Meta（内含 BilledUnits 计费信息）；
4. 输出规整：按index升序排序提取relevanceScore，与输入片段顺序对齐；同时把BilledUnits.searchUnits（搜索单元计费数）映射为Response的TokenUsage，因此集成测试中单次评分totalTokenCount()恒为 1。

重试语义：同步调用通过withRetryMappingExceptions进行maxRetries（默认 2）次失败重试；异步调用对应withRetryMappingExceptionsAsync，重试基于 future 组合实现，不会阻塞线程，且取消操作不会被重试。

异步评分与响应式 RAG

自 1.20.0 起，ScoringModel 新增了实验性（@Experimental）的异步接口，服务于非阻塞 RAG 流程（接口 Javadoc 中明确提及ReRankingContentAggregator）：

• scoreAsync(ScoringRequest)：应用模型默认参数后分发到doScoreAsync；
• doScoreAsync(ScoringRequest)：真正非阻塞的钩子方法。接口默认实现返回携带AsyncNotSupportedException的失败 future——未真正支持异步的模型会在异步路径上快速失败，而不是静默阻塞线程；
• defaultRequestParameters()：每次请求默认应用、可被请求级参数覆盖。

CohereScoringModel覆写了doScoreAsync，其实现 通过CohereClient.rerankAsync()发出非阻塞 HTTP 调用（飞行期间不占线程），并借助propagateCancellation实现"取消 future 即中止在途请求"的尽力而为语义。参考集成测试scoreAsync_should_score_multiple_segments的用法：

ScoringResponse response = model.scoreAsync(ScoringRequest.builder() .documents(segments.stream().map(TextSegment::text).toList()) .query("tell me about dogs") .build()) .get(30, SECONDS); // CompletableFuture，可放入响应式/异步链路 List<Double> scores = response.scores(); // 与 documents 顺序一致

将 CohereScoringModel 接入 RAG 流水线

在 LangChain4j 的 RAG 体系（参见 RAG 教程）中，重排序通常作用于检索器与聚合器之间：先用 EmbeddingStore 宽召回候选片段，再交给CohereScoringModel精排，最终聚合 Top-K 上下文。一种典型的接入方式是自定义ContentRetriever或ContentAggregator，把ScoringModel作为重排器注入：

// 伪代码示意：自定义重排检索器 public class RerankRetriever implements ContentRetriever { private final ContentRetriever baseRetriever; // 底层向量检索器 private final ScoringModel reranker; // CohereScoringModel @Override public List<Content> retrieve(Query query) { List<Content> candidates = baseRetriever.retrieve(query); // 宽召回 // 提取文本片段 -> reranker.scoreAll(...) -> 按分数降序截断 Top-K return rerankedTopK(candidates, query.text(), 5); } }

这种"召回 + 重排"的级联设计既控制了向量检索的召回成本，又借助交叉编码器的高精度评分提升了送入 LLM 的上下文质量。仓库文档 docs/docs/integrations/scoring-reranking-models/cohere.md 中给出的官方示例即 "Advanced RAG with re-ranking using Cohere"，你可以参考 高级 RAG 相关文档 与 advanced-rag.png 了解整体流程设计。

代理配置的注意事项

如果你需要走代理访问 Cohere API，请特别注意：proxy(...)参数已在 LangChain4j 迁移到统一HttpClient抽象后废弃，CohereClient 的 proxy 实现 会在传入非 null 代理时直接抛出UnsupportedOperationException。正确做法是通过httpClientBuilder(...)注入自定义 HTTP 客户端构建器（如配置了代理的 JDK/Apache/OkHttp 客户端构建器），再交给CohereScoringModel.builder()。

本地验证与集成测试

仓库自带的 CohereScoringModelIT 使用 JUnit 5 条件注解@EnabledIfEnvironmentVariable(named = "COHERE_API_KEY", matches = ".+")控制执行：只有设置了COHERE_API_KEY环境变量才会运行，覆盖了单文本评分、多片段评分、异步评分三条路径，并断言：

• 单条评分结果接近预期值（如"labrador retriever"vs"tell me about dogs"得分约0.008，允许 1% 误差）；
• 多片段评分中不相关内容得分低于相关内容；
• 评分响应的tokenUsage().totalTokenCount()为 1（对应 1 个搜索单元计费）。

运行命令：

COHERE_API_KEY=your_key ./mvnw -pl langchain4j-cohere test -Dtest=CohereScoringModelIT

小结

CohereScoringModel让 Java 开发者以寥寥几行代码接入 Cohere 的重排序能力：统一实现ScoringModel接口、与 RAG 检索链路天然兼容、同步/异步双通道支持、重试与超时开箱即用。实际使用时只需牢记三点：优先builder()构建并显式设置modelName；代理配置走httpClientBuilder而非废弃的proxy(...)；异步评分要求模型覆写doScoreAsync（Cohere 实现已内置）。对于追求检索精度的 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