从零到第一个带引用回答：WeKnora RAG 知识库本地部署完整指南

从零到第一个带引用回答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/WeKnoraWeKnora 是一个开源 LLM 知识平台把 PDF、Word、网页这类原始文档变成可查询的 RAG 知识库提供带出处的问答、ReAct 智能体和自维护 Wiki 三种用法。这篇文章写给第一次部署的个人和小团队按从一台裸机到跑通第一个带引用的回答推进配置项在真正用到的地方才讲。它索引的是文档快照不是实时业务数据需要实时数据就得靠数据源同步更新。对首字延迟极敏感的在线客服场景也别急着上智能体模式先用 RAG 模式把延迟测出来再说。拉起全部容器两条命令跑通 RAG 知识库机器上装好 Docker 和 Docker Compose 就行不用另装 Go、Python 或数据库。默认部署包含前端Nginx、app 主服务、docreader 解析服务、ParadeDBPostgreSQL和 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按需追加可以组合知识图谱 Neo4jdocker 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_REGISTRATIONtrue改用邀请链接加人。然后进入知识库上传一份 PDF 或 Markdown。文档状态会走pending → processing → finalizing → completed四个状态列表页实时刷新进度解析完成后能看到分块数。影响这步的配置在 配置样例 里knowledge_base.chunk_size: 512和chunk_overlap: 50分块大小与重叠。块太小上下文断裂太大召回精度下降按文档类型在 256–1024 之间试。单文件上传上限默认 50MBMAX_FILE_SIZE_MB。这是部署期配置改了要重启容器才生效。文件存储默认STORAGE_TYPElocal写进容器卷多副本部署或要对外分享图片时再切 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 postgresapp 反复重启多半是数据库没就绪或.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考