LangChain4j 集成 Cohere 重排序模型：CohereScoringModel 实现 RAG 精排实战指南

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/langchain4jCohere 的 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 groupIddev.langchain4j/groupId artifactIdlangchain4j-cohere/artifactId version1.20.0-beta30/version /dependency从仓库中 langchain4j-cohere/pom.xml 可以看到该模块的依赖结构它声明依赖langchain4j-core提供ScoringModel等核心抽象与langchain4j-http-clientLangChain4j 统一 HTTP 客户端抽象并将langchain4j-http-client-jdk以runtime作用域引入即默认使用 JDK 内置HttpClient发送请求无需额外配置传输层实现。若你的项目已引入其他langchain4j-http-client-*实现如 Apache、OkHttp可以通过自定义HttpClientBuilder替换默认实现。认识 CohereScoringModel官方文档列出了该模块提供的评分模型CohereScoringModel它是 CohereScoringModel.java 中对ScoringModel的完整实现底层调用 Cohere Rerank APIPOST https://api.cohere.ai/v1/rerank。模块内其余类均为内部支撑CohereClientHTTP 客户端封装、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()返回 CohereScoringModelBuilderbuild()时对apiKey做了ensureNotBlank非空校验不传apiKey会直接抛出校验异常。2. 单条文本评分ScoringModel提供score(String text, String query)与score(TextSegment segment, String query)两个便捷方法返回ResponseDoubleResponseDouble response model.score(labrador retriever, tell me about dogs); Double score response.content(); // 相关性分数0~1 之间的小数3. 多条文本批量评分scoreAll(ListTextSegment segments, String query)是重排序场景的核心入口返回与输入片段顺序一一对应的分数列表import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.output.Response; import java.util.List; ListTextSegment segments List.of( TextSegment.from(maine coon), // 猫与狗相关度低 TextSegment.from(labrador retriever) // 狗与狗相关度高 ); ResponseListDouble response model.scoreAll(segments, tell me about dogs); ListDouble 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 源码完整参数如下参数类型默认值说明apiKeyString必填非空校验Cohere API Key建议通过环境变量或配置中心注入modelNameString无默认值Cohere 重排序模型名如rerank-english-v3.0、rerank-multilingual-v3.0baseUrlStringhttps://api.cohere.ai/v1/API 基础地址私有化部署或代理网关时可覆盖timeoutDuration60 秒连接与读取超时同时作用于HttpClient的connectTimeout与readTimeoutmaxRetriesInteger2失败请求的重试次数见下文重试语义httpClientBuilderHttpClientBuilder服务发现加载自定义 HTTP 客户端构建器可精细控制代理、TLS、连接池等proxyjava.net.Proxy无已废弃传入非 null 值会在构建时抛UnsupportedOperationException请改用httpClientBuilderlogRequestsBooleanfalse是否打印请求日志logResponsesBooleanfalse是否打印响应日志loggerorg.slf4j.Logger默认 Logger自定义请求/响应日志所用的 Logger 实例全部参数就位的完整示例与集成测试中的用法一致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的每次评分都走如下调用链组装请求scoreAll将modelName、query、各片段文本组装为 RerankRequest内部类RerankRequestBuilder负责构建结构为modelquerydocuments发送 HTTP 请求CohereClient.rerank() 构造POST {baseUrl}rerank请求携带Content-Type: application/json、Accept: application/json与Authorization: Bearer apiKey头请求体为RerankRequest的 JSON 序列化结果解析响应响应体反序列化为 RerankResponse其中results为 Result 列表含index与relevanceScoremeta为 Meta内含 BilledUnits 计费信息输出规整按index升序排序提取relevanceScore与输入片段顺序对齐同时把BilledUnits.searchUnits搜索单元计费数映射为Response的TokenUsage因此集成测试中单次评分totalTokenCount()恒为 1。重试语义同步调用通过withRetryMappingExceptions进行maxRetries默认 2次失败重试异步调用对应withRetryMappingExceptionsAsync重试基于 future 组合实现不会阻塞线程且取消操作不会被重试。异步评分与响应式 RAG自 1.20.0 起ScoringModel 新增了实验性Experimental的异步接口服务于非阻塞 RAG 流程接口 Javadoc 中明确提及ReRankingContentAggregatorscoreAsync(ScoringRequest)应用模型默认参数后分发到doScoreAsyncdoScoreAsync(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可放入响应式/异步链路 ListDouble 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 ListContent retrieve(Query query) { ListContent 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 retrievervstell me about dogs得分约0.008允许 1% 误差多片段评分中不相关内容得分低于相关内容评分响应的tokenUsage().totalTokenCount()为 1对应 1 个搜索单元计费。运行命令COHERE_API_KEYyour_key ./mvnw -pl langchain4j-cohere test -DtestCohereScoringModelIT小结CohereScoringModel让 Java 开发者以寥寥几行代码接入 Cohere 的重排序能力统一实现ScoringModel接口、与 RAG 检索链路天然兼容、同步/异步双通道支持、重试与超时开箱即用。实际使用时只需牢记三点优先builder()构建并显式设置modelName代理配置走httpClientBuilder而非废弃的proxy(...)异步评分要求模型覆写doScoreAsyncCohere 实现已内置。对于追求检索精度的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考