知识问答 - Knowledge 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 参数不会被识别。

上下文缓存

问答链路已适配模型侧的上下文缓存（KV Cache）：多轮对话与多轮工具调用中请求前缀保持稳定，命中部分的输入 Token 按折扣价计费，且首包延迟降低。缓存分为隐式、显式两种模式，同一请求只生效一种：

	隐式缓存	显式缓存
如何启用	模型支持则默认生效，无需配置，也无法关闭	请求中传 `enable_cache_control: true`
命中确定性	不确定，由系统自动识别公共前缀	确定性命中（前缀一致即命中）
创建缓存计费	输入单价 100%（无额外开销）	输入单价 125%
命中缓存计费	输入单价 20%	输入单价 10%
缓存有效期	不确定，系统定期清理	5 分钟，每次命中后重置
最小可缓存长度	1024 Token	1024 Token

计费比例与有效期以百炼官方文档上下文缓存、显式缓存最佳实践及控制台账单为准。内部实测隐式缓存命中率约为显式缓存的 75%，仅供参考，非官方指标。

开启显式缓存

在 parameters.agent_options 中增加 enable_cache_control 即可，默认 false，其余参数保持不变：

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" \
  -d '{
    "input": {
      "messages": [
        {"role": "user", "content": "这几款酒的产区分别是什么？"}
      ]
    },
    "parameters": {
      "agent_options": {
        "agent_id": "aid-xxxxxxxxxxxxxxxx",
        "enable_cache_control": true
      }
    },
    "stream": true
  }'

模型支持

两种缓存的模型支持范围不同。模型由平台侧配置决定，本接口不暴露模型选择参数，能用哪种缓存取决于问答服务实际使用的模型：

模型	显式缓存	隐式缓存
qwen3.6-plus（当前默认）	支持	不支持
qwen3.6-flash	支持	不支持
qwen3.7-plus	支持	支持

当前默认模型 qwen3.6-plus 不支持隐式缓存：不传 enable_cache_control 时没有任何缓存生效，cached_tokens 会一直为 0，这是模型侧能力限制而非接口异常。要获得缓存收益（降本 + 降首包延迟）需开启显式缓存；仅当服务运行在 qwen3.7-plus 上时，不开启才有隐式缓存兜底。模型支持列表以显式缓存官方文档的“支持的模型”章节为准。

适用场景

缓存收益分两类场景，单请求内的收益比跨请求更稳定、更显著。 强烈推荐：单请求内多次检索与思考。一次提问触发多轮工具调用（多次 semantic_search / execute_sql / 章节浏览 + 中间思考）时，缓存断点会随每轮新增的工具结果向后移动，上一轮的完整上下文（含检索结果）成为下一轮的稳定前缀。问题越复杂、检索轮次越多、检索结果越长，节省越明显，且不受 5 分钟有效期和跨请求前缀变化的影响。 推荐：跨请求复用：

场景	原因
多轮连续对话	从第二轮起可命中上一轮的完整历史前缀，对话越长收益越大
长 System Prompt / 大表结构场景	结构化知识库的表结构会拼进 system prompt，体积大且会话内稳定，是理想的缓存内容
同一份长文档 / 会话文件的反复追问	稳定前缀占比高，一次创建多次命中
对延迟敏感、要求命中确定性的业务	显式缓存是确定性命中，不受后端资源调度影响

成本盈亏判断：显式缓存首次写入多付 25%，之后每次命中省 90%，只要发生至少一次命中，总成本就低于不用缓存。 不建议开启（开了也没收益，甚至更贵）：

场景	原因
一次性单轮短问答	只创建、不命中，白付 25% 创建溢价
前缀不足 1024 Token	达不到最小缓存长度，不会产生缓存
请求间隔超过 5 分钟的低频调用	显式缓存 5 分钟过期，下次请求必然重新创建
多模态文档场景的跨请求复用	图片内容块参与前缀计算，跨请求容易因图片块变化而缓存失效；此类场景建议只指望单请求内的收益
每次会话都换知识库 / 换问答服务配置	前缀（含表结构、知识库信息）不同，无法复用

