API docs by Redocly

Schema 检索 (0.1.3)

Download OpenAPI specification:

Context Loader（服务名 agent-retrieval）的 Schema 探索入口：把一句自然语言 映射到知识网络里的概念（对象类 / 关系类 / 行动类 / 指标类），供 Agent 据此决定下一步调哪个查询接口。

三个端点的分工：

端点 定位 建议
POST /kn/search_schema 标准契约，Schema-only 新接入方用这个
POST /kn/kn_search 兼容壳，吸收旧字段；可选开语义实例召回 仅存量调用方
POST /kn/semantic-search 早期语义检索，带查询理解与实例样本 需要 query_understanding 时用

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。

SchemaSearch

探索知识网络 Schema

统一的 Schema 探索入口。适用于还不确定该继续调用哪个 query_* / find_* / get_* 接口时，先探索相关概念。

**写 SQL 时注意 include_columns**：data_properties[].name 是逻辑名， 物理列名在 mapped_field 里，二者可以不同（同一份资源可被多个对象类以不同 逻辑名映射）。要用 run_sql 直查时置 include_columns=true 拿物理列名。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

header Parameters
x-kn-id
string

知识网络 ID 的 header 形式，供无法改请求体的调用方（如 MCP 客户端固定 注入 header）使用；与请求体的 kn_id 二选一，请求体优先。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

query
required
string

用户查询问题或关键词。

kn_id
string

知识网络 ID。与 x-kn-id 头二选一，本字段优先。

object (SearchSchemaScope)

Schema 探索范围。不传时四类概念全开。四个开关不能同时为 false，否则返回 400。

search_scope 只约束响应输出，不阻断系统内部用相关线索辅助召回。

max_concepts
integer >= 1
Default: 10

每类概念的候选规模上限。

schema_brief
boolean
Default: false

是否只返回精简 Schema；默认返回相对完整的 Schema。

enable_rerank
boolean
Default: true

是否对关系类做精排。

rerank_model
string

覆盖本次请求的精排小模型名。运维 / 高级用户的逃生口，留空走部署级默认 （concept_search_config.rerank_model）。不建议由 Agent 自行选择模型名。

include_columns
boolean
Default: false

是否在每个对象类的 data_properties 上附带物理列名（取自 mapped_field）。 写 run_sql 需要物理列名时置 true；默认 false 以保持响应精简。

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_medical",
  • "query": "最近半年哪些药品的不良反应上报最多"
}

Response samples

Content type
{
  • "object_types": [
    ],
  • "relation_types": [
    ],
  • "action_types": [
    ],
  • "metric_types": [
    ],
  • "nodes": [
    ],
  • "message": "string"
}

探索知识网络 Schema（兼容接口）

兼容历史 kn_search 调用方式的接口。底层与 search_schema 共用同一套逻辑， 默认输出同样收敛为 Schema 结果。

兼容边界：

  • only_schema 缺省按 true 处理，行为与 search_schema 一致；显式传 false 才额外做语义实例召回，命中实例放在 nodes，无命中时给 message；
  • 实例召回失败不影响本次调用：降级为只回 Schema，不报错；
  • retrieval_config 里只有 concept_retrieval.top_k、 concept_retrieval.schema_brief 会被吸收，其余字段被忽略。

只要 Schema 的新接入方请直接用 POST /kn/search_schema。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

query
required
string

用户查询问题或关键词。

kn_id
required
string

知识网络 ID。

object (SearchScope)

语义检索范围（不含指标类开关）。

object or null

检索参数。concept_retrieval 下仅 top_k 与 schema_brief 被吸收； semantic_instance_retrieval 下的实例召回参数生效，其中与相关性直接相关的是：

  • instance_rerank_mode：off（默认）/ on / shadow。shadow 调模型但不改 顺序，只记录两个序的差异，用于在改默认值之前取证。
  • min_reranker_score：相关性闸门。低于该分的实例被丢弃；一条都不达标时返回空， 并在 message 里说明最高分是多少。传 0（默认）则沿用部署配置 instance_search_config.min_reranker_score，后者为 0 时闸门关闭。

闸门自带模型：设了 min_reranker_score 就会为本次查询开启精排——融合分表达的是 通道一致性而非绝对相关度（某通道第一名恒得 1.0），只有精排分能回答「这批到底相不相关」。 代价是每次实例查询多一次模型调用。

阈值不可跨部署照抄：实测两套自有环境上，「明显相关」的精排分一套在 0.16 量级、 另一套在 0.74 量级。校准方法是各跑几条该网络答得上和答不上的 query，取两段分数之间的值。

精排不可用、或模型对所有候选给出同一个分数时，闸门不过滤并在 message 里说明—— 没有判断就不能假装筛过。

only_schema
boolean
Default: true

缺省 true，只回 Schema。传 false 时在概念命中的基础上做一轮语义实例 召回，结果放在 nodes。只有 condition_operations 含 match / knn / == 的属性参与召回，因此没建索引的对象类不会出实例。

enable_rerank
boolean
Default: true

是否对关系类做精排。

rerank_model
string

覆盖精排小模型名；留空走部署级默认。

include_columns
boolean
Default: false

是否附带物理列名。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_medical",
  • "query": "药品不良反应",
  • "only_schema": true,
  • "retrieval_config": {
    }
}

Response samples

Content type
{
  • "object_types": [
    ],
  • "relation_types": [
    ],
  • "action_types": [
    ],
  • "metric_types": [
    ],
  • "nodes": [
    ],
  • "message": "string"
}

语义检索（含查询理解）

基于用户查询意图，返回知识网络中相关的概念。与 search_schema 的差别： 本接口可返回 query_understanding（改写后的查询、识别出的意图与查询策略） 和每个概念的 samples（实例样本），代价是链路更长。

只需要「有哪些概念」时用 search_schema 更省。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

mode
string
Default: "keyword_vector_retrieval"
Enum: "keyword_vector_retrieval" "agent_intent_planning" "agent_intent_retrieval"

检索策略。keyword_vector_retrieval 关键词 + 向量召回（默认，最快）； agent_intent_planning / agent_intent_retrieval 走大模型意图分析， 更准但更慢、更贵。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

query
required
string

用户自然语言查询。

kn_id
required
string

知识网络 ID。

previous_queries
Array of strings

历史查询，用于多轮场景下的查询改写。

object (SearchScope)

语义检索范围（不含指标类开关）。

max_concepts
integer
Default: 10

最大返回概念数量。

rerank_action
string
Default: "vector"
Enum: "default" "llm" "vector"

精排方式：vector 向量精排（默认），llm 走大模型精排。

rerank_llm_model
string

仅 rerank_action=llm 时生效；留空走系统默认大模型。

rerank_vector_model
string

仅 rerank_action=vector 时生效；留空走系统默认小模型。

return_query_understanding
boolean
Default: false

是否返回查询理解信息。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "kn_medical",
  • "query": "最近一年哪家药企的产品召回次数最多",
  • "return_query_understanding": true,
  • "max_concepts": 10
}

Response samples

Content type
{
  • "query_understanding": {
    },
  • "concepts": [
    ],
  • "hits_total": 0
}