API docs by Redocly

上下文加载 · 对象实例查询 API (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。

翻页两条路，互斥：

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

旧的 search_after 数组游标已不再接受：传了会被静默忽略，于是每次都拿回第一页。

认证：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。用 cursor 翻页时 第二页起即如此（下游在游标非空时强制关闭总数计算）。要总数就回到不带 cursor 的首次查询。
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
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 /mcp/proxy/.../call. A verified disabled capture policy admits business calls without this context because no Conversation or Interaction IDs are issued. A verified Trace Core infrastructure outage also admits unrecorded REST execution after a bounded, read-only availability probe.

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:

  • conversation_id: obtained from the Context Loader MCP tool bkn_start_interaction on the first turn
  • interaction_id: obtained from the Context Loader MCP tool bkn_start_interaction

These handles are available only through the provenance MCP tool above. The BKN Trace Core session APIs under /api/agent-observability/v1 accept gateway credentials only from trusted in-cluster services. They do not accept OAuth tokens or bak_ AppKeys; direct external calls receive 401 permission_denied. Context Loader derives the Operation idempotency identity on the server from request correlation, tool name, and normalized input. Callers must not submit operation_key. Network retries should reuse bkn-request-id or provide a stable X-OpenBKN-Client-Invocation-Id for the same logical call. This hint is used only for idempotency and has no role in identity, authorization, or data-isolation decisions.

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 条」时必须显式指定。

cursor
string

游标翻页：上一页响应返回的 cursor 原样回传，不透明字符串。首次查询留空。 与 offset 互斥。

offset
integer

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

Responses

Request samples

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

Response samples

Content type
{
  • "query_source": "local_index",
  • "datas": [
    ],
  • "total_count": 0,
  • "cursor": "string",
  • "effective_permissions": {
    },
  • "row_filter_applied": true
}

语义召回实例

用一句自然语言直接召回实例，不需要先知道对象类和字段名——这是 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"
}