扣子(coze)知识库的两个坑

扣子知识库的隐藏陷阱：智能体开发中的实战经验总结

前两天打算做两个给学员答疑用的「课代表」智能体，想着扣子API挺完善的，准备把它们搭在扣子上。折腾一天之后，现在相当庆幸没提前付费——哪怕是那个9.9/月的版本。

坑一：按层级分段

先说说我们尝试的一个简单场景：把课程视频用通义听悟提炼出逐字稿，里面包含当节课程概要、关键问题、PPT摘录等内容，然后传到扣子知识库里做个智能体。当学员有问题时，这个「课代表」智能体可以简单回答，还能告诉学员这个知识点在哪节课有详细讲解。

导出的 md 文档长这样：

可以说相当完美了：第一，是非常标准的 Markdown 层级关系，可以直接按层级来分段；第二，一共三级，正好符合扣子最大分段层级数。

把资料导进知识库，选了层级分段，也勾选了“检索切片保留层级信息”，结果最终结果直接不可用。

问题出在哪？如果对“检索切片保留层级信息”的理解没错，它应该是把文档的所有第3层（五级标题+正文）切片作为分段，当检索到当前切片时，应该返回当前片段 + 上层标题 + 上上层标题。嗯，这才是关键所在。

但实际情况完全不是这样。它实际的切片逻辑是：把你选择的层级数以下的内容作为分段。比如上面文档包含一级标题、二级标题、五级标题和正文一共四级，如果选择了3层，它会把所有五级标题（不含）以下的正文层级作为片段存在知识库中。某个片段被检索命中后，召回的是当前片段和上面的五级标题，再之前的二级标题和一级标题不返回。

下图是检索结果，可以看到知识库输出的 output 里包含一段内容+最后一个单独的段落文本。

希望官方能把文档写明白，懒得写的话，直接用我上面的介绍也行。给其他开发者闭个坑。

这个坑还算好，写个脚本自己处理一下也就解决了。分享一下最终的解决方案：因为需要智能体最终给出问题讲解课程所在的章节（也就是一级标题），所以直接用 Python 写了脚本。最终处理后的文档自带分隔符，每个分段包含所有上层标题。

坑二：标签不能用

直接说第二个坑：如果你的资料里包含 标签，传到扣子知识库会被直接“吃掉”，并且导致自定义的分段分隔符失效。看截图：整理的 标签直接被吃掉，选择的自定义分隔符 $$ 也直接不起作用了，整个分段直接不可用。

在分段预览里 不显示可以理解，毕竟被前端解析掉了，但自定义分段标识符以及标签内的文本也都不见了，这个就有点迷了。对比一下 Dify 的处理结果，虽然也有一个 bug（分段后会吃掉第一个 < 标签），但信息一个也没落下，预览只是“吃掉”了标签，信息本身没缺失。

就这个 BUG，真的是越专业越没法弄。这次使用 标签来预处理资料，单纯是让 AI 写 Python 脚本时临时起意，不用 XML 也完全可以实现。偶然发现这么一个 BUG 也好，希望还没动工的开发者能提前避坑。当然，更希望官方能优化一下，或者至少在文档里加粗标注提示一下。