导入与使用知识

知识库为智能体提供可引用的业务信息。已有业务检索服务优先用后台 @AgentKnowledge / KnowledgeProvider 接入，详见教程。上传资料和复杂检索按下面模式分流；不必先建设向量索引。根据数据规模和已有系统选择内联、托管或远程模式，再把发布版本加入智能体 allowedKnowledge。

选择模式

模式	适合内容	管理方式
INLINE	少量稳定规则与常见问答	代码声明稳定小型文档
MANAGED	需要独立导入的文本与 Markdown	通过 SDK 摄入并管理版本
REMOTE	已有检索、向量或文档处理服务	平台调用你的检索接口

内置检索支持词项与中文双字匹配。托管文件上传与解析支持 PDF、Office 和配置后的 OCR，参见文件摄入操作；托管知识可配置向量与混合检索，先完成当前模型空间的构建再发布；大容量外部向量服务仍可通过 REMOTE 接入。

内联文档

通过 CapabilityDefinition("knowledge", id, version, definition) 把内联文档放入后台清单；下例解释 definition 字段：

{
  "mode":"INLINE",
  "topK":3,
  "documents":[{"id":"refund-policy","title":"退款规则","text":"退款申请由客服核对订单状态后处理。","source":"https://business.example.com/help/refund","tenantId":"team-a"}]
}

每版本 1–100 篇，每篇正文不超过 16384 字符。source 用作引用来源，内容是否可信仍由业务负责。

托管文档

1. 后台 SDK 声明 mode:MANAGED 的知识草稿。
2. 使用 SDK 托管文档 / 文件摄入方法导入内容，查看任务与分块结果。
3. 核对文档和索引，再发布该知识版本。
4. 将精确版本加入智能体 allowedKnowledge 并发布智能体。

完整方法从托管文本与版本和文件摄入进入。控制台的“管理托管文档”是可选操作入口。

每篇最多 65536 UTF-16 字符，每版本最多 1000 篇。可以选择字符、段落或 Markdown 标题与代码块分块，先预览再导入；未配置时保持原 2000 字符策略。控制台每文件上限 256 KiB，每批最多 25 篇。已发布版本不可改写，新草稿可从有权读取的已发布原文重建，旧版本保留供回退。完整 Java/Kotlin API、重复处理、条件更新和批次结果见托管文档分块与版本运维。

远程检索

后台 @AgentKnowledge 声明知识 Provider，或在清单使用 REMOTE 定义完整 endpoint、secretRef 与 topK（1–10）。服务端请求含 query、topK 和可信应用、用户、租户身份，新版选择 1.0 协议，声明必须实施的业务过滤，返回带来源和分数的 items；旧源仍可使用 documents。配置、Java/Kotlin API、权限与错误见外部知识协议。

若使用业务端解析、向量索引或第三方知识系统，由 REMOTE 服务完成解析和检索，返回有限文本片段。平台不会自动为远程文档下载和解析附件。

租户隔离与引用

tenantId 为空表示应用内共享；非空文档仅提供给匹配租户。远程返回同样经过租户过滤，但远程服务自身仍要执行数据权限控制。

没有匹配内容时不强行加入引用。前端监听 citation.created 展示标题和来源；不要把引用事件当成外部网站内容已经被事实核验。

文档权限

知识发布后仍可按原文档标识设置用户、租户和角色范围或即时禁止访问。详见 文档权限，变更后请开始新会话。

多库选源与按需检索

多个业务库可以通过 Agent 的知识路由选择、融合和词项重排，并让智能体按需再次查询。配置、权限约束和 Java/Kotlin 接入见知识库选源与按需检索。

发布前检查检索效果

在管理托管文档页面使用当前真实身份调试命中、检查可读索引健康，并比较一或两个精确版本的召回率和排名。保存问题集后可在当前授权下复测；历史详情撤权后拒绝读取。完整操作与 SDK 示例见检索调试与版本评测。