集成智能对话搜索--全域AI搜索-火山引擎

文档中心

导航

集成智能对话搜索

最近更新时间：2025.10.21 22:29:10首次发布时间：2025.10.15 00:14:59

您可以使用ChatSearch API进行对话助手的集成。

核心概念：

Session：一个session表示一个用户在一个界面内进行多轮对话的整个过程。每个session包含一个用户的多轮对话历史。
用户信息：在session对话中传入当前对话的用户信息，目前支持传入用户的ID和昵称。传入用户信息将有助于对话引擎积累用户的对话数据来贡献用户的兴趣偏好。
Step：对话助手使用Agent架构，在流失输出最后的答案前会经过思考、工具调用、接收搜索结果等流程，这些流程均会在调用过程中返回相应的步骤事件，以step来区分当前agent的执行阶段。
Payload：代表对话接口输出的非最终回复的一些中间结果，每个step可能会返回不同的payload信息，您可以忽略这些信息，也可以使用这些信息来加工向用户展示的agent中间执行过程。

对话Session启动：

Session启动支持2种模式：

无开场：不进行开场欢迎或开场推荐物品，直接传入第一条用户输入。
进行对话开场：将您配置的开场欢迎语或物品推荐交互返回给用户后，再输入用户的输入问题。对话开场配置由您在控制台配置，见：设置对话开场配置

对话开场

调用示例：

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/{application_id}/chat_search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization:Bearer {API_KEY}' \
  -d '{
    "session_id": "25ee998a-5462-9385-9f18-035f1da7a6e5",
    "user": {
        "_user_id":"ldy_199432",
        "nickname":"用于打招呼的用户昵称"
    },
    "opening_remarks":true
}'

参数解析：
{application_id}：对话场景所属应用的应用ID，可在控制台获取
{API_KEY}：在控制台创建的API key，见API鉴权机制说明
opening_remarks：是否进行开场，传入true
session_id：会话的唯一标识符，用于跟踪和管理用户对话状态，您需要在您的服务端维护Session ID，每次用户的新对话需要传入一个唯一的session_id，一次对话之中session_id需保持一致
_user_id：建议传入，代表一个您的平台中用户的唯一标识。您需要保障用户ID与传入的行为数据中的用户ID一致。如果您在对话开场配置中配置了对话时启动推荐，则必须传入此参数。
nickname：建议传入，会用于开场打招呼时，使用用户自定义的昵称称呼用户。见个性化欢迎语

对话开场返回

仅返回打招呼

控制台没有配置开场推荐时，仅返回欢迎语打招呼内容

输出参数：
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构

content String
流式输出的欢迎语内容

返回示例：

{
  "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"
  }
}

开场返回打招呼+个性化推荐

配置了开场推荐时，agent将先调用推荐接口，使用用户ID获取针对此用户的个性化推荐列表，再进行总结、加工，并以流式的形式输出精选推荐物品和欢迎语，以及推荐问题。
步骤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：物品的全部字段

输出示例：

调用推荐工具

{
    "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6",
      "result": {
           "step_info": {
               "step": "tool call",
               "step_payload": {
                   "param": {"scene_id": "scene-C4fI0e8b"},
                    "tool_name": "rec"
                 }
            }
        }
}

返回推荐工具调用结果

{
    "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
流式输出的欢迎语内容

{
  "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]
  基于推荐列表输出推荐问题，以字符串列表的形式返回

输出精选推荐列表

{
    "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": []
                 }
              ]
      }
}

输出建议问题

{
    "request_id": "6db275e0-8b6d-421d-beb9-b8d7453498b6",
    "result": {
        "payload": {
            "suggestions": [
                "GAZELLE 经典运动板鞋有哪些设计亮点？",
                "还有其他复古风格的鞋类推荐吗？",
                "还有哪些舒适透气的运动休闲鞋？"
            ]
        }
      }
}

无开场对话

说明

这个请求同样适用于开场后输入用户的第一条对话数据，此时需要您传入开场时传入的session_id

