说明

推荐助手接口基于 Recommend 推荐接口已返回的物品及其召回信息，结合用户画像与控制台配置的角色 Prompt（助手身份 / 回答风格 / 追问倾向），由大模型流式生成整批推荐的理由分析，并返回 3 条递进式追问问题。

接口为 SSE（Server-Sent Events）流式接口，正文分片逐段推送，终端可逐字渲染。

推荐助手不新增物品、不重新排序，只解释请求中传入的物品；物品来源、顺序以 Recommend 接口返回为准。

典型调用时序

先调用 Recommend 接口获取推荐物品并渲染推荐商品卡片（毫秒级）

再异步调用本接口流式获取分析与追问（秒级）

用户点击追问时调用 ChatSearch 对话接口

注意事项

使用限制：

受到 HTTP Body 大小限制，单次请求的包体大小最大不超过 10MB。

context.items 建议直接透传 Recommend 接口本次返回的推荐物品，单次最多处理 400 个物品，超出部分不参与分析。

本接口只解释传入的物品，不会召回新物品，也不会改变物品顺序。

依赖要求：

调用前须先在控制台完成推荐场景创建并开启「触发推荐助手」。

context.items._id 必须是物品数据集中存在的物品 ID，且与 Recommend 接口返回一致。

每个物品的 rec_info 可直接透传 Recommend 接口返回的 rec_info（召回通道 + 推荐原因）。

计费：按次对话计费，模型开始流式输出即计 1 次对话；限流、超时导致未实际生成内容时不扣费，详见「计费说明」。

请求说明

请求方式：POST

请求地址

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

请求头

头部	值	说明
Content-Type	application/json	请求体为 JSON。
Authorization	Bearer {API Key}	鉴权信息

鉴权方式

可使用 API Key 或 Access Key 鉴权，详情参考 API鉴权机制说明。

Path 参数

参数	数据类型	是否必选	示例值	描述
application_id	String	必选	76414365027	在控制台创建应用后，系统指定的应用唯一标识，可在控制台查看。
scene_id	String	必选	scene-R01asDfs	推荐场景唯一标识，以 scene- 开头，在控制台推荐策略页查看。角色配置（助手身份 / 回答风格 / 追问倾向）与开关均按该场景读取。

请求参数

请求体

参数	数据类型	是否必选	描述
user	Object<User>	必选	用户信息，用于获取用户画像并标识本次调用归属。
context	Object<RecReasonContext>	必选	单次请求上下文，包含本次推荐物品及召回信息，会与控制台的助手角色配置合并使用。

数据结构

User

参数	数据类型	是否必选	示例值	描述
_user_id	String	必选	"user_199432"	用户唯一标识。用户画像（兴趣标签、历史行为摘要）依据该 ID 获取；未登录用户可在保证全局唯一的前提下使用虚拟用户 ID。

RecReasonContext

参数	数据类型	是否必选	描述
items	Array<RecReasonItem>	必选	本次推荐的物品列表，建议直接透传 Recommend 接口返回的 rec_results（携带各物品的 rec_info）。单次最多 400 个。
additional_context	String	非必选	业务方给助手的额外单次上下文，例如当前频道、活动主题、营销口径等；仅对本次请求生效。内容须遵守业务合规要求，助手不会据此引入物品之外的事实。

RecReasonItem

参数	数据类型	是否必选	示例值	描述
_id	String	必选	"688930"	物品唯一标识，须与 Recommend 接口返回的 _id 一致，且存在于物品数据集中。
rec_info	Array<RecallReason>	必选	见下	推荐信息列表（该物品命中的召回通道及对应推荐原因），可直接透传 Recommend 接口返回值。

RecallReason

参数	数据类型	是否必选	示例值	描述
recall_channel	String	必选	"hot_item"	召回通道标识，取值与 Recommend 接口一致，如 hot_item（高热）、user_profile（用户画像）、multimodal（多模态）、item_cf（相似用户）、item_similarity（父商品/物品相似度）、cold_start（物品冷启动）。
reason	String	必选	"近期热门 Top 3"	该召回通道对应的单物品推荐原因文案（模板模式生成），作为大模型分析的事实输入。

