Cherry Studio ai-core 新增 Rerank 运行时OpenAI 兼容重排模型接入指南【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio导读本文围绕 Cherry Studio 仓库中cherrystudio/ai-core包的 changeset 变更.changeset/aicore-rerank-runtime.md完整解析其引入的 rerank重排序运行时支持包括rerank运行时辅助函数、RerankParams/RerankResult类型、RuntimeExecutor.rerank方法以及面向 OpenAI 兼容服务商的OpenAICompatibleRerankingModel提供者模型含createOpenAICompatibleRerankingModel及其配置/设置类型。读完本文你将掌握如何在 Cherry Studio 的 ai-core 运行时中调用重排模型、理解底层请求/响应协议与校验规则以及 Provider 扩展如何把重排能力挂载到统一运行时上。该功能在项目中主要用于 RAG检索增强生成场景下对候选文档进行二次精排也服务于知识库检索结果的排序优化。变更概览一次 patch 级别的运行时能力扩充该 changeset 声明对cherrystudio/ai-core包的影响级别为patch核心内容是Add rerank runtime support. Exposes arerankruntime helper (plusRerankParams/RerankResulttypes andRuntimeExecutor.rerank) and anOpenAICompatibleRerankingModelprovider model (withcreateOpenAICompatibleRerankingModeland its config/settings types) so OpenAI-compatible providers can serve reranking through the standard runtime.由此可归纳出本次变更交付的两大能力面运行时Runtime层新增rerank辅助函数与RuntimeExecutor.rerank方法并配套RerankParams/RerankResult类型使重排调用与既有的streamText、generateText、generateImage、embedMany等能力并列统一走 ai-core 的运行时管线。提供者模型Provider Model层新增 OpenAI 兼容的OpenAICompatibleRerankingModel及工厂函数createOpenAICompatibleRerankingModel让任何遵循 OpenAI 兼容协议的服务商如 Jina、Cohere 等提供/rerank端点的服务都能通过标准运行时对外提供重排能力。Runtime 层rerank 如何接入统一执行器导出链路与公开 APIrerank从 ai-core 包顶部即作为一等公民导出packages/aiCore/src/index.ts 从./core/runtime导出rerank函数以及RerankParams、RerankResult等类型packages/aiCore/src/core/runtime/index.ts 提供顶层rerank(providerId, options, params, plugins?)便捷函数内部先经extensionRegistry创建对应 provider 的RuntimeExecutor再委托给executor.rerank(params)packages/aiCore/src/core/runtime/types.ts 定义了RerankParams与RerankResult类型。RerankParams的定义要点见 types.tsexport type RerankParamsVALUE extends JSONObject | string string Omit Parameterstypeof rerankVALUE[0], model { model: string | RerankingModelV3 onProviderCall?: RuntimeProviderCallHandler }关键设计泛型VALUE默认为string也可为JSONObject对应 AI SDKrerank的输入文档类型model字段支持字符串模型 ID或预创建的RerankingModelV3实例两种形态字符串 ID 会通过 RuntimeExecutor 的 provider 注册表解析额外提供onProviderCall?: RuntimeProviderCallHandler观测回调用于采集重排调用的运行时指标。RuntimeExecutor.rerank 的实现核心实现在 packages/aiCore/src/core/runtime/executor.tsasync rerankVALUE extends JSONObject | string string(params: RerankParamsVALUE): PromiseRerankResultVALUE { const { model: modelOrId, onProviderCall, ...options } params const rerankingModel typeof modelOrId string ? this.registry.rerankingModel(${this.config.providerId}:${modelOrId} as ${string}:${string}) : modelOrId const startedAt performance.now() const result await _rerankVALUE({ model: rerankingModel, ...options }) emitProviderCall(onProviderCall, { modality: rerank, requestId: ai-core:rerank:${crypto.randomUUID()}, providerId: this.config.providerId, modelId: rerankingModel.modelId, metrics: { timeCompletionMs: Math.max(0, Math.round(performance.now() - startedAt)) }, completedAt: Date.now() }) return result }其行为要点字符串模型 ID 解析RuntimeExecutor内部通过createProviderRegistry构建了以providerId为键的 provider 注册表见 executor.ts此处以${providerId}:${modelId}的形式调用registry.rerankingModel(...)与embedMany的字符串解析路径完全对齐预创建模型直通若调用方直接传入RerankingModelV3实例则跳过注册表直接委托给 AI SDK 的_rerank可观测性重排完成无论成功与否都通过 best-effort 方式触发后向onProviderCall发出modality: rerank事件携带providerId、modelId、timeCompletionMs、completedAt与requestId。事件类型定义见 types.ts其emitProviderCall的容错逻辑异常不影响 AI 结果见 executor.ts。典型调用示例import { createExecutor, rerank } from cherrystudio/ai-core // 方式一顶层便捷函数自动创建 executor const result await rerank(openai-compatible, { apiKey: YOUR_API_KEY, baseURL: https://api.example.com/v1, name: my-reranker-provider }, { model: jina-reranker-v2-base-multilingual, query: 什么是重排序模型, documents: [候选文档A……, 候选文档B……, 候选文档C……], topN: 2, maxRetries: 0, headers: { x-custom: value }, providerOptions: { jina: { returnDocuments: false } }, onProviderCall: (event) console.log(event.metrics.timeCompletionMs) }) console.log(result.rerankedDocuments) // 按相关性降序的文档数组 console.log(result.ranking) // [{ originalIndex, score, document }]参数说明对应 AI SDKrerank的标准参数均可透传参数说明取值/默认model模型 ID 字符串或RerankingModelV3实例必填query查询文本必填documents待排序文档数组string[]或JSONObject[]必填topN返回前 N 个结果可选由服务端决定headers附加请求头可选maxRetries最大重试次数可选默认由 AI SDK 决定providerOptions服务商特定选项可选abortSignal中止信号可选onProviderCallai-core 扩展的观测回调可选Provider 模型层OpenAICompatibleRerankingModel工厂函数与类型createOpenAICompatibleRerankingModel(modelId, settings)及配套类型定义在 packages/ai-sdk-provider/src/openai-compatible-reranking-model.ts并经由 packages/aiCore/src/core/providers/openaiCompatible/rerankingModel.ts 从cherrystudio/ai-sdk-provider原样再导出供 ai-core 内部统一引用。OpenAICompatibleRerankingModelSettings从OpenAICompatibleProviderSettings中挑选了与重排最相关的字段见 openai-compatible-reranking-model.ts设置项作用name提供者名称用于生成 provider 标识见下文baseURL服务端基础地址必填缺省会直接抛错apiKey密钥存在时以Authorization: Bearer apiKey发送headers自定义请求头与上述 Authorization 合并queryParams附加到 URL 的查询参数fetch自定义 fetch 实现可用于代理、日志等OpenAICompatibleRerankingModelConfig则是模型实例的底层配置provider 标识、URL 构造器、header 工厂、fetch由工厂函数内部生成通常无需调用方直接构造。doRerank请求与响应协议模型实现RerankingModelV3specificationVersion v3核心逻辑位于doRerank见 openai-compatible-reranking-model.ts输入约束仅接受documents.type text的文本文档否则抛出 OpenAI-compatible reranking model only supports text documents请求构造POST 到url({ path: /rerank, modelId })请求体为{ model: modelId, query: query, documents: [doc1, doc2], top_n: 2 }响应解析期望响应体形如{ results: [{ index: 0, relevance_score: 0.9 }, ...] }由parseRerankResponse转换为{ index, relevanceScore }数组。响应校验规则parseRerankResponse见 openai-compatible-rerank-model.ts对服务端响应做了严格校验任何不满足都会抛错响应必须包含results数组每个results元素必须是对象index与relevance_score必须是数字index必须是非负整数且小于本次请求的文档总数documentCount防止越界引用。这些校验保证了上游服务返回脏数据时不会静默污染下游排序结果。provider 标识与 URL 细节工厂函数createOpenAICompatibleRerankingModel见 openai-compatible-reranking-model.ts还有两个值得注意的实现细节provider 标识固定为${settings.name}.rerank因此来自openai-compatible提供者的重排模型其 provider 为openai-compatible.rerank测试用例也对此做了断言见 rerankingModel.test.tsbaseURL 归一化先经withoutTrailingSlash去掉末尾斜杠再拼接/rerank路径随后应用queryParams若baseURL缺失则直接抛错 OpenAI-compatible reranking model requires baseURL。与 Provider 扩展体系的集成重排能力并非孤立存在而是通过 ai-core 的ProviderExtension体系自动挂载到每个 OpenAI 兼容 provider 上ProviderExtension.ts 的扩展配置新增可选钩子createRerankingModel?: (modelId, settings) RerankingModelV3在创建 provider 的_doCreateProvider流程中基座 provider 与 variant 变换后的最终 provider 都会调用attachRerankingModel见 ProviderExtension.tsattachRerankingModel的语义是仅在createRerankingModel已配置且目标 provider 尚未原生暴露rerankingModel时才为其补挂provider.rerankingModel (modelId) createRerankingModel(modelId, settings)。也就是说如果某个 SDK 自身已提供原生重排模型则不会覆盖。对于openai-compatible扩展钩子实现在 initialization.ts其内部使用createLazyOpenAICompatibleRerankingModel该函数返回一个 v3 占位模型见 initialization.tsdoRerank首次被调用时才通过动态import(../openaiCompatible/rerankingModel)惰性加载真实实现避免在未使用重排时拉入额外代码同时它再次校验baseURL确保配置完整性。这意味着只要通过 ai-core 的扩展机制创建 OpenAI 兼容 providerRuntimeExecutor.rerank中providerId:modelId的字符串解析路径即可直接工作无需调用方手动装配模型。测试验证三条关键路径均有覆盖仓库为本次变更提供了完整的测试佐证字符串模型 ID 经provider.rerankingModel解析测试resolves a string model id through provider.rerankingModel见 packages/aiCore/src/core/runtime/tests/rerank.test.ts断言mockProvider.rerankingModel收到模型 ID且 AI SDKrerank收到解析后的模型实例与完整参数query、documents、topN、headers、maxRetries、providerOptions、abortSignal预创建模型直通测试accepts a pre-created reranking model见 rerank.test.ts确认传入RerankingModelV3实例时不会再次触发 provider 的rerankingModel工厂注册表路径测试resolves CherryIN rerank models through the provider registry见 rerank.test.ts验证了通过createExecutor(cherryin, { endpointType: jina-rerank })创建的执行器能正确解析BAAI/bge-reranker-v2-m3(free)这类模型 ID生成provider: cherryin.rerank的模型实例。此外createOpenAICompatibleRerankingModel的再导出行为也有专门测试覆盖见 packages/aiCore/src/core/providers/openaiCompatible/tests/rerankingModel.test.ts。使用前提与注意事项服务端协议要求目标服务商必须提供 OpenAI 兼容的POST {baseURL}/rerank端点并返回results: [{ index, relevance_score }]结构同时要求index为文档数组内的合法下标输入类型限制当前实现仅支持文本文档documents.type text传入其他类型如图像会抛错baseURL 是硬性要求createOpenAICompatibleRerankingModel与扩展钩子都会在缺少baseURL时抛错事件观测为 best-effortonProviderCall回调内的异常会被静默吞掉不会影响重排结果本身AI SDK 版本前提类型定义明确基于 AI SDK v6types.ts中注释 AI SDK v6 only has embedMany, no embedrerank运行时包装的也是该版本 SDK 的rerank函数。小结aicore-rerank-runtime这一变更让 Cherry Studio 的 ai-core 包在streamText、generateImage、embedMany之外补齐了第四种运行时能力——重排序。它既提供了对调用方友好的rerank辅助函数与类型安全的RerankParams/RerankResult又通过ProviderExtension.createRerankingModel钩子 懒加载占位模型让任意 OpenAI 兼容服务商的/rerank端点零成本接入统一运行时并全程附带可观测指标与严格的响应校验。对于知识库、RAG 流水线或任何需要先召回、后精排的检索场景这一能力可直接复用 ai-core 既有的 provider 注册表与插件管线是值得优先采用的统一入口。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考