WeKnora RAG 知识库本地部署 30 分钟跑通，配置、检索验证与排障全在这一篇

WeKnora RAG 知识库本地部署 30 分钟跑通配置、检索验证与排障全在这一篇【免费下载链接】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 知识平台docker 部署后把 PDF、Word、网页解析成本地 RAG 知识库提供带引用的 RAG 问答、ReAct 智能体、自动维护的 Wiki 三种用法。这篇面向你——第一次做本地部署的人走完能独立把服务跑起来、配好第一个知识库、验证检索可用并知道卡住时往哪查。文档进入后由 docreader 解析成块向量化写入向量库你提问时走关键词加向量的混合检索大模型基于片段作答并附引用。默认向量库是 ParadeDBPostgreSQL 加 pgvector改RETRIEVE_DRIVER可换成 Milvus、Qdrant、OpenSearch 等组件都能替换支持完全私有化。值不值得用先判断适合团队文档问答、私有知识库、回答必须带出处这类场景。文档格式支持 10 余种LLM 提供方 20 多个组件可替换。下面三类情况建议先别上需要实时业务数据。它索引的是文档快照数据更新要靠数据源同步。对首字延迟极敏感的在线客服。先用 RAG 模式实测延迟再决定要不要上智能体。纯向量检索就能满足、且已有成熟 RAG 栈。迁移收益不高。阶段一 用 docker compose 把服务 30 分钟拉起来准备清单软件Docker、Docker Compose、Git。Go、Python、数据库都不用本地装核心组件全在容器里。资源至少 8GB 可用内存磁盘预留 20GB 以上向量库用 pgvector 时内存压力更小。模型服务这是最容易卡住的一步至少准备一个对话模型 一个向量Embedding模型来源二选一——本地 Ollama先ollama serve并拉好模型或任意 OpenAI 兼容远程 API备好 base_url 和 api_key。网络首次部署要能拉 Docker Hub 镜像后续解析文档、导入网页还需要出站网络。docker compose 启动命令git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env.env.example自带分组注释拉起前重点核对三处DB_*数据库账号密码、REDIS_ADDR、WEKNORA_VERSION镜像版本标签默认 latest。然后docker compose pull docker compose up -d容器出现什么状态才算起来了app 服务内置/health健康检查frontend 会等 app 健康之后才启动所以看到WeKnora-frontend进入 running核心链路基本就通了。习惯单条命令的话./scripts/start_all.sh会先做前置检查、缺.env时自动从模板创建再拉起服务效果等价。可选组件按 profile 追加目的命令知识图谱Neo4jdocker compose --profile neo4j up -d对象存储MinIOdocker compose --profile minio up -d调用链追踪Langfusedocker compose --profile langfuse up -d自建网络搜索SearXNGdocker compose --profile searxng up -d全部功能docker compose --profile full up -d停止用docker compose down。升级时先把WEKNORA_VERSION改成目标 release tag注意 v 前缀再执行docker compose pull docker compose up -d只跑up -d会复用本地旧镜像界面版本可能没跟上。阶段二 配好模型喂进第一份文档模型按知识库配置不是一次性全局初始化登录前端后新建知识库向导会让你为这个库选对话模型和向量模型内置测试按钮直接验证连通性。两个高频坑后端跑在容器里Ollama 地址要填http://host.docker.internal:11434填localhost:11434连不上宿主机。向量模型建库后不要换。换了等于向量维度或语义空间变了整个索引要重建。.env里的核心模型变量配合config/builtin_models.yaml启用声明式配置LLM_MODEL_NAME... # 对话模型 LLM_BASE_URL... # 远程 API 必填 LLM_API_KEY... EMBEDDING_MODEL_NAME... # 向量模型Ollama 时填模型名 EMBEDDING_API_KEY...本地 Ollama 方案里向量模型名就是 Ollama 模型名地址沿用OLLAMA_BASE_URL。启用重排再补 RERANK_MODEL_NAME / RERANK_BASE_URL / RERANK_API_KEY重排、图片理解 VLM、语音转写 ASR 都可以先不开之后在界面随时加。最值得调的就这 4 组参数存储与检索参数集中在config/config.yaml默认值就能跑knowledge_base.chunk_size: 512/chunk_overlap: 50分块大小与重叠。块太小上下文断裂太大召回精度下降按文档类型在 256–1024 之间试。conversation.embedding_top_k: 30向量候选召回数量相关内容总召回不上来就调大。conversation.vector_threshold: 0.2向量相似度下限回答泛泛而谈或拒答时往下调。conversation.rerank_threshold: 0.3/rerank_top_k: 30重排后的过滤线与保留条数开了重排反而更差就下调。另外conversation.max_rounds: 5控制多轮上下文保留轮数默认够用。文件存储默认STORAGE_TYPElocal写入容器卷/data/files多副本或要对外分享图片时再切 MinIO/S3。单文件上限MAX_FILE_SIZE_MB默认 50MB属于部署期配置改完要重启容器才生效。首次部署注册是开放的注册后你会自动拥有一个工作空间并成为 Owner。团队部署建议在第一个账号注册完之后设DISABLE_REGISTRATIONtrue关掉公开注册改用邀请链接加人。上传第一份文档进知识库传一份 PDF 或 Markdown。状态流转是 pending → processing → finalizing → completed列表页实时刷新进度解析完能看到分块数。阶段三 验证检索真的可用四步验证每步都有明确成功标志哪步失败就回到对应参数后端存活curl http://localhost:8080/health应返回{status:ok}。失败先docker compose ps看容器状态。前端可用浏览器打开http://localhost能到达注册/登录页。打不开多为 80、8080 端口被占改.env里的FRONTEND_PORT/APP_PORT。文档解析成功状态走到 completed 且分块数非零。长期卡在 processing主服务日志搜 ERROR最常见是向量模型没配齐。检索回答正确对话页选这个知识库问一个只有文档里才有的事实性问题。成功标志是回答带引用角标点开能跳回原文对应片段。泛泛而谈或拒答回上一节调低vector_threshold或重排阈值。排障速查表 常见症状与第一手命令症状先执行什么最常见原因服务起不来、界面打不开docker compose logs -f app docreader postgres数据库没就绪或.env里DB_*、REDIS_*与容器内实际不符docreader 不健康时 app 会一直等它能启动但上传文档失败主服务日志搜ERROR模型没配齐向量或对话模型缺失时解析流水线直接报错文档里图片不显示设置APP_EXTERNAL_URL本地存储的图片链接走容器内网地址外部设备打不开设置后图片经/r/token代理转发解析慢调WEKNORA_ASYNQ_*_CONCURRENCY系列 worker 池并发扫描件 PDF 和超大文件天然慢单次 DocReader 调用默认 30 分钟超时整个文档任务默认 2 小时回答质量差先调低vector_threshold再开启重排召回阈值过高或向量模型不贴语境换模型等于重建索引分块参数也可能把表格、列表切碎了再进一步 数据源同步与对外集成持续更新接入飞书 Wiki/云文档、Notion、语雀、RSS 等数据源自动增量同步比反复手工上传更适合长期运营。对外集成作用域 API Key能力级授权、可限定到单个知识库给第三方系统调用MCP ServerPyPI 包tencent-weknora-mcp支持 stdio/SSE/HTTP把检索、问答挂给外部智能体weknoraCLI 在终端或 CI 里管知识库。IM 渠道企微、飞书、Slack、Telegram 等十来个渠道直接问答适合客服和内部助手场景。可观测启用--profile langfuse后智能体的推理步骤、工具调用、token 消耗都能追到单次会话级别。权限与注册工作空间内置 Owner/Admin/Contributor/Viewer 四级角色和审计日志生产环境关闭公开注册并用WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL指定首个系统管理员。收尾下一步接一份真实业务文档观察一次完整问答的引用是否正确。然后把.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），仅供参考