WeKnora RAG 知识库本地部署指南：两条命令跑通 Docker，配好模型验检索

WeKnora RAG 知识库本地部署指南两条命令跑通 Docker配好模型验检索【免费下载链接】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 知识平台把 PDF、Word、网页等原始文档解析成可检索的 RAG 知识库附带带引用的文档问答、ReAct 智能体和自维护 Wiki 三种用法。本文带你完成四件事用 Docker Compose 本地部署全部服务、把对话模型和向量模型配出来、用四个验证点确认知识库真的能检索、以及卡住时去哪里查。目标是一个人在 30 分钟内从零跑通。它适合谁三类入口与明确的边界先看结论WeKnora 解决的是「文档快照知识 混合检索」的问题不解决实时业务数据问题。适合团队文档、产品手册、论文资料这类相对静态的知识资产需要带出处的问答、复杂多步查询智能体可调用检索、MCP 工具和网络搜索、以及把文档蒸馏成可编辑互链页面的 Wiki 模式。不适合实时业务数据它索引的是文档快照更新要靠数据源同步对首字延迟极敏感的在线客服先测 RAG 模式延迟再决定是否上智能体已有成熟 RAG 栈且纯向量检索就够的团队。能力面支持 10 余种文档格式、20 多个 LLM 提供方向量库可在 PostgreSQL/pgvector、Milvus、Qdrant、OpenSearch 等之间替换可完全私有化部署。最短路径两条命令拉起的 Docker 部署前置条件只需要三样装好 Docker 与 Docker Compose 的机器建议至少 8GB 可用内存、20GB 磁盘、Git以及一个可用的模型服务本地 Ollama 或任意 OpenAI 兼容 API 二选一——对话模型和向量Embedding模型至少各要一个这是最容易卡住的一步。git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env.env.example 自带分组注释重点确认DB_USER/DB_PASSWORD/DB_NAME数据库、REDIS_ADDR/REDIS_PASSWORD队列、OLLAMA_BASE_URL默认已指向http://host.docker.internal:11434容器内访问宿主机 Ollama 的写法。然后docker compose pull docker compose up -d成功状态长这样docker compose ps里WeKnora-frontend处于 running。frontend 配置了depends_on: app (service_healthy)而 app 又等 postgres 和 docreader 健康后才就绪所以前端起来基本等于整条链路通了。等价替代一键脚本./scripts/start_all.sh会先做前置检查含自动创建.env再拉起适合只想敲一条命令的场景。升级时把.env里WEKNORA_VERSION改成目标 tag 后再docker compose pull up -d只跑up -d会复用本地旧镜像。关键参数怎么配模型、分块与阈值结论默认值就能跑真正影响结果的是四组参数——两个模型、分块、召回阈值。对话模型 向量模型按知识库配置不是一次性全局初始化。登录前端后新建知识库向导里为这个库选对话模型和向量模型内置「测试」按钮可验证连通性。⚠️ 两个坑后端在容器里Ollama 地址必须填http://host.docker.internal:11434填localhost连不上宿主机向量模型建库后不要换——换了维度或语义空间就变了整个索引要重建。knowledge_base.chunk_size: 512/chunk_overlap: 50config/config.yaml分块大小与重叠。块太小上下文断裂太大召回精度下降按文档类型在 256–1024 之间试。conversation.embedding_top_k: 30/vector_threshold: 0.2候选召回数量与向量相似度下限。召回不足时先调这两个。conversation.rerank_threshold: 0.3/rerank_top_k: 30重排过滤线enable_rerank: true时需配 rerank 模型可在「设置 → 模型」里补。conversation.max_rounds: 5多轮上下文保留轮数一般不动。验证四步证明知识库真的能用按顺序做每步都有明确成功标志后端存活→ 操作curl http://localhost:8080/health→ 成功标志返回{status:ok}→ 失败先查docker compose logs app。前端可用→ 操作浏览器打开http://localhost→ 成功标志到达注册/登录页注册后自动拥有一个工作空间且你是 Owner团队部署建议之后设DISABLE_REGISTRATIONtrue关公开注册改用邀请链接加人→ 失败先查端口 80 是否被占。文档解析成功→ 操作在知识库上传一份 PDF 或 Markdown → 成功标志状态走完pending → processing → finalizing → completed能看到分块数 → 失败先查模型是否配齐见下节第一条故障。检索带引用→ 操作对话页选该知识库问一个只有文档里才有的事实性问题 → 成功标志回答带引用角标点开能跳回原文片段 → 失败泛泛而谈或拒答先查vector_threshold是否过高。卡住了先查这几处四个高频故障app 容器反复重启→docker compose logs -f app docreader postgres→ 常见原因数据库没就绪或.env里DB_*、REDIS_*与容器实际不符docreader 不健康时 app 会一直等它。启动正常但上传文档失败→ 主服务日志搜ERROR→ 最常见原因是向量模型或对话模型没配齐解析流水线直接报错确认模型配置后重试。80 / 8080 端口被占→ 改.env里的FRONTEND_PORT/APP_PORT→ 重启后生效。回答质量差→ 按顺序试换更强或更贴合语境的向量模型代价是重建索引→ 调低vector_threshold→ 开启重排 → 检查分块参数是否把表格、列表切碎了。文档里图片不显示→ 本地存储下图片链接走容器内网地址 → 把对象存储 endpoint 改成公网可达或设APP_EXTERNAL_URL让图片经/r/token代理转发。解析慢→ 扫描件 PDF 和超大文件天然慢单次 DocReader 调用默认 30 分钟、整个文档任务默认 2 小时 → 批量导入时用WEKNORA_ASYNQ_*_CONCURRENCY系列变量调各阶段并发系统设置页也支持运行时调整。跑通之后的下一步三个进阶方向数据源自动同步接入飞书 Wiki/云文档、Notion、语雀、RSS 等数据源增量同步长期运营的知识库比反复手工上传省心得多。对外集成作用域 API Key能力级授权、可限定到单个知识库给第三方调用MCP ServerPyPI 包tencent-weknora-mcp支持 stdio/SSE/HTTP把检索问答挂给外部智能体weknoraCLI 在终端或 CI 里管知识库weknora kb list、doc upload、chat。可观测与协作docker compose --profile langfuse up -d启用后智能体的推理步骤、工具调用、token 消耗能追到单次会话级别工作空间内置 Owner/Admin/Contributor/Viewer 四级角色和审计日志多团队协作先邀请、再分角色。跑通上面四步验证后第一件该做的事接入一份真实业务文档完整问一遍逐条核对回答里的引用是否指向正确的原文片段。然后把.env里的模型、存储参数按你的环境固化用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考