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/WeKnora
WeKnora 是一个开源 LLM 知识平台，docker 部署后把 PDF、Word、网页解析成本地 RAG 知识库，提供带引用的 RAG 问答、ReAct 智能体、自动维护的 Wiki 三种用法。这篇面向你——第一次做本地部署的人，走完能独立把服务跑起来、配好第一个知识库、验证检索可用，并知道卡住时往哪查。
文档进入后由 docreader 解析成块，向量化写入向量库；你提问时走关键词加向量的混合检索，大模型基于片段作答并附引用。默认向量库是 ParadeDB（PostgreSQL 加 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 追加
| 目的 | 命令 |
|---|---|
| 知识图谱（Neo4j） | docker compose --profile neo4j up -d |
| 对象存储（MinIO） | docker compose --profile minio up -d |
| 调用链追踪（Langfuse） | docker compose --profile langfuse up -d |
| 自建网络搜索（SearXNG） | docker 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_TYPE=local，写入容器卷/data/files；多副本或要对外分享图片时再切 MinIO/S3。单文件上限MAX_FILE_SIZE_MB默认 50MB，属于部署期配置，改完要重启容器才生效。
首次部署注册是开放的，注册后你会自动拥有一个工作空间并成为 Owner。团队部署建议在第一个账号注册完之后设DISABLE_REGISTRATION=true关掉公开注册，改用邀请链接加人。
上传第一份文档
进知识库传一份 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 Server（PyPI 包
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），仅供参考
