3步在自有服务器部署私有知识库：WeKnora 本地化 RAG 落地实战

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/WeKnoraWeKnora 是一个开源的 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_threshold0.3关键词BM25召回的分数门槛调高则召回更严conversation.vector_threshold0.2向量召回门槛控制语义匹配的相关度下限conversation.rerank_threshold / rerank_top_k0.3 / 30重排序阶段的过滤线与候选条数knowledge_base.chunk_size / chunk_overlap512 / 50文档分块大小与重叠直接影响检索粒度conversation.max_rounds5多轮上下文保留轮数我们的调整经验初期答案太发散时优先提高 rerank_threshold 而不是动向量阈值长表格类文档召回不准时再考虑调小 chunk_size。检索策略本身是混合的——BM25 稀疏召回、Dense 稠密召回、GraphRAG 图谱增强、父子分块都可以组合这些在知识库设置页里按库开关。.env 管基础设施。模型厂商、向量库连接、存储后端、JWT 与 AES 密钥、Langfuse 地址都在这里。API Key 与数据源凭据在库里用 AES-256-GCM 静态加密这块是默认行为不用额外配置。 小贴士每次大模型调用的完整请求/响应可以通过LLM_DEBUG_LOGtrue落到独立文件里。排查为什么这个答案是这样生成的时比翻日志快得多。四、踩过的三个坑和验证方法坑一上传文档卡在处理中或者压根传不上去。官方 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 做 OCROCR_BACKENDvlm。验证部署是否健康我们形成了一套固定动作上传一份已知答案的测试文档用快速问答模式提问确认引用抽屉里能点到原文再开一个 Langfuse 会话配好三把 key 重启即可在 Traces 面板里看这次问答的完整瀑布图和 Token 消耗。能在这两个面板里把链路看到底基本就可以放心放量了。五、跑稳之后值得解锁的扩展方向核心链路稳定后按性价比排个序这几个能力我们陆续开了IM 直达企业微信、飞书、Slack、Telegram 等十个 IM 频道接入员工在聊天窗口里直接提问不用切到 Web 端数据源自动同步飞书知识库、Notion、语雀、RSS 支持增量同步文档更新后知识库跟着更新Wiki 模式对万级文档的库开起来后Agent 会自动生成结构化 Wiki 页面和知识图谱配合人工编辑与回滚把问答系统变成知识资产程序化集成官方 MCP Server29 个工具PyPI 上有现成包、带能力级授权的 API Key、以及 weknora CLI可以把知识库接进你们自己的工具链和 CI 流程。如果你也准备落地建议的路径是先用默认配置 Ollama 跑通上传→问答→验证引用最小闭环一天内可完成再按团队规模决定是否加 Neo4j、MinIO、Langfuse多人协作阶段再开工作区 RBACOwner/Admin/Contributor/Viewer 四级角色。阅读入口部署与常见故障看 docs/QA.md环境变量全量说明在 .env.exampleOllama 集成实现在 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），仅供参考