说明

Viking AI 搜索是一款基于生成式 AI 的企业级 AI 搜索产品，基于大模型的多模态语义表征和理解能力，结合字节跳动信息检索领域多年最佳实践，为客户提供开箱即用的 AI 搜索搭建平台服务，帮助客户轻松搭建和集成端到端的多模态图文搜索和推荐能力。

*

想要体验更多 Viking AI 搜索能力，点击前往：Viking AI 搜索引擎，企业搜推问一体化智能引擎

根据聊天内容，动态处理闲聊，拒答，搜索等意图，再给出合适的用户回复的同时，动态地调用搜索功能并返回搜索到的物品数据。使用对话搜索功能时，您需要自行维护会话session的唯一标识，每次调用可上传session_id： * 上传一个新session_id：默认开启一次新的会话 * 上传已有的session_id：系统自动获取会话历史，并在历史上下文的基础上继续处理用户query # 注意事项 * **使用限制：** * 受到HTTP Body大小限制，单次请求的包体大小最大不超过10MB。 * **返回格式** * 对话接口以流式格式返回，客户端自主实现API调用时需要使用流式方式解析响应。 # 请求地址 * 请求方式：POST * 请求地址： |**服务** |**区域** |**URL** | |---|---|---| |火山引擎 |华北(北京) |`https://aisearch.cn-beijing.volces.com/api/v1/application/{application_id}/chat_search` | |火山引擎 |东南亚(柔佛) |`https://aisearch.ap-southeast-1.volces.com/api/v1/application/{application_id}/chat_search` | |BytePlus |东南亚(柔佛) |`https://aisearch.ap-southeast-1.bytepluses.com/api/v1/application/{application_id}/chat_search` | `{application_id}`：在控制台创建应用后系统指定的应用唯一标识，可在控制台查看 # 鉴权方式可使用API Key或Access Key鉴权，详情参考[API 鉴权机制说明](https://www.volcengine.com/docs/85296/1544950) # 发起对话请求 ## 直接开始对话 **session_id ** `String` `必需` 一次会话的唯一标识，用于关联用户在此次聊天的历史记忆。当启动一次新的对话时，需传入一个新的session_id。 **input_message ** `Object` `必需` 传入session下本轮对话的用户输入： * **content ** `List [Object]` `必需` 用户输入的图片或文本对话信息，可传入多个图片、文本内容元素，包含以下参数： * **type** `String` `必需` 一个内容元素的类型，可传入枚举值： * "text"：该元素为文本信息 * "image_url"：该元素为图片 * **text** `String` `内容元素是文本时必须传入` 内容元素为文本时，使用字符串传入用户输入 * **image_url** `Object` `内容元素是图片时必须传入` 传入图片内容 * **url ** `String` `必需` 内容元素为图时，使用base64编码字符串上传图像文件（支持位图格式） **user** `Object` 传入本次对话的用户信息（目前支持用户的ID和昵称）。建议上传，对话中的用户交互将作为个性化的记忆保存在用户画像，对话中反映的用户偏好将作为个性化推荐的依据。 * **_user_id** `String` 用户的唯一标识 * **nickname** `String` 用户昵称，可用于在对话启动输出欢迎语时 **enable_suggestions ** `Boolean` 是否在对话生成最后输出建议的后续提问。 `true` : 开启建议提问 `false`：不开启建议提问，默认为`false` **reply_mode ** `String` 选择的回复模式，用于控制本次对话所使用的底层模型，在回复效果与响应速度之间进行权衡。可传入枚举值： `balanced`：均衡模式。使用效果更好的模型，检索准确性和回复生成质量更高，响应速度相对较慢。 `fast`：快速模式。使用速度更快的模型，响应延迟更低，但检索准确性和生成效果弱于均衡模式。不传时，默认为 "balanced"。 **opening_remarks** `Boolean` 是否在启动对话时触发欢迎语。 `true: `开启。开启时遵循控制台的“对话启动配置”，可在配置了启动时推荐时开启欢迎语并展示推荐内容，未配置推荐时展示您定义的欢迎语内容。 `false：`不开启。默认为 `false` 使用方法详见：[启动对话时进行欢迎](https://docs.volcengine.com/docs/85296/1873492#68777956) **search_param ** `Object` 指定本次对话中搜索数据集内容时的限定数据集范围、过滤条件等搜索参数 * **page_size** `Integer` 触发搜索时，在对话中返回内容的数量，不传默认为 30，最小为 1 * **dataset_ids** `List[String]` 当应用关联了多个数据集搜索，可限定对话的搜索数据集范围，传入可在对话中被搜索的`数据集ID`列表，以String传入，例如["0999281902","099281972"]。不传默认可搜索所有关联至应用的数据集 * **filters ** `Map < dataset id, filter object>` 在对话中触发搜索数据集内容时，限定搜索的过滤条件，以map传入，key为数据集ID字符串，值为过滤表达式对象。如示例所示： ```JSON "filters":{ "0999281902":{ "op":"must", "field":"parent_content_id", "conds":[""] } } ``` 更多示例详见：[在搜索时过滤](https://docs.volcengine.com/docs/85296/1873488) * **output_fields** `Object` 指定物品数据集数据中的哪些字段在接口中返回展示（在搜索工具的返回结果、对话结束后返回相关物品列表related_items）传入的内容为一个Map对象。 * key：数据源ID (String) * value：该数据源需要返回的字段列表 (Array) 没有在output_fields中指定的数据集，默认返回所有字段；如果不传此参数则默认所有数据集中的数据都返回所有字段。如果数据集中存在嵌套的对象(Object)，则只支持传入上层的字段名。传入不存在的字段或Object内层的字段会被忽略。示例： ```JSON "output_fields":{ "10299201": ["product_code", "product_name", "description"], "10299202": ["content_id", "title", "keywords", "summary"] } ``` **context ** `Object` 传入本次请求的用户环境上下文信息，当前支持上传用户地理位置 * **location** `Object` 用户的地理位置信息，包含经度和纬度。如果您在推荐和搜索中配置了地理位置提权降权，在对话中调用搜索、推荐工具将会生效策略。 * **latitude** `String` 纬度，支持上传字符串格式的数据，如"12.291"，字符串内容必须是一个[\-90,90]之间的数字 * **longitude** String 经度，支持上传字符串格式的数据，如"30.218"，字符串内容必须是一个[\-180,180]之间的数字 **Session启动：** ```Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/${application_id}/chat_search' \ -H 'Content-Type: application/json' \ -H 'Authorization:Bearer ' \ -d '{ "session_id": "25ee998a-5462-9385-9f18-035f1da7a6e5", "user": { "_user_id": "ldy_199432" }, "opening_remarks":true }' ``` **用户传入对话内容** ```Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/${application_id}/chat_search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "session_id": "25ee998a-5462-9385-9f18-035f1da7a6e5", "input_message": { "content":[{"type":"text", "text":"有哪些好看的国产科幻片？"}] }, "user": { "_user_id": "ldy_199432", "nickname":"小A" }, "enable_suggestions": true, "reply_mode": "balanced", "search_param": { "page_size": 30, "dataset_ids": ["111111104"], "filters": { "106265704": { "op": "must", "field": "parent_content_id", "conds": [""] } }, "output_fields": { "10299201": ["product_code", "product_name", "description"], "10299202": ["content_id", "title", "keywords", "summary"] } }, "context": { "location": { "longitude": "-12.299", "latitude": "-10.019" } } }' ``` ## 启动对话时进行欢迎启动对话时可使用 **opening_remarks ** 参数控制是否进行主动的欢迎。开启了此参数后，可根据控制台的配置实现2种交互： * **启动时推荐物品：** 在对话搜索配置中，配置启动时推荐物品，并关联了生效的推荐场景。 * **启动时进行欢迎语：** 在对话搜索配置中，不配置启动时推荐物品，此时自动进行欢迎语的输出。在`opening _remarks`设置为` true`时，请确保`session_id`为一个新的值，且不要传入`input_message`和`search_param`。 ## 对话中上传图片 **Query上传图片格式说明：** 在query.image_url中传入base64格式的图片文件，图片文件的格式和条件限制详见说明：

