简介这是一份面向AI应用开发者与知识库搭建者的万字教程PDF围绕字节跳动Coze平台展开帮助零基础读者理解AI Agent概念并动手构建企业级知识库。内容从AI Agent定义与核心公式切入系统讲解LLM、规划、记忆、工具四大模块对比Copilot与Agent的差异并延伸至开源项目、行业应用、发展趋势及伦理法律议题。教程以Coze为实操主线通过具体知识库案例手把手演示设置、内容添加与维护更新流程兼顾理论框架与落地方法。资源包为1个PDF文件大小约3.46MB结构紧凑便于通读与检索。目前已有324人学习适合希望系统掌握AI Agent原理、快速上手Coze搭建专属知识库的开发者与内容管理者参考。1. 从一堆散落文档到能问答的知识库扣子这条链路到底值不值得走手里攒了几十份 PDF、上百篇公众号文章、还有一堆会议纪要想搭个能问答的知识库第一反应往往是去翻 RAG 的论文和开源框架。但真上手会发现光是把文档切块、向量化、接检索、拼提示词这一套跑通就得折腾好几天更别提后面还要调召回率、处理图片、接工作流。扣子Coze这套东西的价值就在这儿它把知识库的切片、向量化、检索、和大模型对话编排打包成了可视化流程你上传文档、配好工作流就能得到一个能回答问题的 Bot。这份万字教程覆盖的正是从零搭建知识库的完整路径适合手里有资料、想快速做出可用问答系统、但不想从零写 RAG 管线的从业者。它不解决“知识库底层原理”这种问题它解决的是“我明天就想让团队用上这个东西”。2. 扣子知识库的底层逻辑切片、向量化与召回到底怎么配2.1 为什么不是“上传就完事”知识库的三段式处理很多人以为把 PDF 拖进扣子知识库就结束了实际上后台跑的是标准 RAG 流程文档解析 → 文本切片 → 向量化入库 → 检索召回 → 拼进提示词。扣子的封装让前三步变成自动的但自动不代表不用管。切片粒度直接决定召回质量切得太碎单块信息不完整模型拿到半句话没法回答切得太粗一块里混了好几个主题检索时命中率反而下降。常见做法是中文文档按 300500 字切英文按 500800 token 切段落之间保留一定重叠避免关键信息被切断。扣子默认的切片策略对结构清晰的文档够用但如果你上传的是扫描件或者排版混乱的 PDF解析出来的文本本身就是乱的后面怎么切都救不回来。向量化这一步扣子用的是平台内置的 embedding 模型你不需要自己选。但要注意不同 embedding 模型对中文语义的捕捉能力差异很大扣子目前对中文的支持在通用场景下够用如果你的知识库涉及大量专业术语或行业黑话检索效果可能会打折扣。这时候可以考虑在扣子里接入自定义的 embedding 插件或者把专业术语在文档里做一次标准化替换降低模型理解成本。检索召回是最后一道关。扣子知识库支持按相似度召回你可以设召回条数一般设 35 条比较稳。设太少模型拿不到足够上下文设太多无关内容会干扰生成。这里有个血泪经验召回条数不是越多越好我见过有人设 10 条结果模型把不相关的段落也拼进去了回答反而变差。正确做法是先设 3 条跑一轮看回答质量再决定要不要加。2.2 在扣子里建第一个知识库从入口到上传的完整操作打开扣子平台进入工作空间左侧菜单找到“知识库”入口。点“创建知识库”填名称和描述描述写清楚这个库是干什么的后面在工作流里选库时不容易搞混。创建完进入上传界面支持 PDF、Word、TXT、Markdown 等格式也支持直接粘贴文本。上传时注意文件大小限制单个文件别超过平台规定的上限大文件先拆再传。上传后扣子会自动解析和切片你可以在文档列表里看到每个文件被切成了多少段。点进任意一段可以预览切片内容这一步一定要做。我见过太多人上传完直接下一步结果检索效果差回头才发现切片把表格切成了乱码。如果发现切片质量差可以调整切片规则比如按段落切还是按固定长度切扣子提供了基础的自定义选项。# 这不是扣子的命令而是我本地预处理文档的常用脚本 # 把 PDF 转成纯文本去掉页眉页脚再传给扣子 python -c import fitz doc fitz.open(manual.pdf) for page in doc: text page.get_text() # 去掉每页重复的页眉 text text.replace(内部资料 请勿外传, ) print(text) cleaned.txt这段脚本做的是上传前的预处理。扣子虽然能解析 PDF但对页眉页脚和复杂排版的容忍度有限提前在本地把噪音去掉切片质量会明显提升。fitz是 PyMuPDF 的导入名get_text()按页提取文本replace那行是去掉每页重复出现的页眉文字。如果你没有 Python 环境用在线工具或者直接复制粘贴也行核心思路是别让格式噪音进入知识库。2.3 知识库参数怎么调切片长度、召回条数与相似度阈值扣子知识库在创建后可以调整部分参数但入口藏得比较深在知识库设置里。切片长度一般不用改除非你的文档特别短或者特别长。召回条数建议从 3 开始跑几轮问答看效果。相似度阈值这个参数很多人忽略它决定检索时低于多少分的片段直接丢弃。设得太低无关内容会被召回设得太高可能一条都召不回来。常见做法是先不设阈值观察召回片段的相似度分数分布再把阈值卡在分数明显下降的位置。参数建议值说明切片长度300500 字中文文档适用英文可适当加长重叠长度50100 字避免关键信息被切断召回条数35 条先设 3不够再加相似度阈值0.50.7根据实际分数分布调整调参这件事没有万能公式不同文档类型、不同问题类型最优参数都不一样。我一般会准备 10 个典型问题每调一次参数就跑一遍记录回答准确率找到局部最优就停。别追求完美知识库是迭代出来的不是一次配好的。3. 把知识库接进工作流从问答 Bot 到自动生成公众号文章3.1 工作流节点拆解知识库检索 大模型生成怎么串扣子的工作流是可视化编排核心节点就几个开始节点接收用户输入知识库节点做检索大模型节点负责生成回答结束节点输出结果。听起来简单但串的时候有几个细节决定成败。知识库节点需要选库和设召回参数这里和前面知识库设置里的参数是联动的但工作流里可以覆盖。我一般会在工作流里把召回条数设得比知识库默认值稍大一点因为工作流里可以加一个“筛选节点”做二次过滤。大模型节点的提示词是关键不能只写“根据知识库回答”要明确告诉模型如果知识库没有相关内容就回答“我不知道”不要编。这个约束能大幅降低幻觉。// 扣子工作流里大模型节点的提示词模板简化版 const prompt 你是一个基于知识库的问答助手。请严格根据以下知识库片段回答用户问题。 如果知识库片段中没有相关信息直接回答“根据现有资料无法回答该问题”不要编造。 知识库片段 {{knowledge}} 用户问题{{question}} ;这段提示词的核心是两条约束一是“严格根据”二是“没有就说没有”。{{knowledge}}和{{question}}是扣子的变量占位符分别由知识库节点和开始节点传入。很多人写提示词喜欢加“请尽可能详细”之类的修饰在知识库场景下反而容易让模型自由发挥。简洁、约束明确比华丽辞藻有用。3.2 自动生成公众号文章的完整链路从选题到成稿热词里有人问“怎么通过扣子自动生成公众号文章”这个场景比问答复杂因为涉及选题、素材检索、大纲生成、正文撰写、排版输出多个步骤。用扣子工作流可以串起来但每个节点都要单独调。第一步是选题。可以用一个定时触发器每天固定时间跑或者手动输入关键词。选题节点可以用大模型生成提示词写“根据以下领域生成 5 个公众号选题要求有吸引力、不重复”。第二步是素材检索把选题关键词传给知识库节点召回相关片段。第三步是大纲生成把选题和素材一起给大模型让它输出文章大纲。第四步是正文撰写按大纲逐段生成每段都带上知识库素材作为参考。第五步是排版扣子可以接插件做 Markdown 转公众号格式或者直接输出 Markdown 让你手动贴。// 大纲生成节点的提示词示例 const outlinePrompt 你是一个公众号主编。根据以下选题和素材生成一篇 1500 字文章的大纲。 大纲包含 35 个一级标题每个标题下写 23 句要点。 素材中没有提到的内容不要写进大纲。 选题{{topic}} 素材{{knowledge}} ;这个提示词的关键是“素材中没有提到的内容不要写进大纲”防止模型自己编内容。{{topic}}来自选题节点{{knowledge}}来自知识库检索。实际跑的时候你会发现模型有时候会忽略这个约束所以在大纲生成后最好加一个人工审核环节或者再加一个校验节点用另一个大模型调用检查大纲是否超出素材范围。3.3 工作流调试与日志排查回答不准时先看哪里工作流跑起来后回答不准是常态。排查顺序很重要别一上来就改提示词。先看知识库检索结果在工作流日志里能看到每次检索召回了哪些片段、相似度分数是多少。如果召回片段本身就不相关改提示词没用得回去调知识库参数或者重新处理文档。如果召回片段相关但回答不对再去看大模型节点的输入输出检查提示词有没有歧义、变量有没有传对。扣子的工作流日志会记录每个节点的输入输出这是排查的主要依据。我一般会先跑一个测试问题把日志从头到尾看一遍确认每个节点的数据流转是符合预期的。常见问题包括变量名写错导致知识库片段没传进大模型、召回条数设太少导致上下文不足、提示词里的约束被模型忽略。前两个是配置问题第三个是提示词问题分清楚再动手。4. 避坑与常见问题文档解析、召回失败与幻觉排查4.1 上传的 PDF 解析出来是乱码现象上传 PDF 后预览切片内容发现文字顺序错乱、表格变成一堆符号、甚至全是问号。原因PDF 内部结构复杂有的是扫描件没有文字层有的是多栏排版解析顺序错乱有的是字体编码问题。解决扫描件先用 OCR 工具转成文字再上传多栏排版先在本地用工具重排成单栏字体编码问题可以尝试用其他 PDF 阅读器另存为文本再上传。扣子对纯文本和 Markdown 的解析最稳能转格式就转。4.2 知识库明明有内容检索却召不回来现象文档上传成功切片也正常但问相关问题时知识库节点返回空或者返回不相关片段。原因相似度阈值设太高、召回条数设太少、embedding 模型对某些表述不敏感。解决先把相似度阈值降到 0 或者关掉看能不能召回来如果能再逐步调高阈值找到合适位置。召回条数先加到 5 试试。如果还是不行换一种问法看是不是表述差异太大导致语义匹配失败。4.3 模型回答里出现知识库里没有的内容现象问了一个知识库覆盖不到的问题模型没有说“不知道”而是编了一个看起来合理的答案。原因提示词约束不够强或者知识库召回了一些弱相关片段模型把它们当成了依据。解决在提示词里加硬约束比如“只允许使用知识库片段中的原话或直接推论禁止引入外部知识”。同时在知识库节点后加一个过滤节点把相似度低于阈值的片段丢掉。如果还是不行换一个指令遵循能力更强的模型。4.4 工作流跑通了但响应特别慢现象问答 Bot 响应时间超过 10 秒用户体验差。原因召回条数太多导致大模型输入过长、大模型本身推理慢、工作流节点太多串行执行。解决召回条数降到 3大模型输入长度控制住换一个更快的模型做生成能并行的节点改成并行比如多个知识库检索可以同时跑。扣子工作流支持并行分支用好了能省不少时间。4.5 知识库更新后回答还是旧的现象上传了新文档但问答时模型还是用旧内容回答。原因知识库缓存没刷新或者工作流里选的是旧版本的知识库。解决在扣子知识库界面手动触发一次重新索引确保新文档被切片和向量化。工作流里检查知识库节点选的是不是最新版本。如果用了多个知识库确认新文档传到了正确的那一个。5. 进阶技巧用变量和条件分支让知识库问答更可控5.1 用变量做多轮对话的上下文管理扣子的工作流默认是单轮问答用户问一句、系统答一句上一句的内容不会自动带到下一句。但很多场景需要多轮比如用户先问“这个产品的价格”再问“那它的保修期呢”第二句里的“它”需要指代第一句的产品。实现方式是在工作流里加一个变量节点把历史对话存起来每次大模型调用时把历史对话拼进提示词。// 多轮对话的提示词模板 const multiTurnPrompt 以下是之前的对话历史 {{history}} 当前用户问题{{question}} 请根据对话历史和知识库片段回答当前问题。 如果当前问题中有指代词请结合对话历史理解其含义。 知识库片段{{knowledge}} ;{{history}}是一个数组变量每次对话结束后把“用户问 模型答”追加进去。扣子支持在会话级别维护变量具体配置在 Bot 的设置里。这个方案有个边界历史对话太长会挤占知识库片段的 token 空间所以一般只保留最近 35 轮更早的对话做摘要或者直接丢弃。5.2 条件分支不同问题走不同知识库如果你有多个知识库比如一个产品库、一个售后库、一个内部流程库可以用条件分支节点做路由。用户问题进来后先用一个分类节点判断属于哪个领域再走对应的知识库检索。分类可以用大模型做也可以用关键词匹配做。大模型分类更灵活但慢关键词匹配快但覆盖不全。我一般会先用关键词做粗筛命中不了再走大模型兜底。// 关键词路由的简化逻辑 const routeMap { 价格: product_kb, 保修: after_sales_kb, 报销: internal_kb }; function route(question) { for (const [keyword, kb] of Object.entries(routeMap)) { if (question.includes(keyword)) { return kb; } } return default_kb; // 兜底走通用库 }这段逻辑在扣子里可以用代码节点实现也可以用条件分支节点拖拽实现。routeMap是关键词到知识库的映射route函数遍历关键词命中就返回对应知识库 ID没命中走默认库。实际用的时候关键词表要持续维护用户问法千奇百怪靠几个关键词覆盖不全所以兜底策略很重要。5.3 验证知识库效果用测试集跑准确率知识库搭完不是终点得验证效果。我一般会准备一个测试集包含 2030 个典型问题和标准答案跑一遍工作流统计回答准确率。准确率低于 80% 就回去调参数或者补文档。测试集要覆盖不同类型的问题事实型、推理型、否定型、多轮型。事实型问“X 是什么”推理型问“X 和 Y 有什么区别”否定型问“X 是不是 Y”多轮型就是前面说的指代问题。跑测试集的时候把每个问题的召回片段和最终回答都记录下来方便定位问题。如果某个问题回答错了先看召回片段对不对再看提示词有没有问题。这个流程走几轮知识库的效果会明显提升。从那以后我每次搭完知识库都强制走一遍测试集不跑不放心。希望帮到你。本文还有配套的精品资源点击获取