Viking AI 搜索
Viking AI 搜索
文档指南
请输入
- 文档首页
Viking AI 搜索AI搜索引擎用户手册API参考对话搜索接口ChatSearch - 对话搜索
复制全文
下载 pdfChatSearch - 对话搜索
文档反馈
问问助手说明
Viking AI 搜索是一款基于生成式 AI 的企业级 AI 搜索产品，基于大模型的多模态语义表征和理解能力，结合字节跳动信息检索领域多年最佳实践，为客户提供开箱即用的 AI 搜索搭建平台服务，帮助客户轻松搭建和集成端到端的多模态图文搜索和推荐能力。
- 想要体验更多 Viking AI 搜索能力，点击前往：Viking AI 搜索引擎，企业搜推问一体化智能引擎
根据聊天内容，动态处理闲聊，拒答，搜索等意图，再给出合适的用户回复的同时，动态地调用搜索功能并返回搜索到的物品数据。
使用对话搜索功能时，您需要自行维护会话session的唯一标识，每次调用可上传session_id：
- 上传一个新session_id：默认开启一次新的会话
- 上传已有的session_id：系统自动获取会话历史，并在历史上下文的基础上继续处理用户query
注意事项
- 使用限制：
- 受到HTTP Body大小限制，单次请求的包体大小最大不超过10MB。
- 返回格式
- 对话接口以流式格式返回，客户端自主实现API调用时需要使用流式方式解析响应。
请求地址
- 请求方式：POST
- 请求地址：
-
{application_id}：在控制台创建应用后系统指定的应用唯一标识，可在控制台查看
鉴权方式
发起对话请求
直接开始对话
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
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字符串，值为过滤表达式对象。如示例所示：
- output_fields Object
- 指定物品数据集数据中的哪些字段在接口中返回展示（在搜索工具的返回结果、对话结束后返回相关物品列表related_items）
- 传入的内容为一个Map对象。
- key：数据源ID (String)
- value：该数据源需要返回的字段列表 (Array<String>)
- 没有在output_fields中指定的数据集，默认返回所有字段；如果不传此参数则默认所有数据集中的数据都返回所有字段。如果数据集中存在嵌套的对象(Object)，则只支持传入上层的字段名。
- 传入不存在的字段或Object内层的字段会被忽略。
- 示例：
context Object
传入本次请求的用户环境上下文信息，当前支持上传用户地理位置
- location Object
- 用户的地理位置信息，包含经度和纬度。如果您在推荐和搜索中配置了地理位置提权降权，在对话中调用搜索、推荐工具将会生效策略。
- latitude String
- 纬度，支持上传字符串格式的数据，如"12.291"，字符串内容必须是一个[-90,90]之间的数字
- longitude String
- 经度，支持上传字符串格式的数据，如"30.218"，字符串内容必须是一个[-180,180]之间的数字
Session启动：
用户传入对话内容
启动对话时进行欢迎
启动对话时可使用 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 编码正文两部分：
使用过滤
在对话中传入的过滤条件会透传到对话中调用搜索工具的流程，意味着用户在对话中只能针对部分符合条件的数据集物品进行过滤。
与搜索不同，当对话引用了多个数据集时，您需要对多个数据集进行过滤。filter参数传入的是一个Map JSON结构，key为数据集ID（String），值为对数据集中数据的过滤条件。
流式返回
流式返回整体步骤
Chat_search接口的返回采用流式输出，接口调用后，输出流程如下：
调用接口后，对话式搜索agent会经过一系列思考、判断、工具调用流程，最终执行大模型回复的输出。在回复输出之前所有步骤都会返回步骤的事件和中间过程输出，供您去监控输出流程，或在您的界面显示中间处理过程的交互。
接收对话开场内容
若在接口中传入了新的session_id，且将opening _remarks设置为 true，则会触发欢迎语+在启动时个性化推荐一批内容（若控制台配置）。
仅返回欢迎语时
仅返回欢迎语时，流式返回欢迎语内容
输出参数：
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- content String
- 流式输出的欢迎语内容
-
返回示例：
返回欢迎语后，立即返回推荐问题：
输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- payload Object
- 批式一次性输出的内容
- suggestions List[String]
- 欢迎阶段“猜你想搜”问题列表，按控制台配置的最大返回数量返回一个问题列表
返回欢迎语+推荐列表
步骤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：物品的全部字段
输出示例：
- 调用推荐工具
- 返回推荐工具调用结果
步骤2：流式输出欢迎语和推荐理由
返回推荐列表后，模型结合推荐内容、用户画像和上传的用户昵称、时间，生成个性化欢迎语和推荐理由。
输出参数：
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- content String
- 流式输出的欢迎语内容
步骤3：输出与推荐理由、欢迎语相关的精选推荐物品
输出结束后，返回在欢迎语和推荐理由中实际引用的精选推荐物品列表和建议问题
输出参数：
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- payload Object
- 批量输出的内容结构
- related_rec_items List[Object]
- 如果在控制台配置了启动时推荐物品，并关联了生效的推荐场景，接口在输出欢迎语后返回的精选内容列表，列表中包含多个推荐内容。
- _id String
- 物品的ID
- display_fields Object
- 返回物品的全部字段信息
- suggestions List [String]
- 基于推荐列表输出推荐问题，以字符串列表的形式返回
输出精选推荐列表
输出建议问题
接收对话返回内容
用户输入对话内容后，chat_search接口内进行思考、调用搜索并总结，流式输出回复内容。
输入用户query并思考
此阶段返回一个步骤标签，标识接收到了用户的query，并进行分析处理
输出参数：
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- step_info Object
- 步骤相关信息
- step String
- 步骤名称，在分析阶段返回"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 - 搜索
输出示例：
调用数据集搜索工具：
调用视频深度搜索工具：
(调用数据集搜索工具时)返回搜索结果
在工具调用时触发数据集搜索search工具时，返回搜索结果
输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- step_info Object
- 步骤相关信息
- step String
- 步骤名称，在分析阶段返回"get_results"
- payload Object
- 返回步骤信息后，紧接返回搜索结果结构
- search Map<Object>
- 包含搜索调用的信息和搜索结果，每个元素的key为数据集ID(String)
- search_result Object
- 多个数据集中的搜索结果，与搜索接口调用的返回相同，见 Search - 搜索
返回示例
（调用视频深度搜索工具时）返回与用户问题相关的视频内容
在工具调用阶段触发视频深度搜索时，返回与用户问题相关的视频内容（中间结果）
输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- step_info Object
- 步骤相关信息
- step String
- 步骤名称，在此阶段返回"get results"
- step_payload Object
- 返回调用搜索工具时的搜索参数，包含：
- results Map<Object>
- 返回的相关视频内容结果，以字典形式输出，key为视频数据集ID，value为视频的元数据信息。
输出示例
分析搜索结果
调用数据集搜索和视频深度搜索工具获取与用户的问题相关的内容后，模型进行结果分析并准备输出答案，此阶段会输出"analyze result"步骤信息，并持续一个秒级的等待时间。
输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- step_info Object
- 步骤相关信息
- step String
- 步骤名称，在此阶段返回"analyze results"
输出示例
获取流式回复
模型开始生成流式回复，流式返回分析后的总结内容。
输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- step_info Object
- 步骤相关信息
- step String
- 步骤名称，在此阶段返回"reply"
- content String
- 流式返回的字符串
- citation Array [Citation 结构]
- 在需要输出引用的物品、文档内容的时候输出段落的引用溯源的物品数据列表 ，列表中每一个元素是一个Object，包含物品内容的类型、数据集ID和数据ID。在输出的内容无引用时，不输出此字段，在段落结束位置，如果该段落介绍了、或引用了某条媒资信息，将会返回一个列表。citation对象的返回结构如下：
- type String
- 引用的数据类型的枚举，目前仅有"item"：物品数据集中的物品数据
- dataset_id String
- 引用的内容所属的数据集ID
- _id String
- 引用的物品或文档的唯一ID，对应图文物品数据集中的物品ID、视频数据集中的content_id
- display_fields Object
- 引用数据的详细信息。目前在引用文档数据时会返回以下内容：
- doc_id String：文档ID
- doc_name String：文档名称，用于标识引用文档的具体名称
- doc_type String：文档扩展名
- text String：引用的文档切片原文
输出示例
（调用搜索工具时）批量输出回复中引用的物品列表
流式回复结束后，批量输出从多个数据集中搜索出的，在回复中引用的物品列表
输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- payload Object
- 使用payload输出结构化的物品列表数据
- related_items List[Object]
- 返回本次回答中引用的所有物品的全部字段，以及这些引用的物品所属的数据集
- _id String
- 物品的唯一标识
- display_fields Object
- 返回物品的所有字段
- dataset_id String
- 物品来源的数据集
输出示例
（调用视频深度搜索工具时）返回回答相关的视频片段列表及其时间戳信息
视频深度搜索时会返回与用户问题相关的视频片段列表，每个片段包含视频ID、起始时间戳和结束时间戳信息，以便用户快速定位相关内容。
输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- payload Object
- 使用payload输出结构化的片段数据
- video_deep_answer List[Object]
- 返回本次回答中引用的所有物品的全部字段，以及这些引用的物品所属的数据集
- highlights List[Object]
- 返回多个视频内，与用户问题相关的看点片段和总结
- content_id String
- 返回多个视频内，与用户问题相关的看点片段和总结
- video_title String
- 看点所属的视频标题，返回上传的视频媒资中标注的“标题”属性的字段值
- generated_title String
- 视频理解阶段生成的视频标题
- snippets List[Object]
- 视频中的看点片段，包含以下信息：
- start_timestamp Int
- 片段的开始时间戳（秒）
- end_timestamp Int
- 片段的结束时间戳（秒）
- summary String
- 片段的短总结
- cover String
- 片段的非黑首帧截图url，可用于封面展示
输出示例
返回建议问题
传入参数中开启了'enable_suggestion'则会返回与当前搜索相关的建议问题列表，帮助用户进一步探索或优化查询。
输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构
- payload Object
- 使用payload输出建议问题
- suggestions List[String]
- 返回3个推荐用户继续追问的问题
输出示例
说明
最近更新时间：2026.08.09 01:07:01
这个页面对您有帮助吗？
有用
有用
无用
无用