如何 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 服务健康检查通过（它探测/health），frontend 进入 running——frontend 会等 app 健康后才启动，所以 frontend running 基本代表核心链路通了。更省事的做法是./scripts/start_all.sh，它先做前置检查（含自动创建.env）再拉起，效果等价。

基础部署包含 frontend（Nginx）、app 主服务、docreader 解析服务、ParadeDB（PostgreSQL）、Redis。按需组件用--profile追加，可组合：

目的	命令
知识图谱 Neo4j	`docker compose --profile neo4j up -d`
对象存储 MinIO	`docker compose --profile minio up -d`
调用链追踪 Langfuse	`docker 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.example）：

LLM_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_overlap`	512 / 50	分块大小与重叠；块太小上下文断裂，太大召回变粗，按文档类型在 256–1024 间试
`conversation.embedding_top_k`	30	向量候选召回数量；召回不足时上调
`conversation.vector_threshold`	0.2	向量相似度下限；漏召回时调低
`conversation.rerank_threshold`/`rerank_top_k`	0.3 / 30	重排后的过滤线；误杀相关片段时调低
`conversation.max_rounds`	5	多轮上下文保留轮数

文件存储默认STORAGE_TYPE=local（写入容器卷/data/files），多副本或对外分享图片再切 MinIO/S3。单文件上限MAX_FILE_SIZE_MB默认 50MB，是部署期配置，改了须重启容器生效。

验收四步

按顺序做，每步都有可自检的成功标志。

1. 后端存活。

curl http://localhost:8080/health

返回{"status":"ok"}即通过。

2. 前端可达。浏览器打开http://localhost，能到达登录/注册页。首次部署注册开放，注册后自动拥有一个工作空间并成为其 Owner。团队部署建议在注册第一个账号后设DISABLE_REGISTRATION=true，改用邀请链接加人。

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 Server（PyPI 包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。有问题的片段直接在界面里编辑分块并保存——改动会自动重建索引，也留修订历史。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析