简介这套源码包专为希望本地部署知识库系统的开发者和 RAG 技术学习者打造定位为 WeKnora 部署的轻量参考工程。内容覆盖腾讯开源 WeKnora 的部署配置源码集中呈现环境变量、大语言模型、Embedding、Rerank 等模型接入方式同时包含多模态配置与文档分割设置的参考实现适合从入门到实践阶段对照学习。包体共 3 个文件以 .inscode 项目配置文件、HTML 页面文件和 .gitignore 文件为主体压缩包约 7KB规模精简但信息密度较高便于快速定位关键配置内容。目前已有 431 人学习下载是知识库搭建前值得参考的小体积样例。通过这份源码读者可以直观了解 WeKnora 的目录组织、页面入口和服务配置思路减少在环境准备、模型检测、参数填写等环节的试错成本同时为后续进行知识库结构调整、文档分割策略优化和多模态应用扩展打下基础是一份轻量但完整的上手参考。1. WeKnora知识库部署从源码包到可用系统RAG应用今年已经不算新鲜概念但真正能把文档解析、向量化、召回、重排序和对话生成串成完整链条的项目并不多。WeKnora就是这样一个开源知识库平台它把Knova组件的RAG能力包装成带Web界面的可部署系统。如果你手头有一批PDF、Word、扫描件要变成能对话问答的知识库又不想从零写编排代码这份源码包值得花一个下午来部署。它解决的不只是“能跑起来”还有“生产环境下参数怎么调、出了问题怎么排查”。适合有基本Docker和Python经验的开发者前端新手也能照步骤完成部署。2. 部署前选型四个必须提前确认的技术决策2.1 组件架构容器划分与宿主机资源估算WeKnora源码包里的部署方式以Docker Compose为主整体拆成两个核心服务appWeb界面和API和worker异步任务处理。app负责接收请求、管理会话worker负责文档解析、向量化、召回这类耗时操作。两者通过Redis和数据库共享状态所以一个完整部署至少涉及五个容器app、worker、MySQL、Redis、向量库。我第一次部署时犯过资源估算的错误在2核4G的机器上硬上完整套件结果worker一跑文档解析内存直接榨干。实际经验是文档解析环节尤其是OCR是内存大户8G内存起步才稳4G只能处理纯文本场景。磁盘方面宿主要预留20G以上因为除了镜像体积app镜像约2G、worker镜像约3G向量库的文件存储、MySQL的数据文件、上传的原始文档都会占空间。2.2 向量库选型原生支持与版本兼容是硬约束WeKnora原生对接的向量库以Milvus为主也兼容其他方案。这里不推荐自己随便换因为向量库的类型直接影响docker-compose.yml里的连接串写法。Milvus在源码包里是独立容器依赖etcd和MinIO启动顺序上有要求。版本兼容是个容易忽视的细节Milvus 2.3.x和2.4.x的配置项有差异源码包锁定的某个版本就按它的来不要自作主张升级。我遇到过一次升级Milvus后索引类型不兼容导致服务起不来的情况。源码包里如果自带了mysql、redis、minio、etcd这几个基础组件的镜像版本就全部固定使用基础组件之间的依赖关系比想象中更敏感。2.3 嵌入模型与重排序模型的接入方式这里的关键决策是模型用在线API还是本地推理。在线API配置简单base_url和api_key填好就能用但每次解析文档都要调用文档量大时费用不可控。本地推理则要额外部署Ollama或类似推理服务好处是数据不出内网坏处是首次向量化几百个文档时CPU推理速度慢得让人怀疑进程挂了。WeKnora的模型配置集中在某个配置文件里部署前要读三遍。它支持配置多个模型对话模型、嵌入模型、重排序模型可以分别指定。我的建议是先配通在线模型把系统跑起来确认全链路正常后再切换到本地模型一步到位的失败率太高。2.4 端口规划与防火墙策略默认端口规划app的Web页面在7860Gradio框架常用API端口、MySQL 3306、Redis 6379、MinIO 9000、etcd 2379都会占用。部署前先把宿主机防火墙放行清单列好不然所有容器起来了页面就是访问不了。提示容器内端口映射记得统一改至少要在docker-compose.yml里核对一遍别用默认值直接起。2.5 部署信息速查表项目推荐配置备注宿主机内存8G起OCR解析时内存峰值明显磁盘20G镜像约5G文档与向量数据持续增长Docker版本Compose v2旧版v1语法兼容性问题多向量库源码包内置的Milvus别单独升级版本模型接入先在线后本地确认链路后再切本地推理3. 从源码构建服务端镜像两条构建路径与踩坑记录3.1 路径一直接拉取预构建镜像省时方案源码包根目录下有docker-compose.yml文件最省事的方式是直接用镜像仓库里已有的镜像。在执行docker compose up前先执行docker network create weknora-net docker pull xxx/weknora_app:latest docker pull xxx/weknora_worker:latest这段命令先创建自定义网络保证多个容器间通过服务名互访再拉取app和worker镜像。网络创建这一步容易漏但漏了的结果就是容器起来后app找不到worker因为Compose默认网络只在当前项目内生效手动创建的net要显式声明在compose文件里。拉镜像卡住时先检查网络策略再考虑镜像加速配置因为仓库地址在不同网络环境下连通性差异很大。镜像拉取时长受网络影响很大app和worker合起来超过5G若在部署机器上下载困难可以考虑在有加速的环境下先docker pull再docker save成tar包拷到目标机器后docker load导入这招比改一堆配置更接地气。3.2 路径二本地构建源码镜像定制方案拿到源码包后在项目根目录执行cd weknora-source mkdir -p build cp -r server build/ cp -r web build/ docker build -t weknora_app:local -f build/server/Dockerfile build/server/ docker build -t weknora_worker:local -f build/server/Dockerfile.worker build/server/这里把server和web目录复制到build下作为构建上下文然后分别构建app和worker镜像。Dockerfile内容的关键点在前端静态资源Web界面是构建时被打进镜像的如果前端代码有修改必须重新跑一次前端构建才能生效。改了后端Python代码重启容器就能生效改了前端代码要重新构建镜像。不少人在修改前端页面后不重新构建刷新页面发现没有任何变化原因就在这。依赖安装阶段如果出现pip下载超时Docker构建缓存会让问题更难排查因为重新构建时会复用旧的依赖层。3.3 构建后启动前的配置核对启动前先把docker-compose.yml里的关键参数过一遍docker compose config docker compose up -d docker compose logs -f appdocker compose config会校验语法并展开完整配置格式问题比如缩进、引号在这一步就暴露出来。up -d把容器组拉起来然后立刻看app日志确认它是正常启动还是循环重启。最典型的失败是app容器起来后马上退出日志显示连不上MySQL——这种情况优先检查MySQL容器健康状态而不是看app代码。容器健康检查是个好习惯。在compose文件里给MySQL和Redis加上healthcheckapp的depends_on配置condition: service_healthy能在一定程度上解决启动顺序问题。如果没有健康检查MySQL还没就绪时app已经在初始化数据库会出现诡异的表不存在报错。3.4 源码目录中两个必须手改的配置点第一个是config目录下的模型配置。不同推理服务的base_url格式、api_key字段名、模型名写法都可能不同建议先只改一处模型配置不要一次动多个方便定位问题。第二个是docker-compose.yml里的挂载路径。源码包默认的挂载目录可能不满足你的机器环境改挂载目录后注意权限问题容器内用户对挂载目录的读写权限缺失会导致上传文档失败这一点比想象中常见。注意目录权限问题通常表现为上传文档后没有反应查看worker日志能看到Permission denied。4. 初始化知识库与上传文档配置参数、页面操作与验证方法4.1 首次登录页面入口、默认账号与必须改掉的三项默认值部署完成并启动镜像后浏览器访问宿主机IP加映射端口会进入WeKnora的Web界面。登录后第一件事是修改默认密码然后改两处配置参数服务地址IP换了要更新和模型参数默认值通常不匹配实际环境。我在一个模拟项目里部署时发现很多人会在知识库设置里直接点新建但实际的流程是先在系统管理里把模型配置好再去创建知识库。顺序反了会出现知识库里选不到模型的情况。先配模型再建知识库是效率最高的路径避免建完发现模型不可用又回来重配。4.2 创建知识库与上传文档参数名的实际含义在Web界面点新建知识库后会看到知识库ID文档解析方式向量化模型这些字段。知识库ID是知识库在系统内的唯一标识后续API调用和worker内部判断都要靠它建议自定义成有业务含义的名字比如finance-2024别用自动生成的无序编码。文档解析方式一般有文本抽取和OCR识别两种选项文本抽取PDF/Word里有文字层时直接提取速度快、准确率高但扫描件会变成空文本 OCR识别适合扫描件但解析时间长、对中英文混排的准确率依赖模型创建完成后上传一个测试PDF观察worker日志docker logs -f weknora-worker正常情况能看到文档解析成功的日志。如果日志里一直卡着不动大概率是向量化模型没有配置通worker在等待模型响应超时。4.3 测试问答链路召回质量与重排序效果的快速验证上传文档、确认解析成功后进入对话测试页面依次验证三件事第一对话不通先查模型连通性。第二对话通了但回答内容完全没用到知识库检查会话是否绑定了正确的知识库ID。第三回答不准确时对比调整召回候选数和重排序模型的效果。常见现象是闲聊能通但回答跟文档内容完全无关原因基本是会话没有挂上知识库ID。每个会话都要显式指定绑定的知识库不能指望系统自动关联。参数方面召回候选数top_k影响最终回答质量。候选数太小会漏检候选数太大又给重排序模型增加压力。实际调试中先设5看效果再逐步调整到10、15观察答案质量变化。4.4 验证文档正确进入向量库的方法上传后看不到界面反馈解析成功时直接查向量库确认数据是否真正写入。进入Milvus容器执行查询命令看看collection里有没有对应文档的向量记录。这个方法能区分两种情况文档解析成功但前端状态显示延迟和解析本身失败了。同样Redis里能看到任务状态变化如果任务状态一直处于pending就是worker异常。5. 常见部署问题与避坑指南四条高频翻车现象5.1 容器起来了但Web页面一直转圈加载现象docker compose ps看所有容器都是Up状态打开浏览器访问7860端口页面一直转圈甚至白屏。原因前端资源没有正常加载常见有两个原因。一是app容器启动时前端静态资源还在构建中页面已经尝试加载但资源不可用二是浏览器缓存了旧的JavaScript文件与新的前端资源版本不匹配。解决先强制刷新浏览器缓存CtrlShiftR不行就进入app容器内确认静态资源目录文件齐全。前端资源不齐全时重新构建app镜像偶尔是容器启动时资源还没有初始化完成可以restart容器等半分钟再访问。5.2 上传PDF后没有反应worker日志空白现象在页面上传PDF文件界面没有任何动静甚至没有报错提示。查看worker日志发现干净得像什么都没发生过。原因app和worker之间的通信配置异常。app接收上传请求后把解析任务放到了消息队列里但worker连不上同一个消息队列任务就一直堆积着没人处理。更隐蔽的情况是命名空间不一致app把任务发到A队列worker监听B队列。解决检查docker-compose.yml里app和worker的队列连接配置确认它们指向同一个队列实例和相同的库编号。可以curl一下消息队列的非阻塞ping接口确认两个服务都能正常连接。最后一招把worker服务restart一次看日志里是否出现connected to queue之类的标识出现才说明worker已经正常订阅。5.3 文档解析成功但回答内容与文档无关现象能看到解析完成的日志向量化也执行了但问答时模型回答的内容跟上传的文档完全不沾边。原因会话没有正确绑定知识库ID问答链路走的是模型内置常识而不是知识库上下文。另一个原因是知识库里数据还未生效Web界面误点了其他知识库。解决在对话界面确认当前会话绑定的知识库ID与目标知识库ID一致确认知识库里文档状态为已完成而不是处理中。如果ID无误重新发起一次新会话再测试排除了会话历史干扰。5.4 本地模型接入后首次问答等待时间异常长现象本地模型配置完成后发起提问等了很久才出结果甚至超时报错。但看资源占用率CPU并没有跑满。原因本地推理服务与WeKnora的并发配置不匹配一次请求发起多个并发任务推理侧排队或者模型加载到显存的前置耗时被算进了请求响应时间。另一个原因是嵌入模型和生成模型配置被一条消息触发了多个请求推理服务串行处理总耗时就叠加上去了。解决先单独验证推理服务接口的响应耗时用curl或测试脚本直接调用模型接口确认模型本身响应速度正常再调整WeKnora侧的并发配置限制同时发起的请求数最后确认模型没有在每次请求时重新加载——确保调用前模型已经常驻显存/内存请求响应时间会明显改善。6. 进阶技巧用Ollama衔接WeKnora的本地化知识库方案本地化部署意味着数据和推理都不依赖外部服务。WeKnora的模型接入层设计成兼容OpenAI接口风格的格式这让它对接本地推理服务变得直接。Ollama是常见的本地推理运行工具它提供的API接口格式能适配WeKnora的模型配置。一个典型的本地模型配置流程是先在部署Ollama的机器上预拉取所需模型让模型文件提前下载完成。然后确认Ollama监听端口与WeKnora部署在同一台机器时宿主机内互通通常没有问题。最后在WeKnora的模型配置里逐项填写服务地址、模型名称等参数。对话模型、嵌入模型、重排序模型三类模型参数本地部署时常分别指定不同模型。嵌入模型建议单独选择适合中文的Embedding模型重排序模型与对话模型也可以分开配置。这样编排出来的整体效果是文档解析完成、向量化入库、检索召回重排序调整候选顺序最终生成回复——全链路本地执行。配置完成后做一次端到端验证上传一篇测试文档等待解析完成发起提问检查回答质量。对比在线模型方案本地推理首次响应通常慢一些这是模型加载和推理硬件差异导致的正常现象。之后我每次调试完本地模型都会重置掉已上传的旧文档重新走一遍完整流程确认链路终点通畅避免旧数据干扰判断。希望这篇部署经验能帮你少走几步弯路真正把知识库跑起来。本文还有配套的精品资源点击获取