知识库选源与按需检索

本页阅读位置

完成第一轮对话后，按当前业务需求深入。Spring 常规声明优先使用 RegistrationManifest 与注解；本页的底层 register / publish 或直连方法供协议细化与兼容集成参考。

如何启用

将 knowledgeRouting 加入新的 Agent 精确版本；allowedKnowledge 仍是权限上限。没有该配置的旧版本继续逐库检索。先发布知识源，再保存并发布 Agent，新版本验证后再切默认入口。

json

{
  "allowedKnowledge": [{"id":"project-documents","version":"1.0.0"}],
  "knowledgeRouting": {
    "mode":"AUTO",
    "maxSources":2,
    "topK":8,
    "maxRetrievals":8,
    "maxQueriesPerSource":3,
    "sourceTimeoutSeconds":15,
    "sourceMaxChars":16000,
    "maxContextChars":16000,
    "failurePolicy":"FAIL_FAST",
    "rerank":"LEXICAL",
    "rules":[{
      "knowledge":{"id":"project-documents","version":"1.0.0"},
      "queryTerms":["安装","设备"],
      "contextEquals":{"projectType":"monitor"},
      "priority":10
    }]
  }
}

这是 Agent 定义的知识字段片段，完整定义仍需 systemPrompt 和 modelProfile。contextEquals 取自已认证 Context Provider 的返回值；聊天 context 中传同名字段不能使规则命中。先按身份与业务权限筛选来源，再路由，最后对文档实时鉴权。

选择模式

模式	启动行为	运行中检索
未设置 knowledgeRouting	旧逐库方式	不额外暴露知识函数
EAGER	在 maxSources 范围内检索授权来源	不暴露知识函数
AUTO	按规则或说明/标签匹配选源	暴露 knowledge_search
ON_DEMAND	不做启动检索	暴露 knowledge_search

AUTO 与 ON_DEMAND 要求所有模型候选声明 toolCalling=true，保存/发布兼容性预检会拒绝不支持或未知的候选。函数调用仍计入 Agent 的工具调用和模型步骤预算。

新路由仅对实际选中来源检查运行租约，未选中的库租约过期不阻断其他查询；选中来源租约不可用返回 KNOWLEDGE_UNAVAILABLE，可按失败策略处理。版本撤销与文档/业务撤权仍实时检查，旧未配置路由的 Agent 保持原租约行为。

知识定义可配置 description 和最多 16 个 tags，每标签最多 64 字符。Java/Kotlin 的 @AgentKnowledge(tags=[...]) 也生成该字段。自动匹配使用英文词项及中文双字；无匹配时不请求所有来源。

配置规则

knowledge：必须是 allowedKnowledge 中的精确 id/version，规则最多 64 条，同一版本不能重复。
queryTerms：最多 16 个不重复词项，查询包含任意词项即匹配；不区分大小写。
tags：最多 16 个；词项需同时出现在库标签和查询中。
contextEquals：最多 16 项字符串等值条件；仅读取服务端可信上下文。配置词项与上下文时，两组条件共同满足。
always=true：始终选择该来源；配置了可信上下文条件时，仍须满足这些条件。
priority：0–100，高优先级先选，同分按精确来源键稳定排序。

EAGER 不应用选源规则，直接按精确来源键稳定排序限量。AUTO 及 ON_DEMAND 的自动路由应用规则；模型显式指定 sources 时选择指定的已授权来源。规则不能作为额外权限约束，真正的数据隔离必须由业务授权与文档 ACL 执行。

规则至少有词项、标签、可信上下文或 always。没有显式规则的库按 description/tags 的查询匹配程度排序；可以给明确业务规则设置较高 priority。规则、标签与相似度均不能获得新的业务授权。

预算和融合

字段	默认	范围与含义
maxSources	4	1–16，每次路由最多来源数
topK	8	1–50，每次融合最多结果数
maxRetrievals	8	1–64，当前 Agent 调用实际来源请求总数
maxQueriesPerSource	3	1–16，当前调用每精确来源最多请求次数
sourceTimeoutSeconds	15	1–60，每次来源期限受 Agent/祖先较早期限约束
sourceMaxChars	16000	1–65536，每次来源结果的正文字符上限
maxContextChars	16000	1–65536，当前 Agent 调用新增引用正文的累计字符上限

这里统计正文字符，JSON 包装与 metadata 不在知识正文额度内，但仍受根 Agent 字符预算和模型上下文检查约束。每来源仍使用知识定义的 topK（1–10）。来源正文按剩余额度截取，剩余额度为零时不创建新引用。子 Agent 有自己的知识策略，步骤/工具/字符仍同时消费根与祖先额度。

