知识问答 - Agent Studio

POST

/api/v2/apps/knowledge/chat

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/knowledge/chat" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "input": {
      "messages": [
        {"role": "user", "content": [{"type": "text", "text": "什么是百炼知识库？"}]}
      ]
    },
    "parameters": {
      "agent_options": {
        "agent_id": "aid-xxxxxxxxxxxxxxxx"
      }
    },
    "stream": true
  }'

{
  "output": {
    "choices": [
      {
        "message": {
          "role": "assistant",
          "type": "ai",
          "content": "百炼知识库是阿里云百炼平台提供的知识管理服务，支持文档导入、自动切片、语义检索与问答。",
          "extra": {
            "step_change": "generation_start",
            "step": "generating",
            "group": "generating"
          },
          "tool_calls": []
        },
        "finish_reason": ""
      }
    ],
    "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "code": "200",
  "message": "Success",
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

基于知识库的智能问答接口。接口通过 SSE 流式输出，把回答过程拆成三个阶段依次返回：先规划（思考要查什么、查哪个库），再工具调用（执行检索），最后生成（输出回答）。调用前须先在控制台创建并发布问答服务。

响应以 SSE 流式事件返回，事件生命周期为：plan_start → plan_end → tool_calling → tool_return → generation_start → generation_end。plan → tool_calling → tool_return 整段可重复多次（多轮检索）。

基本信息

项目	说明
调用方式	HTTP 接口调用，SSE 流式输出
请求地址	`POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/knowledge/chat`
Content-Type	`application/json`
Accept	建议传 `text/event-stream`
鉴权	`Authorization: Bearer <API-Key>`
限流	默认用户维度 25 QPS

执行阶段

执行阶段（`group`）	说明
`planning`	规划中，包含 start 和 end 事件
`generating`	生成中，包含 start 和 end 事件

当前步骤（`step`）	说明
`planning`	规划中
`tool_calling`	工具调用中（此时 `group` 仍为 `planning`）
`generating`	生成中

由于模型原因 step_change 值可能不存在，请优先使用持久化的 step。空包情况下 step、step_change、group 字段可能不存在。tool_call 由 tool_calling（抛出 tool_calls）与 tool_return（工具返回）两个事件组成。

步骤变化事件

`step`	`step_change`	事件	说明
`planning`	`plan_start`	开始规划	`step` 变为 `planning`，后续 `content` 为规划内容
`planning`	空	规划中	`content` 为规划文本流
`planning`	`plan_end`	结束规划	`step` 即将变化，事件发生时仍为 `planning`
`tool_calling`	`tool_calling`	工具调用	抛出完整 `tool_calls`（含工具名与参数），携带本轮 `usage`
`tool_calling`	`tool_return`	工具返回	`role` 为 `tool`，`content` 为返回摘要，`additional_kwargs.extra_json` 为结构化返回（检索类即 `docs`）
`generating`	`generation_start`	开始生成	后续 `content` 为最终回答文本流
`generating`	空	生成中	`content` 为回答文本流
`generating`	`generation_end`	结束生成	`finish_reason` 为 `stop`，携带最终 `usage`

事件生命周期

工具清单

模型在工具调用阶段会从以下工具里选用，工具名放在 tool_calls[].function.name。arguments 是一段 JSON 字符串，需要再解析一次才能拿到具体参数；工具的返回结果放在 tool_return 帧的 additional_kwargs.extra_json.docs 里。

`function.name`	工具	arguments	返回 `docs[]`
`semantic_search`	知识库搜索	`{"query", "target_ids"}`	命中切片数组，含正文与多维得分
`obtain_file`	获取文件完整内容	`{"file_id", "max_tokens"}`	文件级信息（含 Markdown 预签 URL），全文在 `message.content`
`execute_sql`	执行 SQL 查询（NL2SQL）	`{"sql", "knowledge_base_id"}`	SQL 结果行，每行 = `_citation_index` + 查询列字段
`section_browse`	章节检索	`{"knowledge_base_id", "file_id", "section_path"}`	章节预览（前 300 字）
`section_peruse`	章节精读	`{"knowledge_base_id", "file_id", "section_path", "max_tokens"}`	章节完整内容

max_tokens（obtain_file / section_peruse）为字符串形式的数字，如 "989482"。
target_ids / knowledge_base_id 即知识库（pipeline）ID；section_path 形如 开放接口文档>接口调用说明（> 分隔层级）。
一次请求中多个工具可串联调用（如 semantic_search 定位文件 → obtain_file 取全文）。

临时文件（session_files）

开启控制台文件预解析后，可在对话时临时传入文件。文件 ID 通过 addFile（注册文件）接口获取，完整链路：

调用 applyFileUploadLease 获取上传租约与 OSS 预签名 URL
使用返回的 URL 通过 PUT 上传文件到 OSS
调用 addFile 注册文件，获取 fileId
将该 fileId 传入本接口的 parameters.agent_options.session_files（最多 10 个）

未在控制台开启文件预解析时，session_files 参数不会被识别。

客户端拼接建议

目标	拼接方式
规划全文	累加所有 `step == "planning"` 帧的 `message.content`
最终回答	累加所有 `step == "generating"` 帧的 `message.content`
引用来源	从 `tool_return` 帧的 `additional_kwargs.extra_json.docs` 取，按 `_citation_index` 与正文对应
用量统计	取 `generation_end` 帧顶层 `usage`（最终回答用量）；检索用量见对应 `tool_calling` 帧

多轮对话

平台不保存对话状态，每次请求需传入完整 messages 历史。建议限制历史长度（最近 10 轮），避免超出模型上下文窗口。

Authorizations

string

header

required

DashScope API Key，在控制台 API Key 页面（https://agent.console.aliyun.com/settings/apikey）获取。

Body

application/json

object

required

输入参数。

Show child attributes

object[]

required

对话消息列表，DashScope 标准格式。

Show child attributes

enum<string>

required

消息角色：user 或 assistant。

Available options:user,assistant

string

required

消息内容，支持纯文本或多模态数组。纯文本传字符串；多模态传数组，元素为 ContentPart（如 [{"type":"text","text":"..."},{"type":"image_url","image_url":{"url":"..."}}]）。

string

业务侧自定义请求 ID。

object

required

配置参数字段。

Show child attributes

object

required

Show child attributes

string

required

问答服务（agent）应用 ID，在控制台知识问答页面创建并发布后获取。

string[]

会话文件 ID 列表，最多 10 个。须在控制台开启文件预解析后传入才生效；文件 ID 通过 addFile（注册文件）接口获取。

Required range:items <= 10

boolean

defaulttrue

required

是否开启流式输出。必须填 true，当前版本仅支持流式响应；填 false 或不填请求将失败。

Response

200-application/json

object

Show child attributes

string

业务侧自定义请求 ID（与请求 input.request_id 对应）。

object[]

模型输出信息，长度恒为 1。

Show child attributes

object

一条消息，包含模型回复的内容、工具调用信息和当前所处阶段。

Show child attributes

enum<string>

角色：user、assistant、tool。

Available options:user,assistant,tool

string

生成内容/工具返回内容。planning 阶段（思考内容）为规划文本流，generating 阶段为回答文本流，边界帧可为空字符串。也可是多模态数组。

string

本次 run 的唯一 ID（如 run--xxxx），同一轮内不变。

enum<string>

消息类型：ai（assistant 帧，含思考/planning/生成）、tool（工具返回帧）。

Available options:ai,tool

object[]

工具调用信息，见工具清单。仅 tool_calling 帧携带，其余为 []。

Show child attributes

integer

调用序号，从 0 起。一次工具调用帧可并行触发多个工具，index 标识序号。

string

调用 ID（如 call_xxxx），与后续 tool 帧的 tool_call_id 对应。

string

固定 function。

object

Show child attributes

string

工具调用名称，取值见工具清单（semantic_search / obtain_file / execute_sql / section_browse / section_peruse）。

string

工具调用参数，JSON 字符串（需二次解析），如 {"query": "...", "target_ids": ["..."]}。

string

工具返回帧：对应 tool_calls[].id，用于关联触发帧与返回帧。

object

附加参数。assistant 帧为 {}；tool 帧携带 extra_json，为工具返回的结构化结果（检索类工具为 docs 切片数组，含正文、文档信息、得分等字段）。

object

步骤状态信息。

Show child attributes

enum<string>

大阶段：planning（规划阶段，包含开始和结束事件）、generating（生成阶段，包含开始和结束事件）。工具调用时大阶段还是 planning，只是细分步骤变成 tool_calling。

Available options:planning,generating

enum<string>

当前步骤。step_change 有时可能不返回，建议以 step 为准。

Available options:planning,tool_calling,generating

string

步骤变化事件：plan_start / plan_end / tool_calling / tool_return / generation_start / generation_end，或空（进行中）。空包时可能不存在。

object

请求模型调用详细信息。边界帧携带 agent_name、request_id，有时含 model_name、finish_reason；普通片段为 {}。

string

生成结束原因，仅尾包输出 stop；流式片段为 ""。

string

状态码，成功为 200。

string

状态信息，成功为 Success。

string

请求 ID（DashScope 平台级，全流不变）。

object

Show child attributes

integer

输入 tokens。

integer

输出 tokens。

integer

总 tokens。

integer

命中缓存的 tokens。

​基本信息

​执行阶段

​步骤变化事件

​事件生命周期

​工具清单

​临时文件（session_files）

​客户端拼接建议

​多轮对话

Authorizations

Body

Response

基本信息

执行阶段

步骤变化事件

事件生命周期

工具清单

临时文件（session_files）

客户端拼接建议

多轮对话