请求参数
注意:请求提供动态参数后,将会直接覆盖应用配置中的状态值。
| 参数名 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| stream | bool | 是 | 必须填 true,当前版本仅支持流式响应。若提供false或不提供,请求将失败 |
| input | object | 是 | 输入字段 |
| input.request\_id | str | 否 | 请求ID(业务自定义) |
| input.messages | array\[object\] | 是 | 对话消息 |
| input.messages.\[\].role | str | 是 | 角色,枚举值为:user、assistant |
| input.messages.\[\].content | str | 是 | 消息内容 |
| parameters | object | 是 | 配置参数字段 |
| parameters.agent\_options | object | 是 | 智能体专用参数 |
| parameters.agent\_options.agent\_id | string | 是 | 应用ID |
| parameters.agent\_options.agent\_version | string | 是 | 应用版本 |
| parameters.agent\_options.session\_knowledge | string | 否 | session 会话级别知识 |
| parameters.agent\_options.system\_prompt | string | 否 | 系统提示词 |
| parameters.agent\_options.agent\_policy | string | 否 | 执行策略 - standard: 默认策略(推荐) - agentic: 强制边想边搜 - turbo: 极速模式 |
| parameters.agent\_options.forced\_search | bool | 否 | 是否强制搜索 - 开启时, agent\_policy默认为 standard |
| parameters.agent\_options.enable\_citation | bool | 否 | 是否透出引用信息 |
| parameters.agent\_options.enable\_text\_image\_mixed | bool | 否 | 是否图文并茂生成 |
| parameters.agent\_options.enable\_lemma | bool | 否 | 是否透出百科词条 |
| parameters.agent\_options.related\_video | bool | 否 | 是否透出相关视频 |
| parameters.agent\_options.enable\_rec\_question | bool | 否 | 是否透出相关问题 |
| parameters.agent\_options.show\_step\_info | bool | 否 | 是否展示工具调用状态信息,默认为 false |
| parameters.agent\_options.location | object | 否 | 请求位置信息 |
| parameters.agent\_options.location.address | string | 否 | 具体地址 |
| parameters.agent\_options.location.province | string | 否 | 省份 |
| parameters.agent\_options.location.city | string | 否 | 城市 |
| parameters.agent\_options.location.district | string | 否 | 区/县 |
| parameters.agent\_options.location.longitude | string | 否 | 经度(小数点6位) |
| parameters.agent\_options.location.latitude | string | 否 | 维度(小数点6位) |
返回参数
| 参数名 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| request\_id | str | 是 | 请求ID(dashscope 平台) |
| code | str | 是 | 状态码(成功:200) |
| message | str | 是 | 状态信息 |
| output | object | 是 | 输出字段 |
| output.request\_id | str | 否 | 请求ID(业务自定义) |
| output.choices | array\[object\] | 是 | 模型输出信息 |
| output.choices.\[\].finish\_reason | str | 是 | 生成结束原因,仅尾包输出stop |
| output.choices.\[\].message | object | 是 | 对话消息 |
| output.choices.\[\].message.role | str | 是 | 角色,枚举值为:user、assistant、tool |
| output.choices.\[\].message.content | str | array\[object\] | 是 | 生成内容/工具返回内容 |
| output.choices.\[\].message.reasoning\_content | str | 否 | 思考内容 |
| output.choices.\[\].message.tool\_calls | array\[object\] | 否 | 工具调用信息 |
| output.choices.\[\].message.tool\_calls\[0\].arguments | dcit\[str,object\] | 否 | 工具调用参数 |
| output.choices.\[\].message.tool\_calls\[0\].name | str | 否 | 工具调用名称 |
| output.choices.\[\].message.additional\_kwargs.extra\_json | Any | 否 | 工具调用返回时,携带结构化输出信息 |
| output.choices.\[\].message.extra | dict | 否 | 步骤状态信息 |
| output.choices.\[\].message.extra.group | str | 否 | 执行阶段 |
| output.choices.\[\].message.extra.step\_change | str | 否 | 步骤变化事件 |
| output.choices.\[\].message.extra.step | str | 否 | 当前步骤 |
| output.choices.\[\].message.response\_metadata | dict | 否 | 请求模型调用详细信息 |
| output.usage | object | 否 | 用量统计 |
| output.usage.input\_tokens | int | 否 | 输入 tokens |
| output.usage.output\_tokens | int | 否 | 输出 tokens |
| output.usage.total\_tokens | int | 否 | 总 tokens |
执行阶段枚举
执行阶段(group) | 描述 | 说明 |
|---|---|---|
| planning | 计划中 | 对应plan模型,即系统处于任务规划阶段,该阶段包含 start 和 end 事件 |
| generating | 生成中 | 对应生成模型,表示系统正处于结果生成阶段,此阶段包含 start 和 end 事件。 |
当前步骤(step) | 描述和说明 |
|---|---|
| planning | 计划中 |
| generating | 生成中 |
| tool\_calling | 工具调用中 |
| tool\calling\{工具名称} | 工具调用中,附带工具名称 |
由于模型原因 step_change 值可能为不存在,请尽可能使用持久化的标志step
空包情况下 step、step_change、group 字段的值可能不存在
plan、generation 均由 xxx_start 事件 和 xxx_end 事件两个事件组成
tool_call 由 tool_call_start、tool_calling、tool_return 三个事件组成
tool_call_start 表示工具调用开始、tool_calling 表示获取到完整工具调用的参数并会抛出完整的工具调用参数、tool_return 表示工具调用返回结果,同时会携带结构化的工具返回信息。
事件发生时step的值 | 步骤变化事件 (step_change) | 事件名称 | 解释说明 |
|---|---|---|---|
planning | plan\_start | 开始规划 | step状态变为planning, 表示对应状态的开头(包含当前包)。 |
planning | 空 | 规划中 | 表示正在思考和工具调用 |
planning | plan\_end | 结束规划 | step开始变成其他状态,事件发生时step仍为planning,表示对应状态的结尾(包含当前包)。 |
generating | generation\_start | 开始生成 | 与plan事件同理 |
generating | 空 | 生成中 | 表示正在生成 |
generating | generation\_end | 结束生成 | 与plan事件同理 |
tool_calling_{工具名称} | tool\_call\_start | 开始工具调用 | 表示工具调用开始 |
tool_calling_{工具名称} | tool\_calling | 工具调用中 | 会输出tool\_call的具体参数和工具名称,tool_calling状态变为tool_calling_{工具名称}。 |
tool_calling_{工具名称} | tool\_return | 工具返回 | 会携带工具返回信息,step开始变成其他状态,事件发生时step仍为tool_calling_{工具名称}。 |
Agent tool call message和工具名映射
当有工具调用时,在消息中的["extra"]["step"]字段中,会显示“tool_calling_xx”,显示正在调用的工具是什么。具体消息中的工具调用消息和实际的工具名的映射关系如下表所示。
文本问答
| 工具调用的 step 消息 | 工具名 |
|---|---|
| tool\_calling\_search | 联网搜索 |
| tool\_calling\_visit | 网页阅读 |
| tool\_calling\_video\_search | 视频搜索 |
| tool\_calling\_lemma\_search | 百度词条 |
| tool\_calling\_query\_suggesting | 追问 |
多模态问答
相比于文本问答,新增了 2 个工具图搜图,文搜图。
| 工具调用的 step 消息 | 工具名 |
|---|---|
| tool\_calling\_image\_search | 文搜图 |
| tool\_calling\_image\_to\_image\_search | 图搜图 |
本地生活 POI 工具
| 工具调用的 step 消息 | 工具名 |
|---|---|
| tool\_calling\_poi\_search | 关键字搜索 |
| tool\_calling\_around\_search | 周边搜索 |
工具调用状态信息
参数
工具调用的状态在消息中的["extra"]["step_change"]字段中,工具调用的信息在["extra"]["step_info"]中,工具调用状态和工具调用信息的映射如下:
| 工具调用的 step 状态 | 状态含义 | 工具调用状态信息 step\_info |
|---|---|---|
| tool\_call\_start | 开始工具调用 | 开始调用 xxx 工具 |
| tool\_calling | 正在调用工具 | 正在调用 xxx 工具 |
| tool\_calling\_return | 工具调用完成 | xxx 工具调用完成,xxx |
以联网搜索工具为例,其工具调用的状态信息会经历如下这个状态:
"step_change": "tool_call_start", "step": "tool_calling_search","step_info": "开始调用联网检索工具" "step_change": "tool_calling", "step": "tool_calling_search","step_info": "正在调用联网检索工具" "step_change": "tool_return", "step": "tool_calling_search", "step_info": "联网检索工具调用完成,检索到10个网页"图文并茂消息协议
在开启图文并茂后,模型输出的消息中,会穿插图片,图片在消息正文中的为 html 标准图片格式,示例如下:
<img src=\"xxx\" data-type=\"image\" data-url=\"xxx\" data-title=\"台风后的杭州:蓝天白云如漫画般清新️\" alt=\"杭州 晴天 蓝天\" width=\"1080\" height=\"1410\">标签中:
data-type:数据类型,image 为图片数据
src :图片的 url 地址
data-url :图片的来源网址
data-tile :图片标题
width/height :图片的尺寸宽和高
在包含图片的模型消息中,additional_kwargs 字段中包含了如下两个字段:
data_type,如果为图文并茂的图片消息,则值为 image
data_json,包含当前内容相关的所有图片,正文中只显示一张。这里是所有相关图片的集合,数据类型为 json。
在 data_json 中,每张图片的消息体如下所示:
idx:图片编号 id
url:图片来源网址
title:图片标题
published:网址发布日期
image_info["url"]:图片网址
image_info["width"]:图片宽
image_info["height"]:图片高
{"idx": 15, "query": "杭州 晴天 蓝天", "url": "xxx", "title": "xx", "published": "2024-11-04 03:04:04", "image_info": {"url": "xxx", "width": 1080, "height": 1410}}以下展示了图文并茂消息完整的 3 个消息包示例:
data: { "status_code": 200, "code": "", "message": "", "output": { "choices": [ { "finish_reason": "", "message": { "content": "游玩。\n\n", "additional_kwargs": {}, "response_metadata": {}, "type": "ai", "name": null, "id": "run--019e63e4-e728-7421-b3e5-57b408d6d4b0", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": [], "reasoning_content": "", "role": "assistant", "extra": { "group": "generating", "step_change": "", "step": "generating" } } } ] }, "usage": null, "request_id": "chenwen-test-web-search-01" } data: { "status_code": 200, "code": "", "message": "", "output": { "choices": [ { "finish_reason": "", "message": { "content": "<img src=\"http://miaobi-lite.bj.bcebos.com/miaobi/5mao/b%275Y%2Bw6aOO6L%2BH5ZCO55qE5Zu%2B54mHXzE3MzA2NTY4MTMuMTQ0MDA1NQ%3D%3D%27/0.png\" data-type=\"image\" data-url=\"http://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_4158884509151638702\" data-title=\"台风后的杭州:蓝天白云如漫画般清新\" alt=\"杭州 晴天 蓝天\" width=\"1080\" height=\"1410\">\n\n\n", "additional_kwargs": { "data_type": "image", "data_json": [ { "idx": 15, "query": "杭州 晴天 蓝天", "url": "http://mbd.baidu.com/newspage/data/dtlandingsuper?nid=dt_4158884509151638702", "title": "台风后的杭州:蓝天白云如漫画般清新", "published": "2024-11-04 03:04:04", "image_info": { "url": "http://miaobi-lite.bj.bcebos.com/miaobi/5mao/b%275Y%2Bw6aOO6L%2BH5ZCO55qE5Zu%2B54mHXzE3MzA2NTY4MTMuMTQ0MDA1NQ%3D%3D%27/0.png", "width": 1080, "height": 1410 } }, { "idx": 16, "query": "杭州 晴天 蓝天", "url": "http://m.dianping.com/ugcdetail/175828244?sceneType=0&bizType=29&msource=baiduappugc", "title": "杭州的天空也太美了吧!", "published": "2023-07-26 00:00:00", "image_info": { "url": "http://qcloud.dpfile.com/pc/VWohABccM5j2sRMTT4YdH7qapT46U8bLlM3Wp-xKeMm3OVoihIkmurvV3052Y9Xt.jpg", "width": 2048, "height": 2731 } }, { "idx": 17, "query": "杭州 晴天 蓝天", "url": "http://m.dianping.com/ugcdetail/175964222?sceneType=0&bizType=29&msource=baiduappugc", "title": "杭州蓝天白云很美,只是每次去人都要晒黑两", "published": "2023-07-27 00:00:00", "image_info": { "url": "http://qcloud.dpfile.com/pc/6ScKLghe1ZcE15OpzbomPigY1VkO6o_UTx9z6UB_BoNtf5OGAsnbF-AFIAJjozRl.jpg", "width": 2048, "height": 2731 } } ] }, "response_metadata": {}, "type": "ai", "name": null, "id": "run--019e63e4-e728-7421-b3e5-57b408d6d4b0", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": [], "reasoning_content": "", "role": "assistant", "extra": { "group": "generating", "step_change": "", "step": "generating" } } } ] }, "usage": null, "request_id": "chenwen-test-web-search-01" } data: { "status_code": 200, "code": "", "message": "", "output": { "choices": [ { "finish_reason": "", "message": { "content": "**总结**:", "additional_kwargs": {}, "response_metadata": {}, "type": "ai", "name": null, "id": "run--019e63e4-e728-7421-b3e5-57b408d6d4b0", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": [], "reasoning_content": "", "role": "assistant", "extra": { "group": "generating", "step_change": "", "step": "generating" } } } ] }, "usage": null, "request_id": "chenwen-test-web-search-01" }