说明

传入图片需要满足以下条件：

支持格式：jpeg、png、 webp、bmp、tiff、ico、dib、icns、sgi、jpeg2000。其中，tiff、sgi、icns、jpeg2000 格式图片，需要保证和元数据对齐，如在对象存储中正确设置文件元数据，否则会解析失败。

宽高比（宽/高）：在范围[1/100, 100] 。

边长： [10, 6000] px，即短边像素需大于 10 px，长边像素需小于6000 px。

请确保Base64编码符合标准格式，包含**数据头（Data URI Scheme）** 与 **Base64 编码正文**两部分： ```Plain Text data:[];base64, ``` |**组成部分** |**格式要求** |**说明** |**示例** | |---|---|---|---| |**数据头前缀** |固定为 `data:` |标识该字符串为 Data URI 格式，不可省略或修改 |\- | |**MIME 类型** |需与图片实际格式严格匹配 |用于服务端识别图片类型，禁止随意填写（如 JPG 图填 PNG 的 MIME） |JPG/JPEG：`image/jpeg`；PNG：`image/png`；WebP：`image/webp` | |**分隔符** |固定为 `;base64,` |连接 MIME 类型与 Base64 编码正文，分号、“base64”、逗号均不可省略或替换 |\- | |**Base64 编码正文** |符合 RFC 4648 标准的 Base64 编码字符串 |由图片文件二进制数据直接编码生成，**禁止包含空格、换行符、特殊字符**，需为连续的 ASCII 字符串 | | ## 使用过滤在对话中传入的过滤条件会透传到对话中调用搜索工具的流程，意味着用户在对话中只能针对部分符合条件的数据集物品进行过滤。与搜索不同，当对话引用了多个数据集时，您需要对多个数据集进行过滤。filter参数传入的是一个Map JSON结构，key为数据集ID（String），值为对数据集中数据的过滤条件。过滤条件的写法见：[在搜索时过滤](https://docs.volcengine.com/docs/85296/1873488) # 流式返回 ## 流式返回整体步骤 Chat_search接口的返回采用流式输出，接口调用后，输出流程如下：

