LangChain4j 接入 Voyage AI 重排序模型VoyageAiScoringModel 完整实战指南【免费下载链接】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在 RAG检索增强生成链路中向量检索召回的相关文档往往混有噪声直接送入大模型会拉低生成质量。LangChain4j 提供了统一的ScoringModel抽象并将 Voyage AI 的 Rerank API 封装为开箱即用的VoyageAiScoringModel用于对召回片段进行重排序打分。读完本文你将掌握该模块的依赖引入、构建参数配置、核心调用流程以及如何在 RAG 管线中通过ReRankingContentAggregator使用重排序结果并了解其底层实现与异常处理机制。Maven 依赖引入langchain4j-voyage-ai是独立的模块官方文档给出的坐标如下dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-voyage-ai/artifactId version1.20.0-beta30/version /dependency说明文档中标注的1.20.0-beta30为发布示例版本。从当前仓库快照看langchain4j-voyage-ai/pom.xml 中的模块版本已演进为1.21.0-beta31-SNAPSHOT实际使用时请以你所依赖的 LangChain4j 版本为准并注意该系列版本处于 beta 阶段API 可能随版本微调。引入依赖后还需准备 Voyage AI 的 API Key在 Voyage AI 控制台创建后续构建模型时会用到。模型与核心能力概览该模块提供的重排序模型类为VoyageAiScoringModel源码位于 VoyageAiScoringModel.java。它实现了 LangChain4j 核心模块中的dev.langchain4j.model.scoring.ScoringModel接口底层调用的是 VoyageAiClient.java 中封装的 Voyage AI Rerank APIPOST {baseUrl}/rerank。ScoringModel接口的语义是对查询 若干文档片段逐一打分返回与输入片段一一对应的相关度分数列表。因此VoyageAiScoringModel通过score(String text, String query)返回单片段分数通过scoreAll(ListTextSegment segments, String query)返回多片段分数列表。模型名称枚举VoyageAiScoringModelName枚举VoyageAiScoringModelName.java预置了以下模型名枚举值实际模型名RERANK_1rerank-1RERANK_LITE_1rerank-lite-1RERANK_2rerank-2RERANK_2_LITErerank-2-lite其中rerank-lite-1轻量快速、成本低适合对时延敏感的场景rerank-2系列是较新的模型在 VoyageAiScoringModelTest.java 的 Mock 响应中也能看到rerank-2的身影。modelName既支持传入枚举也支持直接传字符串便于使用官方后续新增的模型。构建 VoyageAiScoringModel全部 Builder 参数VoyageAiScoringModel使用 Builder 模式构建所有可配置参数如下表默认值均来自源码实现参数类型默认值说明apiKeyString必填空则抛异常Voyage AI API Key用于Authorization: Bearer apiKey请求头认证modelNameVoyageAiScoringModelName/String必填重排序模型名见上文枚举baseUrlStringhttps://api.voyageai.com/v1/API 基础地址需以/结尾源码会自动补尾斜杠timeoutDuration60 秒HTTP 请求超时同时用于底层 HTTP 客户端的连接/读取超时兜底maxRetriesInteger2遇到瞬时错误时的最大重试次数topKInteger无已弃用见下文topK 的取舍truncationBoolean无默认由 API 决定是否截断超限输入httpClientBuilderHttpClientBuilderSPI 加载自定义 HTTP 客户端可精细控制代理、超时等customHeadersMap/SupplierMap无自定义请求头Supplier 形式支持 OAuth2 token 等动态刷新场景logRequests/logResponsesBooleanfalse是否打印请求/响应体的调试日志loggerorg.slf4j.Logger默认 Logger覆盖请求/响应日志使用的 Logger一个最小可用的构建示例参考 VoyageAiScoringModelIT.javaimport dev.langchain4j.model.scoring.ScoringModel; import dev.langchain4j.model.voyageai.VoyageAiScoringModel; import java.time.Duration; import static dev.langchain4j.model.voyageai.VoyageAiScoringModelName.RERANK_LITE_1; ScoringModel model VoyageAiScoringModel.builder() .apiKey(System.getenv(VOYAGE_API_KEY)) .modelName(RERANK_LITE_1) .timeout(Duration.ofSeconds(60)) .logRequests(true) .logResponses(true) .build();关于超时与重试的源码细节从 VoyageAiScoringModel.java 的构造逻辑可以看到两个容易忽略的点maxRetries未设置时默认为 2实际请求通过withRetryMappingExceptions(() - client.rerank(request), maxRetries)包装执行timeout默认 60 秒最终会传递给底层 HTTP 客户端在 VoyageAiClient.java 中若未显式设置连接/读取超时则以 15 秒为连接超时、60 秒为读取超时的兜底。打分调用与返回结果单片段打分ResponseDouble response model.score(labrador retriever, tell me about dogs); Double score response.content(); // 相关度分数 int totalTokens response.tokenUsage().totalTokenCount();多片段打分import dev.langchain4j.data.segment.TextSegment; ListTextSegment segments List.of( TextSegment.from(The Maine Coon is a large domesticated cat breed.), TextSegment.from(The sweet-faced, lovable Labrador Retriever is one of Americas most popular dog breeds.) ); ResponseListDouble response model.scoreAll(segments, tell me about dogs); ListDouble scores response.content(); // 与 segments 一一对应从 VoyageAiScoringModelIT.java 的集成测试可以看出两个行为特征分数列表与输入片段顺序一一对应scores.get(0)是猫的片段、scores.get(1)是狗的片段狗的分数更高响应中的TokenUsage只含输入 token 数与总 token 数outputTokenCount为nullfinishReason也为null——因为重排序是纯打分任务不产生生成 token。底层请求与响应映射scoreAll会将片段文本提取后封装为RerankRequest见 RerankRequest.java携带query、documents、model、topK、truncation字段响应解析为RerankResponse见 RerankResponse.java核心结构为data[]每个元素包含relevance_score与对应的文档index以及usage.total_tokens。分数结果如何保证顺序Voyage AI 返回的data是按相关度降序排列的而非输入顺序。因此 scoreAll 实现 会先创建一个与片段数等长、以null填充的分数列表再根据每个结果的index回填分数从而保证scores.get(i)严格对应第i个输入片段。若响应出现以下任一情况会抛出InternalServerException返回的分数数量不等于片段数量expected N scores, but got M出现重复的文档indexindex越界负数或大于等于片段数某个结果缺少relevanceScore。这些防御逻辑在 VoyageAiScoringModelTest.java 中都有对应的 Mock 单测覆盖should_fail_when_response_does_not_contain_one_score_per_segment、should_fail_when_response_contains_duplicate_index、should_fail_when_response_contains_out_of_range_index等感兴趣可直接阅读源码验证。topK 的取舍为何被弃用Builder.topK(Integer)已在1.20.0起标记为Deprecated(forRemoval true)。原因是topK与ScoringModel的语义冲突ScoringModel要求为每个输入片段返回一个分数而topK会要求 Voyage AI 只返回 Top-N 个文档的分数导致无法确定其余片段属于哪个索引。因此现在scoreAll中若设置了topK且topK segments.size()会在发起请求前直接抛出IllegalArgumentException提示改用ReRankingContentAggregator.builder().maxResults(...)来限制最终结果数量见 VoyageAiScoringModel.java 及对应测试 VoyageAiScoringModelTest.java。换句话说打分阶段不要用 topK 截断截断应交给 RAG 聚合阶段完成。在 RAG 管线中使用重排序将VoyageAiScoringModel接入 RAG 的标准姿势是配合核心模块的ReRankingContentAggregator源码见 ReRankingContentAggregator.javaimport dev.langchain4j.rag.content.aggregator.ContentAggregator; import dev.langchain4j.rag.content.aggregator.ReRankingContentAggregator; ContentAggregator aggregator ReRankingContentAggregator.builder() .scoringModel(model) // 传入 VoyageAiScoringModel .maxResults(3) // 重排序后仅保留 Top-3 .build();工作流程为ReRankingContentAggregator先通过内部的querySelector从查询中提取用于打分的文本调用scoringModel.scoreAll(...)对每个召回片段打分再按分数降序排序最后用.limit(maxResults)截断见 ReRankingContentAggregator.java。若未设置maxResults默认值为Integer.MAX_VALUE即保留全部片段。将ContentAggregator挂到RetrievalAugmentor上即可完成向量召回 → 重排序 → 截断的完整链路让最终送入大模型的上下文只保留与查询最相关的内容。日志与调试排查问题时建议开启请求/响应日志VoyageAiScoringModel model VoyageAiScoringModel.builder() .apiKey(System.getenv(VOYAGE_API_KEY)) .modelName(rerank-2) .logRequests(true) // 打印请求体 .logResponses(true) // 打印响应体 .build();底层由LoggingHttpClient实现见 VoyageAiClient.java可观察实际发送的query、documents、model等字段以及返回的relevance_score与total_tokens对确认输入截断、分数分布等问题非常有用。总结VoyageAiScoringModel将 Voyage AI 的重排序能力以标准ScoringModel接口暴露给 LangChain4j 生态具备以下要点支持rerank-1、rerank-lite-1、rerank-2、rerank-2-lite四种模型可通过枚举或字符串指定Builder 提供apiKey、modelName、baseUrl、timeout、maxRetries、truncation、logRequests/logResponses等完整配置返回分数与输入片段严格一一对应并对异常响应做了多层防御校验topK参数已弃用控制重排序后保留数量应使用ReRankingContentAggregator.maxResults(...)。建议进一步阅读仓库中的 官方集成文档、模型实现 VoyageAiScoringModel.java 与集成测试 VoyageAiScoringModelIT.java以获得更完整的上下文。注意集成测试通过EnabledIfEnvironmentVariable(named VOYAGE_API_KEY, matches .)控制运行前需在环境变量中设置VOYAGE_API_KEY。【免费下载链接】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），仅供参考 LangChain4j 接入 Voyage AI 重排序模型：VoyageAiScoringModel 完整实战指南
LangChain4j 接入 Voyage AI 重排序模型VoyageAiScoringModel 完整实战指南【免费下载链接】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在 RAG检索增强生成链路中向量检索召回的相关文档往往混有噪声直接送入大模型会拉低生成质量。LangChain4j 提供了统一的ScoringModel抽象并将 Voyage AI 的 Rerank API 封装为开箱即用的VoyageAiScoringModel用于对召回片段进行重排序打分。读完本文你将掌握该模块的依赖引入、构建参数配置、核心调用流程以及如何在 RAG 管线中通过ReRankingContentAggregator使用重排序结果并了解其底层实现与异常处理机制。Maven 依赖引入langchain4j-voyage-ai是独立的模块官方文档给出的坐标如下dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-voyage-ai/artifactId version1.20.0-beta30/version /dependency说明文档中标注的1.20.0-beta30为发布示例版本。从当前仓库快照看langchain4j-voyage-ai/pom.xml 中的模块版本已演进为1.21.0-beta31-SNAPSHOT实际使用时请以你所依赖的 LangChain4j 版本为准并注意该系列版本处于 beta 阶段API 可能随版本微调。引入依赖后还需准备 Voyage AI 的 API Key在 Voyage AI 控制台创建后续构建模型时会用到。模型与核心能力概览该模块提供的重排序模型类为VoyageAiScoringModel源码位于 VoyageAiScoringModel.java。它实现了 LangChain4j 核心模块中的dev.langchain4j.model.scoring.ScoringModel接口底层调用的是 VoyageAiClient.java 中封装的 Voyage AI Rerank APIPOST {baseUrl}/rerank。ScoringModel接口的语义是对查询 若干文档片段逐一打分返回与输入片段一一对应的相关度分数列表。因此VoyageAiScoringModel通过score(String text, String query)返回单片段分数通过scoreAll(ListTextSegment segments, String query)返回多片段分数列表。模型名称枚举VoyageAiScoringModelName枚举VoyageAiScoringModelName.java预置了以下模型名枚举值实际模型名RERANK_1rerank-1RERANK_LITE_1rerank-lite-1RERANK_2rerank-2RERANK_2_LITErerank-2-lite其中rerank-lite-1轻量快速、成本低适合对时延敏感的场景rerank-2系列是较新的模型在 VoyageAiScoringModelTest.java 的 Mock 响应中也能看到rerank-2的身影。modelName既支持传入枚举也支持直接传字符串便于使用官方后续新增的模型。构建 VoyageAiScoringModel全部 Builder 参数VoyageAiScoringModel使用 Builder 模式构建所有可配置参数如下表默认值均来自源码实现参数类型默认值说明apiKeyString必填空则抛异常Voyage AI API Key用于Authorization: Bearer apiKey请求头认证modelNameVoyageAiScoringModelName/String必填重排序模型名见上文枚举baseUrlStringhttps://api.voyageai.com/v1/API 基础地址需以/结尾源码会自动补尾斜杠timeoutDuration60 秒HTTP 请求超时同时用于底层 HTTP 客户端的连接/读取超时兜底maxRetriesInteger2遇到瞬时错误时的最大重试次数topKInteger无已弃用见下文topK 的取舍truncationBoolean无默认由 API 决定是否截断超限输入httpClientBuilderHttpClientBuilderSPI 加载自定义 HTTP 客户端可精细控制代理、超时等customHeadersMap/SupplierMap无自定义请求头Supplier 形式支持 OAuth2 token 等动态刷新场景logRequests/logResponsesBooleanfalse是否打印请求/响应体的调试日志loggerorg.slf4j.Logger默认 Logger覆盖请求/响应日志使用的 Logger一个最小可用的构建示例参考 VoyageAiScoringModelIT.javaimport dev.langchain4j.model.scoring.ScoringModel; import dev.langchain4j.model.voyageai.VoyageAiScoringModel; import java.time.Duration; import static dev.langchain4j.model.voyageai.VoyageAiScoringModelName.RERANK_LITE_1; ScoringModel model VoyageAiScoringModel.builder() .apiKey(System.getenv(VOYAGE_API_KEY)) .modelName(RERANK_LITE_1) .timeout(Duration.ofSeconds(60)) .logRequests(true) .logResponses(true) .build();关于超时与重试的源码细节从 VoyageAiScoringModel.java 的构造逻辑可以看到两个容易忽略的点maxRetries未设置时默认为 2实际请求通过withRetryMappingExceptions(() - client.rerank(request), maxRetries)包装执行timeout默认 60 秒最终会传递给底层 HTTP 客户端在 VoyageAiClient.java 中若未显式设置连接/读取超时则以 15 秒为连接超时、60 秒为读取超时的兜底。打分调用与返回结果单片段打分ResponseDouble response model.score(labrador retriever, tell me about dogs); Double score response.content(); // 相关度分数 int totalTokens response.tokenUsage().totalTokenCount();多片段打分import dev.langchain4j.data.segment.TextSegment; ListTextSegment segments List.of( TextSegment.from(The Maine Coon is a large domesticated cat breed.), TextSegment.from(The sweet-faced, lovable Labrador Retriever is one of Americas most popular dog breeds.) ); ResponseListDouble response model.scoreAll(segments, tell me about dogs); ListDouble scores response.content(); // 与 segments 一一对应从 VoyageAiScoringModelIT.java 的集成测试可以看出两个行为特征分数列表与输入片段顺序一一对应scores.get(0)是猫的片段、scores.get(1)是狗的片段狗的分数更高响应中的TokenUsage只含输入 token 数与总 token 数outputTokenCount为nullfinishReason也为null——因为重排序是纯打分任务不产生生成 token。底层请求与响应映射scoreAll会将片段文本提取后封装为RerankRequest见 RerankRequest.java携带query、documents、model、topK、truncation字段响应解析为RerankResponse见 RerankResponse.java核心结构为data[]每个元素包含relevance_score与对应的文档index以及usage.total_tokens。分数结果如何保证顺序Voyage AI 返回的data是按相关度降序排列的而非输入顺序。因此 scoreAll 实现 会先创建一个与片段数等长、以null填充的分数列表再根据每个结果的index回填分数从而保证scores.get(i)严格对应第i个输入片段。若响应出现以下任一情况会抛出InternalServerException返回的分数数量不等于片段数量expected N scores, but got M出现重复的文档indexindex越界负数或大于等于片段数某个结果缺少relevanceScore。这些防御逻辑在 VoyageAiScoringModelTest.java 中都有对应的 Mock 单测覆盖should_fail_when_response_does_not_contain_one_score_per_segment、should_fail_when_response_contains_duplicate_index、should_fail_when_response_contains_out_of_range_index等感兴趣可直接阅读源码验证。topK 的取舍为何被弃用Builder.topK(Integer)已在1.20.0起标记为Deprecated(forRemoval true)。原因是topK与ScoringModel的语义冲突ScoringModel要求为每个输入片段返回一个分数而topK会要求 Voyage AI 只返回 Top-N 个文档的分数导致无法确定其余片段属于哪个索引。因此现在scoreAll中若设置了topK且topK segments.size()会在发起请求前直接抛出IllegalArgumentException提示改用ReRankingContentAggregator.builder().maxResults(...)来限制最终结果数量见 VoyageAiScoringModel.java 及对应测试 VoyageAiScoringModelTest.java。换句话说打分阶段不要用 topK 截断截断应交给 RAG 聚合阶段完成。在 RAG 管线中使用重排序将VoyageAiScoringModel接入 RAG 的标准姿势是配合核心模块的ReRankingContentAggregator源码见 ReRankingContentAggregator.javaimport dev.langchain4j.rag.content.aggregator.ContentAggregator; import dev.langchain4j.rag.content.aggregator.ReRankingContentAggregator; ContentAggregator aggregator ReRankingContentAggregator.builder() .scoringModel(model) // 传入 VoyageAiScoringModel .maxResults(3) // 重排序后仅保留 Top-3 .build();工作流程为ReRankingContentAggregator先通过内部的querySelector从查询中提取用于打分的文本调用scoringModel.scoreAll(...)对每个召回片段打分再按分数降序排序最后用.limit(maxResults)截断见 ReRankingContentAggregator.java。若未设置maxResults默认值为Integer.MAX_VALUE即保留全部片段。将ContentAggregator挂到RetrievalAugmentor上即可完成向量召回 → 重排序 → 截断的完整链路让最终送入大模型的上下文只保留与查询最相关的内容。日志与调试排查问题时建议开启请求/响应日志VoyageAiScoringModel model VoyageAiScoringModel.builder() .apiKey(System.getenv(VOYAGE_API_KEY)) .modelName(rerank-2) .logRequests(true) // 打印请求体 .logResponses(true) // 打印响应体 .build();底层由LoggingHttpClient实现见 VoyageAiClient.java可观察实际发送的query、documents、model等字段以及返回的relevance_score与total_tokens对确认输入截断、分数分布等问题非常有用。总结VoyageAiScoringModel将 Voyage AI 的重排序能力以标准ScoringModel接口暴露给 LangChain4j 生态具备以下要点支持rerank-1、rerank-lite-1、rerank-2、rerank-2-lite四种模型可通过枚举或字符串指定Builder 提供apiKey、modelName、baseUrl、timeout、maxRetries、truncation、logRequests/logResponses等完整配置返回分数与输入片段严格一一对应并对异常响应做了多层防御校验topK参数已弃用控制重排序后保留数量应使用ReRankingContentAggregator.maxResults(...)。建议进一步阅读仓库中的 官方集成文档、模型实现 VoyageAiScoringModel.java 与集成测试 VoyageAiScoringModelIT.java以获得更完整的上下文。注意集成测试通过EnabledIfEnvironmentVariable(named VOYAGE_API_KEY, matches .)控制运行前需在环境变量中设置VOYAGE_API_KEY。【免费下载链接】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），仅供参考