简介这是一份面向AI应用开发者与知识库搭建者的万字教程PDF围绕AI Agent概念与字节Coze平台展开帮助零基础读者理解智能体原理并动手构建企业级知识库。内容从AI Agent定义与核心公式切入系统讲解LLM、规划、记忆、工具四大模块对比Copilot与Agent的差异并延伸至开源项目、行业应用、发展趋势及伦理法律等议题。资源包内含1个PDF文件大小约3.46MB结构完整、图文并茂适合按章节顺序通读或作为工具书查阅。教程以Coze为实操主线手把手演示知识库的创建、内容添加、维护更新等环节并配有具体示例读者可据此掌握从资料收集、大纲制定到内容编写与回顾修改的完整流程。目前已有324人学习适合希望快速入门AI Agent并落地企业知识库的开发者与产品人员参考。1. 扣子知识库到底解决什么问题从“文档堆成山”到“问答能落地”很多人第一次听到“基于扣子打造属于自己知识库”脑子里浮现的是把一堆 PDF 丢进去然后就能像跟专家聊天一样问什么答什么。真上手才发现文档传完了问一句“我们产品的退款政策是什么”它要么答非所问要么把三份不同版本的制度混在一起。问题不在模型笨而在于知识库这条链路里切分、召回、重排、提示词任何一环没调好结果都会翻车。扣子Coze这套东西的价值是把 RAG 知识库的工程复杂度压到普通人能操作的程度你不需要自己搭向量数据库、写检索服务只要把资料整理好、配好召回参数、把工作流串起来就能得到一个能回答私域问题的 Bot。它适合谁适合手里有大量内部文档、客服话术、产品手册、行业资料想让这些死资料变成可问答入口的人。这一篇不讲虚的从建库到工作流到避坑一步步拆开讲。2. 建库之前先想清楚知识库的三种范式与选型2.1 结构知识库、RAG 知识库、KG 知识库到底差在哪热词里经常出现“kg知识库、rag知识库和结构知识库区分以及应用场景”这不是学术讨论是选型问题。选错了后面怎么调都别扭。结构知识库本质是把信息存成表格或键值对查询靠精确匹配或 SQL。比如“各城市运费对照表”你问“上海到北京多少钱”它直接查表返回准确率接近 100%。缺点是只能回答你预先结构化好的字段问法稍微一变就查不到。RAG 知识库是把文档切块、向量化、存进向量库查询时先召回相似片段再交给模型生成。它擅长处理非结构化文本比如制度文档、产品说明、会议纪要。扣子默认走的就是这条路。它的软肋是“相似不等于正确”召回片段可能相关但不完整模型就会编。KG 知识库知识图谱是把实体和关系抽出来建成图适合“A 的上级是谁”“B 属于哪个部门”这类关系推理。构建成本最高一般业务用不上。我的建议很直接能用结构知识库解决的别上 RAG只有非结构化文本占主导时才用扣子的 RAG 知识库。很多团队一上来就全量 RAG结果表格类问题准确率惨不忍睹回头再补结构化查询白白多花两周。2.2 什么资料适合进扣子知识库什么资料别碰不是所有文档都值得进库。我一般按三条标准筛第一内容稳定。政策、手册、FAQ 这类半年不变的东西适合。每天变的价格表、库存表不适合进库第二天就过期。第二语义密度高。一份 50 页的 PPT有效信息可能就 3 页其余是图和过渡页。这种要先人工提炼成文字稿再进库否则切出来的块全是废话召回质量极差。第三有明确问答场景。你得先想清楚用户会问什么。如果连自己都不知道要问什么建完库也没人用。提示知识库图片怎么处理是高频问题。扣子的 RAG 知识库对纯图片支持有限图片里的文字信息建议先用 OCR 转成文本再入库或者用 imgunderstand 插件在工作流里单独处理图片理解不要指望向量检索能直接“看懂”图。2.3 建库前的资料预处理清单动手前把资料过一遍能省掉后面大量返工。我通常按这个清单走处理项具体动作目的去重删除同一文档的多个版本只留最新避免召回冲突答案转格式PDF/Word 统一转成纯文本或 Markdown提高切分质量去噪删页眉页脚、水印、广告、目录页减少无效块分段按语义手动分节每节一个主题让切分更准命名文件名体现内容如“退款政策_v3”便于溯源和更新这份清单看着笨但它是后面所有调优的地基。跳过这步直接上传后面召回不准你都不知道该怪谁。3. 在扣子里把知识库跑起来从上传到召回的最小闭环3.1 创建知识库与文档上传的实操步骤登录扣子后进入资源库找到知识库入口新建一个文本知识库。这里有个容易忽略的点知识库类型要选对。扣子提供文本、表格、图片等类型纯文档选文本结构化数据选表格别混着来。上传时支持单文件也支持批量。我一般先传 3 到 5 份核心文档做小范围验证跑通了再全量导入。全量导入一次几百份切分参数没调好等于白传。# 资料预处理示例把 PDF 批量转成纯文本本地用 pdftotext # 假设原始 PDF 都放在 ./raw_pdf 目录 mkdir -p ./clean_txt for f in ./raw_pdf/*.pdf; do # 提取文本-layout 保留基本排版便于后续按段落切分 pdftotext -layout $f ./clean_txt/$(basename $f .pdf).txt done # 检查转换结果空文件说明是扫描件需要走 OCR find ./clean_txt -size 0 -print这段脚本做两件事批量转换和空文件检查。-layout参数保留原始排版对后续按段落切分很关键最后一步找出大小为 0 的文件这些基本是扫描版 PDF纯文本提取拿不到内容必须走 OCR 路线否则传进去也是空块。3.2 分段与清洗决定召回质量的两个参数上传后进入分段设置。扣子一般提供自动分段和自定义分段。自动分段按固定字数切省事但容易把一句话切断。自定义分段可以按分隔符切我通常用换行符加标题符号组合。关键参数是分段长度和重叠长度。我的经验值分段长度500 到 800 字。太短信息不完整太长召回不精准。重叠长度分段长度的 10% 到 15%。防止答案正好卡在两段交界处被切断。举个例子一份 3000 字的制度文档按 600 字切、80 字重叠大概切成 6 段。如果某条规定跨了两段重叠部分能保证至少有一段包含完整语义。清洗环节别偷懒。页眉页脚、页码、“第 X 页共 Y 页”这类内容一定要在预处理阶段删掉否则每个块里都混着这些噪声向量化后相似度计算会被干扰。我见过最离谱的案例一份文档每页都有公司 slogan结果用户问任何问题召回的第一段都是那句 slogan。3.3 召回策略与参数Top-K、相似度阈值怎么设知识库配好后在 Bot 或工作流里调用时召回参数直接决定答案质量。核心三个Top-K召回多少个片段。设太小答案可能没被召回设太大噪声多模型容易被带偏。一般从 3 开始调简单问答 3 到 5 够用复杂问题可以到 8。相似度阈值低于这个分数的片段直接丢弃。设太低不相关的内容也进来设太高可能把正确答案也过滤掉。扣子里一般用默认值起步观察召回结果再微调。召回模式有向量召回、全文召回、混合召回。混合召回兼顾语义和关键词我一般优先选它尤其是文档里有大量专有名词时纯向量召回容易漏掉精确匹配。# 伪代码理解召回参数对结果的影响 # 假设 query 是用户问题chunks 是知识库所有片段 def retrieve(query, chunks, top_k5, threshold0.5): scored [] for chunk in chunks: # 计算 query 与片段的相似度向量点积或余弦相似度 score similarity(query, chunk) # 低于阈值的直接丢弃避免噪声进入上下文 if score threshold: scored.append((score, chunk)) # 按分数降序取前 top_k 个 scored.sort(reverseTrue) return [chunk for _, chunk in scored[:top_k]]这段伪代码说明两件事阈值是“过滤器”Top-K 是“截断器”。阈值先筛掉明显不相关的Top-K 再限制进入模型上下文的数量。调参顺序应该是先调阈值保证召回内容相关再调 Top-K 控制信息量。很多人反过来先猛加 Top-K结果上下文塞满噪声模型开始胡说。4. 用工作流把知识库变成能干活的能力4.1 扣子工作流的最小结构开始、知识库、大模型、结束光有知识库只能做简单问答。要让它自动生成公众号文章、处理图片、对接外部系统就得上工作流。扣子工作流的基本结构是开始节点接收输入中间节点做处理结束节点返回结果。一个典型的知识库问答工作流长这样开始节点接收用户问题。知识库节点用问题去召回相关片段。大模型节点把召回片段和问题一起塞进提示词生成回答。结束节点输出回答。看着简单但每个节点的配置都有讲究。知识库节点要选对知识库、设好召回参数大模型节点要写清楚提示词明确告诉它“只根据提供的资料回答资料里没有就说不知道”。4.2 提示词怎么写让模型只用知识库内容回答提示词是知识库问答的“后悔药”。写得好模型老老实实引用资料写不好它就开始自由发挥。我常用的模板结构你是一个基于知识库回答问题的助手。请严格遵守以下规则 1. 只根据下面提供的【参考资料】回答问题。 2. 如果参考资料中没有相关信息直接回答“根据现有资料无法回答”不要编造。 3. 回答时尽量引用资料中的原文表述保持准确。 4. 如果资料中有多个相关片段综合它们给出完整答案。 【参考资料】 {{knowledge}} 【用户问题】 {{question}}{{knowledge}}和{{question}}是变量分别由知识库节点和开始节点传入。这个模板的关键是第 2 条明确给出“无法回答”的出口。没有这条模型遇到资料里没有的问题大概率会硬编一个答案这在客服场景里是致命的。4.3 把知识库接进自动生成公众号文章的工作流热词里有人问“我想通过扣子制作一份能够自动生成公众号文章的能力该怎么设计提示词”。这其实是知识库加工作流的组合场景。思路是知识库提供素材和事实大模型负责组织成文。工作流可以这样设计开始节点接收主题关键词。知识库节点用关键词召回相关资料。大模型节点一根据资料生成文章大纲。大模型节点二根据大纲和资料扩写成正文。结束节点输出文章。提示词要分两步写。大纲阶段的提示词强调“基于资料提炼结构”正文阶段强调“基于资料和 outline 扩写不要引入资料外的信息”。这样生成的文章既有知识库的事实支撑又有可读性。注意自动生成文章这类场景知识库的召回质量直接决定文章可信度。如果召回的是零散片段模型会强行拼接读起来像缝合怪。建议针对写作场景单独建一个知识库里面放结构完整的素材而不是把客服 FAQ 直接拿来用。5. 避坑与排查知识库答不准的五个真实原因5.1 现象答案总是差一点召回片段不完整原因分段长度设得太大或太小。太大时一个块里混了多个主题向量化后语义被稀释太小时关键信息被切断召回的是半句话。解决把分段长度调到 500 到 800 字重叠 10% 到 15%。然后拿几个典型问题去测看召回片段是否包含完整答案。如果答案跨段适当加大重叠。5.2 现象问 A 答 B召回了不相关的内容原因相似度阈值设得太低或者文档里有大量重复的模板化内容比如每页都有相同的免责声明导致这些噪声片段相似度虚高。解决先提高相似度阈值观察召回结果。同时回到预处理阶段把重复的模板内容删掉。如果文档里专有名词多切换到混合召回模式让关键词匹配也参与打分。5.3 现象模型明明有资料却回答“不知道”原因提示词写得太死或者召回片段没被正确传入大模型节点。常见的是变量名写错知识库节点的输出没接到大模型节点的输入上。解决检查工作流连线确认知识库节点的输出变量正确传给了大模型节点。然后放宽提示词把“只根据资料回答”改成“优先根据资料回答资料不足时可结合常识补充但要说明哪些是资料外的内容”。5.4 现象更新了文档但回答还是旧内容原因知识库更新后没有重新向量化或者 Bot 缓存了旧版本。扣子里修改文档后一般需要重新处理不是保存就生效。解决更新文档后确认知识库状态变为“已处理”。如果还是旧答案检查是否有多个知识库被同时召回旧文档可能还在另一个库里。5.5 现象图片类问题完全答不了原因RAG 知识库对图片的理解能力有限纯图片或图片为主的文档文本提取拿不到有效内容。解决图片先用 OCR 转文本再入库。如果需要在对话中理解用户上传的图片用 imgunderstand 插件单独处理不要指望知识库召回。图片和文本走两条链路各司其职。6. 进阶用混合召回和重排把准确率再提一档基础版跑通后如果准确率还差口气可以上混合召回加重排。混合召回同时用向量相似度和关键词匹配打分对专有名词、型号、人名这类精确匹配场景提升明显。重排是在召回之后加一个精排模型对 Top-K 片段重新排序把最相关的顶到前面。扣子里如果原生不支持重排可以用工作流加一个代码节点或插件节点实现。思路是知识库召回 10 个片段用一个轻量模型对每个片段和问题的相关性打分取前 3 个再传给大模型。这一步会增加延迟但对准确率要求高的场景值得。# 伪代码召回后重排的简化逻辑 def rerank(query, candidates, top_n3): # candidates 是知识库初步召回的片段列表 scored [] for chunk in candidates: # 用更精细的相关性打分可以是交叉编码器或关键词覆盖度 score cross_encoder_score(query, chunk) scored.append((score, chunk)) scored.sort(reverseTrue) # 只保留最相关的 top_n 个减少大模型上下文噪声 return [chunk for _, chunk in scored[:top_n]]重排的核心价值是“精挑细选”。初步召回追求不漏重排追求精准。两步配合比单纯调 Top-K 有效得多。验证方法也简单准备 20 到 30 个典型问题记录每个问题的期望答案然后跑一遍看命中率。改一次参数跑一次对比命中率变化。别凭感觉调用数据说话。我自己踩过最深的坑是一开始图省事把所有文档一股脑传进去分段用默认值结果召回质量惨不忍睹调了两周才发现问题出在预处理。后来养成习惯先花半天整理资料再花半小时建库比反过来省至少三天。知识库这东西功夫在库外。希望帮到你。本文还有配套的精品资源点击获取