扣子知识库实战：从文档到智能问答的RAG工程链路

简介：这是一份面向AI应用开发者与知识库搭建需求者的万字教程资源，围绕AI Agent概念与字节Coze平台展开，帮助零基础读者理解智能体原理并动手构建企业级知识库。内容系统梳理了AI Agent的核心公式——LLM、Planning、Memory、Tools四要素，对比Copilot与Agent在自主性、流程决策上的差异，并延伸至开源项目、行业应用、发展趋势及伦理法律等议题。资源包内含1个PDF文件，大小约3.46MB，结构完整、图文并茂，适合作为系统学习与实操参考。教程以Coze为落地工具，通过具体知识库案例手把手演示设置、内容添加与维护更新流程，读者可据此掌握从概念理解到定制化搭建的完整路径。目前已有324人学习，适合希望快速入门AI Agent并落地企业知识库的开发者与产品人员。

1. 扣子知识库：从一堆散落文档到能问答的智能体，中间差了什么

手里攒了几十份产品手册、会议纪要、客服话术，想用扣子做一个能自动回答问题的知识库智能体，结果上传完文档一测试，回答要么答非所问，要么干脆编造内容。这不是扣子不好用，而是从「有文档」到「能问答」之间，隔着一整套检索增强生成（RAG）的工程链路。扣子知识库的本质，是把文档切片、向量化、存进向量数据库，用户提问时先检索相关片段，再把片段塞进大模型上下文里生成回答。这条链路里任何一个环节参数没调对，最终效果都会打折扣。这篇内容面向已经上手扣子、想认真把知识库做扎实的从业者，从文档预处理一路讲到工作流编排和效果验证，每一步都给可复现的操作和参数建议。

2. 扣子知识库的底层链路：文档进来之后到底发生了什么

2.1 从上传到召回：四个阶段拆开看

很多人以为知识库就是「上传文档 → 提问 → 回答」三步，实际上扣子内部走的是四段式流程。

第一阶段是文档解析。扣子支持 PDF、Word、Markdown、TXT、CSV 等格式，上传后平台会先做文本抽取。PDF 里的表格、图片、双栏排版是解析翻车的高发区，扫描件如果没有 OCR 层，抽出来就是空白。常见做法是上传前自己先确认 PDF 能不能选中文字，不能选中的先过一遍 OCR 工具。

第二阶段是分片（Chunking）。扣子默认按固定长度切分，通常 500～800 字符一段，段间有重叠。分片大小直接决定检索粒度：切太碎，单段信息不完整，模型拿到半句话没法回答；切太大，一段里混了好几个主题，检索命中后噪声太多。我一般会把产品手册按章节标题切，会议纪要按发言人轮次切，客服话术按问答对切，而不是无脑用默认值。

第三阶段是向量化。每个分片经过 Embedding 模型转成一个高维向量，存进向量数据库。扣子平台内置了 Embedding 模型，不需要自己部署。这里的关键点是：向量化质量取决于分片文本的语义完整性，一段被拦腰截断的文字，向量表示本身就是模糊的。

第四阶段是检索与生成。用户提问时，问题先被向量化，然后在向量库里做相似度搜索，召回 Top-K 个最相关的分片，拼进 Prompt 交给大模型生成回答。Top-K 设太小可能漏掉关键信息，设太大则上下文里塞满无关内容，模型反而抓不住重点。

提示：扣子知识库的检索默认走语义相似度，不是关键词匹配。这意味着用户问「退货流程」时，文档里写的是「退款操作步骤」也能命中，但反过来，如果文档里用的是完全不同的术语体系，召回率会明显下降。

2.2 分片策略怎么选：三种场景的实操参数

分片没有万能参数，得看文档类型。下面是我在三种常见场景里验证过的配置思路。

场景一：产品手册 / 技术文档。这类文档结构清晰，有明确的章节层级。建议按标题层级切分，每个二级标题下的内容作为一个分片，如果单段超过 1000 字符再按段落二次切分。扣子支持自定义分段规则，可以用换行符和标题标记做分隔符。重叠长度设 50～100 字符，保证跨段落的句子不被截断。

场景二：客服话术 / FAQ。这类内容天然是问答对格式。一个问句加一个答句作为一个分片，不要拆开。分片长度通常在 200～400 字符，不需要额外重叠。如果话术里有变量占位符（比如「尊敬的{用户名}」），上传前先替换成通用表述，否则向量化时会引入噪声。

场景三：会议纪要 / 聊天记录。这类文本口语化严重，主题跳跃。建议先做一轮人工清洗，把无关的寒暄、重复内容删掉，再按话题段落切分。分片可以适当放大到 800～1200 字符，因为口语化文本单句信息密度低，需要更多上下文才能表达完整意思。

2.3 用扣子工作流串起知识库问答的最小链路

光有知识库还不够，得用工作流把「接收问题 → 检索知识库 → 生成回答」串起来。下面是一个最小可用的工作流配置思路。

