Knowledge Q&A

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

A knowledge-based intelligent Q&A API. The response is delivered via Server-Sent Events (SSE) in a streaming fashion, decomposing the answer generation process into three sequential phases: planning (reasoning about what to search and which knowledge base to query), tool calling (executing retrieval operations), and generation (producing the final answer). Before calling this API, you must first create and publish a Q&A service in the console.

Responses are delivered as SSE events with the following lifecycle: plan_start → plan_end → tool_calling → tool_return → generation_start → generation_end. The entire sequence plan → tool_calling → tool_return may repeat multiple times (for multi-round retrieval).

Basic Information

Item	Description
Invocation method	HTTP API call with SSE streaming output
Request URL	`POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/knowledge/chat`
Content-Type	`application/json`
Accept	Recommended: `text/event-stream`
Authentication	`Authorization: Bearer <API-Key>`
Rate limiting	Default per-user limit: 25 QPS

Execution Phases

Execution phase (`group`)	Description
`planning`	Planning phase — includes both `start` and `end` events
`generating`	Generation phase — includes both `start` and `end` events

Current step (`step`)	Description
`planning`	In planning phase
`tool_calling`	Invoking tools (the `group` remains `planning`)
`generating`	In generation phase

Due to model behavior, the step_change field may be absent. Prioritize using the persistent step field instead. In empty payloads, step, step_change, and group fields may all be missing. A tool_call consists of two distinct events: tool_calling (emitting tool_calls) and tool_return (receiving tool results).

Step Transition Events

`step`	`step_change`	Event	Description
`planning`	`plan_start`	Planning starts	`step` transitions to `planning`; subsequent `content` contains planning text
`planning`	— (empty)	Planning in progress	`content` contains streamed planning text
`planning`	`plan_end`	Planning ends	`step` is about to change; at event emission, `step` is still `planning`
`tool_calling`	`tool_calling`	Tool invocation	Emits full `tool_calls` (including tool name and arguments); includes usage for this round
`tool_calling`	`tool_return`	Tool returns	`role` is `"tool"`; `content` contains summary of returned data; structured result resides in `additional_kwargs.extra_json.docs` (e.g., retrieved documents for search tools)
`generating`	`generation_start`	Generation starts	Subsequent `content` contains streamed final answer text
`generating`	— (empty)	Generation in progress	`content` contains streamed answer text
`generating`	`generation_end`	Generation ends	`finish_reason` is `"stop"`; includes final `usage`

Event Lifecycle

Available Tools

During the tool-calling phase, the model selects from the following tools. The tool name appears in tool_calls[].function.name. The arguments field is a JSON string requiring secondary parsing to extract actual parameters. Tool return values appear in additional_kwargs.extra_json.docs within tool_return frames.

`function.name`	Tool	`arguments`	Returns `docs[]`
`semantic_search`	Knowledge base search	`{"query", "target_ids"}`	Array of matched document chunks, including full text and multi-dimensional scores
`obtain_file`	Retrieve full file content	`{"file_id", "max_tokens"}`	File-level metadata (including Markdown presigned URL); full content in `message.content`
`execute_sql`	Execute SQL query (NL2SQL)	`{"sql", "knowledge_base_id"}`	SQL result rows; each row contains `_citation_index` plus queried column values
`section_browse`	Section-level search	`{"knowledge_base_id", "file_id", "section_path"}`	Section preview (first 300 characters)
`section_peruse`	Section deep-read	`{"knowledge_base_id", "file_id", "section_path", "max_tokens"}`	Full section content

max_tokens (for obtain_file / section_peruse) is a numeric string, e.g., "989482".
target_ids / knowledge_base_id refer to knowledge base (pipeline) IDs; section_path uses > as hierarchical delimiter, e.g., Open API Documentation>API Invocation Guide.
Multiple tools may be chained in one request (e.g., semantic_search locates a file → obtain_file retrieves its full content).

Temporary Files (`session_files`)

When File Pre-parsing is enabled in the console, users can upload temporary files during a conversation. File IDs are obtained via the addFile API. Full workflow:

Call applyFileUploadLease to obtain an upload lease and OSS presigned URL
Upload the file to OSS using the provided PUT URL
Call addFile to register the file and retrieve its fileId
Pass that fileId in parameters.agent_options.session_files of this API (up to 10 files allowed)

If File Pre-parsing is disabled in the console, the session_files parameter will be ignored.

Client-Side Response Assembly Guidance

Goal	Assembly Strategy
Complete planning text	Concatenate `message.content` from all frames where `step == "planning"`
Final answer text	Concatenate `message.content` from all frames where `step == "generating"`
Citation sources	Extract from `additional_kwargs.extra_json.docs` in `tool_return` frames; match `_citation_index` to corresponding positions in answer text
Usage statistics	Use top-level `usage` in `generation_end` frame (final answer usage); retrieval usage appears in respective `tool_calling` frames

Multi-turn Conversations

The platform does not retain conversation state. Each request must include the full messages history. We recommend limiting history length (e.g., last 10 turns) to avoid exceeding the model’s context window.

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

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。

​Basic Information

​Execution Phases

​Step Transition Events

​Event Lifecycle

​Available Tools

​Temporary Files (session_files)

​Client-Side Response Assembly Guidance

​Multi-turn Conversations

Authorizations

Body

Response

Basic Information

Execution Phases

Step Transition Events

Event Lifecycle

Available Tools

Temporary Files (`session_files`)

Client-Side Response Assembly Guidance

Multi-turn Conversations