如何 30 分钟跑通：WeKnora RAG 知识库本地部署完整指南

如何 30 分钟跑通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 给你的 RAG 知识库。两条 docker compose 命令完成本地部署改三处配置四步验收检索是否真正可用一目了然。它值不值得用先给结论知识以文档为主、答案需要出处选它要查实时业务数据别选。场景判断文档问答答案需可追溯到原文✅ 适合知识散在飞书、Notion、语雀需定期同步✅ 适合查询实时业务数据数据库、订单系统❌ 索引的是文档快照需数据源同步首字延迟极敏感的在线客服❌ 先用 RAG 模式实测延迟再定纯向量检索已满足且自有 RAG 栈成熟❌ 无引入必要三种入口分工明确RAG 问答检索片段后直接作答速度快日常查资料用它ReAct 智能体自主规划多步、可调用检索、MCP 工具与网络搜索复杂查询用它Wiki 模式把原始文档蒸馏成相互链接的 Markdown 页面支持编辑与回滚沉淀知识用它。处理链路一行带过文档进入 → docreader 解析分块 → 向量化写库 → 混合检索关键词 向量 可选图谱→ 大模型作答附引用。开跑前的准备清单按顺序打勾缺一项后面都会卡住Docker 与 Docker Compose 已安装可用Git 已安装机器可用内存 ≥ 8GB磁盘 ≥ 20GB模型服务就绪最容易卡住的一步对话模型 向量模型缺一不可。本地 Ollama先ollama serve并拉好模型或任意 OpenAI 兼容远程 API备齐base_url与api_key二选一首次部署可访问 Docker Hub后续网页导入需出站网络无需本地安装 Go、Python 或数据库核心组件全部容器化运行。两条命令跑起来克隆仓库并准备环境变量文件git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env.env.example自带分组注释部署基础、数据与存储、模型、文档解析等。重点确认三处数据库账号密码DB_*、Redis 地址REDIS_ADDR、WEKNORA_VERSION镜像版本默认latest。然后启动docker compose pull docker compose up -d成功的标志docker compose ps里 app 服务健康检查通过它探测/healthfrontend 进入 running——frontend 会等 app 健康后才启动所以 frontend running 基本代表核心链路通了。更省事的做法是./scripts/start_all.sh它先做前置检查含自动创建.env再拉起效果等价。基础部署包含 frontendNginx、app 主服务、docreader 解析服务、ParadeDBPostgreSQL、Redis。按需组件用--profile追加可组合目的命令知识图谱 Neo4jdocker compose --profile neo4j up -d对象存储 MinIOdocker compose --profile minio up -d调用链追踪 Langfusedocker compose --profile langfuse up -d全部功能docker compose --profile full up -d停止docker compose down。升级时先把.env里WEKNORA_VERSION改成目标 release tag再docker compose pull docker compose up -d。⚠️ 只跑up -d会复用本地旧镜像界面版本可能不更新。首次登录要改的三处1. 模型按知识库配置不是一次性全局初始化。登录前端新建知识库时向导让你为这个库选对话模型与向量模型内置「测试」按钮可直接验证连通性。两个高频点后端跑在容器里Ollama 地址要填http://host.docker.internal:11434填localhost:11434连不上宿主机对应变量OLLAMA_BASE_URL见 .env.example。向量模型建库后不要换——维度或语义空间变了等于要重建整个索引。2..env模型变量。走远程 API 时对话侧备LLM_MODEL_NAME/LLM_BASE_URL/LLM_API_KEY向量侧备EMBEDDING_MODEL_NAME/EMBEDDING_BASE_URL/EMBEDDING_API_KEY完整注释见 .env.exampleLLM_MODEL_NAME... LLM_BASE_URL... LLM_API_KEY... EMBEDDING_MODEL_NAME... EMBEDDING_API_KEY...启用重排再补RERANK_MODEL_NAME/RERANK_BASE_URL/RERANK_API_KEY。VLM图片理解、ASR语音转写可先不开界面随时添加。3. 检索参数config/config.yaml。默认值能直接跑调优只看这几组参数默认值作用与方向knowledge_base.chunk_size/chunk_overlap512 / 50分块大小与重叠块太小上下文断裂太大召回变粗按文档类型在 256–1024 间试conversation.embedding_top_k30向量候选召回数量召回不足时上调conversation.vector_threshold0.2向量相似度下限漏召回时调低conversation.rerank_threshold/rerank_top_k0.3 / 30重排后的过滤线误杀相关片段时调低conversation.max_rounds5多轮上下文保留轮数文件存储默认STORAGE_TYPElocal写入容器卷/data/files多副本或对外分享图片再切 MinIO/S3。单文件上限MAX_FILE_SIZE_MB默认 50MB是部署期配置改了须重启容器生效。验收四步按顺序做每步都有可自检的成功标志。1. 后端存活。curl http://localhost:8080/health返回{status:ok}即通过。2. 前端可达。浏览器打开http://localhost能到达登录/注册页。首次部署注册开放注册后自动拥有一个工作空间并成为其 Owner。团队部署建议在注册第一个账号后设DISABLE_REGISTRATIONtrue改用邀请链接加人。3. 文档解析完成。进入知识库上传一份 PDF 或 Markdown状态依次经历pending → processing → finalizing → completed列表页实时刷新。完成时能看到分块数——没有分块数后面的检索无从谈起。4. 回答带引用角标。在对话页选这个知识库提一个只有文档里才有的事实性问题。成功标志回答带引用角标点开能跳回原文对应片段。若回答泛泛而谈或拒答通常是向量模型没配好或阈值过高回到上节调vector_threshold与rerank_threshold。排障速查服务起不来、app 反复重启→ 数据库未就绪或.env里DB_*、REDIS_*与容器实际不符 →docker compose ps看状态docker compose logs -f app docreader postgres找原因docreader 不健康时 app 会一直等它。端口 80/8080 被占则改FRONTEND_PORT/APP_PORT。能启动但上传文档失败→ 对话模型或向量模型没配齐解析流水线直接报错 → 核对.env模型变量是否完整再在主服务日志搜ERROR。文档里图片不显示→ 本地存储下图片链接走容器内网地址外部设备打不开 → 对象存储 endpoint 改公网可达或设APP_EXTERNAL_URL让图片经/r/token代理转发。解析慢→ 扫描件 PDF 与超大文件天然慢 → 单次 DocReader 调用默认超时 30 分钟、单文档任务默认 2 小时WEKNORA_DOCREADER_CALL_TIMEOUT/WEKNORA_DOCUMENT_PROCESS_TIMEOUT批量导入用WEKNORA_ASYNQ_*_CONCURRENCY系列调整各阶段 worker 池。回答质量差或拒答→ 向量模型不贴语境、召回阈值过高、或分块把表格列表切碎 → 顺序处理换更贴语境的向量模型代价是重建索引→ 调低vector_threshold→ 开重排 → 检查分块参数。项目自带端到端评测召回命中率、BLEU/ROUGE有标注数据可量化对比。部署之后持续更新接入飞书 Wiki/云文档、Notion、语雀、RSS 等数据源自动增量同步适合长期运营的知识库见 website-docs/03-features/10-datasource.md。对外集成作用域 API Key 可限定到单个知识库授权第三方MCP ServerPyPI 包tencent-weknora-mcp支持 stdio/SSE/HTTP把检索、问答挂给外部智能体weknoraCLI 在终端或 CI 里管知识库weknora kb list、doc upload、chat见 cli/README.md 与 mcp-server/。IM 渠道企微、飞书、Slack、Telegram 等可直接问答适合客服与内部助手。可观测启用--profile langfuse后智能体推理步骤、工具调用、token 消耗可追到单次会话级别排查为什么这次答错了快很多见 website-docs/03-features/16-observability.md。团队权限工作空间内置 Owner/Admin/Contributor/Viewer 四级角色与审计日志生产环境建议关闭公开注册并配WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL指定首个系统管理员。下一步建议跑通四步验收后接入一份真实业务文档观察一次完整问答的引用是否准确再把.env的模型、存储参数按实际环境固化用docker compose logs -f app盯一两天日志确认没有解析积压或模型超时。遇到解析或配置疑问查 website-docs/01-getting-started/05-troubleshooting.md 与 website-docs/01-getting-started/04-configuration.md。有问题的片段直接在界面里编辑分块并保存——改动会自动重建索引也留修订历史。【免费下载链接】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），仅供参考