上述“不建议”仅指显式缓存收益不划算。由于默认模型 qwen3.6-plus 不支持隐式缓存，不开启 enable_cache_control 并不会退化成隐式缓存兜底，而是完全没有缓存。若这些场景仍希望有一定缓存收益，可评估后照常开启。

查看缓存命中

响应终结帧 usage 中的 cached_tokens 即本次请求命中缓存的输入 Token 数：

{
  "usage": {
    "input_tokens": 12345,
    "output_tokens": 678,
    "total_tokens": 13023,
    "cached_tokens": 9800
  }
}

cached_tokens 是本次请求内多轮模型调用的累计值；
会话首次请求 cached_tokens 必然为 0：首次只创建缓存，尚无可命中的内容，属预期行为；
从第二轮起应观察到 cached_tokens 大于 0，且随对话历史增长而增大；
也可在百炼控制台「模型监控」查看 cache_tokens 指标，或在「账单详情」中按 cache 筛选核对。

注意事项

两种缓存互斥：传了 enable_cache_control: true 即走显式缓存，不再走隐式缓存。默认模型 qwen3.6-plus 上不存在隐式缓存，不开启就是无缓存，而非“退化成隐式”。
首轮无命中是正常的：任何缓存首次都需要先创建，cached_tokens=0 不代表功能异常。
显式缓存 5 分钟有效期：每次命中会重置为 5 分钟；用户长时间不发问，下一次请求会重新创建缓存。
工具定义变化会导致缓存失效：工具定义作为 system prompt 的一部分参与缓存计算。结构化知识库携带 search_filters 时会屏蔽 execute_sql 工具——同一会话中 filter 时有时无会改变工具列表，进而导致 system 前缀无法命中。建议同一会话内保持 kb_search_configs 稳定。
前缀必须逐字节稳定：修改知识库绑定、变更问答服务配置（如自定义指令、会话文件开关）、平台侧调整模型，都会改变前缀，缓存需重新创建。
多模态场景跨请求命中不稳定：带图片输入时图片内容块参与前缀计算，跨请求前缀容易不一致导致缓存失效；这类场景的收益主要来自单请求内的多轮检索，不应按跨请求命中来估算。
超长多轮存在回溯上限：缓存匹配从断点向前回溯最多 20 个 content 块，单轮产生大量消息（多次工具调用 + 图片块）的极端情况下可能超出回溯范围而无法命中。
缓存按账号与模型隔离：不同账号之间、同账号不同模型之间的缓存均不共享。
input_tokens ≠ 创建 + 命中：后端会在提示词之后追加少量 Token（通常 10 以内），计入总输入但不计入缓存统计。

验证缓存效果

在请求中加上 enable_cache_control: true，用一个会触发多轮检索的复杂问题跑一次，观察终结帧 cached_tokens 是否大于 0；
再用同一会话连续追问 2-3 轮（间隔控制在 5 分钟内），观察 cached_tokens 是否随历史增长而增大，并对比首包延迟；
与不传该参数的同样请求做 A/B 对比（默认模型下基线应为 cached_tokens=0），按「适用场景」的判据决定是否常态开启。

客户端拼接建议

目标	拼接方式
规划全文	累加所有 `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 页面获取。

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

defaultfalse

是否开启显式上下文缓存（KV Cache）。true 时请求打下缓存断点，前缀一致即确定性命中，命中部分的输入 Token 按折扣计费且首包延迟降低；false（默认）时不打断点，是否命中取决于模型侧的隐式缓存能力。同一请求只生效一种缓存模式，详见上下文缓存。

boolean

defaulttrue

required

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

Response

200-text/event-stream

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，为多轮模型调用的累计值。会话首次请求必然为 0（首次只创建缓存），第二轮起应大于 0；开启方式见上下文缓存。

​基本信息

​执行阶段

​步骤变化事件

​事件生命周期

​工具清单

​临时文件（session_files）

​上下文缓存

​开启显式缓存

​模型支持

​适用场景

​查看缓存命中

​注意事项

​验证缓存效果

​客户端拼接建议

​多轮对话

Authorizations

Body

Response

基本信息

执行阶段

步骤变化事件

事件生命周期

工具清单

临时文件（session_files）

上下文缓存

开启显式缓存

模型支持

适用场景

查看缓存命中

注意事项

验证缓存效果

客户端拼接建议

多轮对话