3步在自有服务器部署私有知识库：WeKnora 本地化 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 知识库。过去一年我在内网环境里用它接了 Ollama 本地模型，跑通了一条不经过任何第三方 API 的知识问答链路。这篇文章复盘整个落地过程：环境怎么搭、配置怎么调、踩过的坑怎么填。
一、为什么值得把知识库搬回自己的机房
我们的场景很典型：几百份产品手册、故障案例和合规文档散落在网盘和共享目录里，老员工离职后没人答得上来。上云做 RAG 被合规卡住——文档里有客户信息，不能出内网；自建又不想从零写解析、分块、检索这一整套东西。
WeKnora 解决的就是这个组合问题，核心是三件事：
- 快速问答：基于 RAG 的日常查询，答案带引用来源，点一下能看到原文片段；
- Agent 推理：ReAct 模式自主编排知识库检索、MCP 工具和网页搜索，处理多步骤任务；
- Wiki 模式：Agent 自动把原始文档提炼成互相链接的 Markdown 页面，带版本历史和一键回滚。
它覆盖 PDF、Word、Excel、图片等十余种文档格式，模型层兼容 Ollama、OpenAI、DeepSeek、Qwen 等二十多家厂商，向量库从 pgvector 到 Milvus、Qdrant 都能换。对我们来说最关键的是最后一点：大模型、向量库、存储全部可替换，换成 Ollama 之后，整条链路的数据就没有离开过机房。
二、首次部署：三条命令跑起来
前置要求只有 Docker 和 Docker Compose。整个过程比预想的短，主要精力花在配置文件上。
第 1 步：拉代码并复制环境变量模板。
git clone https://gitcode.com/GitHub_Trending/we/WeKnora 之后，把仓库里的 .env.example 复制成 .env。这个文件按 A~J 十个分组注释得很细（部署、存储、向量库、模型、解析、认证……），是我们后面所有调整的唯一入口。
第 2 步：配好本地模型变量。用 Ollama 时，需要在 .env 里写清四个变量：LLM 模型名（如INIT_LLM_MODEL_NAME）、Embedding 模型名、向量维度（INIT_EMBEDDING_MODEL_DIMENSION）和 Embedding 模型 ID。走远程 API 的模型则额外要填 BASE_URL 和 API_KEY。注意向量维度必须和模型实际输出一致，写错了后面入库会直接报错。
第 3 步：启动服务。
docker compose pull && docker compose up -d启动核心服务，浏览器访问 http://localhost 即可登录使用；后端 API 在 8080 端口。用本地 Ollama 的话，先确保宿主机上 Ollama 服务在跑。
⚠️ 注意：如果要知识图谱（Neo4j）、MinIO 对象存储或 Langfuse 追踪，需要加--profile neo4j、--profile minio、--profile langfuse启动，多个 profile 可以叠加。不带 profile 默认只起核心组件。
三、配置怎么调：两个文件各管一摊
跑通之后，日常优化集中在两个位置，建议先搞清楚各自的职责再动手。
config/config.yaml 管"问答行为"。几个值得认识的默认值：
| 配置项 | 默认值 | 作用 |
|---|---|---|
| conversation.keyword_threshold | 0.3 | 关键词（BM25）召回的分数门槛，调高则召回更严 |
| conversation.vector_threshold | 0.2 | 向量召回门槛，控制语义匹配的相关度下限 |
| conversation.rerank_threshold / rerank_top_k | 0.3 / 30 | 重排序阶段的过滤线与候选条数 |
| knowledge_base.chunk_size / chunk_overlap | 512 / 50 | 文档分块大小与重叠，直接影响检索粒度 |
| conversation.max_rounds | 5 | 多轮上下文保留轮数 |
我们的调整经验：初期答案"太发散"时，优先提高 rerank_threshold 而不是动向量阈值；长表格类文档召回不准时，再考虑调小 chunk_size。检索策略本身是混合的——BM25 稀疏召回、Dense 稠密召回、GraphRAG 图谱增强、父子分块都可以组合，这些在知识库设置页里按库开关。
.env 管"基础设施"。模型厂商、向量库连接、存储后端、JWT 与 AES 密钥、Langfuse 地址都在这里。API Key 与数据源凭据在库里用 AES-256-GCM 静态加密，这块是默认行为，不用额外配置。
💡 小贴士：每次大模型调用的完整请求/响应可以通过LLM_DEBUG_LOG=true落到独立文件里。排查"为什么这个答案是这样生成的"时，比翻日志快得多。
四、踩过的三个坑，和验证方法
坑一：上传文档卡在处理中，或者压根传不上去。官方 FAQ 里写得很直白：绝大多数情况是 Embedding 模型和对话模型没配对。先查 .env 里那四个模型变量是否完整，再看docker compose logs -f app有没有 ERROR。
坑二：升级后 Web 界面版本和 release 对不上。只跑docker compose up -d会复用本地缓存镜像。正确姿势是在 .env 里把WEKNORA_VERSION设成目标版本，再 pull + up，让容器真正换上新镜像。
坑三：图片不显示。开了多模态却忘了起 MinIO，或者 bucket 权限不对；从别的机器访问时，compose 里MINIO_PUBLIC_ENDPOINT默认指向 localhost，要换成实际 IP。另外 PaddleOCR 后端在部分平台起不来，官方建议改用外部 VLM 做 OCR（OCR_BACKEND=vlm）。
验证部署是否健康，我们形成了一套固定动作：上传一份已知答案的测试文档，用快速问答模式提问，确认引用抽屉里能点到原文；再开一个 Langfuse 会话（配好三把 key 重启即可），在 Traces 面板里看这次问答的完整瀑布图和 Token 消耗。能在这两个面板里把链路看到底，基本就可以放心放量了。
五、跑稳之后：值得解锁的扩展方向
核心链路稳定后，按性价比排个序，这几个能力我们陆续开了：
- IM 直达：企业微信、飞书、Slack、Telegram 等十个 IM 频道接入，员工在聊天窗口里直接提问，不用切到 Web 端；
- 数据源自动同步：飞书知识库、Notion、语雀、RSS 支持增量同步，文档更新后知识库跟着更新；
- Wiki 模式：对万级文档的库开起来后，Agent 会自动生成结构化 Wiki 页面和知识图谱，配合人工编辑与回滚，把"问答系统"变成"知识资产"；
- 程序化集成：官方 MCP Server（29 个工具，PyPI 上有现成包）、带能力级授权的 API Key、以及 weknora CLI，可以把知识库接进你们自己的工具链和 CI 流程。
如果你也准备落地，建议的路径是：先用默认配置 + Ollama 跑通"上传→问答→验证引用"最小闭环（一天内可完成），再按团队规模决定是否加 Neo4j、MinIO、Langfuse；多人协作阶段再开工作区 RBAC（Owner/Admin/Contributor/Viewer 四级角色）。
阅读入口：部署与常见故障看 docs/QA.md，环境变量全量说明在 .env.example，Ollama 集成实现在 internal/models/，官方文档站源码在 website-docs/。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 专业版体验，手机远程操控游戏修改)
