WeKnora 本地部署实战：如何用 Docker 从零搭出一个可验证的 RAG 知识库

WeKnora 本地部署实战如何用 Docker 从零搭出一个可验证的 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 是一个开源的 RAG检索增强生成即先从知识库检索片段再让大模型作答知识库平台把 PDF、Word、网页等原始文档解析成可检索的分块写入向量库回答时附原文出处并提供 ReAct 智能体和自动维护的 Wiki 两种进阶用法。本文面向第一次用 Docker 本地部署的个人用户和小团队读完你可以亲手拉起全部服务、建库传文档并完成一次有明确成功信号的检索验收而不是“界面打开了就算部署成功”。适合谁用谁可以先停在这里先花 30 秒对号入座比装完再推翻便宜适合手头有一批静态文档手册、制度、笔记、产品资料需要带引用的问答想完全私有化数据不出内网文档需要定期从飞书、Notion、RSS 等来源同步更新。不适合依赖实时业务数据的查询它索引的是文档快照不是数据库对首字延迟极敏感的在线客服建议先只开 RAG 模式实测延迟再决定是否上智能体已经有一套成熟向量检索栈、只需要补个前端的团队。能力边界支持 10 余种文档格式、20 多个 LLM 提供方向量库可选 PostgreSQL默认pgvector、Milvus、Qdrant、OpenSearch 等均可替换部署完全离线也能跑。 判断标准很简单你的问题是“查资料”不是“查现状”。从环境预检到启动最短命令链先预检三件事装完再返工最贵软件Docker、Docker Compose、Git 三件套。Go、Python、数据库都不用本地装核心组件全在容器里。资源默认栈包含 frontendNginx、app 主服务、docreader 解析服务、ParadeDB带 pgvector 的 PostgreSQL、Redis建议机器至少 8GB 可用内存磁盘 20GB 以上。模型服务最容易卡住的一步你至少需要一个对话模型和一个向量Embedding把文本变成可计算相似度的数字向量模型来源二选一本地 Ollama先跑ollama serve并拉好模型任意 OpenAI 兼容的远程 API备齐base_url和api_key。注意首次部署要能从 Docker Hub 拉镜像后续网页导入需要出站网络。然后是最短命令链。克隆仓库并准备环境变量文件git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env.env.example 自带 A–J 分组注释。打开.env只需确认四处DB_USER/DB_PASSWORD/DB_NAME、REDIS_PASSWORD、模型相关变量下一节、WEKNORA_VERSION镜像标签默认latest固定版本请写 release tag如v0.7.0。docker compose pull docker compose up -dcompose 里 app 服务配了/health健康检查frontend 会等 app 健康后才启动——所以看到WeKnora-frontend进入 running基本代表核心链路通了。喜欢单条命令的话./scripts/start_all.sh会先做环境预检包括自动创建缺失的.env再拉起效果等价见 scripts/start_all.sh。按需加组件用--profile可叠加知识图谱加neo4jNEO4J_ENABLE 同时设为true对象存储加minio调用链追踪加langfuse--profile full一次全开。例如docker compose --profile langfuse up -d停止用docker compose down。升级时先改.env的WEKNORA_VERSION再pull up -d只跑up -d会复用本地旧镜像界面版本跟不上。值得动的参数默认值、原因与改动代价存储与检索参数集中在 config/config.yaml挂载进 app 容器默认值能直接跑。这里不穷举只挑真正改变行为的几处每个都回答三问默认多少、为什么重要、改动要付出什么。knowledge_base.chunk_size: 512/chunk_overlap: 50——分块大小与相邻块重叠。块太小一段完整逻辑被切开回答缺上下文块太大单块命中时噪声变多召回精度下降。一般按文档类型在 256–1024 之间试。代价改后要重新解析文档重建索引不是即时生效。conversation.embedding_top_k: 30与vector_threshold: 0.2——向量检索召回的候选条数与相似度下限。阈值设太高正确答案的分块被直接滤掉表现是“文档里有但就是答不出”。conversation.rerank_threshold: 0.3/rerank_top_k: 30且enable_rerank: true——重排用更强的排序模型对候选二次打分默认开启配好 rerank 模型后按 0.3 这条线过滤。召回很噪时把阈值降到 0.2 再观察比一味调top_k有效。conversation.max_rounds: 5——多轮对话保留最近 5 轮上下文调大会增加每次请求的 token 消耗。OLLAMA_BASE_URLhttp://host.docker.internal:11434——app 跑在容器里容器内的localhost是容器自己不是你的机器指向宿主机必须用host.docker.internal。填错不会报“未配置”只会连不上表现为模型测试按钮失败。MAX_FILE_SIZE_MB默认 50——单文件上传上限。它是部署期配置Go、Nginx、docreader、浏览器四层在启动时各读一次改完必须重启相关容器热改不生效。关于向量模型只记一条建库之后换向量模型向量维度和语义空间都变了整个索引需要重建。所以选模型时就用你打算长期用的那个先用知识库向导里的「测试」按钮验证连通性再建库。重排、图片理解VLM、语音转写ASR都可以先不开之后在设置页随时补。文件存储默认STORAGE_TYPElocal写入容器卷/data/files多副本或要对外分享图片时再切 MinIO/S3。验收自检四步确认知识库真的可用每一步都有一个可见的成功信号不成立就跳到「按症状排查」对应条目。后端存活。执行curl http://localhost:8080/health返回{status:ok}。看到 ok说明 app 和它依赖的数据库、Redis 都通了不成立去排查第 1 条。前端与账号。浏览器打开http://localhostfrontend 默认端口 80改过FRONTEND_PORT则换端口能到达注册页。首次部署注册默认开放注册后你自动拥有一个个人工作空间并是 Owner团队部署建议注册完第一个账号后设DISABLE_REGISTRATIONtrue关闭公开注册改用邀请链接加人生产可用WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL指定首个系统管理员。文档解析成功。新建知识库时向导会让你为这个库选对话模型和向量模型——模型是按知识库配的不是一次性全局初始化。上传一份 PDF 或 Markdown 后文档状态会经历pending → processing → finalizing → completed列表页实时刷新进度解析完能看到分块数。看到分块数说明解析链路与向量库写入全通了卡住或报错去排查第 2 条。检索与回答正确。在对话页选这个知识库问一个只有文档里才有的事实性问题。成功标志回答带引用角标点开能跳回原文对应片段。回答泛泛而谈或拒答多半是向量模型没配好或召回阈值过高去排查第 5 条。跑不起来时按症状排查症状 1app 容器反复重启或前端一直转圈。最常见原因数据库没就绪或.env里DB_*、REDIS_*与容器实际不符。docker compose ps docker compose logs -f app docreader postgres看 app 日志里的报错就能定位docreader 不健康时 app 会一直等它。端口被占80、8080就改FRONTEND_PORT/APP_PORT。症状 2服务都正常一传文档解析就报错。最常见原因模型没配齐——向量模型或对话模型缺失时解析流水线直接失败。回知识库向导确认两个模型都在且测试通过再回 app 日志搜ERROR。症状 3文档里图片在外部设备打不开。本地存储部署下图片链接是容器内网地址外网必然 404。两条路设APP_EXTERNAL_URL让图片走 WeKnora 的/r/token代理转发或把对象存储 endpoint 改成公网可达。症状 4解析特别慢。扫描件 PDF 和超大文件天然慢不是故障单次 DocReader 调用默认超时 30 分钟WEKNORA_DOCREADER_CALL_TIMEOUT整个文档任务默认 2 小时WEKNORA_DOCUMENT_PROCESS_TIMEOUT。批量导入时用WEKNORA_ASYNQ_*_CONCURRENCY系列变量提高各阶段 worker 并发系统设置页也支持运行时调整无需重启。症状 5能答但质量差。按代价从小到大依次试调低vector_threshold即时生效→ 配置 rerank 模型并调rerank_threshold即时→ 检查chunk_size是否把表格、列表切碎了需重解析→ 最后才考虑换更强的向量模型代价是重建索引。项目提供端到端评测召回命中率、BLEU/ROUGE有标注数据时可以量化对比调参前后。跑通之后下一步做什么扩展能力一句话带过接入飞书、Notion、语雀、RSS 等数据源做增量同步用作用域 API Key可限定到单个知识库开放给第三方用 MCP ServerPyPI 包tencent-weknora-mcp支持 stdio/SSE/HTTP把检索问答挂给外部智能体用weknoraCLI 在终端或 CI 里管知识库企微、飞书、Slack、Telegram 等 IM 渠道可直接问答--profile langfuse打开后每次回答的推理步骤、工具调用、token 消耗都能追到单次会话级别工作空间自带 Owner/Admin/Contributor/Viewer 四级角色和审计日志。 收尾给三个带验证方式的下一步导入一份真实业务文档问一个事实性问题点引用角标确认跳到的是正确的那段原文——引用跳错片段说明分块或召回有问题。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），仅供参考