WeKnora 本地部署全指南：5 分钟跑通离线 RAG 知识库

WeKnora 本地部署全指南：5 分钟跑通离线 RAG 知识库

【免费下载链接】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

当你需要让模型读懂内部合同，但又不能让任何一个字节离开内网时，这件事的解法其实不复杂——只要整条推理链路都在你自己的机器上跑。WeKnora 是一款开源的 LLM 知识平台，支持完整的本地部署：文档解析、向量化、检索、模型推理全部发生在内网，数据不出机房。它能把一堆原始文档变成可查询的 RAG 知识库、能自主编排工具推理的 Agent，以及一份会自己维护的 Wiki。这一篇就讲怎么把它跑起来、怎么调顺。

🧩 WeKnora 核心能力：解析、调度、隔离三条线

一句话结论：WeKnora 用一条可插拔的文档处理流水线 + 一个统一模型调度层 + 一套面向私有化部署的安全机制，把"文档进、答案出"整条链路搬进了你的内网。

文档处理链路：PDF 到向量的本地流水线

它做的事：接收 PDF、Word、Excel、Markdown 等十余种格式，走完"解析 → 分块 → 向量化 → 入库"四步。怎么做到：解析由独立的 docreader 服务通过 gRPC 完成（也就是主服务只管编排，解析这种重活交给独立进程），分块策略集中在 分块器模块 里实现，默认按 512 token 一片、50 token 重叠切分。对你意味着什么：换解析引擎、换分块参数都不需要动主应用代码，链路是解耦的。

模型调度层：Ollama 只是选项之一

它做的事：统一屏蔽底层模型差异，对话、Embedding（生成向量表示的模型）、Rerank（对召回结果二次排序的模型）走同一套配置接口。怎么做到：模型实现按厂商分文件组织，本地模型由 Ollama 聊天实现 和 Embedding 实现 承接，同时兼容 OpenAI、DeepSeek、Qwen 等二十多家厂商，全部通过 .env 里的声明式变量切换。对你意味着什么：今天用 Ollama 纯离线，明天某条业务线想切云端模型，改的是配置而不是代码。

安全隔离机制：为"数据不出内网"兜底

它做的事：防止敏感信息在传输和存储环节漏出去。怎么做到：API Key 与数据源凭据用 AES-256-GCM 静态加密，出站 HTTP 请求统一走防 SSRF（服务器端请求伪造，即防止服务被诱导访问内网地址）客户端，多用户场景有四级角色矩阵的 RBAC（基于角色的访问控制）。对你意味着什么：部署到内网后，它默认就是按"不可信边界"来设防的，不用自己补安全课。

三条线都看完了，接下来是最实际的部分：从零跑通。

🚀 五分钟上手：三步完成 WeKnora 离线部署

目标很明确：一台装了 Docker 和 Ollama 的机器，五分钟拿到一个可用的本地知识库。

第一步，环境准备。核心只有两样：Docker Compose 跑服务栈，Ollama 提供本地模型。硬件规模可以参考下面这张对照表：

第二步，克隆并启动：

git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env # 按需修改，文件内注释很全 docker compose pull && docker compose up -d

第三步，接入本地模型。先在本机起 Ollama 并拉取模型：

ollama serve > /dev/null 2>&1 & ollama pull qwen2.5:7b ollama pull nomic-embed-text

然后在 .env 里打开这几个关键变量（Ollama 不可用时系统只告警不阻断启动，OLLAMA_OPTIONAL默认就是 true，适合分阶段调试）：

OLLAMA_OPTIONAL=true OLLAMA_BASE_URL=http://host.docker.internal:11434 # 对话与向量化模型名称，按你实际 pull 的填写 # INIT_LLM_MODEL_NAME=... # INIT_EMBEDDING_MODEL_NAME=... # INIT_EMBEDDING_MODEL_DIMENSION=...

跑通后你应该看到：浏览器打开 http://localhost 出现 Web 界面（后端 API 在 8080 端口），注册账号后进入设置页能看到 Ollama 模型已连通，上传一篇 PDF，几分钟后就能带着引用片段问答。

服务跑起来只是及格线，下面是让它"好用"的三个调优动作。

📈 调优实战：检索命中率与解析吞吐的三处调整

结论先行：绝大多数"不好用"来自两处——分块参数和检索阈值没调，以及解析并发保守导致上传后长时间排队。

调整分块与检索阈值，治"答非所问"

现象：模型回答和文档原文对不上，或者引用总是差半句。原因通常是默认 512 的分块把关键段落切散了，或者召回阈值过松把噪声也放了进来。调整方法：在 config/config.yaml 里改两处——

knowledge_base: chunk_size: 512 # 段落长的文档可降到 300，让块更贴近语义边界 chunk_overlap: 50 conversation: vector_threshold: 0.2 # 余弦相似度门槛，答非所问时调高到 0.3 收紧 rerank_threshold: 0.3 # 配合重排模型过滤低分召回

效果变化：分块变小会牺牲一点召回广度但显著提升片段相关性；阈值每上调 0.05，噪声明显减少，代价是偶发的"无匹配"兜底回复变多。

放开解析并发，治"上传后一直排队"

现象：批量上传几十份文档后，解析任务长时间停在队列里。原因：重型解析器默认只有 1 个并发 worker，Embedding 也是小批量。调整方法（.env 中放开）：

DOCREADER_GRPC_MAX_WORKERS=4 # gRPC 解析并发，默认 4，CPU 富余可再调 DOCREADER_MARKITDOWN_MAX_WORKERS=2 # 重型解析器并发，默认 1 # BATCH_EMBED_SIZE 留空走代码默认，内存充足可显式调大

效果变化：同等文档量下的入库时间大致按并发线性缩短；注意这是拿内存换时间，8GB 机器的话 worker 数别超过 2。

本地模型推理提速，治"首字等待久"

现象：纯 CPU 环境下回答首字要等十几秒。做法是两条：对话模型选量化版（同参数量下快近一倍），并通过 Ollama 的标准选项控制上下文窗口与线程数——Ollama 请求里透传num_ctx（上下文长度，文档很长才需要 4096 以上）和num_thread（建议设为物理核心数，超配只会抖动）。效果变化：首字延迟通常能压到一半以内，而回答质量基本不变——因为瓶颈本来就在解码吞吐，不在温度参数。

🔍 踩坑速查与延伸资源

下面是内网友好的社区里出镜率最高的五个故障，按"现象 → 原因 → 动作"对照处理：

延伸资源，按需取用：

• docs/QA.md：官方常见问题排查手册
• docs/api/README.md：全部 REST API 接口参考
• client/example.go：Go 客户端调用示例代码
• docs/LITE.md：Lite 版与标准版能力差异说明，选型用

打开终端，敲下docker compose up -d，你的知识库就在本地跑起来了。

【免费下载链接】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