企业官网建设流程全解析

从零到第一个带引用回答：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 是一个开源 LLM 知识平台，把 PDF、Word、网页这类原始文档变成可查询的 RAG 知识库，提供带出处的问答、ReAct 智能体和自维护 Wiki 三种用法。这篇文章写给第一次部署的个人和小团队，按"从一台裸机到跑通第一个带引用的回答"推进，配置项在真正用到的地方才讲。

它索引的是文档快照，不是实时业务数据，需要实时数据就得靠数据源同步更新。对首字延迟极敏感的在线客服场景也别急着上智能体模式，先用 RAG 模式把延迟测出来再说。

拉起全部容器：两条命令跑通 RAG 知识库

机器上装好 Docker 和 Docker Compose 就行，不用另装 Go、Python 或数据库。默认部署包含前端（Nginx）、app 主服务、docreader 解析服务、ParadeDB（PostgreSQL）和 Redis。建议至少 8GB 可用内存、20GB 以上磁盘。

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

成功标志是WeKnora-frontend进入 running——前端会等 app 的/health检查通过才启动，看到它跑起来基本就是整条链路通了。项目还有个一键脚本./scripts/start_all.sh，会先做前置检查再拉起，效果等价。

可选组件用--profile按需追加，可以组合：

• 知识图谱 Neo4j：docker compose --profile neo4j up -d
• 对象存储 MinIO、调用链追踪 Langfuse：同样方式
• 全部功能：docker compose --profile full up -d

配置模型：最可能卡住的一步

模型是按知识库配的，不是一次性全局初始化。前端新建知识库时，向导会让你为这个库选对话模型和向量（Embedding）模型，自带"测试"按钮验证连通性。

两个高频坑：

• 后端跑在容器里，Ollama 在宿主机时地址必须填http://host.docker.internal:11434，填 localhost 连不上。.env里OLLAMA_BASE_URL的默认值已经是这个地址。
• 向量模型建库后别换。换了等于向量维度或语义空间变了，整个索引要重建。

如果想提前在.env里声明好一套模型，变量名是LLM_MODEL_NAME/LLM_BASE_URL/LLM_API_KEY（对话模型）和EMBEDDING_MODEL_NAME/EMBEDDING_BASE_URL/EMBEDDING_API_KEY（向量模型）。重排、图片理解、语音转写都可以先不开，之后在界面随时加。

导入文档：盯状态走到 completed

首次部署注册是开放的，注册后你会自动拥有一个工作空间并成为其 Owner。团队部署建议注册第一个账号后设DISABLE_REGISTRATION=true，改用邀请链接加人。

然后进入知识库上传一份 PDF 或 Markdown。文档状态会走pending → processing → finalizing → completed四个状态，列表页实时刷新进度，解析完成后能看到分块数。

影响这步的配置在 配置样例 里：

• knowledge_base.chunk_size: 512和chunk_overlap: 50：分块大小与重叠。块太小上下文断裂，太大召回精度下降，按文档类型在 256–1024 之间试。
• 单文件上传上限默认 50MB（MAX_FILE_SIZE_MB）。这是部署期配置，改了要重启容器才生效。
• 文件存储默认STORAGE_TYPE=local，写进容器卷；多副本部署或要对外分享图片时，再切 MinIO/S3 这类对象存储。

验证检索：回答带引用才算数

在对话页选这个知识库，提一个只有文档里才有答案的事实性问题。成功长这样：回答带引用角标，点开能跳回原文对应片段。

回答泛泛而谈或拒答，通常是向量模型没配好，或者召回阈值过高。配置样例 里三组参数管这件事：

• conversation.embedding_top_k: 30与vector_threshold: 0.2：候选召回数量和向量相似度下限；
• conversation.rerank_threshold: 0.3与rerank_top_k: 30：重排后的过滤线；
• conversation.max_rounds: 5：多轮上下文保留轮数。

排查三类高频故障

服务起不来或界面打不开。先看这两条：

docker compose ps docker compose logs -f app docreader postgres

app 反复重启，多半是数据库没就绪，或.env里DB_*、REDIS_*与容器内实际不符；docreader 不健康，app 会一直等它。端口 80、8080 被占，改FRONTEND_PORT/APP_PORT即可。

上传文档失败。最常见原因是模型没配齐——向量模型或对话模型缺失时，解析流水线直接报错。确认.env里模型变量完整，再去主服务日志搜ERROR。

文档里图片不显示。本地存储部署下，图片链接走容器内网地址，外部设备打不开。两个方向：对象存储 endpoint 改成公网可达，或设APP_EXTERNAL_URL让图片经 WeKnora 的/r/<token>代理转发。

解析慢。扫描件 PDF 天然慢，单次 DocReader 调用默认超时 30 分钟，整个文档任务默认 2 小时。批量导入时用WEKNORA_ASYNQ_*_CONCURRENCY系列变量调各阶段 worker 并发，系统设置页也支持运行时改。

下一步：接入一份真实业务文档

四步验证都过了之后，接入一份真实业务文档，观察一次完整问答的引用是否正确。然后把.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