文档中心

Viking AI 搜索

推荐接口

Rerank - 精排接口

说明

此接口为开白能力，若需要使用，请联系火山技术支持或您的客户经理开通。若想要在推荐请求内自带召回物品，请参考 InputItems。

概述

精排接口（Rerank API）是一个独立的排序能力接口，允许您传入自定义的物品列表，利用系统的精排模型对物品进行排序打分。该接口适用于以下场景：

您已有自己的召回候选池，希望借助平台精排模型进行排序

需要将平台作为纯粹的"排序服务"使用

希望对指定物品集合获取个性化排序分数

精排接口将根据用户与物品的特征，返回每个物品的排序分数，并支持可选的提降权规则和打散规则。

接口信息

请求方式：POST

请求接口：

服务	区域	URL
火山引擎	华北(北京)	https://aisearch.cn-beijing.volces.com/api/v1/application/{application_id}/{scene_id}/rerank
火山引擎	东南亚(柔佛)	https://aisearch.ap-southeast-1.volces.com/api/v1/application/{application_id}/{scene_id}/rerank
BytePlus	东南亚(柔佛)	https://aisearch.ap-southeast-1.bytepluses.com/api/v1/application/{application_id}/{scene_id}/rerank

鉴权方式：Bearer Token（通过 Authorization Header 传递 API Key）

Content-Type： application/json

路径参数

参数	类型	必填	说明
application_id	String	是	应用 ID
scene_id	String	是	场景 ID

请求参数

参数	类型	必填	默认值	说明
event_scene	String	是	—	触发推荐的场景界面。传入值应该在产品界面精排场景配置选项中。
items	Object	是	—	物品列表对象
items.items	Array<Object>	是	—	物品数组，每个元素包含物品 ID。上限 400 个
items.items._id	String	是	—	物品 ID，需为已导入系统正排表中的有效 ID
user	Object	是	—	用户信息对象
user._user_id	String	是	—	用户 ID，用于个性化排序
page_size	Int	否	输入的 item 数量	返回物品数量，建议不大于 400。最少 1。
output_fields	Array<String>	否	返回所有字段	指定返回的物品字段列表（如 item_id、title、category 等）
strategy_switch	Object	否	—	策略开关配置
strategy_switch.enable_boost_bury_rule	Boolean	否	false	是否启用提降权规则。启用后，返回的 score 将包含提降权的影响
strategy_switch.enable_diversity_rule	Boolean	否	false	是否启用打散规则
strategy_switch.enable_forced_item	Boolean	否	true	是否启用置顶规则。启用后，如果场景配置了置顶物品，会返回配置的置顶物品。
session_id	String	否	—	用户单次访问的唯一标识建议自定义并确保在一个访问中唯一，例如使用 UUID。了解更多，请查看：置顶推荐物品当推荐场景生效了置顶物品配置并且关闭了「每次刷新时重复推荐」时，平台通过 session_id 判断置顶配置在 24 小时内是否已经针对某次访问生效过。若未提供此参数，24小时内相同访问会出现重复置顶的情况。

返回参数

参数	类型	说明
request_id	String	本次请求唯一标识，用于问题排查
results	Object	返回结果对象
results.rec_results	Array<Object>	排序后的物品列表，按 score 降序排列
results.rec_results._id	String	物品 ID
results.rec_results.display_fields	Object	根据 output_fields 指定返回的物品字段
results.rec_results.score	Float	精排分数（若启用 enable_boost_bury_rule，则包含提降权影响）
extra_info	Object	请求处理额外信息用于查看推荐请求处理逻辑，协助了解和排查配置的合法性和推荐处理逻辑是否符合业务诉求。
extra_info.forced_item_info	Object	置顶物品处理逻辑当推荐场景配置生效了置顶推荐物品配置，参数会返回置顶物品 ID 和生效状态，以便检查是否符合预期。
extra_info.forced_item_info.item_ids	Array<String>	成功置顶的物品 ID 如果物品 ID 不在物品数据集内，平台自动去除物品。
extra_info.forced_item_info.skipped	Boolean	置顶生效状态 session_id 参数配置，请查看：请求体 true ：session_id已在24小时内出现，置顶不生效 false：session_id未在24小时内出现，置顶生效。

请求示例

基础请求

返回示例

错误处理

本接口错误码，请参见公共错误码。

常见问题（FAQ）

Q：单次请求最多支持多少个物品？

A：单次请求上限为 400 个物品。如果物品数量超过 400，请分批调用接口并合并结果。

Q：传入的物品 ID 不存在会怎样？

A：如果传入的 _id 不在系统正排表中，该物品将不会出现在返回结果中，不会报错。

Q：精排接口会触发曝光去重或下发去重吗？

A：不会。精排接口不参与过滤规则、曝光去重、下发去重，返回物品也不会更新到下发去重表中。

Q：启用提降权规则后，score 有什么变化？

A：当 enable_boost_bury_rule 设为 true 时，返回的 score 将包含精排分数和提降权规则的综合影响。

Q：精排接口和推荐接口有什么区别？

A：推荐接口包含完整的召回 → 精排 → 重排链路；精排接口仅提供排序能力，需要您自行传入候选物品列表，系统仅做排序打分。

最近更新时间：2026.08.09 01:07:02

这个页面对您有帮助吗？

有用

无用