WeKnora RAG 知識庫本地部署 30 分鐘跑通配置、檢索驗證與排障全在這一篇【免費下載鏈接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.項目地址: https://gitcode.com/GitHub_Trending/we/WeKnoraWeKnora 是一個開源 LLM 知識平臺docker 部署后把 PDF、Word、網(wǎng)頁解析成本地 RAG 知識庫提供帶引用的 RAG 問答、ReAct 智能體、自動維護的 Wiki 三種用法。這篇面向你——第一次做本地部署的人走完能獨立把服務跑起來、配好第一個知識庫、驗證檢索可用并知道卡住時往哪查。文檔進入后由 docreader 解析成塊向量化寫入向量庫你提問時走關(guān)鍵詞加向量的混合檢索大模型基于片段作答并附引用。默認向量庫是 ParadeDBPostgreSQL 加 pgvector改RETRIEVE_DRIVER可換成 Milvus、Qdrant、OpenSearch 等組件都能替換支持完全私有化。值不值得用先判斷適合團隊文檔問答、私有知識庫、回答必須帶出處這類場景。文檔格式支持 10 余種LLM 提供方 20 多個組件可替換。下面三類情況建議先別上需要實時業(yè)務數(shù)據(jù)。它索引的是文檔快照數(shù)據(jù)更新要靠數(shù)據(jù)源同步。對首字延遲極敏感的在線客服。先用 RAG 模式實測延遲再決定要不要上智能體。純向量檢索就能滿足、且已有成熟 RAG 棧。遷移收益不高。階段一 用 docker compose 把服務 30 分鐘拉起來準備清單軟件Docker、Docker Compose、Git。Go、Python、數(shù)據(jù)庫都不用本地裝核心組件全在容器里。資源至少 8GB 可用內(nèi)存磁盤預留 20GB 以上向量庫用 pgvector 時內(nèi)存壓力更小。模型服務這是最容易卡住的一步至少準備一個對話模型 一個向量Embedding模型來源二選一——本地 Ollama先ollama serve并拉好模型或任意 OpenAI 兼容遠程 API備好 base_url 和 api_key。網(wǎng)絡(luò)首次部署要能拉 Docker Hub 鏡像后續(xù)解析文檔、導入網(wǎng)頁還需要出站網(wǎng)絡(luò)。docker compose 啟動命令git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env.env.example自帶分組注釋拉起前重點核對三處DB_*數(shù)據(jù)庫賬號密碼、REDIS_ADDR、WEKNORA_VERSION鏡像版本標簽默認 latest。然后docker compose pull docker compose up -d容器出現(xiàn)什么狀態(tài)才算起來了app 服務內(nèi)置/health健康檢查frontend 會等 app 健康之后才啟動所以看到WeKnora-frontend進入 running核心鏈路基本就通了。習慣單條命令的話./scripts/start_all.sh會先做前置檢查、缺.env時自動從模板創(chuàng)建再拉起服務效果等價。可選組件按 profile 追加目的命令知識圖譜Neo4jdocker compose --profile neo4j up -d對象存儲MinIOdocker compose --profile minio up -d調(diào)用鏈追蹤Langfusedocker compose --profile langfuse up -d自建網(wǎng)絡(luò)搜索SearXNGdocker compose --profile searxng up -d全部功能docker compose --profile full up -d停止用docker compose down。升級時先把WEKNORA_VERSION改成目標 release tag注意 v 前綴再執(zhí)行docker compose pull docker compose up -d只跑up -d會復用本地舊鏡像界面版本可能沒跟上。階段二 配好模型喂進第一份文檔模型按知識庫配置不是一次性全局初始化登錄前端后新建知識庫向?qū)屇銥檫@個庫選對話模型和向量模型內(nèi)置測試按鈕直接驗證連通性。兩個高頻坑后端跑在容器里Ollama 地址要填http://host.docker.internal:11434填localhost:11434連不上宿主機。向量模型建庫后不要換。換了等于向量維度或語義空間變了整個索引要重建。.env里的核心模型變量配合config/builtin_models.yaml啟用聲明式配置LLM_MODEL_NAME... # 對話模型 LLM_BASE_URL... # 遠程 API 必填 LLM_API_KEY... EMBEDDING_MODEL_NAME... # 向量模型Ollama 時填模型名 EMBEDDING_API_KEY...本地 Ollama 方案里向量模型名就是 Ollama 模型名地址沿用OLLAMA_BASE_URL。啟用重排再補 RERANK_MODEL_NAME / RERANK_BASE_URL / RERANK_API_KEY重排、圖片理解 VLM、語音轉(zhuǎn)寫 ASR 都可以先不開之后在界面隨時加。最值得調(diào)的就這 4 組參數(shù)存儲與檢索參數(shù)集中在config/config.yaml默認值就能跑knowledge_base.chunk_size: 512/chunk_overlap: 50分塊大小與重疊。塊太小上下文斷裂太大召回精度下降按文檔類型在 256–1024 之間試。conversation.embedding_top_k: 30向量候選召回數(shù)量相關(guān)內(nèi)容總召回不上來就調(diào)大。conversation.vector_threshold: 0.2向量相似度下限回答泛泛而談或拒答時往下調(diào)。conversation.rerank_threshold: 0.3/rerank_top_k: 30重排后的過濾線與保留條數(shù)開了重排反而更差就下調(diào)。另外conversation.max_rounds: 5控制多輪上下文保留輪數(shù)默認夠用。文件存儲默認STORAGE_TYPElocal寫入容器卷/data/files多副本或要對外分享圖片時再切 MinIO/S3。單文件上限MAX_FILE_SIZE_MB默認 50MB屬于部署期配置改完要重啟容器才生效。首次部署注冊是開放的注冊后你會自動擁有一個工作空間并成為 Owner。團隊部署建議在第一個賬號注冊完之后設(shè)DISABLE_REGISTRATIONtrue關(guān)掉公開注冊改用邀請鏈接加人。上傳第一份文檔進知識庫傳一份 PDF 或 Markdown。狀態(tài)流轉(zhuǎn)是 pending → processing → finalizing → completed列表頁實時刷新進度解析完能看到分塊數(shù)。階段三 驗證檢索真的可用四步驗證每步都有明確成功標志哪步失敗就回到對應參數(shù)后端存活curl http://localhost:8080/health應返回{status:ok}。失敗先docker compose ps看容器狀態(tài)。前端可用瀏覽器打開http://localhost能到達注冊/登錄頁。打不開多為 80、8080 端口被占改.env里的FRONTEND_PORT/APP_PORT。文檔解析成功狀態(tài)走到 completed 且分塊數(shù)非零。長期卡在 processing主服務日志搜 ERROR最常見是向量模型沒配齊。檢索回答正確對話頁選這個知識庫問一個只有文檔里才有的事實性問題。成功標志是回答帶引用角標點開能跳回原文對應片段。泛泛而談或拒答回上一節(jié)調(diào)低vector_threshold或重排閾值。排障速查表 常見癥狀與第一手命令癥狀先執(zhí)行什么最常見原因服務起不來、界面打不開docker compose logs -f app docreader postgres數(shù)據(jù)庫沒就緒或.env里DB_*、REDIS_*與容器內(nèi)實際不符docreader 不健康時 app 會一直等它能啟動但上傳文檔失敗主服務日志搜ERROR模型沒配齊向量或?qū)υ捘Ｐ腿笔r解析流水線直接報錯文檔里圖片不顯示設(shè)置APP_EXTERNAL_URL本地存儲的圖片鏈接走容器內(nèi)網(wǎng)地址外部設(shè)備打不開設(shè)置后圖片經(jīng)/r/token代理轉(zhuǎn)發(fā)解析慢調(diào)WEKNORA_ASYNQ_*_CONCURRENCY系列 worker 池并發(fā)掃描件 PDF 和超大文件天然慢單次 DocReader 調(diào)用默認 30 分鐘超時整個文檔任務默認 2 小時回答質(zhì)量差先調(diào)低vector_threshold再開啟重排召回閾值過高或向量模型不貼語境換模型等于重建索引分塊參數(shù)也可能把表格、列表切碎了再進一步 數(shù)據(jù)源同步與對外集成持續(xù)更新接入飛書 Wiki/云文檔、Notion、語雀、RSS 等數(shù)據(jù)源自動增量同步比反復手工上傳更適合長期運營。對外集成作用域 API Key能力級授權(quán)、可限定到單個知識庫給第三方系統(tǒng)調(diào)用MCP ServerPyPI 包tencent-weknora-mcp支持 stdio/SSE/HTTP把檢索、問答掛給外部智能體weknoraCLI 在終端或 CI 里管知識庫。IM 渠道企微、飛書、Slack、Telegram 等十來個渠道直接問答適合客服和內(nèi)部助手場景?？捎^測啟用--profile langfuse后智能體的推理步驟、工具調(diào)用、token 消耗都能追到單次會話級別。權(quán)限與注冊工作空間內(nèi)置 Owner/Admin/Contributor/Viewer 四級角色和審計日志生產(chǎn)環(huán)境關(guān)閉公開注冊并用WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL指定首個系統(tǒng)管理員。收尾下一步接一份真實業(yè)務文檔觀察一次完整問答的引用是否正確。然后把.env的模型、存儲參數(shù)按實際環(huán)境固化用docker compose logs -f app盯兩天日志確認沒有解析積壓或模型超時。遇到答錯的片段直接在界面里編輯分塊并保存改動會自動重建索引并留修訂歷史。【免費下載鏈接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.項目地址: https://gitcode.com/GitHub_Trending/we/WeKnora創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 WeKnora RAG 知識庫本地部署 30 分鐘跑通，配置、檢索驗證與排障全在這一篇
WeKnora RAG 知識庫本地部署 30 分鐘跑通配置、檢索驗證與排障全在這一篇【免費下載鏈接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.項目地址: https://gitcode.com/GitHub_Trending/we/WeKnoraWeKnora 是一個開源 LLM 知識平臺docker 部署后把 PDF、Word、網(wǎng)頁解析成本地 RAG 知識庫提供帶引用的 RAG 問答、ReAct 智能體、自動維護的 Wiki 三種用法。這篇面向你——第一次做本地部署的人走完能獨立把服務跑起來、配好第一個知識庫、驗證檢索可用并知道卡住時往哪查。文檔進入后由 docreader 解析成塊向量化寫入向量庫你提問時走關(guān)鍵詞加向量的混合檢索大模型基于片段作答并附引用。默認向量庫是 ParadeDBPostgreSQL 加 pgvector改RETRIEVE_DRIVER可換成 Milvus、Qdrant、OpenSearch 等組件都能替換支持完全私有化。值不值得用先判斷適合團隊文檔問答、私有知識庫、回答必須帶出處這類場景。文檔格式支持 10 余種LLM 提供方 20 多個組件可替換。下面三類情況建議先別上需要實時業(yè)務數(shù)據(jù)。它索引的是文檔快照數(shù)據(jù)更新要靠數(shù)據(jù)源同步。對首字延遲極敏感的在線客服。先用 RAG 模式實測延遲再決定要不要上智能體。純向量檢索就能滿足、且已有成熟 RAG 棧。遷移收益不高。階段一 用 docker compose 把服務 30 分鐘拉起來準備清單軟件Docker、Docker Compose、Git。Go、Python、數(shù)據(jù)庫都不用本地裝核心組件全在容器里。資源至少 8GB 可用內(nèi)存磁盤預留 20GB 以上向量庫用 pgvector 時內(nèi)存壓力更小。模型服務這是最容易卡住的一步至少準備一個對話模型 一個向量Embedding模型來源二選一——本地 Ollama先ollama serve并拉好模型或任意 OpenAI 兼容遠程 API備好 base_url 和 api_key。網(wǎng)絡(luò)首次部署要能拉 Docker Hub 鏡像后續(xù)解析文檔、導入網(wǎng)頁還需要出站網(wǎng)絡(luò)。docker compose 啟動命令git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env.env.example自帶分組注釋拉起前重點核對三處DB_*數(shù)據(jù)庫賬號密碼、REDIS_ADDR、WEKNORA_VERSION鏡像版本標簽默認 latest。然后docker compose pull docker compose up -d容器出現(xiàn)什么狀態(tài)才算起來了app 服務內(nèi)置/health健康檢查frontend 會等 app 健康之后才啟動所以看到WeKnora-frontend進入 running核心鏈路基本就通了。習慣單條命令的話./scripts/start_all.sh會先做前置檢查、缺.env時自動從模板創(chuàng)建再拉起服務效果等價。可選組件按 profile 追加目的命令知識圖譜Neo4jdocker compose --profile neo4j up -d對象存儲MinIOdocker compose --profile minio up -d調(diào)用鏈追蹤Langfusedocker compose --profile langfuse up -d自建網(wǎng)絡(luò)搜索SearXNGdocker compose --profile searxng up -d全部功能docker compose --profile full up -d停止用docker compose down。升級時先把WEKNORA_VERSION改成目標 release tag注意 v 前綴再執(zhí)行docker compose pull docker compose up -d只跑up -d會復用本地舊鏡像界面版本可能沒跟上。階段二 配好模型喂進第一份文檔模型按知識庫配置不是一次性全局初始化登錄前端后新建知識庫向?qū)屇銥檫@個庫選對話模型和向量模型內(nèi)置測試按鈕直接驗證連通性。兩個高頻坑后端跑在容器里Ollama 地址要填http://host.docker.internal:11434填localhost:11434連不上宿主機。向量模型建庫后不要換。換了等于向量維度或語義空間變了整個索引要重建。.env里的核心模型變量配合config/builtin_models.yaml啟用聲明式配置LLM_MODEL_NAME... # 對話模型 LLM_BASE_URL... # 遠程 API 必填 LLM_API_KEY... EMBEDDING_MODEL_NAME... # 向量模型Ollama 時填模型名 EMBEDDING_API_KEY...本地 Ollama 方案里向量模型名就是 Ollama 模型名地址沿用OLLAMA_BASE_URL。啟用重排再補 RERANK_MODEL_NAME / RERANK_BASE_URL / RERANK_API_KEY重排、圖片理解 VLM、語音轉(zhuǎn)寫 ASR 都可以先不開之后在界面隨時加。最值得調(diào)的就這 4 組參數(shù)存儲與檢索參數(shù)集中在config/config.yaml默認值就能跑knowledge_base.chunk_size: 512/chunk_overlap: 50分塊大小與重疊。塊太小上下文斷裂太大召回精度下降按文檔類型在 256–1024 之間試。conversation.embedding_top_k: 30向量候選召回數(shù)量相關(guān)內(nèi)容總召回不上來就調(diào)大。conversation.vector_threshold: 0.2向量相似度下限回答泛泛而談或拒答時往下調(diào)。conversation.rerank_threshold: 0.3/rerank_top_k: 30重排后的過濾線與保留條數(shù)開了重排反而更差就下調(diào)。另外conversation.max_rounds: 5控制多輪上下文保留輪數(shù)默認夠用。文件存儲默認STORAGE_TYPElocal寫入容器卷/data/files多副本或要對外分享圖片時再切 MinIO/S3。單文件上限MAX_FILE_SIZE_MB默認 50MB屬于部署期配置改完要重啟容器才生效。首次部署注冊是開放的注冊后你會自動擁有一個工作空間并成為 Owner。團隊部署建議在第一個賬號注冊完之后設(shè)DISABLE_REGISTRATIONtrue關(guān)掉公開注冊改用邀請鏈接加人。上傳第一份文檔進知識庫傳一份 PDF 或 Markdown。狀態(tài)流轉(zhuǎn)是 pending → processing → finalizing → completed列表頁實時刷新進度解析完能看到分塊數(shù)。階段三 驗證檢索真的可用四步驗證每步都有明確成功標志哪步失敗就回到對應參數(shù)后端存活curl http://localhost:8080/health應返回{status:ok}。失敗先docker compose ps看容器狀態(tài)。前端可用瀏覽器打開http://localhost能到達注冊/登錄頁。打不開多為 80、8080 端口被占改.env里的FRONTEND_PORT/APP_PORT。文檔解析成功狀態(tài)走到 completed 且分塊數(shù)非零。長期卡在 processing主服務日志搜 ERROR最常見是向量模型沒配齊。檢索回答正確對話頁選這個知識庫問一個只有文檔里才有的事實性問題。成功標志是回答帶引用角標點開能跳回原文對應片段。泛泛而談或拒答回上一節(jié)調(diào)低vector_threshold或重排閾值。排障速查表 常見癥狀與第一手命令癥狀先執(zhí)行什么最常見原因服務起不來、界面打不開docker compose logs -f app docreader postgres數(shù)據(jù)庫沒就緒或.env里DB_*、REDIS_*與容器內(nèi)實際不符docreader 不健康時 app 會一直等它能啟動但上傳文檔失敗主服務日志搜ERROR模型沒配齊向量或?qū)υ捘Ｐ腿笔r解析流水線直接報錯文檔里圖片不顯示設(shè)置APP_EXTERNAL_URL本地存儲的圖片鏈接走容器內(nèi)網(wǎng)地址外部設(shè)備打不開設(shè)置后圖片經(jīng)/r/token代理轉(zhuǎn)發(fā)解析慢調(diào)WEKNORA_ASYNQ_*_CONCURRENCY系列 worker 池并發(fā)掃描件 PDF 和超大文件天然慢單次 DocReader 調(diào)用默認 30 分鐘超時整個文檔任務默認 2 小時回答質(zhì)量差先調(diào)低vector_threshold再開啟重排召回閾值過高或向量模型不貼語境換模型等于重建索引分塊參數(shù)也可能把表格、列表切碎了再進一步 數(shù)據(jù)源同步與對外集成持續(xù)更新接入飛書 Wiki/云文檔、Notion、語雀、RSS 等數(shù)據(jù)源自動增量同步比反復手工上傳更適合長期運營。對外集成作用域 API Key能力級授權(quán)、可限定到單個知識庫給第三方系統(tǒng)調(diào)用MCP ServerPyPI 包tencent-weknora-mcp支持 stdio/SSE/HTTP把檢索、問答掛給外部智能體weknoraCLI 在終端或 CI 里管知識庫。IM 渠道企微、飛書、Slack、Telegram 等十來個渠道直接問答適合客服和內(nèi)部助手場景?？捎^測啟用--profile langfuse后智能體的推理步驟、工具調(diào)用、token 消耗都能追到單次會話級別。權(quán)限與注冊工作空間內(nèi)置 Owner/Admin/Contributor/Viewer 四級角色和審計日志生產(chǎn)環(huán)境關(guān)閉公開注冊并用WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL指定首個系統(tǒng)管理員。收尾下一步接一份真實業(yè)務文檔觀察一次完整問答的引用是否正確。然后把.env的模型、存儲參數(shù)按實際環(huán)境固化用docker compose logs -f app盯兩天日志確認沒有解析積壓或模型超時。遇到答錯的片段直接在界面里編輯分塊并保存改動會自動重建索引并留修訂歷史。【免費下載鏈接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.項目地址: https://gitcode.com/GitHub_Trending/we/WeKnora創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考