{
"output": {
"choices": [
{
"message": {
"role": "assistant",
"type": "ai",
"content": "A Bailian Knowledge Base is a knowledge management service on Alibaba Cloud Model Studio that supports document import, automatic chunking, semantic search, and Q&A.",
"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"
}
Knowledge Base–grounded Q&A. The endpoint streams the answer over SSE in three phases: first planning (deciding what to search and which Knowledge Base), then tool calling (running the retrieval), then generation (producing the answer). Create and publish the Q&A service in the console first.
The response streams SSE events in this lifecycle: plan_start → plan_end → tool_calling → tool_return → generation_start → generation_end. The plan → tool_calling → tool_return segment can repeat multiple times (multi-round retrieval).
step_change may be absent due to the model — prefer the persistent step. On empty frames, step, step_change, and group may all be absent. A tool_call consists of two events: tool_calling (emits tool_calls) and tool_return (tool result).
During the tool-calling phase the model picks from the tools below; the tool name is in tool_calls[].function.name. arguments is a JSON string — parse it once more to get the actual parameters. The tool result lives in the tool_return frame's additional_kwargs.extra_json.docs.
function.name
Tool
arguments
Return docs[]
semantic_search
Knowledge Base search
{"query", "target_ids"}
Matched chunk array with body and multi-dim scores
obtain_file
Fetch full file content
{"file_id", "max_tokens"}
File-level info (incl. Markdown presigned URL); full text in message.content
execute_sql
Run SQL (NL2SQL)
{"sql", "knowledge_base_id"}
SQL result rows; each row = _citation_index + query columns
After enabling in-chat file parsing in the console, you can pass a file mid-conversation. The file ID comes from the addFile (register file) endpoint. Full flow:
The Q&A pipeline is adapted for model-side context caching (KV Cache): the request prefix stays stable across multi-turn dialogue and multi-round tool calls, so cached input tokens are billed at a discounted rate and time-to-first-token drops. Two cache modes exist, and only one applies per request:
Implicit cache
Explicit cache
How to enable
On by default when the model supports it; cannot be turned off
Pass enable_cache_control: true in the request
Hit determinism
Non-deterministic; the system auto-detects common prefixes
Deterministic — a matching prefix is a hit
Cache creation cost
100% of input price (no extra charge)
125% of input price
Cache hit price
20% of input price
10% of input price
TTL
Non-deterministic; cleaned up by the system periodically
5 minutes, reset on every hit
Minimum cacheable length
1024 tokens
1024 tokens
Pricing ratios and TTL are subject to the official Model Studio docs — Context Cache and Explicit Cache Best Practices — and your console bill. Internal benchmarks put the implicit-cache hit rate at roughly 75% of explicit caching; this is an empirical figure, not an official metric.
The two cache modes are supported on different model sets. The model is configured on the platform side — this endpoint exposes no model-selection parameter — so which cache mode is available depends on the model your Q&A service actually runs on:
Model
Explicit cache
Implicit cache
qwen3.6-plus (current default)
Supported
Not supported
qwen3.6-flash
Supported
Not supported
qwen3.7-plus
Supported
Supported
The current default model qwen3.6-plus does not support implicit caching: without enable_cache_control, no cache is in effect at all and cached_tokens stays 0 — this is a model-side capability limit, not an endpoint defect. To gain cache benefits (lower cost + lower TTFT), turn on explicit caching. Only when the service runs on qwen3.7-plus does "implicit caching as a fallback" hold. For the model support list, refer to the "Supported models" section of the official explicit-cache doc.
Cache gains fall into two categories — intra-request gains are more stable and more significant than cross-request ones.Strongly recommended: multiple retrieval and reasoning rounds within one request. When one question triggers multiple tool-calling rounds (repeated semantic_search / execute_sql / section browsing plus intermediate reasoning), the cache breakpoint moves forward with each new tool result, and the previous round's full context (including retrieval results) becomes a stable prefix for the next. The more complex the question, the more retrieval rounds, and the longer the results, the greater the savings — unaffected by the 5-minute TTL or cross-request prefix drift.Recommended: cross-request reuse:
Scenario
Why
Multi-turn continuous dialogue
From the second turn on, the request hits the full history prefix of the previous turn; the longer the dialogue, the greater the gain
Long system prompt / large table schemas
Structured Knowledge Base schemas are stitched into the system prompt — large and stable within a session, ideal cache content
Repeated follow-ups on the same long document / session file
High share of stable prefix; create once, hit many times
Explicit caching is deterministic and unaffected by backend scheduling
Break-even: explicit caching costs 25% extra on first write and saves 90% on every subsequent hit — one hit is enough to beat no caching at all.Not recommended (no gain, or even more expensive):
Scenario
Why
One-shot single-turn short Q&A
Creates but never hits — you pay the 25% creation premium for nothing
Prefix shorter than 1024 tokens
Below the minimum cacheable length; nothing gets cached
Low-frequency calls spaced over 5 minutes apart
The explicit cache expires in 5 minutes; the next request re-creates it
Cross-request reuse in multimodal document scenarios
Image content blocks participate in prefix computation and easily diverge across requests; count only on intra-request gains
Switching Knowledge Bases / service configs every session
Different prefixes (schemas, KB info) cannot be reused
"Not recommended" only means explicit caching doesn't pay off there. Because the default model qwen3.6-plus doesn't support implicit caching, leaving enable_cache_control off doesn't fall back to implicit caching — it means no caching at all. If you still want some cache benefit in these scenarios, evaluate and enable it anyway.
The two cache modes are mutually exclusive: enable_cache_control: true means explicit caching only, no implicit caching. On the default model qwen3.6-plus there is no implicit cache, so leaving it off means no cache — not a "fallback to implicit".
No hit on the first turn is normal: any cache must be created first; cached_tokens=0 doesn't indicate a malfunction.
5-minute TTL for explicit cache: every hit resets it to 5 minutes; after a long pause, the next request re-creates the cache.
Tool-definition changes invalidate the cache: tool definitions are part of the system prompt used in cache computation. For structured Knowledge Bases, carrying search_filters suppresses the execute_sql tool — if filters come and go within one session, the tool list changes and the system prefix misses. Keep kb_search_configs stable within a session.
The prefix must be byte-for-byte stable: rebinding Knowledge Bases, changing service configs (e.g. custom instructions, the session-file switch), or a platform-side model change all alter the prefix and force cache re-creation.
Cross-request hits are unstable in multimodal scenarios: with image input, image content blocks participate in prefix computation and easily diverge across requests; gains in such scenarios come mainly from intra-request multi-round retrieval — don't estimate by cross-request hits.
Backtracking limit on very long turns: cache matching backtracks at most 20 content blocks from the breakpoint; extreme turns with many messages (multiple tool calls + image blocks) may exceed the range and miss.
Caches are isolated by account and model: no sharing across accounts, or across models within one account.
input_tokens ≠ created + hit: the backend appends a few tokens (usually under 10) after the prompt; they count toward total input but not toward cache statistics.
Add enable_cache_control: true and run a complex question that triggers multi-round retrieval; check whether the final frame's cached_tokens is greater than 0;
Follow up 2-3 more turns in the same session (within 5 minutes); check whether cached_tokens grows with history and compare time-to-first-token;
A/B against the same request without the parameter (baseline should be cached_tokens=0 on the default model), then decide whether to keep it on based on "When to use it".
The platform doesn't persist conversation state — pass the full messages history on every request. Cap history length (around the last 10 turns) to stay within the model's context window.
Message content. Either a string for plain text or a multimodal array of ContentPart (e.g. [{"type":"text","text":"..."},{"type":"image_url","image_url":{"url":"..."}}]).
Session file ID list, up to 10. Only takes effect after enabling in-chat file parsing in the console; file IDs are obtained via the addFile (register file) endpoint.
Whether to enable explicit context caching (KV Cache). When true, the request sets a cache breakpoint and deterministically hits the cache whenever the prefix matches — cached input tokens are billed at a discounted rate and time-to-first-token is reduced. When false (default), no breakpoint is set and any hit depends on the model's implicit caching capability. Only one cache mode applies per request; see Context caching.
Generated content / tool return content. During planning (thinking) it's the planning text stream; during generating it's the answer text stream; boundary frames can be an empty string. Can also be a multimodal array.
Additional kwargs. {} on assistant frames; on tool frames it carries extra_json — the structured tool result (for retrieval tools, a docs chunk array with body, document info, and scores).
Top-level phase — planning (with start and end events) or generating (with start and end events). During tool calling the top-level phase stays planning; only the finer-grained step switches to tool_calling.
Step transition event: plan_start / plan_end / tool_calling / tool_return / generation_start / generation_end, or empty (in progress). May be absent on empty frames.
Input tokens that hit the context cache, accumulated across the multiple model calls within this request. Always 0 for the first request of a session (the first request only creates the cache); should be greater than 0 from the second turn on. See Context caching.