在扣子工作流编辑器里，新建一个工作流，依次添加三个节点：

节点1：开始节点 - 输入参数：user_query（String，用户提问） 节点2：知识库检索节点 - 选择已创建的知识库 - 查询变量：引用开始节点的 user_query - Top-K：5（先设5，后续根据效果调整） - 相似度阈值：0.5（低于此值的结果不返回） 节点3：大模型节点 - 模型选择：按需选择（建议先用平台默认模型跑通） - 系统提示词： 你是一个基于知识库回答问题的助手。 请严格根据以下参考资料回答用户问题。 如果参考资料中没有相关信息，直接说「我没有找到相关内容」，不要编造。 参考资料： {{知识库检索节点的输出}} - 用户提示词：{{user_query}}

这段配置的逻辑是：开始节点接收用户输入，知识库检索节点拿问题去向量库召回相关分片，大模型节点把召回内容作为上下文生成回答。关键参数有两个——Top-K 和相似度阈值。Top-K 控制召回数量，相似度阈值控制召回质量。初期建议 Top-K 设 5、阈值设 0.5，跑一批测试问题后看召回内容是否相关，再微调。

注意：系统提示词里那句「如果参考资料中没有相关信息，直接说没有找到」非常重要。不写这句话，模型在召回内容不相关时会强行编造答案，这是知识库问答最常见的翻车方式。

3. 把知识库接进智能体：从单轮问答到多轮对话的配置细节

3.1 智能体编排里知识库节点的挂载方式

工作流跑通之后，下一步是把知识库能力挂到智能体上。扣子的智能体编排页面里，知识库是作为一个能力开关存在的。打开知识库开关，选择已创建的知识库，智能体在对话时就会自动调用检索。

但这里有个容易忽略的点：智能体模式下，知识库的调用时机是由模型自己判断的。用户说「你好」时模型不会去检索，用户问「退货政策是什么」时才会触发。这个判断依赖模型的意图识别能力，如果发现该检索的时候没检索，可以在智能体的提示词里加一句「当用户问题涉及产品、政策、流程等具体信息时，必须先检索知识库再回答」。

另一种更可控的方式是不用智能体的自动知识库开关，而是在工作流里显式挂载知识库检索节点，然后把工作流发布为智能体的技能。这样每次调用都会走检索，不会出现「模型觉得不需要查」的情况。两种方式各有适用场景：自动模式适合开放域对话，显式模式适合客服、技术支持这类必须基于知识库回答的场景。

3.2 多轮对话里怎么保持上下文不丢

单轮问答跑通后，多轮对话是下一个坎。用户先问「退货政策是什么」，接着问「那运费谁出」，第二句话里没有「退货」这个关键词，如果检索时只拿第二句话去搜，很可能召回无关内容。

解决办法是在检索前做一轮查询改写。扣子工作流里可以加一个大模型节点，专门负责把多轮对话压缩成一个独立的检索查询。配置思路如下：

节点：查询改写（大模型节点） - 输入：对话历史 + 当前用户输入 - 提示词： 根据以下对话历史，将用户的最新问题改写成一个独立的、 包含完整语义的检索查询。只输出改写后的查询语句，不要解释。 对话历史：{{对话历史变量}} 最新问题：{{user_query}} - 输出：rewritten_query（String） 节点：知识库检索 - 查询变量：引用 rewritten_query

这样「那运费谁出」会被改写成「退货时运费由谁承担」，检索命中率会明显提升。查询改写节点会增加一次模型调用，有延迟成本，但在多轮场景下这个代价值得花。

3.3 知识库更新后怎么让智能体同步生效

文档不是一成不变的。产品更新了手册、客服话术改了版本，知识库也得跟着更新。扣子知识库里，新增文档会自动向量化并入库，但删除旧文档后，对应的向量数据需要手动触发重新索引，否则旧内容仍然会被检索到。

我一般会养成一个习惯：每次批量更新文档后，在知识库管理页面点一次「重新索引」，等索引状态变成「已完成」再去测试。另外，如果更新频率高，建议给文档加版本号或日期前缀，比如「产品手册_v2.3_20250101」，这样在检索结果里能直观看出召回的是哪个版本的内容，排查问题时省很多事。

4. 避坑与排查：知识库效果不好的五个真实原因

4.1 召回内容相关但回答跑偏

现象：检索出来的分片确实和问题相关，但模型生成的回答答非所问，或者把多个分片的内容混在一起说。

原因：通常是系统提示词没有约束模型的回答范围。模型看到多段参考资料时，倾向于把所有内容都塞进回答里，而不是只提取和问题直接相关的部分。

解决：在系统提示词里加一条「只使用与用户问题直接相关的参考资料，不要把所有参考资料的内容都复述一遍」。另外可以把 Top-K 从 5 降到 3，减少干扰。

4.2 相似度阈值设太高导致召回为空