响应说明

响应为 SSE 事件流，每个事件为一行 data: {JSON 载荷}（本文示例中省略 data: 前缀），载荷统一携带 request_id，按以下顺序推送：

顺序	事件	载荷特征	说明
1	会话初始化	result.payload.rec_reason.session_id	返回会话 ID，用于后续排查和追问
2	开始答复	result.step_info.step = "reply"	标记正文开始生成。
3	正文流式分片	result.content 非空	大模型生成的推荐理由分析，逐 token 推送，客户端按到达顺序拼接即可。
4	追问建议	result.payload.suggestions	推荐追问问题数组，正常返回 3 条（按品类/场景 → 具体属性 → 对比/决策递进）；降级场景仅返回 1 条通用追问。
5	结束标记	result.stop_reason = "stop"	标记本次答复完成；随后服务端关闭流。

响应参数

参数	类型	描述
request_id	String	请求 ID，全链路唯一标识，用于问题排查。
result	Object	答复内容载体，不同事件携带的字段不同。
result.step_info	Object	答复步骤信息。
result.step_info.step	String	答复步骤：reply（开始/正在答复正文）、stop（答复完成）。
result.content	String	答复正文的流式分片，按到达顺序拼接为完整分析；可能包含内联物品引用标记 <ref>_id</ref>。降级 / 风控场景下为对应兜底文案。
result.payload	Object	扩展载荷。
result.payload.rec_reason	Object	推荐助手会话信息（会话初始化事件返回）。
result.payload.rec_reason.session_id	String	会话 ID，可在 ChatSearch 对话接口中传入以延续本次推荐上下文进行追问。
result.payload.suggestions	Array<String>	推荐追问问题列表。正常 3 条、降级 1 条；问题文本不包含引用标记。
result.stop_reason	String	结束标记，答复完成时为 "stop"。

接口示例

请求示例

响应示例

按事件顺序接收到的数据流，示例为便于阅读分行展示，实际每个事件为一个行）：

客户端处理建议：

维护一个字符串缓冲区，将所有 content 分片按到达顺序拼接后渲染；

收到 suggestions 后渲染为可点击的追问按钮；收到 stop_reason=stop 后结束 loading 状态；

推荐追问（对接对话接口）

用户点击追问问题后，调用 ChatSearch 对话接口完成多轮对话：

POST /api/v1/application/{application_id}/chat_search

推荐追问在 ChatSearch 原有请求体上扩展以下参数；

扩展请求参数

参数	数据类型	是否必选	描述
query	String	必选	用户点击的追问问题文本（字段沿用 ChatSearch 既有定义）。
is_recommend	Boolean	非必选	固定传 true，标识本次为推荐追问：跳过搜索召回，使用 items 构建上下文。当 is_recommend=true 时，对话接口跳过搜索召回，直接以传入的推荐物品作为引用源构建上下文，回答始终围绕本批推荐物品展开。
dataset_id	String	必选	推荐物品所属物品数据集 ID，用于获取物品详情信息。
items	Array<ChatSearchRecommendItem>	非必选	本次推荐的物品列表（同 rec_reason 入参的物品），携带各召回通道推荐原因。

ChatSearchRecommendItem

参数	数据类型	是否必选	描述
_id	String	必选	物品 ID，示例："WSHOE001"。
rec_info	Array<RecallReason>	必选	推荐信息列表，结构同上文 RecallReason（recall_channel + reason）。

请求示例

计费说明

计费模式：按次对话计费，不按 Token 对外计费。

计费时点：模型开始流式输出（首个正文分片返回）即计为 1 次对话；请求结束时统一上报。

不计费情形：开关关闭、配额预校验失败、模型限流、超时等导致模型未实际生成内容的请求。

错误码

通用错误码请参见公共错误码文档。

Viking AI 搜索