API docs by Redocly

对象实例查询 (0.1.3)

Download OpenAPI specification:

按对象类查询实例数据。Context Loader（服务名 agent-retrieval）在这里做的是 面向 Agent 的收口：接受结构化条件，转发给 ontology-query，再把结果按 Agent 能直接消费的形态返回。

典型链路：search_schema 拿到对象类与可用算子 → 本接口取实例 → 从每条记录的 _instance_identity 取标识 → 喂给 action.yaml 的 get_action_info 或 logic-property.yaml 的 logic-property-resolver。

翻页两条路，互斥：

  • search_after 游标翻页：适用于对象索引 / 数据视图路径，只能顺翻，不能跳页； 把上一页响应里的 search_after 原样回传即可，响应里没有该字段就是没有下一页。
  • offset 偏移翻页：适用于资源（vega 表源）路径，可跳任意页。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ AppKey）。

ObjectInstance

查询对象实例

按单个对象类查询实例。kn_id / ot_id 走 query 参数，过滤与分页走请求体。

条件两种写法：

  • filters：扁平简写，多个条件按 AND 组合，value_from 自动取 const。 覆盖「字段 op 值 [AND ...]」这类绝大多数场景。
  • condition：完整嵌套结构，需要 OR / 多层嵌套时用。

两者同传时 condition 优先，filters 被忽略。

算子白名单以对象类为准：可用算子看 get_object_types 返回的 condition_operations，不要照抄本文档的枚举全集。对绑定 Vega 资源的对象类， 这份清单由 BKN 按资源上真实建成的索引派生：字段建了全文索引才出现 match / multi_match，建了向量索引且 embedding 模型可解析才出现 knn。 没建索引的字段只保留按属性类型推导的比较算子。

文本检索选哪个：match 走全文索引，按分析器分词后词法命中；knn 走向量 索引，能召回字面不重合的表述（换个说法、跨语言）。两者是独立算子，没有隐式 融合；要同时用就放进 or 的 sub_conditions。knn 另需 limit_key: k 与 limit_value: <近邻数>。

条件里用了字段不支持的算子时，ontology-query 返回 400 并原样透传错误详情 （如 OntologyQuery.InvalidParameter.Condition）。

_score 的取舍：纯结构化过滤在底层落成常量打分查询，每条命中分数相同， 没有相关度语义，因此响应里的 _score 会被剥掉，避免调用方误以为结果按相关度 排序。只有查询里含 knn 或 match 这类真正打分的算子时才保留 _score。

排序：sort 可选，多字段按数组顺序依次比较（前一个相等才看后一个）。 不传时的默认序不保证语义——既不是「最新」也不是「最相关」，因此 「最近的 N 条」「金额最高的 N 个」必须显式传 sort，不能靠 limit 截默认序。 field 是否属于该对象类由 ontology-query 校验，非法字段或非法 direction 返回 400 并透传原因。

总数：响应的 total_count 为满足过滤条件的实例总数，不受 limit 限制， 无需请求方开启。判断「一共多少条」读它即可，不必翻页累加。三态要分清：

  • 有值且大于 0：真实总数。
  • 值为 0：真实零命中（字段存在）。
  • 字段缺失：本次没有计算总数，不能推断为 0。用 search_after 翻页时 第二页起即如此（下游在游标非空时强制关闭总数计算）。要总数就回到不带 search_after 的首次查询。
Authorizations:
OAuth2AppKey
query Parameters
kn_id
required
string

知识网络 ID。

ot_id
required
string

对象类 ID。

include_logic_params
boolean
Default: false

是否返回逻辑属性的计算参数。默认 false，结果不含逻辑属性字段与值； 逻辑属性求值请用 logic-property.yaml。

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 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

object (Condition)

过滤条件。逻辑算子（and / or）用 sub_conditions 组合子条件； 叶子条件用 field + operation + value + value_from。

value 与 value_from 必须成对出现，且 value_from 目前只支持 const。

Array of objects (FlatFilter)