先过滤租户、文档 ACL 与正匹配，再融合。融合采用 RRF：对各源排名加权，不把厂商不同分数直接相加；输出 fusionScore 为有限 0–1。NONE 保留融合次序，LEXICAL 再按查询词项匹配重排；它是可复测的词项重排，不是语义模型 Rerank。

结构化来源相同且正文指纹相同时合并；无结构化来源的不同库文档不只凭同名编号合并。重复检索仍重新请求并校验权限，已存在的引用可以复用原编号，不重复消费新增正文额度。原始供应商 score 保留，与融合排名分数分别展示。

按需知识函数

模型可调用 knowledge_search，参数仅包含查询与可选来源精确键：

json

{"query":"设备安装规范","sources":["project-documents@1.0.0"]}

省略 sources 时使用路由规则。指定来源必须仍属于当前授权的 allowedKnowledge；未知来源、错版本或重复键返回 KNOWLEDGE_SOURCE_DENIED，不会调用业务 Provider。模型不能通过函数传 appId、subjectId、tenantId 或可信上下文。

结果为 {"references":[...]}，每项含平台生成的 citationId、knowledge 精确引用、content 和可用的来源信息。结果作为不可信工具数据进入后续模型步骤，不提升工具权限。不匹配返回空 references；不能把模型自己编写的来源编号当可信引用。

Java 与 Kotlin

JavaKotlin

java

var routing = KnowledgeRouting.builder()
    .mode(KnowledgeRouting.Mode.AUTO)
    .maxSources(2).maxRetrievals(8).maxQueriesPerSource(3)
    .sourceTimeoutSeconds(15).maxContextChars(16000)
    .rerank(KnowledgeRouting.Rerank.LEXICAL)
    .rule("project-documents", "1.0.0", List.of("安装"), List.of(),
          Map.of("projectType", "monitor"), 10, false)
    .build();
// 完整 Agent 定义中加入 routing.definition()，同时保留 allowedKnowledge 精确引用。

kotlin

import dev.sparktide.sdk.KnowledgeRouting
import dev.sparktide.sdk.kotlin.knowledgeRouting

val routing = knowledgeRouting {
    mode = KnowledgeRouting.Mode.AUTO
    maxSources = 2
    maxContextChars = 16000
    rule("project-documents", "1.0.0") {
        queryTerms = listOf("安装")
        contextEquals = mapOf("projectType" to "monitor")
        priority = 10
    }
}
// 完整 Agent 定义中的 "knowledgeRouting" 使用 routing.definition()。

控制台与排障

在 Agent 配置选择“知识库选择与检索”，填写方式、各项上限、失败策略和规则。精确知识库版本必须同时已在 allowedKnowledge 中配置；新 Agent 保存后查看“模型兼容性”，再发布。知识库配置中可填写标签。

现象	检查方法
未选择某库	查看 knowledge.planned 的 sources/reason；核对词项、标签、可信上下文与 maxSources
成功但无引用	查看 knowledge.retrieved 是否 EMPTY、融合 count 和正文额度；无匹配不强塞文档
KNOWLEDGE_BUDGET_EXCEEDED	实际来源次数已达总数或单库上限；不自动重试
KNOWLEDGE_SOURCE_DENIED	sources 超过授权范围、错精确版本或重复键
单库暂时不可用	FAIL_FAST 终止；SKIP_TRANSIENT 仅跳过超时、不可用与限流
KNOWLEDGE_ACCESS_DENIED / PROTOCOL_ERROR	两种策略均终止，不能借部分成功绕过权限或协议验证

knowledge.planned 记录固定来源与原因，knowledge.retrieved 记录来源结果，knowledge.fused 记录最终数量、重排方式和当前检索/正文消耗，citation.created 可带 retrievalId、knowledgeVersion、fusionScore。客户端可直接通过 SDK 事件流读取；平台生成的事件、精确版本和现时授权是事实来源。

迁移与回滚

先新增精确 Agent 版本验证选源，不修改已发布版本。回滚切回旧 Agent 引用，保留调用记录及知识 ACL；不会重放已执行工具或模型调用。此配置不增加内置 PDF/OCR、向量检索或鉴权来源预览能力；这些能力有独立接入与实施边界。

文档来源与验证记录

状态：已确认；日期：2026-09-30；责任人：SparkTide 维护者；关联任务：K03；来源：KnowledgeRouting、ExecutionEngine、Registry 与后台 SDK；适用：0.1 发布线。

知识库选源与按需检索 ​

如何启用 ​

选择模式 ​

配置规则 ​

预算和融合 ​

按需知识函数 ​

Java 与 Kotlin ​

控制台与排障 ​

迁移与回滚 ​