在 LangChain4j 中使用 IBM watsonx.ai 实现文档重排序WatsonxScoringModel 完整接入指南【免费下载链接】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-watsonx模块接入 IBM watsonx.ai 的 Rerank 能力使用WatsonxScoringModel对一组文本片段TextSegment按与查询query的相关性打分排序。读完本文你将掌握依赖引入、IBM Cloud / Cloud Pak for Data 两种认证方式、WatsonxScoringModel的完整配置项与调用方式以及自定义 HttpClient、SSL 配置等企业级场景的实战方案可直接用于 RAG 检索后的重排序环节。ScoringModel 与 RAG 重排序在 RAG检索增强生成流程中向量检索阶段往往会召回一批候选文档其中部分文档与用户查询相关度较低。此时通常会引入一个重排序rerank阶段用专门的 cross-encoder 类模型对查询-文档对进行精排只把最相关的片段送入 LLM 上下文。LangChain4j 在 langchain4j-core 中为此定义了ScoringModel接口ResponseDouble score(String text, String query)/score(TextSegment segment, String query)对单个文本打分ResponseListDouble scoreAll(ListTextSegment segments, String query)批量打分返回分数列表顺序与传入的 segments 一一对应自 1.20.0 起还引入了实验性的scoreAsync(ScoringRequest)异步接口可服务于非阻塞 RAG 流程如ReRankingContentAggregator。WatsonxScoringModel正是该接口在 IBM watsonx.ai 上的官方实现它内部封装了 IBM 官方watsonx-aiJava SDK当前仓库 langchain4j-watsonx/pom.xml 中引入的版本为com.ibm.watsonx:watsonx-ai:0.40.0的RerankService让 Java 开发者用 LangChain4j 统一的 API 即可调用 watsonx.ai 的重排序模型。添加 Maven 依赖在pom.xml中引入langchain4j-watsonx模块dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-watsonx/artifactId version1.20.0-beta30/version /dependency说明文档示例版本为1.20.0-beta30仓库当前快照版本可从 langchain4j-watsonx/pom.xml 的parent节点确认如1.21.0-beta31-SNAPSHOT。发布版本请以 Maven 中央仓库实际可用版本为准。认证方式三种 Authenticatorwatsonx.ai 的认证统一通过Authenticator接口抽象WatsonxScoringModel等所有服务构建器既支持.apiKey(...)快捷方式也支持传入完整的Authenticator实例.authenticator(...)。从 WatsonxConnectionBuilder 的源码可以看到两者最终在 WatsonxScoringModel 的构造函数中被合并处理指定了authenticator就用它否则回退到apiKey自动生成 IBM Cloud IAM 令牌var rerankServiceBuilder nonNull(builder.authenticator) ? RerankService.builder().authenticator(builder.authenticator) : RerankService.builder().apiKey(builder.apiKey);三种典型场景认证方式适用部署说明IBMCloudAuthenticatorIBM Cloud 公有云最简单使用 API Key 换取 IAM 令牌通过.apiKey(...)快捷方式触发CP4DAuthenticatorCloud Pak for DataCP4D私有化部署需要指定实例 baseUrl、用户名与 API Key自定义 Authenticator任意环境实现Authenticator接口即可接入自有令牌体系示例IBM Cloud 认证快捷方式WatsonxScoringModel.builder() .baseUrl(CloudRegion.FRANKFURT) .apiKey(your-api-key) // Simple IBM Cloud authentication .projectId(your-project-id) .modelName(cross-encoder/ms-marco-minilm-l-12-v2) .build();示例Cloud Pak for Data 认证WatsonxScoringModel.builder() .baseUrl(https://my-instance-url) .authenticator( // For Cloud Pak for Data deployments CP4DAuthenticator.builder() .baseUrl(https://my-instance-url) .username(username) .apiKey(api-key) .build() ) .projectId(my-project-id) .modelName(cross-encoder/ms-marco-minilm-l-12-v2) .build();注意CP4D 环境必须显式传入CP4DAuthenticator并配置好baseUrl、username与apiKey单纯使用.apiKey(...)无法完成 CP4D 私有化部署的认证。完整 Builder 配置项一览WatsonxScoringModel的 Builder 继承自 WatsonxConnectionBuilder 与 WatsonxBuilder支持以下配置配置项类型默认值说明baseUrl(...)CloudRegion/String/URI无watsonx.ai ML API 端点传CloudRegion时自动取对应区域的mlEndpoint()如https://us-south.ml.cloud.ibm.comapiKey(...)String无IBM Cloud API Key用于生成 IAM 访问令牌与authenticator二选一authenticator(...)Authenticator无完整认证器实例IBMCloudAuthenticator、CP4DAuthenticator或自定义实现projectId(...)String无IBM Cloud 项目 ID与spaceId必须且只能设置一个spaceId(...)String无IBM Cloud 部署空间Deployment SpaceID与projectId必须且只能设置一个modelName(...)String无watsonx.ai 重排序模型 ID如cross-encoder/ms-marco-minilm-l-12-v2、ibm/slate-125m-english-rtrvr-v2见 WatsonxScoringModel.Builderversion(...)String无watsonx.ai API 版本日期如2024-05-31timeout(...)Duration60 秒HTTP 请求超时时间logRequests(...)Booleanfalse调试时打印发送到 watsonx.ai 的请求体logResponses(...)Booleanfalse调试时打印 watsonx.ai 返回的响应体httpClient(...)java.net.http.HttpClientSDK 默认自定义 HTTP 客户端TLS/代理等场景verifySsl(...)booleantrue是否校验 SSL 证书私有化环境可置false其中projectId与spaceId的互斥约束在 WatsonxBuilder 的源码注释中明确要求Exactly one of projectId or spaceId must be set构建请求时二者都会写入 Rerank 请求体单元测试 WatsonxScoringModelTest 同时断言了projectId与spaceId的透传。创建 IBM Cloud API Key 与查找 Project ID创建 API Key登录 IBM Cloud 控制台的 IAM 管理页面cloud.ibm.com/iam/apikeys点击Create 填写名称后即可生成 API Key请妥善保存仅创建时可见一次。查找 Project ID打开 watsonx.ai 项目控制台dataplatform.cloud.ibm.com/projects/?contextwx进入你的项目切换到Manage管理标签页在Details详细信息区域复制Project ID。使用 WatsonxScoringModel 打分与重排序基础调用scoreAll 批量打分ScoringModel scoringModel WatsonxScoringModel.builder() .baseUrl(CloudRegion.FRANKFURT) .apiKey(your-api-key) .projectId(your-project-id) .modelName(cross-encoder/ms-marco-minilm-l-12-v2) .build(); var scores scoringModel.scoreAll( List.of( TextSegment.from(Example_1), TextSegment.from(Example_2) ), Hello from watsonx.ai ); System.out.println(scores);调用后返回ResponseListDouble其中分数的下标与传入TextSegment列表的顺序严格对应而非模型返回的自然顺序。这一保证来自 WatsonxScoringModel.scoreAll 的实现它先把TextSegment列表映射为字符串列表inputs调用 SDK 的rerankService.rerank(query, inputs, parameters)再按RerankResult.index()把每个分数放回原始位置ListString inputs segments.stream().map(TextSegment::text).toList(); RerankResponse response WatsonxExceptionMapper.INSTANCE.withExceptionMapper( () - rerankService.rerank(query, inputs, parameters)); var content new Double[response.results().size()]; for (RerankResult rerankResult : response.results()) content[rerankResult.index()] rerankResult.score();同时Response中携带TokenUsageinputTokenCount便于统计本次重排序的输入消耗。单文本打分scoreScoringModel接口还提供了score(text, query)便捷方法底层复用scoreAll并对单个结果做断言见 ScoringModel.javavar response scoringModel.score( Water boils at 100 degrees Celsius at sea level., At what temperature does water boil? ); System.out.println(response.content()); // 相关性分数带 RerankParameters 的精细控制除默认调用外WatsonxScoringModel还提供接收 SDKRerankParameters的重载scoreAll(segments, query, parameters)支持如truncateInputTokens截断输入 token 数、returnQuery、returnInputs等参数RerankParameters parameters RerankParameters.builder() .modelId(modelId) .projectId(projectId) .spaceId(spaceId) .truncateInputTokens(512) .returnQuery(true) .returnInputs(true) .build(); var scores scoringModel.scoreAll(segments, query, parameters);集成测试 WatsonxScoringModelIT 验证了truncateInputTokens(4)确实能显著降低inputTokenCount适合需要控制成本的长文本场景。空输入与空查询的容错从 WatsonxScoringModel 源码可见当segments为null/空列表或query为null/空白字符串时会直接返回空结果而不发起网络请求这一行为同样被单元测试 testScoreAllWithParameters 覆盖。自定义 HttpClient 与 SSL 配置在企业内网或 Cloud Pak for Data 环境中常常需要自定义 TLS/SSL 配置、代理等。所有 watsonx.ai 服务与认证器均支持通过 Builder 传入java.net.http.HttpClient。使用自定义 HttpClientHttpClient httpClient HttpClient.newBuilder() .sslContext(createCustomSSLContext()) .executor(ExecutorProvider.ioExecutor()) .build(); EmbeddingModel embeddingModel WatsonxEmbeddingModel.builder() .baseUrl(https://my-instance-url) .modelName(ibm/granite-embedding-278m-multilingual) .projectId(project-id) .httpClient(httpClient) // Custom HttpClient .authenticator( CP4DAuthenticator.builder() .baseUrl(https://my-instance-url) .username(username) .apiKey(api-key) .httpClient(httpClient) // Custom HttpClient .build() ) .build();重要提示在 Cloud Pak for Data 场景使用自定义HttpClient时必须同时在服务构建器如WatsonxScoringModel.builder()和认证器构建器如CP4DAuthenticator.builder()上设置同一个 HttpClient 实例以保证所有请求含令牌获取的 HTTP 行为一致。这一模式同样适用于WatsonxScoringModel。仅禁用 SSL 校验如果只需要关闭证书校验而不想构造完整 HttpClient可以直接使用verifySsl(false)EmbeddingModel embeddingModel WatsonxEmbeddingModel.builder() .baseUrl(https://my-instance-url) .modelName(ibm/granite-embedding-278m-multilingual) .projectId(project-id) .verifySsl(false) // Disable SSL verification .authenticator( CP4DAuthenticator.builder() .baseUrl(https://my-instance-url) .username(username) .apiKey(api-key) .verifySsl(false) // Disable SSL verification .build() ) .build();verifySsl默认值为true见 WatsonxConnectionBuilder 的字段初始化protected boolean verifySsl true;仅在可信内网等明确场景下才应关闭生产环境建议保持开启。从源码看底层调用链结合 WatsonxScoringModel 源码一次重排序的完整调用链为WatsonxScoringModel.scoreAll(segments, query[, parameters]) └─ RerankService.builder() .authenticator(...) 或 .apiKey(...) .baseUrl(...).modelId(...).version(...) .projectId(...).spaceId(...) .timeout(...).logRequests(...).logResponses(...) .httpClient(...).verifySsl(...) .build() └─ rerankService.rerank(query, inputs, parameters) // IBM watsonx-ai SDK 异常统一经 WatsonxExceptionMapper 映射为 LangChain4j 异常 └─ 按 RerankResult.index() 重排分数 → ResponseListDouble TokenUsage几个值得注意的工程细节异常映射SDK 抛出的底层异常会通过WatsonxExceptionMapper转换为 LangChain4j 的统一异常体系业务代码无需感知 SDK 细节版本参数version用于指定 watsonx.ai API 版本日期建议显式设置以获得稳定行为调试开关logRequests(true)/logResponses(true)会在排查认证或参数问题时打印完整请求/响应体模型目录WatsonxModelCatalog中内置了rerank分类的模型元数据见 WatsonxModelCatalog.java当前官方文档示例推荐的模型 ID 为cross-encoder/ms-marco-minilm-l-12-v2完整可用的 rerank 模型列表请查阅 watsonx.ai 官方模型文档fm-models-embed页面的 rerank 小节。测试与验证方式仓库中针对该模块提供了两类测试单元测试WatsonxScoringModelTest.java通过 Mockito mockRerankService验证了 Builder 参数透传modelId/projectId/spaceId均出现在请求 payload 中、scoreAll返回分数与输入顺序一致、RerankParameters重载、空输入容错等行为集成测试WatsonxScoringModelIT.java需要设置四个环境变量后运行仅当全部存在时启用WATSONX_API_KEYIBM Cloud API KeyWATSONX_PROJECT_ID项目 IDWATSONX_URLwatsonx.ai 端点地址WATSONX_RERANK_MODEL重排序模型 ID。集成测试同时是很好的使用参考它验证了水在 100 摄氏度沸腾文本对水在什么温度沸腾查询得分大于 0、以及三条候选片段中描述水星的片段得分最高scores.get(1) scores.get(0)直观展示了重排序在相关性排序上的实际效果。将 WatsonxScoringModel 用于 RAG 重排序由于WatsonxScoringModel实现了标准的ScoringModel接口它可以直接嵌入 LangChain4j 的 RAG 链路中作为重排序组件例如配合ContentRetriever的ReRankingContentAggregator使用先由向量库召回候选片段再用 watsonx.ai 的 cross-encoder 模型按与查询的相关性精排最后只保留 Top-K 片段送入 LLM。相比 BM25 或纯向量相似度cross-encoder 重排序通常能带来更精准的上下文选择尤其适合企业级问答、语义检索等对准确率敏感的 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），仅供参考 在 LangChain4j 中使用 IBM watsonx.ai 实现文档重排序：WatsonxScoringModel 完整接入指南
在 LangChain4j 中使用 IBM watsonx.ai 实现文档重排序WatsonxScoringModel 完整接入指南【免费下载链接】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-watsonx模块接入 IBM watsonx.ai 的 Rerank 能力使用WatsonxScoringModel对一组文本片段TextSegment按与查询query的相关性打分排序。读完本文你将掌握依赖引入、IBM Cloud / Cloud Pak for Data 两种认证方式、WatsonxScoringModel的完整配置项与调用方式以及自定义 HttpClient、SSL 配置等企业级场景的实战方案可直接用于 RAG 检索后的重排序环节。ScoringModel 与 RAG 重排序在 RAG检索增强生成流程中向量检索阶段往往会召回一批候选文档其中部分文档与用户查询相关度较低。此时通常会引入一个重排序rerank阶段用专门的 cross-encoder 类模型对查询-文档对进行精排只把最相关的片段送入 LLM 上下文。LangChain4j 在 langchain4j-core 中为此定义了ScoringModel接口ResponseDouble score(String text, String query)/score(TextSegment segment, String query)对单个文本打分ResponseListDouble scoreAll(ListTextSegment segments, String query)批量打分返回分数列表顺序与传入的 segments 一一对应自 1.20.0 起还引入了实验性的scoreAsync(ScoringRequest)异步接口可服务于非阻塞 RAG 流程如ReRankingContentAggregator。WatsonxScoringModel正是该接口在 IBM watsonx.ai 上的官方实现它内部封装了 IBM 官方watsonx-aiJava SDK当前仓库 langchain4j-watsonx/pom.xml 中引入的版本为com.ibm.watsonx:watsonx-ai:0.40.0的RerankService让 Java 开发者用 LangChain4j 统一的 API 即可调用 watsonx.ai 的重排序模型。添加 Maven 依赖在pom.xml中引入langchain4j-watsonx模块dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-watsonx/artifactId version1.20.0-beta30/version /dependency说明文档示例版本为1.20.0-beta30仓库当前快照版本可从 langchain4j-watsonx/pom.xml 的parent节点确认如1.21.0-beta31-SNAPSHOT。发布版本请以 Maven 中央仓库实际可用版本为准。认证方式三种 Authenticatorwatsonx.ai 的认证统一通过Authenticator接口抽象WatsonxScoringModel等所有服务构建器既支持.apiKey(...)快捷方式也支持传入完整的Authenticator实例.authenticator(...)。从 WatsonxConnectionBuilder 的源码可以看到两者最终在 WatsonxScoringModel 的构造函数中被合并处理指定了authenticator就用它否则回退到apiKey自动生成 IBM Cloud IAM 令牌var rerankServiceBuilder nonNull(builder.authenticator) ? RerankService.builder().authenticator(builder.authenticator) : RerankService.builder().apiKey(builder.apiKey);三种典型场景认证方式适用部署说明IBMCloudAuthenticatorIBM Cloud 公有云最简单使用 API Key 换取 IAM 令牌通过.apiKey(...)快捷方式触发CP4DAuthenticatorCloud Pak for DataCP4D私有化部署需要指定实例 baseUrl、用户名与 API Key自定义 Authenticator任意环境实现Authenticator接口即可接入自有令牌体系示例IBM Cloud 认证快捷方式WatsonxScoringModel.builder() .baseUrl(CloudRegion.FRANKFURT) .apiKey(your-api-key) // Simple IBM Cloud authentication .projectId(your-project-id) .modelName(cross-encoder/ms-marco-minilm-l-12-v2) .build();示例Cloud Pak for Data 认证WatsonxScoringModel.builder() .baseUrl(https://my-instance-url) .authenticator( // For Cloud Pak for Data deployments CP4DAuthenticator.builder() .baseUrl(https://my-instance-url) .username(username) .apiKey(api-key) .build() ) .projectId(my-project-id) .modelName(cross-encoder/ms-marco-minilm-l-12-v2) .build();注意CP4D 环境必须显式传入CP4DAuthenticator并配置好baseUrl、username与apiKey单纯使用.apiKey(...)无法完成 CP4D 私有化部署的认证。完整 Builder 配置项一览WatsonxScoringModel的 Builder 继承自 WatsonxConnectionBuilder 与 WatsonxBuilder支持以下配置配置项类型默认值说明baseUrl(...)CloudRegion/String/URI无watsonx.ai ML API 端点传CloudRegion时自动取对应区域的mlEndpoint()如https://us-south.ml.cloud.ibm.comapiKey(...)String无IBM Cloud API Key用于生成 IAM 访问令牌与authenticator二选一authenticator(...)Authenticator无完整认证器实例IBMCloudAuthenticator、CP4DAuthenticator或自定义实现projectId(...)String无IBM Cloud 项目 ID与spaceId必须且只能设置一个spaceId(...)String无IBM Cloud 部署空间Deployment SpaceID与projectId必须且只能设置一个modelName(...)String无watsonx.ai 重排序模型 ID如cross-encoder/ms-marco-minilm-l-12-v2、ibm/slate-125m-english-rtrvr-v2见 WatsonxScoringModel.Builderversion(...)String无watsonx.ai API 版本日期如2024-05-31timeout(...)Duration60 秒HTTP 请求超时时间logRequests(...)Booleanfalse调试时打印发送到 watsonx.ai 的请求体logResponses(...)Booleanfalse调试时打印 watsonx.ai 返回的响应体httpClient(...)java.net.http.HttpClientSDK 默认自定义 HTTP 客户端TLS/代理等场景verifySsl(...)booleantrue是否校验 SSL 证书私有化环境可置false其中projectId与spaceId的互斥约束在 WatsonxBuilder 的源码注释中明确要求Exactly one of projectId or spaceId must be set构建请求时二者都会写入 Rerank 请求体单元测试 WatsonxScoringModelTest 同时断言了projectId与spaceId的透传。创建 IBM Cloud API Key 与查找 Project ID创建 API Key登录 IBM Cloud 控制台的 IAM 管理页面cloud.ibm.com/iam/apikeys点击Create 填写名称后即可生成 API Key请妥善保存仅创建时可见一次。查找 Project ID打开 watsonx.ai 项目控制台dataplatform.cloud.ibm.com/projects/?contextwx进入你的项目切换到Manage管理标签页在Details详细信息区域复制Project ID。使用 WatsonxScoringModel 打分与重排序基础调用scoreAll 批量打分ScoringModel scoringModel WatsonxScoringModel.builder() .baseUrl(CloudRegion.FRANKFURT) .apiKey(your-api-key) .projectId(your-project-id) .modelName(cross-encoder/ms-marco-minilm-l-12-v2) .build(); var scores scoringModel.scoreAll( List.of( TextSegment.from(Example_1), TextSegment.from(Example_2) ), Hello from watsonx.ai ); System.out.println(scores);调用后返回ResponseListDouble其中分数的下标与传入TextSegment列表的顺序严格对应而非模型返回的自然顺序。这一保证来自 WatsonxScoringModel.scoreAll 的实现它先把TextSegment列表映射为字符串列表inputs调用 SDK 的rerankService.rerank(query, inputs, parameters)再按RerankResult.index()把每个分数放回原始位置ListString inputs segments.stream().map(TextSegment::text).toList(); RerankResponse response WatsonxExceptionMapper.INSTANCE.withExceptionMapper( () - rerankService.rerank(query, inputs, parameters)); var content new Double[response.results().size()]; for (RerankResult rerankResult : response.results()) content[rerankResult.index()] rerankResult.score();同时Response中携带TokenUsageinputTokenCount便于统计本次重排序的输入消耗。单文本打分scoreScoringModel接口还提供了score(text, query)便捷方法底层复用scoreAll并对单个结果做断言见 ScoringModel.javavar response scoringModel.score( Water boils at 100 degrees Celsius at sea level., At what temperature does water boil? ); System.out.println(response.content()); // 相关性分数带 RerankParameters 的精细控制除默认调用外WatsonxScoringModel还提供接收 SDKRerankParameters的重载scoreAll(segments, query, parameters)支持如truncateInputTokens截断输入 token 数、returnQuery、returnInputs等参数RerankParameters parameters RerankParameters.builder() .modelId(modelId) .projectId(projectId) .spaceId(spaceId) .truncateInputTokens(512) .returnQuery(true) .returnInputs(true) .build(); var scores scoringModel.scoreAll(segments, query, parameters);集成测试 WatsonxScoringModelIT 验证了truncateInputTokens(4)确实能显著降低inputTokenCount适合需要控制成本的长文本场景。空输入与空查询的容错从 WatsonxScoringModel 源码可见当segments为null/空列表或query为null/空白字符串时会直接返回空结果而不发起网络请求这一行为同样被单元测试 testScoreAllWithParameters 覆盖。自定义 HttpClient 与 SSL 配置在企业内网或 Cloud Pak for Data 环境中常常需要自定义 TLS/SSL 配置、代理等。所有 watsonx.ai 服务与认证器均支持通过 Builder 传入java.net.http.HttpClient。使用自定义 HttpClientHttpClient httpClient HttpClient.newBuilder() .sslContext(createCustomSSLContext()) .executor(ExecutorProvider.ioExecutor()) .build(); EmbeddingModel embeddingModel WatsonxEmbeddingModel.builder() .baseUrl(https://my-instance-url) .modelName(ibm/granite-embedding-278m-multilingual) .projectId(project-id) .httpClient(httpClient) // Custom HttpClient .authenticator( CP4DAuthenticator.builder() .baseUrl(https://my-instance-url) .username(username) .apiKey(api-key) .httpClient(httpClient) // Custom HttpClient .build() ) .build();重要提示在 Cloud Pak for Data 场景使用自定义HttpClient时必须同时在服务构建器如WatsonxScoringModel.builder()和认证器构建器如CP4DAuthenticator.builder()上设置同一个 HttpClient 实例以保证所有请求含令牌获取的 HTTP 行为一致。这一模式同样适用于WatsonxScoringModel。仅禁用 SSL 校验如果只需要关闭证书校验而不想构造完整 HttpClient可以直接使用verifySsl(false)EmbeddingModel embeddingModel WatsonxEmbeddingModel.builder() .baseUrl(https://my-instance-url) .modelName(ibm/granite-embedding-278m-multilingual) .projectId(project-id) .verifySsl(false) // Disable SSL verification .authenticator( CP4DAuthenticator.builder() .baseUrl(https://my-instance-url) .username(username) .apiKey(api-key) .verifySsl(false) // Disable SSL verification .build() ) .build();verifySsl默认值为true见 WatsonxConnectionBuilder 的字段初始化protected boolean verifySsl true;仅在可信内网等明确场景下才应关闭生产环境建议保持开启。从源码看底层调用链结合 WatsonxScoringModel 源码一次重排序的完整调用链为WatsonxScoringModel.scoreAll(segments, query[, parameters]) └─ RerankService.builder() .authenticator(...) 或 .apiKey(...) .baseUrl(...).modelId(...).version(...) .projectId(...).spaceId(...) .timeout(...).logRequests(...).logResponses(...) .httpClient(...).verifySsl(...) .build() └─ rerankService.rerank(query, inputs, parameters) // IBM watsonx-ai SDK 异常统一经 WatsonxExceptionMapper 映射为 LangChain4j 异常 └─ 按 RerankResult.index() 重排分数 → ResponseListDouble TokenUsage几个值得注意的工程细节异常映射SDK 抛出的底层异常会通过WatsonxExceptionMapper转换为 LangChain4j 的统一异常体系业务代码无需感知 SDK 细节版本参数version用于指定 watsonx.ai API 版本日期建议显式设置以获得稳定行为调试开关logRequests(true)/logResponses(true)会在排查认证或参数问题时打印完整请求/响应体模型目录WatsonxModelCatalog中内置了rerank分类的模型元数据见 WatsonxModelCatalog.java当前官方文档示例推荐的模型 ID 为cross-encoder/ms-marco-minilm-l-12-v2完整可用的 rerank 模型列表请查阅 watsonx.ai 官方模型文档fm-models-embed页面的 rerank 小节。测试与验证方式仓库中针对该模块提供了两类测试单元测试WatsonxScoringModelTest.java通过 Mockito mockRerankService验证了 Builder 参数透传modelId/projectId/spaceId均出现在请求 payload 中、scoreAll返回分数与输入顺序一致、RerankParameters重载、空输入容错等行为集成测试WatsonxScoringModelIT.java需要设置四个环境变量后运行仅当全部存在时启用WATSONX_API_KEYIBM Cloud API KeyWATSONX_PROJECT_ID项目 IDWATSONX_URLwatsonx.ai 端点地址WATSONX_RERANK_MODEL重排序模型 ID。集成测试同时是很好的使用参考它验证了水在 100 摄氏度沸腾文本对水在什么温度沸腾查询得分大于 0、以及三条候选片段中描述水星的片段得分最高scores.get(1) scores.get(0)直观展示了重排序在相关性排序上的实际效果。将 WatsonxScoringModel 用于 RAG 重排序由于WatsonxScoringModel实现了标准的ScoringModel接口它可以直接嵌入 LangChain4j 的 RAG 链路中作为重排序组件例如配合ContentRetriever的ReRankingContentAggregator使用先由向量库召回候选片段再用 watsonx.ai 的 cross-encoder 模型按与查询的相关性精排最后只保留 Top-K 片段送入 LLM。相比 BM25 或纯向量相似度cross-encoder 重排序通常能带来更精准的上下文选择尤其适合企业级问答、语义检索等对准确率敏感的 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），仅供参考