如果你不想集成我们提供的开场白和推荐，可以传入新的session和用户的第一条对话信息，立即开始对话：

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/{application_id}/chat_search' \ 
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer <API Key>' \ 
  -d '{
    "session_id": "25ee998a-5462-9385-9f18-035f1da7a6e5",  
    "input_message": { 
        "content":[{"type":"text", "text":"有哪些好看的国产科幻片？"}] 
    }, 
    "user": { 
        "_user_id": "ldy_199432" 
    },
    "search_param": {
        "page_size": 20,
        "dataset_ids": ["111111104"],
        "filters": {   
            "106265704": {
                "op": "must",
                "field": "parent_content_id",
                "conds": [""]
            }
        } 
    }
    "enable_suggestion":true
}'

参数说明：
input_message：用户的输入对话内容。可包含图片和文本信息。
search_params：在对话中调用搜索工具时需要遵循的参数。包含返回的首页结果大小、限定在某个数据集内搜索、限定数据集的搜索过滤条件
enable_suggestion：回复最后是否输出用户继续问的问题。默认为false。

参数详解见ChatSearch - 对话搜索

说明

对于视频对话，如果您想在对话时仅向用户展示、推荐系列内容（如电视剧的一整季而不是单集），则需要传入以下filter：
"{应用绑定的视频数据集ID}": {"op": "must","field": "parent_content_id","conds": [""]}

接收对话返回信息

传入用户的输入信息后，接口流式返回agent的执行过程和最终的回复内容。详细返回执行流程和参数说明见：ChatSearch - 对话搜索。
流式返回的信息在step为"reply"时开始流式输出。输出内容包含markdown格式的回复文本内容，和回复内容段落引用的物品字段。返回字段如下：

输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构

step_info Object
步骤相关信息
- step String
  步骤名称，在此阶段返回"reply"
content String
流式返回的字符串
citation Array [Citation 结构]
在需要输出引用的物品、文档内容的时候输出段落的引用溯源的物品数据列表，列表中每一个元素是一个Object，包含物品内容的类型、数据集ID和数据ID。在输出的内容无引用时，不输出此字段，在段落结束位置，如果该段落介绍了、或引用了某条媒资信息，将会返回一个列表。citation对象的返回结构如下：
- type String
  引用的数据类型的枚举，会返回以下值："item"物品数据集中的物品数据；"document"文档数据集中的文档
- 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":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"为"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"你"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"推荐"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"以下"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"适合"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"夜店"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"的"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"口红"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"："}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"\\"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"n"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"-"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":" Glam"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"orous"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":" Ch"}}
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"content":"icks"}}
... ...
{"request_id":"f7d26edd3d1da65b49fccde4244629f3","result":{"citation":{"type":"item","dataset_id":"289112891","_id":"P19029XJSKK_0928812"}}}

（视频应用）输出回复引用的视频片段信息

视频应用中用户的问题会触发视频深度搜索，此时在返回流式输出的内容后会返回与用户问题相关的视频片段列表，每个片段包含视频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，可用于封面展示

输出示例

{
    "payload":{
        "video_deep_answer":{
            "106706135":{
                "highlights":[
                    {"content_id":"video_episode_002",
                    "generated_title":"物理学崩塌下的倒计时谜局与科学边界之争",
                    "video_title":"",
                    "snippets":[{
                        "start_timestamp":262,
                        "end_timestamp":322,
                        "summary":"物理学不存在了",
                        "cover":"XXX"}]},
                    {"content_id":"video_episode_020",
                    "generated_title":"混沌宇宙中的数学困局与文明新生",
                    "video_title":"",
                    "snippets":[{
                        "start_timestamp":1412,
                        "end_timestamp":1465,
                        "summary":"文明的纪念碑墓碑",
                        "cover":"XXXX"},
                        {"start_timestamp":1948,
                        "end_timestamp":2001,
                        "summary":"物理学从未存在",
                        "cover":"XXXXX"}]}]
                    }
                ]
            }
        }
    }
}

返回建议问题

传入参数中开启了'enable_suggestion'则会返回与当前搜索相关的建议问题列表，帮助用户进一步探索或优化查询。

输出参数
request_id String
此次请求的唯一请求标识
result Object
流式返回的顶层结构

payload Object
使用payload输出建议问题
- suggestions List[String]
  返回3个推荐用户继续追问的问题

输出示例

{   
    "request_id":"ba88a50a58928940c56f2399fd176045",
    "result":{
        "payload":{
            "suggestions":["“物理学不存在了”是谁说的？","杨冬的遗书还有哪些内容？","“虫子从未被战胜”出自哪一集？"]
         }
    }
}

说明

更多集成的实践，详见：最佳实践 - 配置和集成对话式搜索