Download OpenAPI specification:
Context Loader（服务名 agent-retrieval）的 Schema 探索入口：把一句自然语言
映射到知识网络里的概念（对象类 / 关系类 / 行动类 / 指标类），供 Agent
据此决定下一步调哪个查询接口。
两个端点的分工：
| 端点 | 定位 | 建议 |
|---|---|---|
POST /kn/search_schema |
标准契约，Schema-only | 新接入方用这个 |
POST /kn/kn_search |
兼容壳，吸收旧字段；可选开语义实例召回 | 仅存量调用方 |
search_schema 固定为 Schema-only：不返回实例数据，也不承担实例检索。
kn_search 默认同样只回 Schema，只有显式传 only_schema: false 时才在概念命中的
基础上做一轮语义实例召回，并把命中实例放在 nodes 里。参与召回的只有
condition_operations 里带 match / knn / == 的属性——没建索引的对象类不出实例。
拿到概念后，实例数据也可以走
object-instance.yaml、instance-subgraph.yaml，
或 data-access.yaml 的 run_sql。
响应格式：本模块所有端点都支持 ?response_format=toon，返回
application/toon（同构数组压成表格，比 JSON 省 token）；默认 json。
认证：Authorization: Bearer <token>，token 为 OAuth access token 或用户自助
签发的 AppKey（bak_ 前缀）。账户身份由服务端从凭据解析，调用方不需要也
不应该自己传 x-account-id。
统一的 Schema 探索入口。适用于还不确定该继续调用哪个 query_* / find_* /
get_* 接口时，先探索相关概念。
**写 SQL 时注意 include_columns**：data_properties[].name 是逻辑名，
物理列名在 mapped_field 里，二者可以不同（同一份资源可被多个对象类以不同
逻辑名映射）。要用 run_sql 直查时置 include_columns=true 拿物理列名。
| response_format | string Default: "json" Enum: "json" "toon" 响应格式。 |
| x-kn-id | string 知识网络 ID 的 header 形式，供无法改请求体的调用方（如 MCP 客户端固定
注入 header）使用；与请求体的 |
object (BKNContext) BKN Trace business-provenance context identifying the business
conversation and interaction to which this call belongs. Required on
MCP business tools and REST execution APIs while capture is enabled
and Trace Core is available;
optional on REST reads and Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded. Both required child fields are server-issued handles and must not be invented by the caller:
These handles are available only through the provenance MCP tool above.
The BKN Trace Core session APIs under | |
| query required | string 用户查询问题或关键词。 |
| kn_id | string 知识网络 ID。与 |
object (SearchSchemaScope) Schema 探索范围。不传时四类概念全开。四个开关不能同时为
| |
| max_concepts | integer >= 1 Default: 10 每类概念的候选规模上限。 |
| schema_brief | boolean Default: false 是否只返回精简 Schema；默认返回相对完整的 Schema。 |
| enable_rerank | boolean Default: true 是否对关系类做精排。 |
| rerank_model | string 覆盖本次请求的精排小模型名。运维 / 高级用户的逃生口，留空走部署级默认
（ |
| include_columns | boolean Default: false 是否在每个对象类的 |
| enum_query | string 按显示名或编码检索枚举项，多个词用空格隔开，任一词命中即返回。用于没有展开的枚举：
超过展开上限（默认 50 项）的大字典，以及精简模式下的所有枚举。不传时这些枚举只给
|
{- "kn_id": "kn_medical",
- "query": "最近半年哪些药品的不良反应上报最多"
}{- "object_types": [
- { }
], - "relation_types": [
- { }
], - "action_types": [
- { }
], - "metric_types": [
- { }
], - "nodes": [
- { }
], - "message": "string"
}兼容历史 kn_search 调用方式的接口。底层与 search_schema 共用同一套逻辑，
默认输出同样收敛为 Schema 结果。
兼容边界：
only_schema 缺省按 true 处理，行为与 search_schema 一致；显式传
false 才额外做语义实例召回，命中实例放在 nodes，无命中时给 message；retrieval_config 里只有 concept_retrieval.top_k、
concept_retrieval.schema_brief 会被吸收，其余字段被忽略。只要 Schema 的新接入方请直接用 POST /kn/search_schema。
| response_format | string Default: "json" Enum: "json" "toon" 响应格式。 |
object (BKNContext) BKN Trace business-provenance context identifying the business
conversation and interaction to which this call belongs. Required on
MCP business tools and REST execution APIs while capture is enabled
and Trace Core is available;
optional on REST reads and Naming it makes the call managed: the service records an Operation under that interaction and attempts to return a receipt and capture evidence. Omitting it entirely, or sending an empty object, makes an eligible REST read or proxy call ad hoc. Only those two shapes are ad hoc — one id without the other, or a misspelt field, is refused rather than quietly downgraded. Both required child fields are server-issued handles and must not be invented by the caller:
These handles are available only through the provenance MCP tool above.
The BKN Trace Core session APIs under | |
| query required | string 用户查询问题或关键词。 |
| kn_id required | string 知识网络 ID。 |
object (KnSearchScope)
| |
object or null 检索参数。
闸门自带模型：设了 阈值不可跨部署照抄：实测两套自有环境上，「明显相关」的精排分一套在 0.16 量级、 另一套在 0.74 量级。校准方法是各跑几条该网络答得上和答不上的 query，取两段分数之间的值。 精排不可用、或模型对所有候选给出同一个分数时，闸门不过滤并在 | |
| only_schema | boolean Default: true 缺省 |
| enable_rerank | boolean Default: true 是否对关系类做精排。 |
| rerank_model | string 覆盖精排小模型名；留空走部署级默认。 |
| include_columns | boolean Default: false 是否附带物理列名。 |
| enum_query | string 按显示名或编码检索未展开枚举的枚举项。 |
{- "kn_id": "kn_medical",
- "query": "药品不良反应",
- "only_schema": true,
- "retrieval_config": {
- "concept_retrieval": {
- "top_k": 5,
- "schema_brief": true
}
}
}{- "object_types": [
- { }
], - "relation_types": [
- { }
], - "action_types": [
- { }
], - "metric_types": [
- { }
], - "nodes": [
- { }
], - "message": "string"
}