WeKnora 知识库 RAG 部署教程：10 分钟从零到生产的完整指南

WeKnora 知识库 RAG 部署教程10 分钟从零到生产的完整指南【免费下载链接】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 知识管理平台能把原始文档变成可查询的 RAG 系统、自主推理 Agent 和自动维护的 Wiki。跟完本文你会完成一次完整的 Docker 部署、看懂系统架构并拿到生产环境所需的配置、调优和排障要点。 部署前提与环境自查开工前需要准备什么这一节帮你确认机器够不够用、工具链装没装齐避免部署到一半才发现问题。硬件要求满足其一即可开始内存最低 4GB跑生产建议 8GB 以上存储至少 20GB 可用空间CPU4 核以上支持 AVX2 指令集软件依赖Docker 20.10 及以上版本Docker Compose 2.0 及以上版本系统Ubuntu 20.04 / CentOS 8 / macOS 12两条命令先确认工具链版本不达标就先升级再继续。docker --version docker compose version 第一次部署怎么跑通克隆、启动与健康检查这一节的目标只有一个让你尽快看到服务跑起来拿到第一个正反馈。整条部署路径只有三步克隆代码、生成环境变量文件、一键启动。# 拉取项目代码并进入目录 git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora下面这条命令用仓库自带的模板生成.env之后需要编辑它填入数据库、LLM 等关键参数文件内有注释说明。cp .env.example .env nano .env启动脚本会自动完成环境检查、镜像拉取和容器编排启动后终端会打印各服务状态./scripts/start_all.sh --all启动完成后做两道验证都通过才算真正部署成功。第一道是健康检查直接请求后端探活接口curl http://localhost:8080/health第二道是打开浏览器访问http://localhost能看到前端界面即正常。默认分工是前端容器对外跑 80 端口API 服务跑 8080 端口前端通过 Nginx 反向代理把/api流量转给后端所以浏览器只需要记住 80 这一个入口。️ 启动之后看懂系统架构图与文档处理全流程服务跑起来后这一节帮你把黑盒打开弄清楚你的文档从上传到被回答中间经过哪些组件。整个架构按数据流向可以拆成四个层次从左到右依次是接入层Web UI 与 REST API、6 种以上 IM 机器人、MCP Server、浏览器扩展所有请求从这里进来。处理层文档解析引擎docreader 独立容器、分块与向量化、知识图谱构建、RAG 问答和 Agent 推理循环支持流式返回。存储层PostgreSQL 做主库向量库支持 8 种以上后端pgvector、Qdrant、Milvus、Weaviate 等Neo4j 存图谱文件可放本地或 MinIO 等 7 种对象存储Redis 负责缓存和队列。外部服务层20 LLM 提供商、网络搜索引擎、MCP 工具与数据源连接器。一次典型问答的数据流是这样的你的文档先被 docreader 解析成结构化内容按 512 字左右切成块并生成向量入索引库你提问时系统先做查询重写再走关键词 向量的混合召回用重排序模型筛出最相关的片段最后交给 LLM 带引用作答。理解这条链路后后面所有调优参数你就知道各自卡在哪一环节了。⚙️ 关键配置速查哪些参数什么情况下才需要改这一节把散在config/config.yaml和.env里的高频参数收进一张表让你改配置时不用满仓库找。参数控制什么默认值何时需要改chunk_size文档分块大小字512文档类型偏长表格或代码块时调大碎片化严重时调小chunk_overlap相邻分块重叠量50默认约为 chunk_size 的 10%一般不动embedding_top_k向量召回条数30召回总是漏答案时提到 50rerank_top_k重排后保留条数30想压缩上下文、降低 token 成本时调小keyword_threshold关键词匹配阈值0.3关键词召回噪声多时调高vector_threshold向量相似度阈值0.2向量召回噪声多时调高rerank_threshold重排序准入阈值0.3答案引用不相关片段时调高enable_rewrite/enable_query_expansion查询重写与扩展开关均为 true短问句效果差时确认开启长问句反而被改坏时可关max_roundsAgent 单轮任务的最大推理轮数5复杂多步任务总提前停步时调到 3-10改检索类参数只需要编辑config/config.yaml后重启 app 容器改MAX_FILE_SIZE_MB、STORAGE_TYPE这类运行参数则改.env。两类文件的作用范围不同别改错地方。 开发测试生产三环境参数对比一张表看清差异这一节回答同一套部署在不同环境里该拧哪些旋钮用一张横向对比表加每环境两三条要点带过不贴大段配置块。参数开发测试生产LOG_LEVELdebuginfowarnCONCURRENCY_POOL_SIZE21032MAX_FILE_SIZE_MB10020050STORAGE_TYPElocalminiominioNEO4J_ENABLEfalsetruetrueLangfuse 监控关关开采样率 0.1开发环境本地存储最简单文件直接落在数据卷里关掉图谱省资源debug 日志配合docker compose logs -f app排错最快。测试环境把并发池提到 10 模拟中等负载开上 MinIO 和 Neo4j 做全功能验证重点测大文件上传和图谱抽取两条重路径。生产环境并发池放到 32 顶高并发文件大小压回 50MB 保护系统开 10% 采样率的 Langfuse 留监控数据但别全量上报。需要图谱、MinIO 或 Langfuse 这类可选组件时启动命令加 profile 即可组合例如docker compose --profile neo4j --profile minio up -d。 性能调优与容量规划检索质量、资源上限与规模选型这一节把三件常被分开讲的事合在一起讲召回质量怎么调、容器资源怎么限、数据涨到一定量之后往哪个方向扩。检索质量默认配置下已经开了查询重写和扩展如果实际问答里召回了但不相关优先动rerank_threshold而不是 top_k相关但没召回才去动embedding_top_k和两个阈值。嵌入维度跟随所选模型常见为 768 或 1536换嵌入模型后必须重建索引。容器资源给 app 容器一个明确的上限能防止单实例吃光宿主机。下面的片段可直接放进docker-compose.yml的 app 服务app: deploy: resources: limits: cpus: 2 # 上限 2 核 memory: 4G reservations: cpus: 1 # 保底 1 核 memory: 2GPostgreSQL 单独给内存配额向量检索的重查询都压在这上面。规模选型按数据量三档走避免一上来就上集群。数据规模推荐配置可支撑量级小于 10GB单节点 PostgreSQL Qdrant约 100 QPS10-100GBPostgreSQL 主从 Milvus 集群约 500 QPS100GB 以上PostgreSQL 分片 Weaviate 集群1000 QPS缓存侧给 Redis 分配 2-4GB 内存淘汰策略用 allkeys-lru超时 300 秒这是命中率和内存占用之间的平衡点。更多向量库选型细节可以看 使用其他向量数据库。 生产加固访问控制、网络隔离与可观测性这一节把上线前的安全动作一次收齐谁有权限、流量走哪条路、数据怎么加密、出了问题往哪里看。访问控制上生产环境建议关自助注册、换上自己的密钥# 写入 .env 的鉴权与加密参数 DISABLE_REGISTRATIONfalse # 按需决定关注册可再改 true JWT_SECRET换成一段足够长的随机串 SYSTEM_AES_KEY换成32字节的随机串WeKnora 自带工作空间级 RBACOwner / Admin / Contributor / Viewer 四级角色和按空间隔离的审计日志多团队使用时按 RBAC 说明 配角色即可。网络隔离记住四条所有后端服务只走WeKnora-network内部网络对外只暴露前端容器的 80/443 端口PostgreSQL 和 Redis 不映射到宿主机MinIO 走内网地址公网访问只经前端代理。数据加密覆盖传输和存储两层app 与 docreader 之间的 gRPC 可启用 TLSGRPC_TLS_ENABLEDtrue并配好GRPC_TLS_CERT/GRPC_TLS_KEY/GRPC_TLS_CA三个路径变量MinIO 开 SSLPostgreSQL 设POSTGRES_SSL_MODErequire。可观测性用 Langfuse 接上四个变量填齐即生效采样率 0.1 表示只上报 10% 的链路兼顾成本和排障能力# 可观测性写入 .env LANGFUSE_ENABLEDtrue LANGFUSE_HOSThttps://cloud.langfuse.com LANGFUSE_SAMPLE_RATE0.1 LANGFUSE_RELEASEv1.0.0️ 故障排查速查常见故障现象与处理办法这一节给你一张现象 → 原因 → 处理速查表外加一个固定的诊断顺序排障时先对表再动手。现象可能原因处理办法数据库连接失败PostgreSQL 启动慢于依赖检查调大 healthcheck 超时时间向量检索超时Qdrant / Milvus 资源不足调高向量库容器内存限制文件上传失败MinIO 凭证错误核对MINIO_ACCESS_KEY_ID等配置知识图谱不可用Neo4j 没启用设NEO4J_ENABLEtrue并以 neo4j profile 重启诊断按这个顺序走从外到内一层层收口# 第 1 步环境自检 ./scripts/start_all.sh --check # 第 2 步看容器状态 docker compose ps # 第 3 步盯应用日志 docker compose logs -f app # 第 4 步探活接口 curl http://localhost:8080/health性能类问题再往前一步用docker stats看各容器 CPU 和内存曲线用docker compose exec app curl测容器间网络延迟数据库侧查 PostgreSQL 慢查询日志Langfuse 上看 P99 延迟和错误率。更细的疑难杂症可以先翻仓库自带的 QA 文档。部署检查清单与进阶功能入口按顺序勾完这份清单你的部署就算交付了每条都对应本文某一节的动作。Docker 与 Compose 版本达标资源满足最低配置80、8080 端口可用防火墙放行磁盘剩余空间超过 20GB.env中数据库与存储凭证已填密钥已替换LLM 服务地址可达模型配置正确./scripts/start_all.sh --all后docker compose ps全部 runningcurl http://localhost:8080/health返回正常前端页面可访问注册、登录流程走通上传一篇文档并提问引用与回答正常生产环境已按加固节配置 RBAC、TLS 与监控进阶方向都留了入口需要时再展开知识图谱设NEO4J_ENABLEtrue并配NEO4J_URIbolt://neo4j:7687详见 KnowledgeGraph 配置文档。多模型配置把config/builtin_models.yaml.example复制为config/builtin_models.yaml声明式配置多个 LLM 与嵌入模型实现故障切换。可观测性全量参数Langfuse 集成文档。API 参考与更多排障docs/api/目录和docs/QA.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），仅供参考