WeKnora部署实践5分钟跑通一个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、网页、Office 文档这些原始资料变成可问答的 RAG 知识库还能派生出推理 Agent 和自动维护的 Wiki。想给团队搭一套文档问得懂的内部知识库照着这篇部署实践走Docker 环境下 5 分钟左右就能跑起来。先认识一下这个项目WeKnora 做的事情很简单你上传文档它负责解析、切块、向量化之后你用自然语言提问它从你的资料里检索并生成带引用的回答。最大的亮点是一份数据多种用法——同一批文档既能做传统 RAG 问答也能让 Agent 自主检索推理还可以沉淀成带图谱的 Wiki 页面。整体由几个容器分工协作前端界面、Go 后端app、文档解析服务docreader、PostgreSQL 和 Redis架构如下部署前准备部署前先把环境自查一遍缺一项都会卡住后面的步骤项目要求说明Docker Docker Compose已安装且服务在运行全部服务以容器方式运行这是唯一的硬性依赖内存建议 8GB 以上核心 5 个容器同时跑再叠加文档解析和向量检索内存偏小会吃力磁盘预留 20GB镜像、数据库、上传的原始文件都落在这里端口80、8080前端界面用 80后端 API 用 8080被占用时可在.env里改大模型Ollama 或任意 LLM API默认走 OllamaOLLAMA_BASE_URL指向http://host.docker.internal:11434也可以改用云端 API 的内置模型文档解析流水线本身比较重扫描件 PDF 尤其耗资源机器低配的话上传大文档时耐心等待即可别急着重启。5分钟跑起来整个过程就四步每步执行完看下输出再继续git clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora拿到全部代码和配置文件。cp .env.example .env复制环境变量模板。.env里的数据库账号、Redis 地址、存储类型都有可直接用的默认值首次体验不改也能跑。docker compose pull拉取最新镜像第一次会比较久。docker compose up -d后台启动核心服务然后打开浏览器访问http://localhost看到初始化向导界面就算成功了两个验证动作浏览器访问http://localhost:8080/health返回正常说明后端已就绪在界面上新建一个知识库传一个 PDF稍后对它提问回答能带引用就代表整条链路通了。停止服务用docker compose down数据在 Docker 卷里重启不丢。按场景配置.env变量很多但不同场景真正要动的只有几个。检索和分块参数集中在 config/config.yamlapp 容器启动时会挂载它下面是三种典型场景的关键差异。场景一本地试玩保持默认即可什么都不用改STORAGE_TYPElocal文件落在本地卷GIN_MODErelease并发池CONCURRENCY_POOL_SIZE默认 5。大模型用本机 Ollama 最省心——先ollama serve拉一个对话模型和一个 embedding 模型再在设置页选为默认模型。场景二小团队试用重点是把文件存得稳、图谱能用这两件事做上docker compose --profile neo4j --profile minio up -dneo4jprofile 启动知识图谱端口 7474/7687minioprofile 启动对象存储9000/9001MinIO 控制台可在 9001 端口查看上传的原始文件。同时在.env里把STORAGE_TYPE改为minioNEO4J_ENABLE设为trueMAX_FILE_SIZE_MB默认 50按团队习惯放宽改完docker compose up -d生效。场景三生产环境生产上只动安全相关参数性能参数保持默认先观察GIN_MODErelease、LOG_LEVELinfo日志走 stdout 由容器采集DISABLE_REGISTRATIONtrue关闭公开注册新用户通过邀请链接加入SYSTEM_AES_KEY必须换成自己生成的 32 字节强随机值——API Key、模型凭证等敏感字段靠它加密落盘丢了就无法恢复WEKNORA_VERSION从latest固定到具体 release tag升级时先docker compose pull再up -d避免拉了没换、换了没拉。检索质量调优放在 config/config.yaml 的conversation段embedding_top_k: 30是向量初筛条数回答不准时先调它keyword_threshold0.3、vector_threshold0.2、rerank_threshold0.3分别对应关键词、向量、重排三道门槛阈值调低会多召回。分块参数chunk_size: 512/chunk_overlap: 50对长文档问答效果影响大改完需要重新解析知识库才生效。常见坑与排查现象一app 容器反复重启前端打不开可能原因后端没通过健康检查常见是数据库连不上或DB_PASSWORD里的特殊字符#、等没处理好。排查动作docker compose logs app看报错重点核对.env中DB_USER/DB_PASSWORD/DB_NAME和 postgres 容器是否健康docker compose ps。现象二能打开界面但提问无响应或 502可能原因app 还没就绪时前端就转发了请求或者模型没配好。排查动作curlhttp://localhost:8080/health在设置页确认默认 LLM 和 embedding 模型都能连通——用 Ollama 时注意容器默认访问host.docker.internal:11434Mac/Win 上没问题Linux 上如果host.docker.internal不通把OLLAMA_BASE_URL改成http://172.17.0.1:11434试试。现象三上传大文件失败或解析卡住可能原因超过MAX_FILE_SIZE_MB默认 50MB限制扫描件 PDF 解析本身耗时长。排查动作先确认文件大小确实在限制内还卡住调大WEKNORA_DOCREADER_CALL_TIMEOUT默认 30 分钟单次解析 RPC 超时日志里看 docreader 容器的输出。现象四知识图谱菜单是灰的 / 图谱查不到可能原因光设NEO4J_ENABLEtrue没用Neo4j 容器本身要用 profile 拉起来。排查动作用docker compose --profile neo4j up -d启动 Neo4j确认 7687 端口在监听再回设置页验证连接。具体见 docs/开启知识图谱功能.md。现象五换了向量库之后检索结果为空可能原因RETRIEVE_DRIVER换了比如从postgres换成qdrant但向量数据还留在旧库里新库是空的。排查动作新库需要先重新向量化已有知识库同时确认新库里 embedding 维度和模型一致。选型细节参考 docs/使用其他向量数据库.md。上生产之前扩展性向量检索默认走 PostgreSQLParadeDB内建能力数据量大或想单独扩容时通过 profile 换成 Qdrant、Milvus、Weaviate 等独立向量库RETRIEVE_DRIVER甚至支持多库并行检索。App 是无状态服务加副本时注意共享同一个 Redis 和存储后端即可。安全关闭公开注册、邀请制加人docs/RBAC说明.md 有完整的多租户角色设计JWT_SECRET和SYSTEM_AES_KEY用随机值并离线备份数据库和 MinIO 默认只监听容器内部网络不要额外映射到宿主机。监控接上 Langfuse 能看清每次问答的完整链路——docker compose --profile langfuse up -d自建一套Web 界面在 3000 端口或在.env里指向云端 Langfuse配合LANGFUSE_SAMPLE_RATE控制采样率说明文档在 docs/Langfuse集成.md。部署本身只是起点真正拉开差距的是后续的知识库组织方式和检索调参。建议接着看 README_CN.md 里的功能全貌命令行重度用户可以试一下 cli/README.md 的官方 CLI用weknora doc upload直接把本地文档灌进知识库。【免费下载链接】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），仅供参考