簡(jiǎn)介這是一份面向AI應(yīng)用開發(fā)者與知識(shí)庫(kù)搭建需求者的萬(wàn)字教程資源圍繞AI Agent概念與字節(jié)Coze平臺(tái)展開幫助零基礎(chǔ)讀者理解智能體原理并動(dòng)手構(gòu)建企業(yè)級(jí)知識(shí)庫(kù)。內(nèi)容系統(tǒng)梳理了AI Agent的核心公式——LLM、Planning、Memory、Tools四要素對(duì)比Copilot與Agent在自主性、流程決策上的差異并延伸至開源項(xiàng)目、行業(yè)應(yīng)用、發(fā)展趨勢(shì)及倫理法律等議題。資源包內(nèi)含1個(gè)PDF文件大小約3.46MB結(jié)構(gòu)完整、圖文并茂適合作為系統(tǒng)學(xué)習(xí)與實(shí)操參考。教程以Coze為落地工具通過(guò)具體知識(shí)庫(kù)案例手把手演示設(shè)置、內(nèi)容添加與維護(hù)更新流程讀者可據(jù)此掌握從概念理解到定制化搭建的完整路徑。目前已有324人學(xué)習(xí)適合希望快速入門AI Agent并落地企業(yè)知識(shí)庫(kù)的開發(fā)者與產(chǎn)品人員。1. 扣子知識(shí)庫(kù)從一堆散落文檔到能問(wèn)答的智能體中間差了什么手里攢了幾十份產(chǎn)品手冊(cè)、會(huì)議紀(jì)要、客服話術(shù)想用扣子做一個(gè)能自動(dòng)回答問(wèn)題的知識(shí)庫(kù)智能體結(jié)果上傳完文檔一測(cè)試回答要么答非所問(wèn)要么干脆編造內(nèi)容。這不是扣子不好用而是從「有文檔」到「能問(wèn)答」之間隔著一整套檢索增強(qiáng)生成RAG的工程鏈路。扣子知識(shí)庫(kù)的本質(zhì)是把文檔切片、向量化、存進(jìn)向量數(shù)據(jù)庫(kù)用戶提問(wèn)時(shí)先檢索相關(guān)片段再把片段塞進(jìn)大模型上下文里生成回答。這條鏈路里任何一個(gè)環(huán)節(jié)參數(shù)沒(méi)調(diào)對(duì)最終效果都會(huì)打折扣。這篇內(nèi)容面向已經(jīng)上手扣子、想認(rèn)真把知識(shí)庫(kù)做扎實(shí)的從業(yè)者從文檔預(yù)處理一路講到工作流編排和效果驗(yàn)證每一步都給可復(fù)現(xiàn)的操作和參數(shù)建議。2. 扣子知識(shí)庫(kù)的底層鏈路文檔進(jìn)來(lái)之后到底發(fā)生了什么2.1 從上傳到召回四個(gè)階段拆開看很多人以為知識(shí)庫(kù)就是「上傳文檔 → 提問(wèn) → 回答」三步實(shí)際上扣子內(nèi)部走的是四段式流程。第一階段是文檔解析。扣子支持 PDF、Word、Markdown、TXT、CSV 等格式上傳后平臺(tái)會(huì)先做文本抽取。PDF 里的表格、圖片、雙欄排版是解析翻車的高發(fā)區(qū)掃描件如果沒(méi)有 OCR 層抽出來(lái)就是空白。常見(jiàn)做法是上傳前自己先確認(rèn) PDF 能不能選中文字不能選中的先過(guò)一遍 OCR 工具。第二階段是分片Chunking?？圩幽J(rèn)按固定長(zhǎng)度切分通常 500800 字符一段段間有重疊。分片大小直接決定檢索粒度切太碎單段信息不完整模型拿到半句話沒(méi)法回答切太大一段里混了好幾個(gè)主題檢索命中后噪聲太多。我一般會(huì)把產(chǎn)品手冊(cè)按章節(jié)標(biāo)題切會(huì)議紀(jì)要按發(fā)言人輪次切客服話術(shù)按問(wèn)答對(duì)切而不是無(wú)腦用默認(rèn)值。第三階段是向量化。每個(gè)分片經(jīng)過(guò) Embedding 模型轉(zhuǎn)成一個(gè)高維向量存進(jìn)向量數(shù)據(jù)庫(kù)?？圩悠脚_(tái)內(nèi)置了 Embedding 模型不需要自己部署。這里的關(guān)鍵點(diǎn)是向量化質(zhì)量取決于分片文本的語(yǔ)義完整性一段被攔腰截?cái)嗟奈淖窒蛄勘硎颈旧砭褪悄：?。第四階段是檢索與生成。用戶提問(wèn)時(shí)問(wèn)題先被向量化然后在向量庫(kù)里做相似度搜索召回 Top-K 個(gè)最相關(guān)的分片拼進(jìn) Prompt 交給大模型生成回答。Top-K 設(shè)太小可能漏掉關(guān)鍵信息設(shè)太大則上下文里塞滿無(wú)關(guān)內(nèi)容模型反而抓不住重點(diǎn)。提示扣子知識(shí)庫(kù)的檢索默認(rèn)走語(yǔ)義相似度不是關(guān)鍵詞匹配。這意味著用戶問(wèn)「退貨流程」時(shí)文檔里寫的是「退款操作步驟」也能命中但反過(guò)來(lái)如果文檔里用的是完全不同的術(shù)語(yǔ)體系召回率會(huì)明顯下降。2.2 分片策略怎么選三種場(chǎng)景的實(shí)操參數(shù)分片沒(méi)有萬(wàn)能參數(shù)得看文檔類型。下面是我在三種常見(jiàn)場(chǎng)景里驗(yàn)證過(guò)的配置思路。場(chǎng)景一產(chǎn)品手冊(cè) / 技術(shù)文檔。這類文檔結(jié)構(gòu)清晰有明確的章節(jié)層級(jí)。建議按標(biāo)題層級(jí)切分每個(gè)二級(jí)標(biāo)題下的內(nèi)容作為一個(gè)分片如果單段超過(guò) 1000 字符再按段落二次切分。扣子支持自定義分段規(guī)則可以用換行符和標(biāo)題標(biāo)記做分隔符。重疊長(zhǎng)度設(shè) 50100 字符保證跨段落的句子不被截?cái)?。?chǎng)景二客服話術(shù) / FAQ。這類內(nèi)容天然是問(wèn)答對(duì)格式。一個(gè)問(wèn)句加一個(gè)答句作為一個(gè)分片不要拆開。分片長(zhǎng)度通常在 200400 字符不需要額外重疊。如果話術(shù)里有變量占位符比如「尊敬的{用戶名}」上傳前先替換成通用表述否則向量化時(shí)會(huì)引入噪聲。場(chǎng)景三會(huì)議紀(jì)要 / 聊天記錄。這類文本口語(yǔ)化嚴(yán)重主題跳躍。建議先做一輪人工清洗把無(wú)關(guān)的寒暄、重復(fù)內(nèi)容刪掉再按話題段落切分。分片可以適當(dāng)放大到 8001200 字符因?yàn)榭谡Z(yǔ)化文本單句信息密度低需要更多上下文才能表達(dá)完整意思。文檔類型分片長(zhǎng)度重疊長(zhǎng)度分隔依據(jù)產(chǎn)品手冊(cè)500800 字符50100 字符標(biāo)題層級(jí)客服話術(shù)200400 字符0問(wèn)答對(duì)會(huì)議紀(jì)要8001200 字符100150 字符話題段落2.3 用扣子工作流串起知識(shí)庫(kù)問(wèn)答的最小鏈路光有知識(shí)庫(kù)還不夠得用工作流把「接收問(wèn)題 → 檢索知識(shí)庫(kù) → 生成回答」串起來(lái)。下面是一個(gè)最小可用的工作流配置思路。在扣子工作流編輯器里新建一個(gè)工作流依次添加三個(gè)節(jié)點(diǎn)節(jié)點(diǎn)1開始節(jié)點(diǎn) - 輸入?yún)?shù)user_queryString用戶提問(wèn) 節(jié)點(diǎn)2知識(shí)庫(kù)檢索節(jié)點(diǎn) - 選擇已創(chuàng)建的知識(shí)庫(kù) - 查詢變量引用開始節(jié)點(diǎn)的 user_query - Top-K5先設(shè)5后續(xù)根據(jù)效果調(diào)整 - 相似度閾值0.5低于此值的結(jié)果不返回 節(jié)點(diǎn)3大模型節(jié)點(diǎn) - 模型選擇按需選擇建議先用平臺(tái)默認(rèn)模型跑通 - 系統(tǒng)提示詞 你是一個(gè)基于知識(shí)庫(kù)回答問(wèn)題的助手。 請(qǐng)嚴(yán)格根據(jù)以下參考資料回答用戶問(wèn)題。 如果參考資料中沒(méi)有相關(guān)信息直接說(shuō)「我沒(méi)有找到相關(guān)內(nèi)容」不要編造。 參考資料 {{知識(shí)庫(kù)檢索節(jié)點(diǎn)的輸出}} - 用戶提示詞{{user_query}}這段配置的邏輯是開始節(jié)點(diǎn)接收用戶輸入知識(shí)庫(kù)檢索節(jié)點(diǎn)拿問(wèn)題去向量庫(kù)召回相關(guān)分片大模型節(jié)點(diǎn)把召回內(nèi)容作為上下文生成回答。關(guān)鍵參數(shù)有兩個(gè)——Top-K 和相似度閾值。Top-K 控制召回?cái)?shù)量相似度閾值控制召回質(zhì)量。初期建議 Top-K 設(shè) 5、閾值設(shè) 0.5跑一批測(cè)試問(wèn)題后看召回內(nèi)容是否相關(guān)再微調(diào)。注意系統(tǒng)提示詞里那句「如果參考資料中沒(méi)有相關(guān)信息直接說(shuō)沒(méi)有找到」非常重要。不寫這句話模型在召回內(nèi)容不相關(guān)時(shí)會(huì)強(qiáng)行編造答案這是知識(shí)庫(kù)問(wèn)答最常見(jiàn)的翻車方式。3. 把知識(shí)庫(kù)接進(jìn)智能體從單輪問(wèn)答到多輪對(duì)話的配置細(xì)節(jié)3.1 智能體編排里知識(shí)庫(kù)節(jié)點(diǎn)的掛載方式工作流跑通之后下一步是把知識(shí)庫(kù)能力掛到智能體上。扣子的智能體編排頁(yè)面里知識(shí)庫(kù)是作為一個(gè)能力開關(guān)存在的。打開知識(shí)庫(kù)開關(guān)選擇已創(chuàng)建的知識(shí)庫(kù)智能體在對(duì)話時(shí)就會(huì)自動(dòng)調(diào)用檢索。但這里有個(gè)容易忽略的點(diǎn)智能體模式下知識(shí)庫(kù)的調(diào)用時(shí)機(jī)是由模型自己判斷的。用戶說(shuō)「你好」時(shí)模型不會(huì)去檢索用戶問(wèn)「退貨政策是什么」時(shí)才會(huì)觸發(fā)。這個(gè)判斷依賴模型的意圖識(shí)別能力如果發(fā)現(xiàn)該檢索的時(shí)候沒(méi)檢索可以在智能體的提示詞里加一句「當(dāng)用戶問(wèn)題涉及產(chǎn)品、政策、流程等具體信息時(shí)必須先檢索知識(shí)庫(kù)再回答」。另一種更可控的方式是不用智能體的自動(dòng)知識(shí)庫(kù)開關(guān)而是在工作流里顯式掛載知識(shí)庫(kù)檢索節(jié)點(diǎn)然后把工作流發(fā)布為智能體的技能。這樣每次調(diào)用都會(huì)走檢索不會(huì)出現(xiàn)「模型覺(jué)得不需要查」的情況。兩種方式各有適用場(chǎng)景自動(dòng)模式適合開放域?qū)υ掞@式模式適合客服、技術(shù)支持這類必須基于知識(shí)庫(kù)回答的場(chǎng)景。3.2 多輪對(duì)話里怎么保持上下文不丟單輪問(wèn)答跑通后多輪對(duì)話是下一個(gè)坎。用戶先問(wèn)「退貨政策是什么」接著問(wèn)「那運(yùn)費(fèi)誰(shuí)出」第二句話里沒(méi)有「退貨」這個(gè)關(guān)鍵詞如果檢索時(shí)只拿第二句話去搜很可能召回?zé)o關(guān)內(nèi)容。解決辦法是在檢索前做一輪查詢改寫?？圩庸ぷ髁骼锟梢约右粋€(gè)大模型節(jié)點(diǎn)專門負(fù)責(zé)把多輪對(duì)話壓縮成一個(gè)獨(dú)立的檢索查詢。配置思路如下節(jié)點(diǎn)查詢改寫大模型節(jié)點(diǎn) - 輸入對(duì)話歷史 當(dāng)前用戶輸入 - 提示詞 根據(jù)以下對(duì)話歷史將用戶的最新問(wèn)題改寫成一個(gè)獨(dú)立的、 包含完整語(yǔ)義的檢索查詢。只輸出改寫后的查詢語(yǔ)句不要解釋。 對(duì)話歷史{{對(duì)話歷史變量}} 最新問(wèn)題{{user_query}} - 輸出rewritten_queryString 節(jié)點(diǎn)知識(shí)庫(kù)檢索 - 查詢變量引用 rewritten_query這樣「那運(yùn)費(fèi)誰(shuí)出」會(huì)被改寫成「退貨時(shí)運(yùn)費(fèi)由誰(shuí)承擔(dān)」檢索命中率會(huì)明顯提升。查詢改寫節(jié)點(diǎn)會(huì)增加一次模型調(diào)用有延遲成本但在多輪場(chǎng)景下這個(gè)代價(jià)值得花。3.3 知識(shí)庫(kù)更新后怎么讓智能體同步生效文檔不是一成不變的。產(chǎn)品更新了手冊(cè)、客服話術(shù)改了版本知識(shí)庫(kù)也得跟著更新?？圩又R(shí)庫(kù)里新增文檔會(huì)自動(dòng)向量化并入庫(kù)但刪除舊文檔后對(duì)應(yīng)的向量數(shù)據(jù)需要手動(dòng)觸發(fā)重新索引否則舊內(nèi)容仍然會(huì)被檢索到。我一般會(huì)養(yǎng)成一個(gè)習(xí)慣每次批量更新文檔后在知識(shí)庫(kù)管理頁(yè)面點(diǎn)一次「重新索引」等索引狀態(tài)變成「已完成」再去測(cè)試。另外如果更新頻率高建議給文檔加版本號(hào)或日期前綴比如「產(chǎn)品手冊(cè)_v2.3_20250101」這樣在檢索結(jié)果里能直觀看出召回的是哪個(gè)版本的內(nèi)容排查問(wèn)題時(shí)省很多事。4. 避坑與排查知識(shí)庫(kù)效果不好的五個(gè)真實(shí)原因4.1 召回內(nèi)容相關(guān)但回答跑偏現(xiàn)象檢索出來(lái)的分片確實(shí)和問(wèn)題相關(guān)但模型生成的回答答非所問(wèn)或者把多個(gè)分片的內(nèi)容混在一起說(shuō)。原因通常是系統(tǒng)提示詞沒(méi)有約束模型的回答范圍。模型看到多段參考資料時(shí)傾向于把所有內(nèi)容都塞進(jìn)回答里而不是只提取和問(wèn)題直接相關(guān)的部分。解決在系統(tǒng)提示詞里加一條「只使用與用戶問(wèn)題直接相關(guān)的參考資料不要把所有參考資料的內(nèi)容都復(fù)述一遍」。另外可以把 Top-K 從 5 降到 3減少干擾。4.2 相似度閾值設(shè)太高導(dǎo)致召回為空現(xiàn)象用戶問(wèn)了一個(gè)知識(shí)庫(kù)里明明有答案的問(wèn)題但模型回答「沒(méi)有找到相關(guān)內(nèi)容」。原因相似度閾值設(shè)得過(guò)高比如 0.8而用戶提問(wèn)的措辭和文檔表述差異較大向量相似度沒(méi)達(dá)到閾值檢索結(jié)果為空。解決先把閾值降到 0.40.5 測(cè)試看召回內(nèi)容是否相關(guān)。如果降閾值后召回內(nèi)容質(zhì)量下降說(shuō)明問(wèn)題出在分片或 Embedding 質(zhì)量上而不是閾值本身。扣子的檢索日志里能看到每次召回的相似度分?jǐn)?shù)對(duì)著日志調(diào)比盲猜快得多。4.3 PDF 里的表格和圖片內(nèi)容丟失現(xiàn)象上傳的產(chǎn)品規(guī)格 PDF 里表格中的參數(shù)在回答時(shí)完全查不到。原因扣子默認(rèn)的 PDF 解析器對(duì)表格和圖片的處理能力有限表格內(nèi)容可能被解析成亂序文本圖片里的文字直接丟失。解決表格內(nèi)容建議手動(dòng)轉(zhuǎn)成 Markdown 表格或 CSV 再上傳。圖片里的文字先用 OCR 工具提取成文本作為補(bǔ)充文檔一起上傳。如果 PDF 本身就是掃描件必須先過(guò) OCR否則上傳后解析出來(lái)是空的。4.4 知識(shí)庫(kù)文檔多了之后檢索變慢現(xiàn)象知識(shí)庫(kù)里文檔從幾十份增加到幾百份后每次問(wèn)答的響應(yīng)時(shí)間明顯變長(zhǎng)。原因向量庫(kù)的檢索耗時(shí)隨數(shù)據(jù)量增長(zhǎng)而增加同時(shí) Top-K 召回后塞進(jìn)模型上下文的內(nèi)容變多模型推理時(shí)間也變長(zhǎng)。解決一是控制單次召回的分片總長(zhǎng)度扣子工作流里可以在檢索節(jié)點(diǎn)后加一個(gè)文本截?cái)喙?jié)點(diǎn)限制總字符數(shù)不超過(guò) 2000。二是如果文檔量確實(shí)大考慮按業(yè)務(wù)線拆成多個(gè)知識(shí)庫(kù)智能體根據(jù)用戶問(wèn)題先路由到對(duì)應(yīng)知識(shí)庫(kù)再檢索。4.5 同一個(gè)問(wèn)題每次回答不一樣現(xiàn)象用戶問(wèn)同一個(gè)問(wèn)題兩次回答的內(nèi)容有差異有時(shí)候甚至矛盾。原因大模型生成本身有隨機(jī)性temperature 參數(shù)大于 0加上每次召回的分片可能略有不同導(dǎo)致回答不穩(wěn)定。解決在模型節(jié)點(diǎn)把 temperature 調(diào)到 0 或接近 0讓生成結(jié)果盡量確定。同時(shí)在系統(tǒng)提示詞里明確「如果多個(gè)參考資料之間有矛盾以日期最新的為準(zhǔn)」給模型一個(gè)沖突消解規(guī)則。5. 讓知識(shí)庫(kù)回答更準(zhǔn)的兩個(gè)進(jìn)階技巧5.1 用重排序把最相關(guān)的分片頂?shù)角懊婵圩又R(shí)庫(kù)默認(rèn)只做向量相似度檢索但向量相似度高不等于語(yǔ)義相關(guān)度高。一個(gè)有效的補(bǔ)充手段是加一個(gè)重排序Rerank環(huán)節(jié)先召回 Top-10 個(gè)分片再用重排序模型對(duì)這 10 個(gè)分片按與問(wèn)題的實(shí)際相關(guān)度重新打分取前 3 個(gè)塞進(jìn)模型上下文。扣子工作流里可以通過(guò)插件市場(chǎng)找重排序插件或者用 HTTP 請(qǐng)求節(jié)點(diǎn)調(diào)用外部重排序服務(wù)。配置思路是知識(shí)庫(kù)檢索節(jié)點(diǎn) Top-K 設(shè)為 10后面接重排序節(jié)點(diǎn)重排序節(jié)點(diǎn)輸出 Top-3再傳給大模型節(jié)點(diǎn)。這樣做的代價(jià)是多一次模型調(diào)用但召回精度提升明顯尤其是在文檔量大、主題分散的場(chǎng)景下。5.2 用測(cè)試集量化知識(shí)庫(kù)效果而不是憑感覺(jué)知識(shí)庫(kù)調(diào)優(yōu)最怕憑感覺(jué)?！父杏X(jué)回答還行」和「回答準(zhǔn)確率 85%」是兩回事。建議建一個(gè)最小測(cè)試集從真實(shí)用戶問(wèn)題里挑 3050 個(gè)每個(gè)問(wèn)題標(biāo)注正確答案所在的那份文檔和段落。然后跑一遍自動(dòng)測(cè)試看每個(gè)問(wèn)題召回的分片里是否包含標(biāo)注段落以及最終回答是否正確。扣子本身沒(méi)有內(nèi)置的批量測(cè)試工具但可以用工作流的 API 接口寫一個(gè)簡(jiǎn)單的 Python 腳本批量調(diào)用import requests # 替換為你的工作流 API 地址和 Token API_URL https://api.coze.cn/v1/workflow/run TOKEN your_token_here test_cases [ {question: 退貨需要幾天內(nèi)申請(qǐng), expected_doc: 售后政策_(dá)v2}, {question: 企業(yè)版最多支持多少人, expected_doc: 產(chǎn)品定價(jià)表}, # 補(bǔ)充更多測(cè)試用例 ] for case in test_cases: resp requests.post(API_URL, json{ workflow_id: your_workflow_id, parameters: {user_query: case[question]} }, headers{Authorization: fBearer {TOKEN}}) result resp.json() # 檢查返回內(nèi)容中是否包含預(yù)期文檔的關(guān)鍵信息 print(f問(wèn)題{case[question]}) print(f回答{result.get(data, {}).get(output, )}) print(---)這段腳本的邏輯是把測(cè)試問(wèn)題逐個(gè)發(fā)給工作流 API收集回答人工或自動(dòng)比對(duì)是否命中預(yù)期內(nèi)容。參數(shù)說(shuō)明workflow_id在扣子工作流發(fā)布后的 API 頁(yè)面能拿到parameters里的 key 要和開始節(jié)點(diǎn)的輸入?yún)?shù)名一致。跑完一輪后把召回失敗和回答錯(cuò)誤的問(wèn)題單獨(dú)拎出來(lái)分析是分片問(wèn)題、閾值問(wèn)題還是提示詞問(wèn)題針對(duì)性修。我自己的習(xí)慣是每次調(diào)整知識(shí)庫(kù)配置后都跑一遍這個(gè)測(cè)試集記錄準(zhǔn)確率變化。有一次把分片長(zhǎng)度從 500 調(diào)到 800準(zhǔn)確率從 72% 漲到 86%但也有一次調(diào)完反而降了后來(lái)發(fā)現(xiàn)是某幾份文檔的格式特殊統(tǒng)一參數(shù)不適用。這種問(wèn)題不跑測(cè)試集根本發(fā)現(xiàn)不了。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取