openJiuwen 的 ChatReranker 实战：基于 Chat Completion Logprobs 的相关性重排-北京尧图网络

人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载导读ChatReranker是 openJiuwen agent-core-javacom.openjiuwen.retrieval.reranker.ChatReranker提供的一种特殊重排器它不依赖专用的 rerank 端点而是复用标准 chat completion 服务通过yes/no两个 token 的 logprob 计算候选文档与查询的相关性分数。本文围绕该类的设计原理、RerankerConfig配置要点、请求构造细节、分数解析算法与兼容性探测方法展开并结合仓库源码与测试用例逐层拆解帮助你快速在检索RAG链路中接入基于 chat 服务的重排能力。一、类定位ChatReranker extends StandardReranker在 openJiuwen 的检索模块中重排器统一继承自 Reranker 抽象基类其核心接口只有两个CompletableFutureMapString, Double rerank(...)异步重排返回文档 → 相关性分数映射MapString, Double rerankSync(...)同步重排。ChatReranker与 StandardReranker 共享这套抽象但两者面向的服务与调用方式完全不同维度StandardRerankerChatReranker请求端点POST {apiBase}/rerankvLLM 风格POST {apiBase}/chat/completions打分依据服务端返回的relevance_score客户端根据yes/notoken 的 logprob 自行计算单次调用候选数可一次传入多个文档每个候选单独发起一次请求是否依赖 logprobs 能力不依赖强依赖服务不支持则直接报错ChatReranker的类声明位于 retrieval/src/main/java/com/openjiuwen/retrieval/reranker/ChatReranker.java#L38源码注释明确指出它是对 Python 版openjiuwen/core/retrieval/reranker/chat_reranker.py的 Java 对齐实现因此接口语义与 Python 版本保持一致。从源码结构看设计者将ChatReranker放在独立的retrieval模块中com.openjiuwen.retrieval.reranker包而配置类RerankerConfig、数据模型Document与抽象基类Reranker位于核心模块com.openjiuwen.core.foundation.store.base_reranker包模块边界清晰。二、核心原理用 yes/no token 的 logprob 计算相关性ChatReranker的文档说明非常简洁只有三条端点固定为/chat/completions每个候选会单独发起一次请求RerankerConfig.yesNoIds必须包含两个 token id测试确认缺失时会抛出异常。这三条背后对应着一套完整的算法流程。整条链路是将查询与候选文档拼成对话请求模型只生成 1 个 token并开启 logprobs 返回 top 候选 token 及其对数概率最后用 yes/no 概率之比归一化出分数。2.1 请求的构造requestParams源码 ChatReranker.java#L178-L202 展示了请求参数的完整组装逻辑消息结构固定两条消息——system消息内容为Judge whether the Document meets the requirements based on the Query and the Instruct provided. user消息内容由三部分模板拼接而成Instruct: %s Query: %s Document: %s其中instruct传Boolean.TRUE时使用默认指令Given a search query, retrieve relevant candidates that answer the query.传入自定义字符串时使用自定义指令传入Boolean.FALSE时仅保留Query与Document部分见buildQueryChatReranker.java#L277-L282。固定生成参数测试 ChatRerankerTest.java#L52-L79 明确断言了这些取值参数值作用modelRerankerConfig.modelName指定模型temperature0强制确定性输出避免采样抖动影响分数max_tokens1只让模型输出一个 token即 yes 或 nologprobstrue开启对数概率返回top_logprobs5返回概率最高的 5 个候选 tokenlogit_bias两个 yes/no token id 各加偏置5抬高 yes/no 的生成概率引导模型二选一logit_bias的构造遍历config.getYesNoIds()对两个 token id 分别施加5的偏置ChatReranker.java#L193-L197。这正是yes_no_ids配置存在的意义——你必须提供目标模型词表中是/否两个 token 的 id重排器才能精准引导并识别输出。extra_body透传RerankerConfig.extraBody中额外的自定义参数会以putAll方式合并进请求体ChatReranker.java#L198-L200方便对接不同服务商特有的请求字段。2.2 响应的解析与分数计算parseResponse拿到 chat completion 响应后parseResponseChatReranker.java#L132-L170执行以下步骤从choices[0].logprobs.content[0].top_logprobs中取出 top 候选 token 列表对每个 token用Math.exp(logprob)还原概率值将 token 文本小写化后按前缀匹配以yes开头计入 yes 概率以no开头计入 no 概率因此YES,、No.这类带标点或大小写的变体也能正确识别Python Parity 测试 ChatRerankerPythonParityTest.java#L155-L177 验证了大小写与前缀场景对 yes、no 各自取最大值作为该侧概率最终相关性分数 yesScore / (yesScore noScore)若两者之和为 0则分数取 0ChatReranker.java#L165-L168。可以直观理解为模型认为候选文档越能满足查询输出 yes 的概率越高归一化后分数越接近 1反之越接近 0。2.3 为什么每个候选单独请求一次与StandardReranker支持批量传入文档不同ChatReranker的输入被严格限制为List且 size 必须为 1extractSingleDocumentChatReranker.java#L255-L267元素可以是String或 Document。这是因为 yes/no 打分天然是一对一的判别任务一次只让模型对一个文档做是否相关的判定才能得到干净的概率。传多个文档、空列表或非 List 输入都会抛出input to chat reranker must be a list[str | Document] of size 1异常ChatReranker.java#L269-L275。需要重排多个候选时由调用方循环发起多次请求。三、RerankerConfig 配置要点ChatReranker的构造参数是 RerankerConfig这是一个带 Lombok Builder 的配置类关键字段如下字段JSON 字段名默认值说明apiKeyapi_keyAPI Key非空时自动附带Authorization: Bearer key请求头apiBaseapi_base无服务地址不要带/chat/completions后缀构造时会自动归一化modelNamemodel_name兼容别名model模型名称请求体中的model字段timeout—timeout10.0秒单次 HTTP 请求超时temperaturetemperature0.95注意ChatReranker请求时强制写死temperature0此配置对 chat 重排不生效topPtop_p0.1同上chat 请求中未透传yesNoIdsyes_no_ids无必填恰好两个整数 token idextraBodyextra_body空 Map透传到请求体的额外参数3.1 yes_no_ids 的校验逻辑构造ChatReranker时isValidYesNoIdsChatReranker.java#L251-L253要求yesNoIds非空、size 恰好为 2 且两个元素均非 null。任一条不满足都会抛出RETRIEVAL_RERANKER_INPUT_INVALID错误错误信息为chat reranker require \yes_no_ids\ to be specified in RerankerConfig。测试 ChatRerankerTest.java#L36-L49 分别用null和仅一个 id 的配置验证了异常行为此外 ChatRerankerPythonParityTest.java#L67-L80 还验证了非整数类型的 id如[yes,no]在 JSON 反序列化阶段就会失败。具体取哪两个 token id取决于目标模型的词表。示例代码注释中给出了一组参考值9454,2753见 ChatRerankerExample.java#L36-L37实际使用请按模型词表查询确认。3.2 api_base 的归一化无论apiBase是否携带尾部斜杠或/chat/completions后缀normalizeBaseUrlChatReranker.java#L323-L329都会将其规整为纯基地址最终请求 URI 固定为{apiBase}/chat/completions。测试 ChatRerankerTest.java#L183 断言了https://api.example.com/v1对应的最终地址为https://api.example.com/v1/chat/completions。3.3 请求头与重试请求头默认包含Content-Type: application/jsonapiKey非空时追加Authorization: Bearer key额外头extraHeaders会合并覆盖ChatReranker.java#L88-L95。构造重载可指定maxRetries、retryWait和自定义HttpClient默认值为重试 3 次、等待 0.1 秒。重试逻辑见 ChatReranker.java#L204-L249仅在非 2xx 响应或 IO 异常时重试最终失败抛出RETRIEVAL_RERANKER_REQUEST_CALL_FAILED。四、代码示例从配置到打分仓库提供了可直接运行的完整示例 ChatRerankerExample.java下面给出核心使用范式import com.openjiuwen.retrieval.reranker.ChatReranker; import com.openjiuwen.core.foundation.store.base_reranker.RerankerConfig; // 1. 构造配置yes_no_ids 必填两个 token id RerankerConfig config RerankerConfig.builder() .apiBase(https://your-endpoint/v1) .apiKey(your-api-key) .modelName(your-model) .yesNoIds(List.of(9454, 2753)) // 参考值按模型词表确认 .build(); // 2. 实例化重排器 ChatReranker reranker new ChatReranker(config); // 3.可选兼容性探测确认服务支持 logprobs if (!reranker.testCompatibility()) { // 服务不支持 chat-completion 重排需更换服务或改用 StandardReranker return; } // 4. 重排单个候选查询单个文档String 或 Document 均可instruct 可用 Boolean 或自定义字符串 MapString, Double score reranker.rerankSync( Hello, List.of(bonjour), Boolean.TRUE, Map.of()); MapString, Double customScore reranker.rerankSync( Hello, List.of(bonjour), greeting in french, Map.of());示例程序会分别打印默认指令与自定义指令下的分数并输出两者之差default... custom... delta...见 ChatRerankerExample.java#L57-L67直观展示自定义指令对相关度判断的影响。4.1 运行方式示例运行说明见 examples/retrieval/README.md简要流程为在仓库根目录编译并生成 classpathmvn -DskipTests compile mvn dependency:build-classpath -Dmdep.outputFiletarget/retrieval_examples.classpath运行ChatRerankerExample并用 JVM 参数覆盖配置java -DCHAT_RERANKER_YES_NO_IDS9454,2753 -cp target/classes;examples;examples/retrieval;$(Get-Content target/retrieval_examples.classpath -Raw) ChatRerankerExample相关覆盖项包括CHAT_RERANKER_MODEL、CHAT_RERANKER_API_BASE、CHAT_RERANKER_API_KEY与必填的CHAT_RERANKER_YES_NO_IDS未设置后者时示例会提示配置错误并直接退出。五、兼容性探测为什么需要 testCompatibilitytestCompatibility()ChatReranker.java#L100-L111是 chat 重排接入前的重要试金石它用(test, [test])发起一次最小请求若成功则说明服务支持 logprobs返回true若抛异常则记录The selected service does not support chat-completion-based reranking并返回false。由于 yes/no 打分强依赖choices[0].logprobs.content[0].top_logprobs服务端若关闭 logprobs 或返回结构不符合 OpenAI 兼容格式parseResponse会抛出RETRIEVAL_RERANKER_REQUEST_CALL_FAILEDthe service does not support logprobs for chat reranker to functionChatReranker.java#L138-L143。示例 ChatRerankerExample.java#L41-L46 在正式重排前先执行探测探测失败即中止避免后续逐条请求全部失败。测试 ChatRerankerTest.java#L187-L193 与 ChatRerankerPythonParityTest.java#L299-L313 分别覆盖了成功与失败两条路径。六、实现与测试佐证本功能的测试覆盖非常完整可以作为理解实现细节的活文档ChatRerankerTest.java校验 yes_no_ids 缺失异常、请求参数与 extraBody 合并、输入校验、logprobs 解析、端点地址与额外请求头ChatRerankerPythonParityTest.java逐条对齐 Python 版TestChatReranker的用例覆盖 token 大小写、前缀匹配、非整数 id、零概率场景、异步rerank与同步rerankSync、兼容性探测等基类抽象与文档模型Reranker.java、Document.java。关于异步与线程模型rerank异步方法通过CompletableFuture.supplyAsync(..., IO_EXECUTOR)执行IO_EXECUTOR是一个由OpenJiuwenExecutors.newBoundedModulePool(chat-reranker-io, true)创建的有界模块线程池ChatReranker.java#L40-L42。由于每个候选一次请求、批量候选需多次请求在需要重排大量候选时建议使用异步接口并发提交并留意线程池容量。七、适用场景与注意事项适用场景当你的部署环境只有 chat completion 端点例如未部署 vLLM 专用 rerank 服务、或模型本身没有 rerank 头且服务端支持 logprobs 返回时ChatReranker可以零额外服务地提供重排能力适合 RAG 检索后的粗排/精排、答案候选筛选等场景。注意事项yes_no_ids必须配置且恰好两个 token id否则构造直接抛异常每个候选一次请求批量重排会产生 N 次模型调用存在明显的成本与延迟放大需按业务量评估服务必须支持logprobstrue且返回top_logprobs结构接入前务必先跑testCompatibility()temperature、top_p等配置在 chat 请求中会被固定的temperature0覆盖不要依赖它们调节输出源码在构造时打印ChatReranker support is experimental in openJiuwen, you have been warned.警告日志ChatReranker.java#L75当前实现仍标注为实验性能力生产接入前建议结合自身服务验证打分稳定性。结语ChatReranker提供了一条复用 chat completion 实现重排的轻量路径固定端点、yes/no token 打分、单候选逐次请求配合严格的yes_no_ids校验与兼容性探测保证了方案的可用边界清晰可控。结合 StandardReranker 与 RerankerConfig开发者可以在同一检索链路中按服务能力灵活选择重排实现。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐openJiuwen ChatReranker 实战指南基于 Chat Completion logprobs 的智能重排序实现openJiuwen ChatReranker 实战指南基于 Chat Completion logprobs 的智能重排序实现本文档是 openJiu人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 检索重排序Reranker模块完全指南接口设计、三类实现与 ChatReranker 实战openJiuwen agent core 检索重排序Reranker模块完全指南接口设计、三类实现与 ChatReranker 实战本文是 openJ人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习Langchain-Chatchat 重排序模块 LangchainReranker 深度解析基于 CrossEncoder 的知识库相关性排序实现Langchain Chatchat 重排序模块 LangchainReranker 深度解析基于 CrossEncoder 的知识库相关性排序实现 Lang人工智能大模型RAGAI Agent本地部署后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

openJiuwen 的 ChatReranker 实战：基于 Chat Completion Logprobs 的相关性重排

相关推荐

SpringBoot+Vue+MyBatis+MySQL打造知识竞赛管理系统

用AI Agent编排开源手绘技能包，零成本批量做手绘解说视频

QtPropertyBrowser移植实战：Visual Studio下编译DLL并完成跨工程调用

更多资讯

AI影片制作全流程拆解：从分镜脚本到批量渲染的完整工作流

WebSocket抓包分析实战：从协议帧到真实问题排查

C++节点编辑器实战：命令模式、编组与命中检测优化

AI多模态创作：把ADHD抽象感受拆解成可视化视频

基于窗函数反求法的NLFM信号设计与脉压验证

Microsoft Remote Desktop for macOS 深度指南：RDP 协议、ARM64 原生与 macOS 系统集成

今日更新

Cephadm实战指南：Linux系统工程师的生产级Ceph集群部署与排障

不想再被 Token 额度卡脖子？把免费 API 接入 WorkBuddy 的完整教程

ITK中SpatialObject几何体系解析：坐标系、变换与管道集成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？