现象：用户问了一个知识库里明明有答案的问题，但模型回答「没有找到相关内容」。

原因：相似度阈值设得过高（比如 0.8），而用户提问的措辞和文档表述差异较大，向量相似度没达到阈值，检索结果为空。

解决：先把阈值降到 0.4～0.5 测试，看召回内容是否相关。如果降阈值后召回内容质量下降，说明问题出在分片或 Embedding 质量上，而不是阈值本身。扣子的检索日志里能看到每次召回的相似度分数，对着日志调比盲猜快得多。

4.3 PDF 里的表格和图片内容丢失

现象：上传的产品规格 PDF 里，表格中的参数在回答时完全查不到。

原因：扣子默认的 PDF 解析器对表格和图片的处理能力有限，表格内容可能被解析成乱序文本，图片里的文字直接丢失。

解决：表格内容建议手动转成 Markdown 表格或 CSV 再上传。图片里的文字先用 OCR 工具提取成文本，作为补充文档一起上传。如果 PDF 本身就是扫描件，必须先过 OCR，否则上传后解析出来是空的。

4.4 知识库文档多了之后检索变慢

现象：知识库里文档从几十份增加到几百份后，每次问答的响应时间明显变长。

原因：向量库的检索耗时随数据量增长而增加，同时 Top-K 召回后塞进模型上下文的内容变多，模型推理时间也变长。

解决：一是控制单次召回的分片总长度，扣子工作流里可以在检索节点后加一个文本截断节点，限制总字符数不超过 2000。二是如果文档量确实大，考虑按业务线拆成多个知识库，智能体根据用户问题先路由到对应知识库再检索。

4.5 同一个问题每次回答不一样

现象：用户问同一个问题，两次回答的内容有差异，有时候甚至矛盾。

原因：大模型生成本身有随机性（temperature 参数大于 0），加上每次召回的分片可能略有不同，导致回答不稳定。

解决：在模型节点把 temperature 调到 0 或接近 0，让生成结果尽量确定。同时在系统提示词里明确「如果多个参考资料之间有矛盾，以日期最新的为准」，给模型一个冲突消解规则。

5. 让知识库回答更准的两个进阶技巧

5.1 用重排序把最相关的分片顶到前面

扣子知识库默认只做向量相似度检索，但向量相似度高不等于语义相关度高。一个有效的补充手段是加一个重排序（Rerank）环节：先召回 Top-10 个分片，再用重排序模型对这 10 个分片按与问题的实际相关度重新打分，取前 3 个塞进模型上下文。

扣子工作流里可以通过插件市场找重排序插件，或者用 HTTP 请求节点调用外部重排序服务。配置思路是：知识库检索节点 Top-K 设为 10，后面接重排序节点，重排序节点输出 Top-3，再传给大模型节点。这样做的代价是多一次模型调用，但召回精度提升明显，尤其是在文档量大、主题分散的场景下。

5.2 用测试集量化知识库效果，而不是凭感觉

知识库调优最怕凭感觉。「感觉回答还行」和「回答准确率 85%」是两回事。建议建一个最小测试集：从真实用户问题里挑 30～50 个，每个问题标注正确答案所在的那份文档和段落。然后跑一遍自动测试，看每个问题召回的分片里是否包含标注段落，以及最终回答是否正确。

扣子本身没有内置的批量测试工具，但可以用工作流的 API 接口写一个简单的 Python 脚本批量调用：

import requests # 替换为你的工作流 API 地址和 Token API_URL = "https://api.coze.cn/v1/workflow/run" TOKEN = "your_token_here" test_cases = [ {"question": "退货需要几天内申请？", "expected_doc": "售后政策_v2"}, {"question": "企业版最多支持多少人？", "expected_doc": "产品定价表"}, # 补充更多测试用例 ] for case in test_cases: resp = requests.post(API_URL, json={ "workflow_id": "your_workflow_id", "parameters": {"user_query": case["question"]} }, headers={"Authorization": f"Bearer {TOKEN}"}) result = resp.json() # 检查返回内容中是否包含预期文档的关键信息 print(f"问题：{case['question']}") print(f"回答：{result.get('data', {}).get('output', '')}") print("---")

这段脚本的逻辑是：把测试问题逐个发给工作流 API，收集回答，人工或自动比对是否命中预期内容。参数说明：workflow_id在扣子工作流发布后的 API 页面能拿到，parameters里的 key 要和开始节点的输入参数名一致。跑完一轮后，把召回失败和回答错误的问题单独拎出来分析，是分片问题、阈值问题还是提示词问题，针对性修。

我自己的习惯是每次调整知识库配置后都跑一遍这个测试集，记录准确率变化。有一次把分片长度从 500 调到 800，准确率从 72% 涨到 86%，但也有一次调完反而降了，后来发现是某几份文档的格式特殊，统一参数不适用。这种问题不跑测试集根本发现不了。希望帮到你。

本文还有配套的精品资源，点击获取