扁平过滤简写，多个条件按 AND 组合。与 condition 互斥，同传时 condition 优先。需要 OR 或嵌套时改用 condition。

limit
integer [ 1 .. 10000 ]
Default: 10

返回条数。

properties
Array of strings

指定返回的属性字段；不传返回全部属性。

Array of objects (SortSpec)

排序字段，按数组顺序依次比较。不传时默认序不保证语义，需要「最新 / 最大 / 最小的前 N 条」时必须显式指定。

search_after
Array of any

游标翻页：上一页响应返回的 search_after 原样回传。首次查询留空。 与 offset 互斥。

offset
integer

偏移翻页：适用于资源（vega 表源）路径，可跳页。与 search_after 互斥。

Responses

Request samples

Content type
application/json
Example
{
  • "filters": [
    ],
  • "limit": 20,
  • "properties": [
    ]
}

Response samples

Content type
{
  • "datas": [
    ],
  • "total_count": 0,
  • "search_after": [
    ]
}

语义召回实例

用一句自然语言直接召回实例，不需要先知道对象类和字段名——这是 search_schema（只回 Schema）与 query_object_instance（要先给出结构化条件） 之间缺的那一步。

执行两段：先按 query 锁定相关对象类，再在这些对象类上做语义实例召回； 向量（knn）与全文（match）两路并发发出后按名次融合，因此两种命中都能进入结果。

自足：除实例行外，还附带读懂它们所需的对象类精简定义（object_types， 只含真正出了实例的那几个），单次调用就够用，不必再回头查 Schema。 只有 condition_operations 含 match / knn 的属性参与召回， 没建索引的对象类不会出实例。

无命中不是错误：返回空 nodes 加一句 message，不返回 5xx。

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

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

Request Body schema: application/json
required
kn_id
string

知识网络 ID。也可改用 X-Kn-ID 请求头传入。

query
required
string

自然语言问题或关键词。整句直接传，不必拆成字段条件——向量通道吃整句， 全文通道由分析器分词。

concept_groups
Array of strings

限定召回范围到指定的 BKN 概念分组；不传则在整个知识网络内召回。

object_types
Array of strings

把召回范围钉死在这几个对象类上，只取对象类 id（例如 material），不接受名称。 id 来自 search_schema 响应的 concept_id、本接口响应的 object_type_id 或 get_kn_detail 的 object_types[].id。不传则不限。 过滤发生在相关性排序与 max_object_types 截断之前，因此点名的对象类不会因为 排名靠后被挤掉。列表里的 id 一个都不存在时返回空 nodes，并在 message 里 列出这些 id。

exclude_object_types
Array of strings

从召回范围里排除这几个对象类，同样只取对象类 id。适合上一轮返回里混进了噪音 对象类、想重跑一次时用；与 object_types 有重叠时以排除为准。

max_object_types
integer >= 1
Default: 10

参与实例召回的对象类数量上限。每多一个对象类多一轮下游查询。

max_instances_per_type
integer >= 1
Default: 5

每个对象类最多返回几条实例。

rerank
boolean
Default: false

是否对召回结果做语义精排。默认关。开启后由 cross-encoder 逐条判断相关性并 重排返回顺序（score 不变，模型分单独落在 reranker_score， 见响应说明），能分辨名次融合分不出的语义差异。 代价是多一次模型调用（约 100~400ms），且要求部署里注册了精排小模型； 模型不可用时自动退回原顺序，不报错。

include_object_types
boolean
Default: true

是否附带命中对象类的精简定义。默认附带——不附带的话，要读懂返回的实例 还得再调一次 get_object_types，而那一趟会把同一个 query 的概念召回重跑一遍。

Responses

Request samples

Content type
application/json
{
  • "kn_id": "string",
  • "query": "string",
  • "concept_groups": [
    ],
  • "object_types": [
    ],
  • "exclude_object_types": [
    ],
  • "max_object_types": 10,
  • "max_instances_per_type": 5,
  • "rerank": false,
  • "include_object_types": true
}

Response samples

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