知识库

知识库 用于从指定知识库中检索与查询内容相关的文档片段，支持语义检索、策略选择等多种检索方式，并可配置召回数量等参数。它常用于智能问答、上下文增强与内容推荐，能有效补充模型知识、减少幻觉。

指令标识：KnowledgeBase
指令类型：基础节点
指令描述：从知识库中检索相关内容，支持多种检索策略和配置

先选使用方式

工作流支持「可视化编排」和「代码编排」两种创建方式。知识库 在两种方式里都能用，核心业务参数一致，区别主要是你通过界面配置，还是通过 Python 脚本配置。

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「知识库」节点，选择目标知识库并填写查询内容	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 `bots.knowledgeBase(kbId=123456, queryStr="...", outKey="...")`	熟悉代码、需要复用脚本或批量生成流程的用户

第一次使用建议先用可视化编排跑通，再迁移到 Python 代码编排。下方「参数说明」同时给出界面字段和代码参数名，方便两种方式对应。

什么时候用？

需要根据用户问题从企业知识库中检索相关答案或参考资料。
需要为大模型提供相关背景知识和上下文，提升回答质量和时效性。
需要基于用户查询从知识库中推荐相关文档、资料或内容。

使用前确认

已确定目标知识库（知识库 ID），且工作流与知识库在同一空间。
目标知识库已发布（未发布的知识库无法被检索）。
已准备好查询内容（queryStr 不能为空）。
已规划好用于保存检索结果的输出变量。

可视化编排：从 0 到跑通

下面用一个常见场景演示：根据用户问题从知识库检索答案。按 4 步即可跑起来：

在工作流画布中添加 知识库 指令。
在右侧配置面板选择 知识库 ID 并填写 查询内容：

知识库 ID：123456
查询内容：如何办理退货手续

按需设置 召回策略 ID 与 最大召回数量。
在 将结果保存至 填写变量名（例如 kbResult），点击运行查看检索结果。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
知识库 ID	`kbId`	Long	是	-	要查询的知识库唯一标识 ID，不能为空，例如 `123456`
召回策略 ID	`strategyConfigId`	Long	否	-	知识库召回时使用的策略配置 ID，用于指定召回策略和算法，例如 `789`
最大召回数量	`topK`	Integer	否	-	限制返回的知识条目最大数量，默认返回所有匹配结果，例如 `10`
输入参数	`queryStr`	String	是	-	查询知识库的提示词或问题内容，不能为空，例如 `如何办理退货手续`
出参	`outputList`	String(JSON)	否	-	输出参数定义，JSON 格式，定义要获取的变量名列表（包括 `resultList`、`output`）
是否发送消息	`sendMsgFlag`	Boolean	否	true	是否在节点运行时发送消息

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	`outKey`	String	否	存储知识库查询结果的输出变量名，包含结果列表和首条结果文本，例如 `kbResult`

通过 outputList 定义的变量名（默认包含 resultList、output）可在后续流程中引用：

变量名	类型	说明
`resultList`	Array<Object>	检索结果列表，包含匹配的文档片段及相关信息
`output`	String	检索结果的文本拼接，将所有片段内容合并为一个字符串

resultList 数组元素字段说明：

字段名	类型	说明
`reRankScore`	Float	重排后的相关度分数，如 0.684931
`score`	Float	原始检索的相关度分数，如 0.654572
`docId`	String	文档片段的唯一标识 ID
`rank`	Integer	检索结果的排名位置，从 1 开始
`text`	String	检索到的文档片段内容文本
`retrievalModel`	Integer	检索模型标识，如 1 表示语义检索
`source`	Object	文档来源信息，包含数据集、文件等元数据
`nodeId`	String	节点 ID

成功标准

运行日志中没有空间、发布或参数相关错误。
输出变量中 resultList 包含匹配的文档片段。
output 变量中包含拼接后的检索文本。

失败排查

现象 / 报错原文	可能原因	处理建议
找不到可选的知识库	工作流与知识库不在同一空间，或未发布	确认两者在同一空间，且知识库已发布
检索结果为空	召回数量过少、检索模式不匹配，或库内无相关信息	调整召回数量与策略，或补充知识库内容
召回不准确	文本分段粒度不当或相关度系数设置不合理	优化文本分段，调整召回策略与相关度系数
返回内容过多影响性能	召回数量设置过大	合理设置 `topK`，必要时采用分页加载

Python 代码编排

代码编排以 Python 为主。运行上下文由代码编排模板创建，示例里只需要关注业务指令本身。

# 从知识库检索相关内容，结果保存到 kbResult
bots.knowledgeBase(
    kbId=123456,
    queryStr="如何办理退货手续",
    outKey="kbResult",
)

如需指定召回策略和召回数量：

bots.knowledgeBase(
    kbId=123456,
    strategyConfigId=789,
    topK=10,
    queryStr="如何办理退货手续",
    sendMsgFlag=False,
    outKey="kbResult",
)

可视化表单里的「知识库 ID」「召回策略 ID」「最大召回数量」「输入参数」「将结果保存至」分别对应代码里的 kbId、strategyConfigId、topK、queryStr、outKey。

如果你想在工作流中通过节点动态编排指令，可使用执行指令（XML）节点。

常见问题

Q1：知识库召回效果不准确怎么办？

A：可从以下方面调整：

优化策略	优化说明
文本分段	分段粒度过大或过小都会影响召回，过大引入无关内容，过小导致召回不全面
召回策略调整	尝试不同的召回策略，根据场景选择合适的检索方式和算法
调整相关度系数	过严格可能召回过少，过宽松可能引入噪声

Q2：无法在节点中找到要用的知识库？

A：检查工作流和知识库是否在同一空间（只能配置自己空间内的知识库），并确认知识库已发布。

Q3：检索结果如何在流程中使用？

A：通过 resultList 获取结构化片段，通过 output 获取拼接文本，便于后续判断、展示或自动化处理。

知识库