戰(zhàn)：一站式RAG知識(shí)庫(kù)解決復(fù)雜文檔解析)
1. 為什么我最終從拼接式RAG換成了 WeKnora 這種一站式方案說個(gè)真實(shí)場(chǎng)景我手頭維護(hù)的資料庫(kù)大概有三百多份文檔包括產(chǎn)品白皮書、售前方案PPT、掃描版合同、客戶FAQ、以及大量帶表格和圖片的PDF。原本的檢索方式就是網(wǎng)盤加文件夾再配一個(gè)全文搜索工具真到了去年給某客戶報(bào)的報(bào)價(jià)是什么這種問題翻十幾分鐘是常態(tài)。最初我并沒有直接上 WeKnora而是走了很多人都會(huì)走的路自己拼一套R(shí)AG。向量庫(kù)用 MilvusEmbedding 用 BGELLM 打算先接云端 API文檔解析用 PyMuPDF 配合自研規(guī)則做切片。折騰了兩周能跑通但效果一言難盡——表格被切得粉碎掃描件直接是空文本圖片里的關(guān)鍵信息一個(gè)都抽不出來問出來的答案驢唇不對(duì)馬嘴。后來在一個(gè)開源社區(qū)的討論帖里看到 WeKnora才知道騰訊微信團(tuán)隊(duì)開源了這個(gè)項(xiàng)目。它的定位和普通RAG框架不太一樣它不是讓你自己拼裝而是把數(shù)據(jù)接入、文檔理解、切片、索引、混合檢索、重排、生成、Agent 編排全部串成一條完整流水線而且對(duì)中文場(chǎng)景的處理明顯更細(xì)致。我把它部署到本地之后第一個(gè)感覺是這才是文檔該有的待遇。PAW 文檔理解流水線能把版面分析、OCR、表格轉(zhuǎn) Markdown、圖表信息提取這些臟活全部接管這在以前是我要寫幾千行代碼去做的事。這套系統(tǒng)適合誰來用我覺得大概是兩類人一類是像我一樣被各種格式混亂、掃描件居多、表格密布的文檔折磨得夠嗆想搭一個(gè)真正能問問題的內(nèi)部知識(shí)庫(kù)另一類是團(tuán)隊(duì)已經(jīng)有一些 LLM 使用經(jīng)驗(yàn)但發(fā)現(xiàn)通用 RAG 框架對(duì)復(fù)雜文檔的解析和召回精度不夠需要一個(gè)更完整的開源知識(shí)庫(kù)底座。整篇文章我會(huì)把選型理由、模型決策、部署步驟、踩坑過程、調(diào)優(yōu)方法完整記錄下來按我實(shí)際操作順序?qū)懖皇钦罩俜?README 念后者很多關(guān)鍵彎路根本不會(huì)告訴你。先給一個(gè)結(jié)論如果你現(xiàn)在的痛點(diǎn)只是缺一個(gè)工作流編排平臺(tái)那 Dify 可能更合適但如果痛點(diǎn)在于文檔根本進(jìn)不去、檢索不準(zhǔn)、表格一塌糊涂WeKnora 這種把文檔解析做到極致的開源知識(shí)庫(kù)方案會(huì)更能解決問題。2. 部署前的關(guān)鍵決策模型放哪、機(jī)器要多大、選哪家Embedding2.1 LLM 選型我用 Ollama 跑 Qwen而不是直接接云端 API標(biāo)題既然叫本地部署實(shí)錄那大模型也應(yīng)該是本地的否則沒意義。我最早考慮過直接把 WeKnora 的 LLM 接口指向 OpenAI 兼容的云端 API這樣最省事但數(shù)據(jù)都要出內(nèi)網(wǎng)在辦公場(chǎng)景里過不了安全這一關(guān)。所以最后選了 Ollama 作為本地模型運(yùn)行時(shí)。Ollama 的好處是極簡(jiǎn)一條命令拉模型一條命令起服務(wù)而且它提供了 OpenAI 兼容接口WeKnora 配置模型時(shí)可以直接走 OpenAI 兼容協(xié)議非常方便。模型選擇上我對(duì)比了三個(gè)方向Qwen2.5-7B-Instruct中文理解能力扎實(shí)7B 量級(jí)在 CPU 上也能勉強(qiáng)跑起來是我最終的主力模型。DeepSeek-R1-Distill-Qwen-7B推理能力強(qiáng)但速度偏慢適合做逐步推理類的復(fù)雜問題。熱詞里也有 deepseek 本地部署說明這條路很多人走通了。Qwen2.5-14B如果你有 16GB 以上顯存強(qiáng)烈建議直接上 14B答案質(zhì)量比 7B 高一個(gè)檔次尤其是長(zhǎng)文檔總結(jié)場(chǎng)景。量化級(jí)別我選的 Q4_K_M。7B 的 Q4_K_M 模型文件大概 4.7GB14B 大概 9GB這是 CPU 推理和顯存占用之間的平衡點(diǎn)。再低比如 Q2 就別用了質(zhì)量衰減肉眼可見。2.2 Embedding 和 Rerank 不能省這是檢索精度的真正分水嶺很多教程只教你配置 LLMEmbedding 隨便選一個(gè)Rerank 干脆不配。我在實(shí)操中的結(jié)論是Rerank 對(duì)回答質(zhì)量的影響甚至大于換一個(gè)大模型。Embedding 我用的是 BAAI 的 bge-m3原因很直接它對(duì)中文語義的支持明顯好于 nomic-embed-text 這類英文為主的模型而且支持 8192 token 的長(zhǎng)文本處理整段方案描述不容易被截?cái)?。?Ollama 里拉下來就是一條命令的事。Rerank 也是 BGE 家族的 bge-reranker-v2-m3。它做的事情是先讓向量檢索和關(guān)鍵詞檢索各召回一批候選文檔比如總共 50 條Rerank 再逐條計(jì)算和問題的真實(shí)相關(guān)性把最相關(guān)的 5 到 10 條排到最前面。這一步可以理解為粗篩靠向量精排靠重排。如果你硬件緊張可以先用一小批數(shù)據(jù)測(cè)試確認(rèn)檢索精度成為瓶頸了再補(bǔ)上 Rerank這個(gè)優(yōu)先級(jí)是對(duì)的。2.3 硬件底線我的實(shí)測(cè)配置與建議我部署用的是一臺(tái)舊工作站放在辦公網(wǎng)里4 核 8 線程 CPU32GB 內(nèi)存沒有 GPU。這個(gè)配置跑 Qwen2.5-7B 的 CPU 推理單輪問答大概 3 到 6 秒能忍但并發(fā)一多就明顯吃力。文檔解析特別是 OCR 階段非常吃 CPU批量導(dǎo)入 PDF 時(shí)整個(gè)系統(tǒng)會(huì)卡頓。給幾個(gè)可以參考的檔位部署規(guī)模內(nèi)存CPU/GPU模型覆蓋場(chǎng)景嘗鮮驗(yàn)證16GB4核CPU7B Q4量化單用戶少量文檔小型團(tuán)隊(duì)32GB8核CPU或入門GPU7B~14B5~10人使用生產(chǎn)環(huán)境64GB24GB顯存GPU14B多并發(fā)大量文檔一個(gè)容易被忽略的點(diǎn)內(nèi)存不只是給 LLM 用的。文檔解析進(jìn)程、Embedding 模型、向量索引、Rerank 都會(huì)常駐內(nèi)存我實(shí)測(cè)純 7B 模型 bge-m3 嵌入 bge-reranker加上 WeKnora 前后端內(nèi)存占用輕松到 14GB。16GB 的機(jī)器跑全套真的很緊張建議至少 32GB。3. 從克隆代碼到首次啟動(dòng)環(huán)境準(zhǔn)備、依賴安裝和常見版本坑3.1 環(huán)境準(zhǔn)備Python 版本是第一個(gè)坑WeKnora 的部署方式在倉(cāng)庫(kù) README 里有明確說明但版本更新比較頻繁一些細(xì)節(jié)會(huì)變。我按當(dāng)時(shí)實(shí)際操作的流程記錄你部署時(shí)如果發(fā)現(xiàn)命令不一致以你拉取到的分支 README 為準(zhǔn)。先準(zhǔn)備基礎(chǔ)環(huán)境。我踩的第一個(gè)坑就是 Python 版本必須用 3.10 或 3.11太老或太新的版本在裝依賴時(shí)都可能出編譯錯(cuò)誤。我一開始用的是系統(tǒng)自帶的 Python 3.9安裝 requirements 里的某些依賴直接報(bào)錯(cuò)換到 3.10 虛擬環(huán)境就正常了。sudo apt install python3.10-venv python3.10 -m venv weknora-venv source weknora-venv/bin/activate前端部分需要 Node.js 和 pnpm我用的是 Node 18。WeKnora 的前端是 Vue3 技術(shù)棧直接用 pnpm 管理依賴。3.2 后端依賴PaddleOCR 是最大的定時(shí)炸彈克隆代碼后進(jìn)入項(xiàng)目目錄安裝后端依賴git clone https://github.com/Tencent/WeKnora.git cd WeKnora pip install -r requirements.txt這個(gè)命令表面上普普通通但里面的雷在 PaddleOCR 相關(guān)依賴上。我第一次裝的時(shí)候直接用默認(rèn)命令pip 給我裝了一堆依賴跑起來才發(fā)現(xiàn) Paddle 的版本和 Python 不兼容進(jìn)程直接崩掉。正確的姿勢(shì)是先單獨(dú)裝 CPU 版 PaddlePaddle再裝 PaddleOCR裝完之后再用 requirements 裝其余部分。順序搞反了就很容易踩到 Paddle 把 numpy 依賴鎖上的坑。pip install paddlepaddle # CPU版本別默認(rèn)裝GPU版否則CUDA依賴會(huì)卡死你 pip install paddleocr如果你的文檔全是文本型 PDF不需要 OCR可以在 WeKnora 的解析配置里把 OCR 模塊關(guān)掉能省不少 CPU 占用。這個(gè)后面會(huì)再提。前端構(gòu)建pnpm install pnpm build第一次構(gòu)建會(huì)拉不少依賴耐心等就好。這個(gè)環(huán)節(jié)倒沒遇到太詭異的坑最多是網(wǎng)絡(luò)問題導(dǎo)致個(gè)別包下載超時(shí)重試即可。3.3 配置與啟動(dòng)把默認(rèn)端口和數(shù)據(jù)庫(kù)搞清楚WeKnora 的配置文件主要在項(xiàng)目目錄下的 config 相關(guān)文件里里面涉及數(shù)據(jù)庫(kù)地址、服務(wù)端口、日志路徑等。默認(rèn)配置可以走 SQLite小規(guī)模驗(yàn)證足夠如果團(tuán)隊(duì)一起用建議換成 MySQL不然并發(fā)寫入了會(huì)鎖庫(kù)。啟動(dòng)方式我按官方命令來后端是一個(gè) Python 服務(wù)前端是一個(gè)靜態(tài)站點(diǎn)。開發(fā)模式下前端用 dev server 跑生產(chǎn)環(huán)境用 build 后的靜態(tài)文件讓后端托管或者單獨(dú)用 Nginx 代理。首次啟動(dòng)后瀏覽器訪問前端地址它會(huì)引導(dǎo)初始化管理員賬號(hào)。到這里還沒接入模型系統(tǒng)能打開但問不了問題因?yàn)檫€沒配 LLM。這里有一個(gè)值得強(qiáng)調(diào)的細(xì)節(jié)系統(tǒng)默認(rèn)監(jiān)聽地址如果是 127.0.0.1只有本機(jī)能訪問如果想讓局域網(wǎng)同事用啟動(dòng)時(shí)要把 host 改為 0.0.0.0。但是不要把這個(gè)服務(wù)直接暴露到公網(wǎng)這個(gè)我們?cè)谧詈笠徽略僬归_說。4. 接通本地模型讓問答系統(tǒng)真正開口說話4.1 管理后臺(tái)配置 LLM 接口WeKnora 啟動(dòng)后進(jìn)入管理后臺(tái)找到模型供應(yīng)商配置頁面。這里支持多種 provider本地部署場(chǎng)景下最常用的是 OpenAI 兼容接口或者 Ollama 直連取決于版本選項(xiàng)。我當(dāng)時(shí)的配置是這樣的base_url 填http://127.0.0.1:11434/v1api_key 填任意值比如ollama因?yàn)楸镜?Ollama 不校驗(yàn) keymodel 名稱填qwen2.5:7b-instruct注意必須是 Ollama 里 pull 下來的確切名稱多一個(gè)冒號(hào)少一個(gè) tag 都會(huì)報(bào)錯(cuò)Embedding 模型同理把模型類型切到 embeddingbase_url 指到 Ollama 的地址模型名填bge-m3。Rerank 如果配了也是同樣的思路。4.2 連通性測(cè)試先 curl 后頁面別一上來就怪系統(tǒng)配置完成后WebUI 里通常有測(cè)試按鈕。如果提示連接失敗不要急著懷疑是 WeKnora 的問題先在本機(jī)用 curl 驗(yàn)證 Ollama 接口是否正常curl -X POST http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5:7b-instruct,messages:[{role:user,content:你好}]}能正常返回內(nèi)容說明 Ollama 沒問題問題出在 WeKnora 側(cè)的地址或者網(wǎng)絡(luò)。這里有個(gè)非常經(jīng)典的坑如果你用 Docker 方式跑 WeKnora容器里的 127.0.0.1 指向的是容器自己不是宿主機(jī)。這時(shí)候要把 base_url 改成http://host.docker.internal:11434/v1Linux 下如果用 docker compose可以加extra_hosts: - host.docker.internal:host-gateway。我在這一步卡了快一個(gè)小時(shí)。另一個(gè)容易踩的是 CORS。瀏覽器直接訪問前端頁面發(fā)起跨域請(qǐng)求時(shí)Ollama 默認(rèn)對(duì)來源有限制。解決辦法是給 Ollama 設(shè)置環(huán)境變量OLLAMA_ORIGINS* ollama serve簡(jiǎn)單粗暴但本地內(nèi)網(wǎng)環(huán)境這么干問題不大。要注意的是這個(gè)環(huán)境變量是進(jìn)程級(jí)的設(shè)置完要重啟 ollama 服務(wù)。4.3 第一次真實(shí)問答預(yù)期管理很重要模型配好之后我先建了一個(gè)很小的知識(shí)庫(kù)放了一份 Markdown 格式的 FAQ文檔內(nèi)容是XX 系統(tǒng)如何開通、常見錯(cuò)誤碼含義。導(dǎo)入成功后做索引然后提問客戶反饋登錄一直失敗錯(cuò)誤碼 10023怎么處理效果比我預(yù)期的好系統(tǒng)能準(zhǔn)確引用 FAQ 里的對(duì)應(yīng)條目并且返回了處理建議答案下面還掛了引用來源。但同時(shí)我也發(fā)現(xiàn)了第一個(gè)問題7B 模型對(duì)問題的理解過于字面化如果問題里不包含錯(cuò)誤碼它就不太會(huì)聯(lián)想到相關(guān) FAQ。這說明檢索鏈路本身該做的活已經(jīng)做完了瓶頸開始轉(zhuǎn)向模型推理能力。所以我建議第一次測(cè)試時(shí)把預(yù)期調(diào)低一點(diǎn)不要指望 7B 模型在沒有 Rerank、沒有調(diào)優(yōu)的情況下就給出驚艷答案。第一步只確認(rèn)鏈路通、引用準(zhǔn)后面再逐步優(yōu)化。5. 文檔解析和 Agentic RAG 的真實(shí)體驗(yàn)PAW 到底強(qiáng)在哪5.1 把一份掃描版方案 PDF 扔給 PAW 之后的對(duì)比為了測(cè)試 WeKnora 的文檔理解能力我專門找了一份舊方案文檔一個(gè)掃描版的 PDF大概是十幾頁里面包含彩色封面、目錄、帶財(cái)務(wù)數(shù)據(jù)的表格、幾張架構(gòu)圖、還有一些手寫批注的痕跡。我將它導(dǎo)入 WeKnora后臺(tái)任務(wù)跑了一陣子打開解析結(jié)果一看確實(shí)有點(diǎn)東西文字內(nèi)容被完整 OCR 出來了表格被還原成了 Markdown 表格格式架構(gòu)圖里的文字說明也被單獨(dú)提取成了圖片注釋多欄排版的閱讀順序沒有被搞亂。這些都是之前我用開源工具自研解析時(shí)會(huì)崩潰的典型場(chǎng)景。再用對(duì)照組來驗(yàn)證同一份 PDF 用 PyMuPDF 直接抽文本結(jié)果是一些空行和偶爾亂碼因?yàn)檎麄€(gè)文件本質(zhì)是圖片用單純的開源 OCR 工具跑文字是出來了但表格結(jié)構(gòu)完全丟了多欄文字串成了一坨。PAW 的價(jià)值在于流水線式地把版面分析、OCR、表格結(jié)構(gòu)識(shí)別、閱讀順序還原串起來而不是單點(diǎn)工具能比的事。5.2 混合檢索和 Rerank 在生產(chǎn)中的真實(shí)分工WeKnora 的檢索不是單一向量召回而是混合了語義向量、關(guān)鍵詞命中、知識(shí)圖譜關(guān)聯(lián)。這一點(diǎn)在業(yè)務(wù)文檔里非常有用。舉個(gè)例子文檔里經(jīng)常出現(xiàn)CRM-2024-01這種產(chǎn)品編號(hào)。你拿向量去搜CRM-2024-01效果通常不穩(wěn)定因?yàn)橄蛄磕Ｐ蛯?duì)這個(gè)字符串的理解很弱但關(guān)鍵詞檢索能精準(zhǔn)命中。反過來客戶關(guān)系管理系統(tǒng)的升級(jí)方案這種語義描述關(guān)鍵詞搜不到向量能輕松召回到相關(guān)段落?；旌蠙z索就是讓這兩條路各自發(fā)揮優(yōu)勢(shì)再合并結(jié)果。Rerank 在最終的排序階段把關(guān)。之前我把上下文數(shù)量設(shè)得很大一次性送三十條檢索結(jié)果給模型結(jié)果上下文爆炸回答質(zhì)量急劇下降。加上 Rerank 之后先把候選壓縮到 top 5模型輸入更干凈回答質(zhì)量直接提升。所以我在調(diào)優(yōu)時(shí)把 Rerank 的優(yōu)先級(jí)放在很前面。5.3 Agentic RAG 的實(shí)際效果什么時(shí)候該用什么時(shí)候別濫用WeKnora 的 Agentic RAG 模式在管理后臺(tái)可以開啟。它的邏輯是讓模型不再做一次檢索一次回答而是先拆解用戶的復(fù)雜問題再?zèng)Q定去哪個(gè)知識(shí)庫(kù)檢索、調(diào)用什么工具、分幾步回答。我測(cè)試過一個(gè)多步驟問題對(duì)比新老兩版售后服務(wù)政策中退換貨時(shí)效的變化并總結(jié)對(duì)客戶溝通的影響?；A(chǔ) RAG 模式下模型很容易只找到其中一個(gè)版本就開答漏掉對(duì)比。切到 Agent 模式后它會(huì)先拆成找到兩個(gè)版本-抽取退換貨條款-對(duì)比差異-生成結(jié)論幾步看起來更接近人的檢索路徑。但我也要潑一盆冷水Agent 模式不是默認(rèn)開啟就萬事大吉的。如果知識(shí)庫(kù)范圍太大、工具權(quán)限沒有收斂模型反而會(huì)自由發(fā)揮檢索一些無關(guān)的內(nèi)容甚至憑空生成中間結(jié)論。我的做法是在配置里把 Agent 可訪問的知識(shí)庫(kù)范圍明確限定并給每個(gè)知識(shí)庫(kù)加上清晰的角色描述。別讓它自由發(fā)揮太多。6. 踩坑實(shí)錄從部署到穩(wěn)定運(yùn)行的完整排查鏈路6.1 癥狀一模型服務(wù)連接超時(shí)排查到最后是 localhost 指向問題現(xiàn)象頁面測(cè)試連接提示 LLM 服務(wù)連接超時(shí)。這是部署最常遇到的第一個(gè)大坑。排查鏈路先在宿主機(jī)執(zhí)行curl http://127.0.0.1:11434/v1確認(rèn) Ollama 服務(wù)確實(shí)在跑。再確認(rèn) WeKnora 的 base_url 是否正確。如果 WeKnora 跑在 Docker 容器里127.0.0.1指容器自己必須改用host.docker.internal。檢查 Ollama 是否開啟了跨域限制。前端直連時(shí)會(huì)報(bào) CORS 錯(cuò)誤設(shè)置OLLAMA_ORIGINS*后重啟。最后定位到的根因其實(shí)就是第二點(diǎn)容器內(nèi)外 localhost 的含義不同。這個(gè)坑在本地部署里極具代表性屬于寫配置時(shí)看起來完全正確跑起來就是不通的典型。6.2 癥狀二文檔索引成功但答案答非所問現(xiàn)象知識(shí)庫(kù)索引任務(wù)顯示成功提問后答案和文檔內(nèi)容沒有明確關(guān)系甚至引用來源都不對(duì)。排查鏈路先打開文檔解析結(jié)果確認(rèn)文本內(nèi)容是否真的被正確提取。結(jié)果發(fā)現(xiàn)文本在但被切成片段。再檢查檢索調(diào)試頁面看輸入問題后到底召回了哪些片段。發(fā)現(xiàn)召回的段落里只有一半和問題相關(guān)另一半是其他主題的內(nèi)容。進(jìn)一步查了 chunk 設(shè)置默認(rèn)的切分大小偏大一段話里混了兩個(gè)主題向量檢索時(shí)語義就不夠聚焦。解決方案是重建索引并把切片策略調(diào)小。比如 chunk_size 從默認(rèn)值調(diào)成 512上下文重疊 100。具體要結(jié)合文檔特點(diǎn)調(diào)但方向是讓每個(gè)切片盡量聚焦單一主題。改完后重新導(dǎo)入或重建索引答案質(zhì)量明顯好轉(zhuǎn)。這個(gè)過程讓我意識(shí)到一個(gè)經(jīng)常被忽視的事情RAG 系統(tǒng)的錯(cuò)誤不一定出在模型很多是先出在文檔切片環(huán)節(jié)。切片像切菜切得太大一鍋燉不下切得太碎味道就散了。WeKnora 雖然切片策略可配置但默認(rèn)值未必適合你的文檔。6.3 癥狀三7B 模型回答讀不出重點(diǎn)開頭啰嗦、結(jié)尾敷衍現(xiàn)象Qwen2.5-7B 在長(zhǎng)文檔問答時(shí)答案前半段在復(fù)述文檔標(biāo)題后半段直接說請(qǐng)參考文檔第X頁沒有實(shí)際內(nèi)容。排查鏈路檢查送進(jìn)模型的上下文內(nèi)容發(fā)現(xiàn)一次塞了太多檢索片段超出了模型的 32K 上下文窗口被系統(tǒng)自動(dòng)截?cái)?。截?cái)嗪竽Ｐ椭豢吹搅宋臋n開頭的章節(jié)信息沒看到真正的內(nèi)容段落。量化模型本身對(duì)長(zhǎng)文本的歸納能力有限7B 在上下文很長(zhǎng)時(shí)容易只看見開頭和結(jié)尾。解決方案有兩步第一步是我的老辦法啟用 Rerank 后把召回?cái)?shù)量從 10 降到 5讓上下文更精煉第二步是把 max_new_tokens 調(diào)大一些給模型更多輸出空間。條件允許的情況下?lián)Q 14B 模型會(huì)徹底改善這類問題。6.4 癥狀四導(dǎo)入文檔時(shí)解析任務(wù)失敗日志指向 PaddleOCR現(xiàn)象批量導(dǎo)入 PDF 時(shí)部分任務(wù)失敗日志里有 Paddle 相關(guān)的異常。排查鏈路確認(rèn)是 GPU 版 Paddle 在沒有 CUDA 環(huán)境時(shí)的兼容問題卸載后安裝 CPU 版解決。部分掃描版 PDF 存在旋轉(zhuǎn)頁需要開啟 OCR 中的自動(dòng)旋轉(zhuǎn)校正選項(xiàng)。對(duì)于雙欄排版的掃描件版面分析尤其重要。如果不開版面分析兩欄文字會(huì)被按行串聯(lián)上下文語義錯(cuò)亂。最終建議是如果你的文檔以掃描件為主先單獨(dú)跑一輪 OCR 測(cè)試任務(wù)確認(rèn) Paddle 環(huán)境沒問題再批量導(dǎo)入。批量導(dǎo)入前用小樣本試跑能省下不少排查任務(wù)失敗的時(shí)間。7. 部署完之后的日常使用與進(jìn)階方向7.1 我的日常操作流從搭好到用好系統(tǒng)穩(wěn)定運(yùn)行之后我把日常操作固定成了一套流程。新增文檔統(tǒng)一放到一個(gè)待處理目錄定期上傳到 WeKnora 并觸發(fā)解析每周跑一輪事先準(zhǔn)備的問題測(cè)試集——大概二十個(gè)常見客戶問題逐個(gè)問答看答案質(zhì)量有沒有波動(dòng)如果換了模型版本先用這套測(cè)試集做 A/B 對(duì)比不會(huì)直接在生產(chǎn)知識(shí)庫(kù)上開新模型。另外一個(gè)容易被忽略的事是索引維護(hù)。文檔更新后舊索引里的內(nèi)容不會(huì)自動(dòng)消失需要重新導(dǎo)入或刪除。我的做法是給每個(gè)知識(shí)庫(kù)設(shè)定負(fù)責(zé)人文檔版本更新時(shí)同步做索引重建。不然舊版本和新版本的內(nèi)容混在檢索結(jié)果里答案可能引用已經(jīng)作廢的政策或報(bào)價(jià)。7.2 團(tuán)隊(duì)權(quán)限與 SSOOIDC 和賬號(hào)體系WeKnora 支持多用戶體系而且熱詞里也有weknora oidc這個(gè)檢索詞說明不少人在問 SSO 集成的問題。我在內(nèi)網(wǎng)環(huán)境里配置了 OIDC 對(duì)接企業(yè)現(xiàn)有的統(tǒng)一認(rèn)證這樣團(tuán)隊(duì)成員不需要單獨(dú)注冊(cè)賬號(hào)直接用公司賬號(hào)登錄。這一塊在團(tuán)隊(duì)場(chǎng)景里幾乎是必須的否則每個(gè)人都要手動(dòng)開賬號(hào)權(quán)限也不好收斂。權(quán)限控制的粒度上我的建議是業(yè)務(wù)敏感的知識(shí)庫(kù)要有獨(dú)立的訪問權(quán)限控制不要讓所有登錄用戶都能看全量文檔。我們實(shí)際就把財(cái)務(wù)相關(guān)規(guī)則庫(kù)和銷售產(chǎn)品庫(kù)分開了不同角色只能檢索自己有權(quán)限的知識(shí)庫(kù)。7.3 結(jié)合 Dify 做更復(fù)雜的工作流編排部署完一段時(shí)間后我也嘗試了把 WeKnora 和 Dify 結(jié)合。思路是WeKnora 負(fù)責(zé)文檔解析、知識(shí)庫(kù)管理和精準(zhǔn)檢索Dify 負(fù)責(zé)更靈活的對(duì)話工作流、外部工具接入、以及和現(xiàn)有業(yè)務(wù)系統(tǒng)對(duì)接。比如客戶問題進(jìn)來自動(dòng)分類-不同分類走不同知識(shí)庫(kù)-再觸發(fā)工單創(chuàng)建這類流程Dify 的編排體驗(yàn)比 WeKnora 內(nèi)置功能更細(xì)膩。兩個(gè)開源項(xiàng)目各司其職反而是比較舒服的組合方式。7.4 進(jìn)階功能GraphRAG 和模型微調(diào)如果知識(shí)庫(kù)里的實(shí)體關(guān)系很復(fù)雜比如供應(yīng)鏈關(guān)系、組織架構(gòu)、人員變動(dòng)這類數(shù)據(jù)可以考慮開啟 WeKnora 的圖增強(qiáng)能力也就是 GraphRAG 方向。它會(huì)把文檔中的實(shí)體和關(guān)系抽出來構(gòu)建知識(shí)圖譜檢索時(shí)不光找相似段落還能沿著關(guān)系鏈找答案。我實(shí)測(cè)在公司上下游關(guān)聯(lián)這類問題上圖譜增強(qiáng)明顯比純向量檢索強(qiáng)。模型微調(diào)這塊我沒有深入但客觀說必要性不大。對(duì)大多數(shù)團(tuán)隊(duì)換更好的基礎(chǔ)模型、調(diào)好切片和檢索參數(shù)收益遠(yuǎn)大于微調(diào)。微調(diào)是針對(duì)模型回答風(fēng)格或特定領(lǐng)域術(shù)語做定制時(shí)才需要考慮的選項(xiàng)。整套系統(tǒng)跑了快兩個(gè)月最直觀的感受是開源知識(shí)庫(kù)的差距不在模型而在文檔解析和檢索鏈路的成熟度。WeKnora 讓我把精力從怎么洗文檔、怎么搭索引這類臟活里解放出來集中到真正的調(diào)優(yōu)和場(chǎng)景設(shè)計(jì)上。如果你手里也有一堆無法直接喂給大模型的文檔我建議直接拿 WeKnora 跑一輪最小知識(shí)庫(kù)驗(yàn)證先把鏈路通起來再逐步加 Rerank、Agent 和 Dify 工作流。后面我還打算把企業(yè)微信里的歷史消息自動(dòng)同步進(jìn)去到時(shí)候再更新一篇實(shí)踐記錄。 WeKnora本地部署實(shí)戰(zhàn)：一站式RAG知識(shí)庫(kù)解決復(fù)雜文檔解析
1. 為什么我最終從拼接式RAG換成了 WeKnora 這種一站式方案說個(gè)真實(shí)場(chǎng)景我手頭維護(hù)的資料庫(kù)大概有三百多份文檔包括產(chǎn)品白皮書、售前方案PPT、掃描版合同、客戶FAQ、以及大量帶表格和圖片的PDF。原本的檢索方式就是網(wǎng)盤加文件夾再配一個(gè)全文搜索工具真到了去年給某客戶報(bào)的報(bào)價(jià)是什么這種問題翻十幾分鐘是常態(tài)。最初我并沒有直接上 WeKnora而是走了很多人都會(huì)走的路自己拼一套R(shí)AG。向量庫(kù)用 MilvusEmbedding 用 BGELLM 打算先接云端 API文檔解析用 PyMuPDF 配合自研規(guī)則做切片。折騰了兩周能跑通但效果一言難盡——表格被切得粉碎掃描件直接是空文本圖片里的關(guān)鍵信息一個(gè)都抽不出來問出來的答案驢唇不對(duì)馬嘴。后來在一個(gè)開源社區(qū)的討論帖里看到 WeKnora才知道騰訊微信團(tuán)隊(duì)開源了這個(gè)項(xiàng)目。它的定位和普通RAG框架不太一樣它不是讓你自己拼裝而是把數(shù)據(jù)接入、文檔理解、切片、索引、混合檢索、重排、生成、Agent 編排全部串成一條完整流水線而且對(duì)中文場(chǎng)景的處理明顯更細(xì)致。我把它部署到本地之后第一個(gè)感覺是這才是文檔該有的待遇。PAW 文檔理解流水線能把版面分析、OCR、表格轉(zhuǎn) Markdown、圖表信息提取這些臟活全部接管這在以前是我要寫幾千行代碼去做的事。這套系統(tǒng)適合誰來用我覺得大概是兩類人一類是像我一樣被各種格式混亂、掃描件居多、表格密布的文檔折磨得夠嗆想搭一個(gè)真正能問問題的內(nèi)部知識(shí)庫(kù)另一類是團(tuán)隊(duì)已經(jīng)有一些 LLM 使用經(jīng)驗(yàn)但發(fā)現(xiàn)通用 RAG 框架對(duì)復(fù)雜文檔的解析和召回精度不夠需要一個(gè)更完整的開源知識(shí)庫(kù)底座。整篇文章我會(huì)把選型理由、模型決策、部署步驟、踩坑過程、調(diào)優(yōu)方法完整記錄下來按我實(shí)際操作順序?qū)懖皇钦罩俜?README 念后者很多關(guān)鍵彎路根本不會(huì)告訴你。先給一個(gè)結(jié)論如果你現(xiàn)在的痛點(diǎn)只是缺一個(gè)工作流編排平臺(tái)那 Dify 可能更合適但如果痛點(diǎn)在于文檔根本進(jìn)不去、檢索不準(zhǔn)、表格一塌糊涂WeKnora 這種把文檔解析做到極致的開源知識(shí)庫(kù)方案會(huì)更能解決問題。2. 部署前的關(guān)鍵決策模型放哪、機(jī)器要多大、選哪家Embedding2.1 LLM 選型我用 Ollama 跑 Qwen而不是直接接云端 API標(biāo)題既然叫本地部署實(shí)錄那大模型也應(yīng)該是本地的否則沒意義。我最早考慮過直接把 WeKnora 的 LLM 接口指向 OpenAI 兼容的云端 API這樣最省事但數(shù)據(jù)都要出內(nèi)網(wǎng)在辦公場(chǎng)景里過不了安全這一關(guān)。所以最后選了 Ollama 作為本地模型運(yùn)行時(shí)。Ollama 的好處是極簡(jiǎn)一條命令拉模型一條命令起服務(wù)而且它提供了 OpenAI 兼容接口WeKnora 配置模型時(shí)可以直接走 OpenAI 兼容協(xié)議非常方便。模型選擇上我對(duì)比了三個(gè)方向Qwen2.5-7B-Instruct中文理解能力扎實(shí)7B 量級(jí)在 CPU 上也能勉強(qiáng)跑起來是我最終的主力模型。DeepSeek-R1-Distill-Qwen-7B推理能力強(qiáng)但速度偏慢適合做逐步推理類的復(fù)雜問題。熱詞里也有 deepseek 本地部署說明這條路很多人走通了。Qwen2.5-14B如果你有 16GB 以上顯存強(qiáng)烈建議直接上 14B答案質(zhì)量比 7B 高一個(gè)檔次尤其是長(zhǎng)文檔總結(jié)場(chǎng)景。量化級(jí)別我選的 Q4_K_M。7B 的 Q4_K_M 模型文件大概 4.7GB14B 大概 9GB這是 CPU 推理和顯存占用之間的平衡點(diǎn)。再低比如 Q2 就別用了質(zhì)量衰減肉眼可見。2.2 Embedding 和 Rerank 不能省這是檢索精度的真正分水嶺很多教程只教你配置 LLMEmbedding 隨便選一個(gè)Rerank 干脆不配。我在實(shí)操中的結(jié)論是Rerank 對(duì)回答質(zhì)量的影響甚至大于換一個(gè)大模型。Embedding 我用的是 BAAI 的 bge-m3原因很直接它對(duì)中文語義的支持明顯好于 nomic-embed-text 這類英文為主的模型而且支持 8192 token 的長(zhǎng)文本處理整段方案描述不容易被截?cái)?。?Ollama 里拉下來就是一條命令的事。Rerank 也是 BGE 家族的 bge-reranker-v2-m3。它做的事情是先讓向量檢索和關(guān)鍵詞檢索各召回一批候選文檔比如總共 50 條Rerank 再逐條計(jì)算和問題的真實(shí)相關(guān)性把最相關(guān)的 5 到 10 條排到最前面。這一步可以理解為粗篩靠向量精排靠重排。如果你硬件緊張可以先用一小批數(shù)據(jù)測(cè)試確認(rèn)檢索精度成為瓶頸了再補(bǔ)上 Rerank這個(gè)優(yōu)先級(jí)是對(duì)的。2.3 硬件底線我的實(shí)測(cè)配置與建議我部署用的是一臺(tái)舊工作站放在辦公網(wǎng)里4 核 8 線程 CPU32GB 內(nèi)存沒有 GPU。這個(gè)配置跑 Qwen2.5-7B 的 CPU 推理單輪問答大概 3 到 6 秒能忍但并發(fā)一多就明顯吃力。文檔解析特別是 OCR 階段非常吃 CPU批量導(dǎo)入 PDF 時(shí)整個(gè)系統(tǒng)會(huì)卡頓。給幾個(gè)可以參考的檔位部署規(guī)模內(nèi)存CPU/GPU模型覆蓋場(chǎng)景嘗鮮驗(yàn)證16GB4核CPU7B Q4量化單用戶少量文檔小型團(tuán)隊(duì)32GB8核CPU或入門GPU7B~14B5~10人使用生產(chǎn)環(huán)境64GB24GB顯存GPU14B多并發(fā)大量文檔一個(gè)容易被忽略的點(diǎn)內(nèi)存不只是給 LLM 用的。文檔解析進(jìn)程、Embedding 模型、向量索引、Rerank 都會(huì)常駐內(nèi)存我實(shí)測(cè)純 7B 模型 bge-m3 嵌入 bge-reranker加上 WeKnora 前后端內(nèi)存占用輕松到 14GB。16GB 的機(jī)器跑全套真的很緊張建議至少 32GB。3. 從克隆代碼到首次啟動(dòng)環(huán)境準(zhǔn)備、依賴安裝和常見版本坑3.1 環(huán)境準(zhǔn)備Python 版本是第一個(gè)坑WeKnora 的部署方式在倉(cāng)庫(kù) README 里有明確說明但版本更新比較頻繁一些細(xì)節(jié)會(huì)變。我按當(dāng)時(shí)實(shí)際操作的流程記錄你部署時(shí)如果發(fā)現(xiàn)命令不一致以你拉取到的分支 README 為準(zhǔn)。先準(zhǔn)備基礎(chǔ)環(huán)境。我踩的第一個(gè)坑就是 Python 版本必須用 3.10 或 3.11太老或太新的版本在裝依賴時(shí)都可能出編譯錯(cuò)誤。我一開始用的是系統(tǒng)自帶的 Python 3.9安裝 requirements 里的某些依賴直接報(bào)錯(cuò)換到 3.10 虛擬環(huán)境就正常了。sudo apt install python3.10-venv python3.10 -m venv weknora-venv source weknora-venv/bin/activate前端部分需要 Node.js 和 pnpm我用的是 Node 18。WeKnora 的前端是 Vue3 技術(shù)棧直接用 pnpm 管理依賴。3.2 后端依賴PaddleOCR 是最大的定時(shí)炸彈克隆代碼后進(jìn)入項(xiàng)目目錄安裝后端依賴git clone https://github.com/Tencent/WeKnora.git cd WeKnora pip install -r requirements.txt這個(gè)命令表面上普普通通但里面的雷在 PaddleOCR 相關(guān)依賴上。我第一次裝的時(shí)候直接用默認(rèn)命令pip 給我裝了一堆依賴跑起來才發(fā)現(xiàn) Paddle 的版本和 Python 不兼容進(jìn)程直接崩掉。正確的姿勢(shì)是先單獨(dú)裝 CPU 版 PaddlePaddle再裝 PaddleOCR裝完之后再用 requirements 裝其余部分。順序搞反了就很容易踩到 Paddle 把 numpy 依賴鎖上的坑。pip install paddlepaddle # CPU版本別默認(rèn)裝GPU版否則CUDA依賴會(huì)卡死你 pip install paddleocr如果你的文檔全是文本型 PDF不需要 OCR可以在 WeKnora 的解析配置里把 OCR 模塊關(guān)掉能省不少 CPU 占用。這個(gè)后面會(huì)再提。前端構(gòu)建pnpm install pnpm build第一次構(gòu)建會(huì)拉不少依賴耐心等就好。這個(gè)環(huán)節(jié)倒沒遇到太詭異的坑最多是網(wǎng)絡(luò)問題導(dǎo)致個(gè)別包下載超時(shí)重試即可。3.3 配置與啟動(dòng)把默認(rèn)端口和數(shù)據(jù)庫(kù)搞清楚WeKnora 的配置文件主要在項(xiàng)目目錄下的 config 相關(guān)文件里里面涉及數(shù)據(jù)庫(kù)地址、服務(wù)端口、日志路徑等。默認(rèn)配置可以走 SQLite小規(guī)模驗(yàn)證足夠如果團(tuán)隊(duì)一起用建議換成 MySQL不然并發(fā)寫入了會(huì)鎖庫(kù)。啟動(dòng)方式我按官方命令來后端是一個(gè) Python 服務(wù)前端是一個(gè)靜態(tài)站點(diǎn)。開發(fā)模式下前端用 dev server 跑生產(chǎn)環(huán)境用 build 后的靜態(tài)文件讓后端托管或者單獨(dú)用 Nginx 代理。首次啟動(dòng)后瀏覽器訪問前端地址它會(huì)引導(dǎo)初始化管理員賬號(hào)。到這里還沒接入模型系統(tǒng)能打開但問不了問題因?yàn)檫€沒配 LLM。這里有一個(gè)值得強(qiáng)調(diào)的細(xì)節(jié)系統(tǒng)默認(rèn)監(jiān)聽地址如果是 127.0.0.1只有本機(jī)能訪問如果想讓局域網(wǎng)同事用啟動(dòng)時(shí)要把 host 改為 0.0.0.0。但是不要把這個(gè)服務(wù)直接暴露到公網(wǎng)這個(gè)我們?cè)谧詈笠徽略僬归_說。4. 接通本地模型讓問答系統(tǒng)真正開口說話4.1 管理后臺(tái)配置 LLM 接口WeKnora 啟動(dòng)后進(jìn)入管理后臺(tái)找到模型供應(yīng)商配置頁面。這里支持多種 provider本地部署場(chǎng)景下最常用的是 OpenAI 兼容接口或者 Ollama 直連取決于版本選項(xiàng)。我當(dāng)時(shí)的配置是這樣的base_url 填http://127.0.0.1:11434/v1api_key 填任意值比如ollama因?yàn)楸镜?Ollama 不校驗(yàn) keymodel 名稱填qwen2.5:7b-instruct注意必須是 Ollama 里 pull 下來的確切名稱多一個(gè)冒號(hào)少一個(gè) tag 都會(huì)報(bào)錯(cuò)Embedding 模型同理把模型類型切到 embeddingbase_url 指到 Ollama 的地址模型名填bge-m3。Rerank 如果配了也是同樣的思路。4.2 連通性測(cè)試先 curl 后頁面別一上來就怪系統(tǒng)配置完成后WebUI 里通常有測(cè)試按鈕。如果提示連接失敗不要急著懷疑是 WeKnora 的問題先在本機(jī)用 curl 驗(yàn)證 Ollama 接口是否正常curl -X POST http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5:7b-instruct,messages:[{role:user,content:你好}]}能正常返回內(nèi)容說明 Ollama 沒問題問題出在 WeKnora 側(cè)的地址或者網(wǎng)絡(luò)。這里有個(gè)非常經(jīng)典的坑如果你用 Docker 方式跑 WeKnora容器里的 127.0.0.1 指向的是容器自己不是宿主機(jī)。這時(shí)候要把 base_url 改成http://host.docker.internal:11434/v1Linux 下如果用 docker compose可以加extra_hosts: - host.docker.internal:host-gateway。我在這一步卡了快一個(gè)小時(shí)。另一個(gè)容易踩的是 CORS。瀏覽器直接訪問前端頁面發(fā)起跨域請(qǐng)求時(shí)Ollama 默認(rèn)對(duì)來源有限制。解決辦法是給 Ollama 設(shè)置環(huán)境變量OLLAMA_ORIGINS* ollama serve簡(jiǎn)單粗暴但本地內(nèi)網(wǎng)環(huán)境這么干問題不大。要注意的是這個(gè)環(huán)境變量是進(jìn)程級(jí)的設(shè)置完要重啟 ollama 服務(wù)。4.3 第一次真實(shí)問答預(yù)期管理很重要模型配好之后我先建了一個(gè)很小的知識(shí)庫(kù)放了一份 Markdown 格式的 FAQ文檔內(nèi)容是XX 系統(tǒng)如何開通、常見錯(cuò)誤碼含義。導(dǎo)入成功后做索引然后提問客戶反饋登錄一直失敗錯(cuò)誤碼 10023怎么處理效果比我預(yù)期的好系統(tǒng)能準(zhǔn)確引用 FAQ 里的對(duì)應(yīng)條目并且返回了處理建議答案下面還掛了引用來源。但同時(shí)我也發(fā)現(xiàn)了第一個(gè)問題7B 模型對(duì)問題的理解過于字面化如果問題里不包含錯(cuò)誤碼它就不太會(huì)聯(lián)想到相關(guān) FAQ。這說明檢索鏈路本身該做的活已經(jīng)做完了瓶頸開始轉(zhuǎn)向模型推理能力。所以我建議第一次測(cè)試時(shí)把預(yù)期調(diào)低一點(diǎn)不要指望 7B 模型在沒有 Rerank、沒有調(diào)優(yōu)的情況下就給出驚艷答案。第一步只確認(rèn)鏈路通、引用準(zhǔn)后面再逐步優(yōu)化。5. 文檔解析和 Agentic RAG 的真實(shí)體驗(yàn)PAW 到底強(qiáng)在哪5.1 把一份掃描版方案 PDF 扔給 PAW 之后的對(duì)比為了測(cè)試 WeKnora 的文檔理解能力我專門找了一份舊方案文檔一個(gè)掃描版的 PDF大概是十幾頁里面包含彩色封面、目錄、帶財(cái)務(wù)數(shù)據(jù)的表格、幾張架構(gòu)圖、還有一些手寫批注的痕跡。我將它導(dǎo)入 WeKnora后臺(tái)任務(wù)跑了一陣子打開解析結(jié)果一看確實(shí)有點(diǎn)東西文字內(nèi)容被完整 OCR 出來了表格被還原成了 Markdown 表格格式架構(gòu)圖里的文字說明也被單獨(dú)提取成了圖片注釋多欄排版的閱讀順序沒有被搞亂。這些都是之前我用開源工具自研解析時(shí)會(huì)崩潰的典型場(chǎng)景。再用對(duì)照組來驗(yàn)證同一份 PDF 用 PyMuPDF 直接抽文本結(jié)果是一些空行和偶爾亂碼因?yàn)檎麄€(gè)文件本質(zhì)是圖片用單純的開源 OCR 工具跑文字是出來了但表格結(jié)構(gòu)完全丟了多欄文字串成了一坨。PAW 的價(jià)值在于流水線式地把版面分析、OCR、表格結(jié)構(gòu)識(shí)別、閱讀順序還原串起來而不是單點(diǎn)工具能比的事。5.2 混合檢索和 Rerank 在生產(chǎn)中的真實(shí)分工WeKnora 的檢索不是單一向量召回而是混合了語義向量、關(guān)鍵詞命中、知識(shí)圖譜關(guān)聯(lián)。這一點(diǎn)在業(yè)務(wù)文檔里非常有用。舉個(gè)例子文檔里經(jīng)常出現(xiàn)CRM-2024-01這種產(chǎn)品編號(hào)。你拿向量去搜CRM-2024-01效果通常不穩(wěn)定因?yàn)橄蛄磕Ｐ蛯?duì)這個(gè)字符串的理解很弱但關(guān)鍵詞檢索能精準(zhǔn)命中。反過來客戶關(guān)系管理系統(tǒng)的升級(jí)方案這種語義描述關(guān)鍵詞搜不到向量能輕松召回到相關(guān)段落?；旌蠙z索就是讓這兩條路各自發(fā)揮優(yōu)勢(shì)再合并結(jié)果。Rerank 在最終的排序階段把關(guān)。之前我把上下文數(shù)量設(shè)得很大一次性送三十條檢索結(jié)果給模型結(jié)果上下文爆炸回答質(zhì)量急劇下降。加上 Rerank 之后先把候選壓縮到 top 5模型輸入更干凈回答質(zhì)量直接提升。所以我在調(diào)優(yōu)時(shí)把 Rerank 的優(yōu)先級(jí)放在很前面。5.3 Agentic RAG 的實(shí)際效果什么時(shí)候該用什么時(shí)候別濫用WeKnora 的 Agentic RAG 模式在管理后臺(tái)可以開啟。它的邏輯是讓模型不再做一次檢索一次回答而是先拆解用戶的復(fù)雜問題再?zèng)Q定去哪個(gè)知識(shí)庫(kù)檢索、調(diào)用什么工具、分幾步回答。我測(cè)試過一個(gè)多步驟問題對(duì)比新老兩版售后服務(wù)政策中退換貨時(shí)效的變化并總結(jié)對(duì)客戶溝通的影響?；A(chǔ) RAG 模式下模型很容易只找到其中一個(gè)版本就開答漏掉對(duì)比。切到 Agent 模式后它會(huì)先拆成找到兩個(gè)版本-抽取退換貨條款-對(duì)比差異-生成結(jié)論幾步看起來更接近人的檢索路徑。但我也要潑一盆冷水Agent 模式不是默認(rèn)開啟就萬事大吉的。如果知識(shí)庫(kù)范圍太大、工具權(quán)限沒有收斂模型反而會(huì)自由發(fā)揮檢索一些無關(guān)的內(nèi)容甚至憑空生成中間結(jié)論。我的做法是在配置里把 Agent 可訪問的知識(shí)庫(kù)范圍明確限定并給每個(gè)知識(shí)庫(kù)加上清晰的角色描述。別讓它自由發(fā)揮太多。6. 踩坑實(shí)錄從部署到穩(wěn)定運(yùn)行的完整排查鏈路6.1 癥狀一模型服務(wù)連接超時(shí)排查到最后是 localhost 指向問題現(xiàn)象頁面測(cè)試連接提示 LLM 服務(wù)連接超時(shí)。這是部署最常遇到的第一個(gè)大坑。排查鏈路先在宿主機(jī)執(zhí)行curl http://127.0.0.1:11434/v1確認(rèn) Ollama 服務(wù)確實(shí)在跑。再確認(rèn) WeKnora 的 base_url 是否正確。如果 WeKnora 跑在 Docker 容器里127.0.0.1指容器自己必須改用host.docker.internal。檢查 Ollama 是否開啟了跨域限制。前端直連時(shí)會(huì)報(bào) CORS 錯(cuò)誤設(shè)置OLLAMA_ORIGINS*后重啟。最后定位到的根因其實(shí)就是第二點(diǎn)容器內(nèi)外 localhost 的含義不同。這個(gè)坑在本地部署里極具代表性屬于寫配置時(shí)看起來完全正確跑起來就是不通的典型。6.2 癥狀二文檔索引成功但答案答非所問現(xiàn)象知識(shí)庫(kù)索引任務(wù)顯示成功提問后答案和文檔內(nèi)容沒有明確關(guān)系甚至引用來源都不對(duì)。排查鏈路先打開文檔解析結(jié)果確認(rèn)文本內(nèi)容是否真的被正確提取。結(jié)果發(fā)現(xiàn)文本在但被切成片段。再檢查檢索調(diào)試頁面看輸入問題后到底召回了哪些片段。發(fā)現(xiàn)召回的段落里只有一半和問題相關(guān)另一半是其他主題的內(nèi)容。進(jìn)一步查了 chunk 設(shè)置默認(rèn)的切分大小偏大一段話里混了兩個(gè)主題向量檢索時(shí)語義就不夠聚焦。解決方案是重建索引并把切片策略調(diào)小。比如 chunk_size 從默認(rèn)值調(diào)成 512上下文重疊 100。具體要結(jié)合文檔特點(diǎn)調(diào)但方向是讓每個(gè)切片盡量聚焦單一主題。改完后重新導(dǎo)入或重建索引答案質(zhì)量明顯好轉(zhuǎn)。這個(gè)過程讓我意識(shí)到一個(gè)經(jīng)常被忽視的事情RAG 系統(tǒng)的錯(cuò)誤不一定出在模型很多是先出在文檔切片環(huán)節(jié)。切片像切菜切得太大一鍋燉不下切得太碎味道就散了。WeKnora 雖然切片策略可配置但默認(rèn)值未必適合你的文檔。6.3 癥狀三7B 模型回答讀不出重點(diǎn)開頭啰嗦、結(jié)尾敷衍現(xiàn)象Qwen2.5-7B 在長(zhǎng)文檔問答時(shí)答案前半段在復(fù)述文檔標(biāo)題后半段直接說請(qǐng)參考文檔第X頁沒有實(shí)際內(nèi)容。排查鏈路檢查送進(jìn)模型的上下文內(nèi)容發(fā)現(xiàn)一次塞了太多檢索片段超出了模型的 32K 上下文窗口被系統(tǒng)自動(dòng)截?cái)?。截?cái)嗪竽Ｐ椭豢吹搅宋臋n開頭的章節(jié)信息沒看到真正的內(nèi)容段落。量化模型本身對(duì)長(zhǎng)文本的歸納能力有限7B 在上下文很長(zhǎng)時(shí)容易只看見開頭和結(jié)尾。解決方案有兩步第一步是我的老辦法啟用 Rerank 后把召回?cái)?shù)量從 10 降到 5讓上下文更精煉第二步是把 max_new_tokens 調(diào)大一些給模型更多輸出空間。條件允許的情況下?lián)Q 14B 模型會(huì)徹底改善這類問題。6.4 癥狀四導(dǎo)入文檔時(shí)解析任務(wù)失敗日志指向 PaddleOCR現(xiàn)象批量導(dǎo)入 PDF 時(shí)部分任務(wù)失敗日志里有 Paddle 相關(guān)的異常。排查鏈路確認(rèn)是 GPU 版 Paddle 在沒有 CUDA 環(huán)境時(shí)的兼容問題卸載后安裝 CPU 版解決。部分掃描版 PDF 存在旋轉(zhuǎn)頁需要開啟 OCR 中的自動(dòng)旋轉(zhuǎn)校正選項(xiàng)。對(duì)于雙欄排版的掃描件版面分析尤其重要。如果不開版面分析兩欄文字會(huì)被按行串聯(lián)上下文語義錯(cuò)亂。最終建議是如果你的文檔以掃描件為主先單獨(dú)跑一輪 OCR 測(cè)試任務(wù)確認(rèn) Paddle 環(huán)境沒問題再批量導(dǎo)入。批量導(dǎo)入前用小樣本試跑能省下不少排查任務(wù)失敗的時(shí)間。7. 部署完之后的日常使用與進(jìn)階方向7.1 我的日常操作流從搭好到用好系統(tǒng)穩(wěn)定運(yùn)行之后我把日常操作固定成了一套流程。新增文檔統(tǒng)一放到一個(gè)待處理目錄定期上傳到 WeKnora 并觸發(fā)解析每周跑一輪事先準(zhǔn)備的問題測(cè)試集——大概二十個(gè)常見客戶問題逐個(gè)問答看答案質(zhì)量有沒有波動(dòng)如果換了模型版本先用這套測(cè)試集做 A/B 對(duì)比不會(huì)直接在生產(chǎn)知識(shí)庫(kù)上開新模型。另外一個(gè)容易被忽略的事是索引維護(hù)。文檔更新后舊索引里的內(nèi)容不會(huì)自動(dòng)消失需要重新導(dǎo)入或刪除。我的做法是給每個(gè)知識(shí)庫(kù)設(shè)定負(fù)責(zé)人文檔版本更新時(shí)同步做索引重建。不然舊版本和新版本的內(nèi)容混在檢索結(jié)果里答案可能引用已經(jīng)作廢的政策或報(bào)價(jià)。7.2 團(tuán)隊(duì)權(quán)限與 SSOOIDC 和賬號(hào)體系WeKnora 支持多用戶體系而且熱詞里也有weknora oidc這個(gè)檢索詞說明不少人在問 SSO 集成的問題。我在內(nèi)網(wǎng)環(huán)境里配置了 OIDC 對(duì)接企業(yè)現(xiàn)有的統(tǒng)一認(rèn)證這樣團(tuán)隊(duì)成員不需要單獨(dú)注冊(cè)賬號(hào)直接用公司賬號(hào)登錄。這一塊在團(tuán)隊(duì)場(chǎng)景里幾乎是必須的否則每個(gè)人都要手動(dòng)開賬號(hào)權(quán)限也不好收斂。權(quán)限控制的粒度上我的建議是業(yè)務(wù)敏感的知識(shí)庫(kù)要有獨(dú)立的訪問權(quán)限控制不要讓所有登錄用戶都能看全量文檔。我們實(shí)際就把財(cái)務(wù)相關(guān)規(guī)則庫(kù)和銷售產(chǎn)品庫(kù)分開了不同角色只能檢索自己有權(quán)限的知識(shí)庫(kù)。7.3 結(jié)合 Dify 做更復(fù)雜的工作流編排部署完一段時(shí)間后我也嘗試了把 WeKnora 和 Dify 結(jié)合。思路是WeKnora 負(fù)責(zé)文檔解析、知識(shí)庫(kù)管理和精準(zhǔn)檢索Dify 負(fù)責(zé)更靈活的對(duì)話工作流、外部工具接入、以及和現(xiàn)有業(yè)務(wù)系統(tǒng)對(duì)接。比如客戶問題進(jìn)來自動(dòng)分類-不同分類走不同知識(shí)庫(kù)-再觸發(fā)工單創(chuàng)建這類流程Dify 的編排體驗(yàn)比 WeKnora 內(nèi)置功能更細(xì)膩。兩個(gè)開源項(xiàng)目各司其職反而是比較舒服的組合方式。7.4 進(jìn)階功能GraphRAG 和模型微調(diào)如果知識(shí)庫(kù)里的實(shí)體關(guān)系很復(fù)雜比如供應(yīng)鏈關(guān)系、組織架構(gòu)、人員變動(dòng)這類數(shù)據(jù)可以考慮開啟 WeKnora 的圖增強(qiáng)能力也就是 GraphRAG 方向。它會(huì)把文檔中的實(shí)體和關(guān)系抽出來構(gòu)建知識(shí)圖譜檢索時(shí)不光找相似段落還能沿著關(guān)系鏈找答案。我實(shí)測(cè)在公司上下游關(guān)聯(lián)這類問題上圖譜增強(qiáng)明顯比純向量檢索強(qiáng)。模型微調(diào)這塊我沒有深入但客觀說必要性不大。對(duì)大多數(shù)團(tuán)隊(duì)換更好的基礎(chǔ)模型、調(diào)好切片和檢索參數(shù)收益遠(yuǎn)大于微調(diào)。微調(diào)是針對(duì)模型回答風(fēng)格或特定領(lǐng)域術(shù)語做定制時(shí)才需要考慮的選項(xiàng)。整套系統(tǒng)跑了快兩個(gè)月最直觀的感受是開源知識(shí)庫(kù)的差距不在模型而在文檔解析和檢索鏈路的成熟度。WeKnora 讓我把精力從怎么洗文檔、怎么搭索引這類臟活里解放出來集中到真正的調(diào)優(yōu)和場(chǎng)景設(shè)計(jì)上。如果你手里也有一堆無法直接喂給大模型的文檔我建議直接拿 WeKnora 跑一輪最小知識(shí)庫(kù)驗(yàn)證先把鏈路通起來再逐步加 Rerank、Agent 和 Dify 工作流。后面我還打算把企業(yè)微信里的歷史消息自動(dòng)同步進(jìn)去到時(shí)候再更新一篇實(shí)踐記錄。