调用接口后，对话式搜索agent会经过一系列思考、判断、工具调用流程，最终执行大模型回复的输出。在回复输出之前所有步骤都会返回步骤的事件和中间过程输出，供您去监控输出流程，或在您的界面显示中间处理过程的交互。 ## 接收对话开场内容若在接口中传入了新的session_id，且将`opening _remarks`设置为` true`，则会触发欢迎语+在启动时个性化推荐一批内容（若控制台配置）。 ### 仅返回欢迎语时仅返回欢迎语时，流式返回欢迎语内容 **输出参数：** **request_id ** `String` 此次请求的唯一请求标识 **result ** `Object` 流式返回的顶层结构 * **content** `String` 流式输出的欢迎语内容 **返回示例：** ```JSON { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "#"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": " 🎬"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": " Hi"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "，"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "下午"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "好"} } ... ... { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": { "stop_reason": "stop" } } ``` 返回欢迎语后，立即返回推荐问题： **输出参数** **request_id ** `String` 此次请求的唯一请求标识 **result ** `Object` 流式返回的顶层结构 * **payload** `Object` 批式一次性输出的内容 * **suggestions** `List[String]` 欢迎阶段“猜你想搜”问题列表，按控制台配置的最大返回数量返回一个问题列表 ```JSON { "request_id": "fc627693-cc53-4903-8de6-9a49a51f4e05", "result": { "payload": { "suggestions": [ "监听耳机有哪些流行颜色可选？", "游戏耳机有哪些颜色可选？", "苹果的监听耳机靠谱吗？", "耳机保修一般是多长时间？", "续航5小时耳机适合啥场合？", "有防抖功能的微单推荐吗？", "微单相机的保修政策一般是怎样的？", "视频新手适合的微单相机？" ] } } } ``` ### 返回欢迎语+推荐列表 **步骤1：启动时调用个性化推荐工具** 启动对话时开始使用用户ID调用推荐工具，获取个性化推荐列表。 **输出参数：** **request_id ** `String` 此次请求的唯一请求标识 **result ** `Object` 流式返回的顶层结构 * **step_info** `Object` 输出步骤描述结构 * **step ** `Object` 步骤名称，在调用工具时返回: `tool call`：调用推荐工具 `get_results`：获取推荐列表 * **tool_name** `String` Step为 tool call 时返回工具名称，在启动推荐物品时会输出"rec" * **step_payload ** `Object` 随步骤输出的附加信息，如工具调用信息 * **param** Object 调用推荐的场景参数，默认使用控制台配置的首页推荐场景的scene_id {"scene_id":"<控制台选择的scene_id\>"} * **payload** `Object` 推荐工具调用返回内容 * **rec** `Object` 推荐工具返回结构体 * **rec_results** `List[Object]` 推荐返回内容列表，列表中包含多个推荐内容。内容包含： _id：推荐内容的物品ID display_fields：物品的全部字段 **输出示例：** * 调用推荐工具 ```JSON { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "step_info": { "step": "tool call", "step_payload": { "param": {"scene_id": "scene-C4fI0e8b"}, "tool_name": "rec" } } } } ``` * 返回推荐工具调用结果 ```JSON { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "step_info": { "step": "get results" } } } { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "payload": { "rec": { "rec_results": [ { "_id": "019992810", "display_fields": { "_hash_item_id": 4635372581706750000, "formatted_description_info": {} "articleId": "GK9607", "contents": [] }] } } ``` **步骤2：流式输出欢迎语和推荐理由** 返回推荐列表后，模型结合推荐内容、用户画像和上传的用户昵称、时间，生成个性化欢迎语和推荐理由。 **输出参数：** **request_id ** `String` 此次请求的唯一请求标识 **result ** `Object` 流式返回的顶层结构 * **content** `String` 流式输出的欢迎语内容 ```JSON { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "#"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": " 🎬"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": " Hi"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "，"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "下午"} } { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": {"content": "好"} } ... ... { "request_id": "11fcaddc-addc-4a22-ae18-c6c39f4bbe8a", "result": { "stop_reason": "stop" } } ``` **步骤3：输出与推荐理由、欢迎语相关的精选推荐物品** 输出结束后，返回在欢迎语和推荐理由中实际引用的精选推荐物品列表和建议问题 **输出参数：** **request_id ** `String` 此次请求的唯一请求标识 **result ** `Object` 流式返回的顶层结构 * **payload** `Object` 批量输出的内容结构 * **related_rec_items** `List[Object]` 如果在控制台配置了启动时推荐物品，并关联了生效的推荐场景，接口在输出欢迎语后返回的精选内容列表，列表中包含多个推荐内容。 * **_id ** `String` 物品的ID * **display_fields** `Object` 返回物品的全部字段信息 * **suggestions** `List [String]` 基于推荐列表输出推荐问题，以字符串列表的形式返回 **输出精选推荐列表** ```JSON { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "payload": { "related_rec_items": [ { "_id": "019992810", "display_fields": { "_hash_item_id": 4635372581706750000, "formatted_description_info": {}, "articleId": "GK9607", "contents": [] } ] } } ``` **输出建议问题** ```JSON { "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6", "result": { "payload": { "suggestions": [ "GAZELLE 经典运动板鞋有哪些设计亮点？", "还有其他复古风格的鞋类推荐吗？", "还有哪些舒适透气的运动休闲鞋？" ] } } } ``` ## 接收对话返回内容用户输入对话内容后，chat_search接口内进行思考、调用搜索并总结，流式输出回复内容。 ### 输入用户query并思考此阶段返回一个步骤标签，标识接收到了用户的query，并进行分析处理 **输出参数：** **request_id ** `String` 此次请求的唯一请求标识 **result ** `Object` 流式返回的顶层结构 **step_info ** `Object` 步骤相关信息 **step ** `String` 步骤名称，在分析阶段返回"analyze requirement" **输出示例：** ```JSON { "request_id":"d9bb3f4a025bfced6e75762510d76af0", "result":{ "step_info":{ "step":"analyze requirement" } } } ``` ### 工具调用此步骤返回一个步骤标签，并使用payload输出工具调用的过程数据，包含两个工具： * **搜索数据集：** 调用Search工具在应用关联的数据集中进行搜索。 * **视频深度搜索：** 调用视频搜索和视频理解工具对视频内容进行深度解析和检索。 **输出参数** **request_id ** `String` 此次请求的唯一请求标识 **result ** `Object` 流式返回的顶层结构 * **step_info ** `Object` 步骤相关信息 * **step ** `String` 步骤名称，在分析阶段返回"tool call" * **step_payload** `Object` 返回调用搜索工具时的搜索参数，包含： * **tool_name ** `String` 搜索数据集时返回："search" 视频深度搜索时返回："video search and analysis" * **params** `List[Object]` 工具调用的参数列表 * **search_request** `Map` 调用搜索数据集时展示搜索工具调用的`search_request `列表，包含对多个数据集的搜索参数。每组搜索参数中包含：dataset_id, query, filter等参数，详见：[Search - 搜索](https://www.volcengine.com/docs/85296/1544974?lang=zh) **输出示例：** 调用数据集搜索工具： ```JSON { "request_id":"d9bb3f4a025bfced6e75762510d76af0", "result":{ "step_info":{ "step":"tool call", "step_payload":{ "param":{ "search_requests": [ { "query":{"text":"暖光补光的枪机"}, "page_size":30, "page_number":1, "dataset_id":"111111111" } ] }, "tool_name":"search" } } } } ``` 调用视频深度搜索工具： ```JSON { "request_id":"d9bb3f4a025bfced6e75762510d76af0", "result":{ "step_info":{ "step":"tool call", "step_payload":{ "param":{ "search_requests": [ { "query":{"text":"三体中有哪些经典台词"}, "dataset_id":"106261599" } ] }, "tool_name":"video search and analysis" } } } } ``` ### (调用数据集搜索工具时)返回搜索结果在工具调用时触发数据集搜索search工具时，返回搜索结果 **输出参数** **request_id ** `String` 此次请求的唯一请求标识 **result ** `Object` 流式返回的顶层结构 * **step_info ** `Object` 步骤相关信息 * **step ** `String` 步骤名称，在分析阶段返回"get_results" * **payload ** `Object` 返回步骤信息后，紧接返回搜索结果结构 * **search** `Map