好多朋友在群里问我腾讯开源的WeKnora到底能不能在本地跑起来跟Dify、FastGPT这些比又有什么不一样。我花了两天时间用Docker加Ollama把整套多模态知识库在本地环境里部署了起来中间踩了不少坑也理清了这套东西的设计思路。今天不整虚的直接把整个过程拆开揉碎讲给你听从环境准备、镜像拉取到模型接入、排错避坑一条龙讲清楚保证你看完能自己动手复现一套。先给还不了解的朋友交代一下背景。WeKnora是腾讯开源的一个知识库问答RAG引擎跟传统只处理文字的RAG框架不同它把OCR、版面分析、表格识别、图片理解这些能力直接做进了pipeline里所以PDF扫描件、PPT截图、网页表格这些乱七八糟的格式它都能解析入库。再加上它内置了GraphRAG、知识图谱构建这类高级玩法市面上能同时把这些能力打包得这么完整的开源项目确实不多。我这次选择的部署路径是Docker Compose编排容器加上Ollama管理本地大模型。之所以这么组合是因为WeKnora本身只有服务端代码和前端界面推理侧的模型还得自己接。Ollama恰好能把Qwen、DeepSeek这些开源模型在本地一键拉起来两边一配合就能做到真正的数据不出内网、全链路本地化。下面我把每个环节拆开讲包括我踩过的坑和最终稳定运行的配置希望能给你省点时间。1. WeKnora是什么为什么值得本地部署1.1 先搞懂WeKnora到底解决什么问题在聊部署之前我觉得有必要先把WeKnora的定位讲清楚不然你一上来就会困惑这玩意儿跟Dify这类工作流平台到底什么区别。Dify是一个大模型应用开发平台重点在搭建业务流程、编排Agent、管理Prompt它的强项是“应用开发”。WeKnora则更聚焦在“知识问答”这一个场景它默认解决的是怎么把文档变成可检索的知识再基于知识做精确回答。WeKnora在技术架构上的几个核心亮点是我这次重点测试的方向。第一是它自研的DeepDoc文档解析引擎。这个组件不是简单把PDF转成文本而是通过版面分析把文档切成标题、段落、表格、图片、页眉页脚这些不同区域再分别用OCR、表格结构识别、图像描述模型做处理。比如一份扫描版的合同它能识别出表格里的金额和条款并把表格结构还原成Markdown这比传统RAG框架拿个PDF解析库硬提文本要精细得多。第二是它的混合检索策略。它同时支持稠密向量检索和稀疏关键词检索再加上重排序模型把三种结果融合后重新排序。这样做的好处很明显纯向量检索对专有名词有先天劣势比如公司内部缩写“KT-2233项目”语义检索会跑偏但关键词检索能精准命中反过来大段的语义问法又得靠向量模型兜底。两者配合命中率和准确率都上了一个台阶。第三是它对多模态数据的支持。WeKnora可以把图片以视觉向量形式入库用户在提问时系统会先判断是否需要视觉检索然后派发到不同的检索链路。这意味着你传一本带大量插图的说明书进去问“这张图里的按键布局是什么”它也能给你找出来。这个能力传统RAG框架基本给不了也是我选择重点测试它的原因之一。1.2 多模态知识库和传统知识库的差别传统以文本Embedding为主的知识库处理PDF时先暴力提取文字遇到扫描件就做OCR然后按固定长度切块。这种方案的痛点是切块粒度不好把握切短了上下文不完整切长了向量检索精度下降而且对表格、图片、多栏排版基本无能为力。WeKnora的思路从一开始就不一样。DeepDoc解析出的结构里表格被转成Markdown文本图片被单独抽取出来走视觉模型处理段落结构被保留避免标题和正文被机械切碎。向量化也不是一刀切文本进文本模型处理图片进视觉模型处理各自存各自的向量。检索的时候文本问题和图片问题会走不同的检索通道最终统一汇总给大模型回答。我在实际测试里有个很直观的感受同一份包含大量表格的产品手册在传统知识库里问“第三页的规格参数表里接口类型这一列的值有哪些”答案经常是残缺的因为表格被切块后语义就碎了。但在WeKnora里表格被完整还原成结构化文本再入库这个问题就基本被根治了。如果你经常要处理财报、技术手册、论文PDF这类带大量表格图表的文档这个差异会非常明显。1.3 为什么选择Docker加Ollama这套组合WeKnora官方给了好几种部署方案有源码启动、有Docker Compose、也有Kubernetes。我最终选Docker加Ollama核心考量是干净和快。源码启动太折腾。WeKnora后端依赖中间件不少需要MySQL存元数据、Elasticsearch或MINIO做对象存储、Redis做缓存还要装Python依赖、前端构建每一步都可能因为系统环境不同出幺蛾子。Docker Compose把这些依赖全部打包进容器编排文件一条命令就能拉起整套服务环境隔离性也好不会在你机器上留一堆乱七八糟的依赖。Ollama则负责搞定模型侧。WeKnora本身不自带大模型需要接入推理服务。Ollama的好处是支持命令行一键管理模型拉取、启动、切换模型都极简单同时它默认监听11434端口提供OpenAI兼容的API格式WeKnora配置模型时填一个URL就能接通。网上很多教程还停留在手动部署vLLM或Xinference的层面上对新人太不友好Ollama显然更省心。这套组合还有个隐藏优势是资源可控。WeKnora本体和依赖中间件全走容器Ollama的模型放本机磁盘两者都能随时启停不会开机自启占内存。我自己的实践是部署完成后整套服务稳定运行一周无异常内存占用约6GB左右含一个7B级模型常驻对一台32GB内存的开发机来说完全没压力。2. 部署前的环境准备与方案选型2.1 硬件与系统要求先说说硬件底线。WeKnora本身不太吃配置服务端加上MySQL、Redis、Elasticsearch这些依赖8GB内存就能跑起来但会有点紧张。真正的资源大头是模型推理这部分在Ollama里。如果你只是测试功能建议准备16GB内存加一块4GB以上显存的NVIDIA显卡如果你要正经用于生产32GB内存加12GB以上显存的显卡是合理起点。以我自己的机器为例Ubuntu 22.04系统32GB内存NVIDIA RTX 3060 12GB显卡部署7B参数量的Qwen模型量化精度4bit显存占用约6GB整体运行流畅。如果没有NVIDIA显卡纯CPU跑7B模型也能出结果但每个问题可能要等10秒以上体验会打折扣AMD显卡可以尝试Ollama的ROCm支持但兼容性需要自己试建议先用CPU跑通流程再折腾加速。操作系统方面Linux是首选Ubuntu 20.04以上版本配置起来最顺。Windows用户建议用WSL2跑Docker不要直接在Windows下装Docker Desktop处理因为WeKnora的数据解析和向量化流程在Linux容器里更顺而且WSL2和GPU透传的配合也更成熟。macOS用户如果是Apple Silicon芯片跑CPU推理问题不大但GPU加速基本指望不上适合轻量测试。2.2 务必先装好DockerDocker的安装这里不展开讲每个系统的细节但有几个关键点想说一下。Windows用户如果装Docker Desktop碰到的第一个坑大概率是“Docker Desktop failed to start because virtualization support is not detected”这类报错。这个基本是BIOS里虚拟化没开或者Windows的Hyper-V和WSL2功能没启用。你需要在控制面板里把“适用于Linux的Windows子系统”和“虚拟机平台”这两个功能勾上重启后再打开Docker Desktop就正常了。Linux用户安装方式简单很多curl -fsSL https://get.docker.com | bash sudo systemctl enable docker sudo systemctl start docker这里有个小细节很多教程不会告诉你。你最好把当前用户加入docker组否则每条命令都要加sudo不够顺手sudo usermod -aG docker $USER newgrp docker装完之后记得检查一下Docker Compose版本WeKnora的编排需要Compose V2语法支持docker compose version如果提示没有这个命令多半是Docker版本偏老需要单独安装docker-compose-plugin这个包。后面要用WeKnora的docker-compose.yml这一步能省掉很多后续的麻烦。2.3 安装Ollama并准备好模型Ollama的安装官方给了一行脚本Linux和macOS直接跑curl -fsSL https://ollama.com/install.sh | shWindows用户直接去官网下载OllamaSetup.exe安装包就行。安装完成后验证一下服务状态ollama --version ollama serveOllama默认的模型存储目录在Linux的~/.ollama/modelsWindows在C:\Users\你的用户名\.ollama\models。如果你C盘空间紧张可以通过设置环境变量OLLAMA_MODELS来改存储位置这点在下面避坑部分会细说。接下来是拉取模型。WeKnora官方推荐用一个Embedding模型加一个推理模型组合Embedding负责把文本变成向量入库检索推理模型负责最终答案生成。我自己用的是下面这组配置# 文本向量化模型负责把文档和问题转成向量 ollama pull bge-m3 # 推理模型负责最终回答7B参数的Qwen在中文场景表现不错 ollama pull qwen2.5:7bbge-m3是BAAI开源的嵌入模型中文效果稳定而且WeKnora官方docker-compose里默认的向量维度配置就是兼容这类模型的。qwen2.5系列在中文知识问答上表现可靠7B在消费级显卡上能流畅跑起来。如果你想测试多模态能力比如图片问答可以再拉一个视觉模型ollama pull qwen2.5vl:7b这个模型可以让WeKnora对图片内容做描述和问答属于多模态链路里的一环但如果你只是想先跑通文本知识库可以后续再加。3. 使用Docker Compose本地部署WeKnora全流程3.1 拉取镜像前的准备老规矩先把项目代码拿下来。WeKnora的官方仓库在GitHub上项目名是Tencent/WeKnora直接克隆到本地git clone https://github.com/Tencent/WeKnora.git cd WeKnora仓库里有个docker目录里面放着编排文件和配套的配置。目录结构大致是这样的docker/ ├── docker-compose.yml ├── .env.example └── ...你需要先看一眼.env.example文件把里面的环境变量复制一份出来改成.envcp .env.example .env这里面的变量我会挑几个重点讲一下。首先是MYSQL_PASSWORD和REDIS_PASSWORD这几个中间件的密码默认值一定要改掉不要用example里的弱密码然后是EMBEDDING_MODEL_NAME这个要跟Ollama里拉取的Embedding模型名保持一致比如你拉的是bge-m3这里就填bge-m3还有你的模型API地址默认一般是http://host.docker.internal:11434这个在Win和Mac上可以直接用Linux下可能要改成实际IP或者配置extra_hosts这个在避坑部分细说。3.2 编写并理解docker-compose.ymlWeKnora的docker-compose.yml包含的容器服务还不少主要有以下几个weknora主服务就是后端服务负责文档解析、编排和API、weknora-ui前端界面、mysql元数据存储、redis缓存、elasticsearch向量检索、minio对象存储这几类。先承认一个事实这个编排文件默认配置的中间件规格是不低的。Elasticsearch默认分配了2GB堆内存MySQL默认数据目录挂载在容器内部如果不做持久化配置容器销毁数据就没了。所以我的建议是修改docker-compose.yml把关键数据卷挂载到宿主机目录这样才能保证数据安全。这里给出一个简化版的编排重点说明我需要自定义什么services: weknora: image: weknora/weknora:latest ports: - 9477:9477 environment: - MYSQL_HOSTmysql - MYSQL_PORT3306 - MYSQL_USERweknora - MYSQL_PASSWORDyour_password - REDIS_HOSTredis - REDIS_PORT6379 - EMBEDDING_MODEL_NAMEbge-m3 - EMBEDDING_API_BASEhttp://host.docker.internal:11434 - LLM_API_BASEhttp://host.docker.internal:11434 volumes: - ./data:/app/data depends_on: - mysql - redis - elasticsearch注意看我重点改的几个地方。第一个是API地址http://host.docker.internal:11434是Docker容器里访问宿主机服务的一个特殊域名Windows和Mac的Docker Desktop直接支持但Linux默认不支持需要在docker-compose.yml里加extra_hosts配置extra_hosts: - host.docker.internal:host-gateway第二个是向量化模型的地址配置。WeKnora在对接Embedding模型时需要两个参数一个是模型名称一个是API地址。模型名称要和Ollama拉取的完全一致比如bge-m3API地址要能通到Ollama的11434端口。第三个是Elasticsearch的配置。默认的docker-compose.yml里Elasticsearch可能会设置密码或安全认证你在WeKnora的环境变量里要记得对应填写而且ES的jvm.options里堆内存大小建议根据机器情况调整默认2GB在16GB内存机器上问题不大但如果你是8GB内存的机器建议改小到1GB。3.3 启动服务与首次登录配置改好之后就可以启动了。在docker目录下执行docker compose up -d第一次启动会拉一批镜像WeKnora主服务、前端、MySQL、Redis、Elasticsearch、MinIO全部要下载时间长短取决于你的网络通常需要十几分钟到半小时不等。拉取完成后用下面命令看容器状态docker compose ps正常情况下所有服务的STATUS应该显示Up或者healthy。如果发现有容器反复重启用下面的命令看日志定位问题docker compose logs -f weknora等服务全部起来之后打开浏览器访问http://localhost:9477就能看到WeKnora的登录界面。首次登录需要使用默认管理员账号admin密码在项目的README或者.env配置里能查到。登录之后建议第一时间修改密码。这里说一个我踩过的坑有个朋友在部署时前端界面打开了但登录一直报错后来排查发现是MySQL容器没起来因为密码字段里带了特殊字符导致环境变量解析出问题。所以如果你的中间件密码里包含$、、#这类字符务必在.env文件里加单引号包裹或者干脆用纯数字加字母的密码省得折腾。3.4 配置Ollama模型接入登录进去之后先别急着建知识库第一件事是确认WeKnora后端能连上Ollama。在WeKnora的管理后台里找到模型配置相关入口把下面几个参数填好推理模型地址http://host.docker.internal:11434宿主机Ollama的地址推理模型名称qwen2.5:7bEmbedding模型地址http://host.docker.internal:11434Embedding模型名称bge-m3配置保存后先做一个简单的连通性测试直接在对话框里发一句话比如“你好做一个自我介绍”如果模型响应正常说明整个链路通了。为什么要先做这一步因为很多人在建知识库之前没测试模型连通性结果建完知识库后一问三不知排查半天才发现根本不是知识库的问题而是模型压根没接上。先把地基打好后面才不会浪费感情。4. 实测从零搭建一个多模态知识库4.1 数据准备与上传链路通了之后就可以正经搭一个知识库了。我准备了一份公司内部的产品手册PDF里面包含大量产品图片、规格参数表格和操作说明排版比较复杂正好用来测试WeKnora的文档解析能力。在管理后台里新建一个知识库起个名字然后选择上传文件。WeKnora的上传界面会把文档解析过程可视化解析分成几个阶段版面分析、OCR识别、表格还原、文本提取、图片抽取。每个阶段都有进度反馈你可以直接观察到DeepDoc组件在逐页处理文档。解析完成后系统会显示文档里提取出来的结构化内容预览包括识别出的标题层级、表格的Markdown格式、抽取出的图片数量。这个阶段如果发现某些扫描页识别效果差可以先人工检查一下比到最后问答时发现答案错误再回头排查要高效得多。我在首次测试时就发现一个表格被识别成了两段文本问题出在那一页表格上有两处大面积留白DeepDoc把表格区域切开了。后来换了个清晰度更高的PDF版本问题就解决了。4.2 自定义Chunk切分与向量化入库解析完文档下一步是参数配置这一步非常关键因为切分的粗细直接决定后续检索的精准度。WeKnora在知识库配置里开放了切块大小和重叠窗口设置默认值是300个字符重叠50个字符这个参数不是死的需要根据文档类型调整。我的经验是技术文档、合同条款这类结构规整的文本可以稍微调大到400到500个字符让每个切片保留更多上下文语义而FAQ、新闻资讯这类短平快的文本保持300甚至更小反而更精准。另外一定要打开“保留标题层级”的选项WeKnora可以利用文档结构自动把标题信息拼进切片内容里这一步能显著提升长文档的召回率。配置好后点击向量化WeKnora会把结构化内容通过bge-m3模型逐个转换为向量写入Elasticsearch。这个过程同样有进度条一份30页的PDF处理时间大概两三分钟速度取决于Embedding模型的推理速度和文档复杂度。向量化完成后知识库就正式可用了。4.3 检索问答实测与调优一切就绪提几个问题看看效果。我先问了一个典型的长尾问题“产品在高温高湿环境下长时间运行推荐的保养周期是多少”这个问题同时包含语义关键词和具体细节很考验检索能力。WeKnora的回答让我印象比较深刻它没有直接把某一段原文生硬地贴出来而是基于检索到的多个段落综合生成了答案并且附带了来源引用。响应时间大概两秒其中检索加排序耗时不到一秒生成时间占了大头整体体验还算流畅。接着测试表格能力我问“第三章节的规格参数表里各型号的接口类型分别是什么”这类问题在传统文本Embedding方案里几乎必挂但WeKnora准确地把表格内容定位并转成了结构化数据供模型引用。这说明DeepDoc解析出来的表格水平确实比普通方案高出一大截。再测视觉能力如果之前拉了qwen2.5vl模型可以在知识库里上传一些含产品实物图的文档然后问“根据文档中的示意图设备背面板从左到右有哪几个接口”。WeKnora会先走视觉检索链路找到相关图片再交给视觉语言模型做识别理解最终给出图文结合的回答。这一步极其惊艳但也对文档里的图片清晰度有要求如果图片本身模糊或拍摄角度不正识别率会明显下降。5. 常见问题与避坑指南5.1 Docker启动失败与资源不足这里把部署过程中最常遇到的问题整理一下这些都是我和周围朋友实测中高频踩的坑优先级从高到低。问题一Docker Desktop报“virtualization support not detected”这个在Windows上尤其常见原因是BIOS虚拟化没开或者Windows功能没启用。处理方式在BIOS里开启Intel VT-x或AMD-V然后在控制面板里启用“虚拟机平台”和“适用于Linux的Windows子系统”重启后再打开Docker Desktop。问题二Elasticsearch容器反复重启Elasticsearch最常见的坑是vm.max_map_count不足Linux下执行这个命令解决sudo sysctl -w vm.max_map_count262144如果想永久生效把vm.max_map_count262144写进/etc/sysctl.conf。另一个坑是内存不足默认JVM堆设了2GB如果机器只有8GB内存建议改成1GB。问题三端口被占用WeKnora的端口是9477MySQL默认用3306如果本机已经装了MySQL或Redis会跟容器端口冲突。最简单的办法是改docker-compose.yml里的宿主端口映射例如把MySQL映射改成{ 3307:3306 }然后把.env里对应端口同步修改。5.2 镜像下载慢与Docker配置调优国内网络环境下拉取Docker官方镜像经常慢到怀疑人生这是部署过程中最磨人的环节。我不推荐去找各种来路不明的镜像加速地址因为安全性和稳定性都没法保证。比较稳的路线有两个一是直接用官方源挂代理或错峰下载二是如果公司或学校有可用的镜像仓库优先从那里面拉。在拉取镜像之前可以先确认当前Docker使用的镜像源docker info | grep -A 5 Registry Mirrors如果需要调整可以编辑/etc/docker/daemon.json配置镜像加速地址改完记得重启docker服务。但我要提醒一句任何第三方镜像源的稳定性和安全性都不如官方源有保障如果在生产环境使用务必评估清楚再决定。5.3 Ollama模型下载慢的处理Ollama拉取模型同样存在下载慢的问题bge-m3这种几百MB的模型还好qwen2.5:7b这种4GB级别的模型如果网速不给力真的能急死人。一个可行的技巧是把模型文件从其他机器上拷贝过来放到Ollama的模型目录里然后执行ollama list它会自动扫描并识别本地已有的模型。这个方法特别适合那些在公司内网下载了大模型、想拷贝到家里的机器的场景。另一个经验是拉大模型时尽量选在网络空闲时段比如凌晨实测速度快很多。5.4 知识库回答质量差的问题如果你发现问答效果不佳先别急着怪模型大概率是前置环节出了问题。我总结了一个排查顺序先检查文档解析质量在知识库的文档详情里看看DeepDoc有没有把表格和图片正确提取有没有版面识别错误。再检查切块参数如果回答内容答非所问可以试试缩小切块大小、增加重叠如果回答过于碎片化就调大切块。最后检查检索结果在调试页面里看看检索返回了哪些切片排名靠前的切片里有没有包含答案。如果检索结果本身就找不到相关内容那问题大概率出在文档质量或Embedding模型上可以试试换个文档格式上传或者换个Embedding模型。如果检索到了正确切片但回答还是错的那才是推理模型能力不够的问题这时换更大参数的模型才有意义。5.5 多模态能力不生效我刚开始测试时文档里明明有图片但视觉问答链路就是不触发。后来排查发现是视觉模型没配置好。WeKnora的多模态链路要单独指定视觉模型而且知识库上传的文档必须在解析时“抽取图片”开关处于开启状态这部分配置在知识库的高级设置里。如果你用了qwen2.5vl却还是不走视觉链路检查一下这两处配置是否到位。另一个容易忽略的点是视觉检索和文本检索的向量空间是不同的模型生成的维度也可能不同所以图片和文本的相似度不能直接跨模型比较。WeKnora在这块做了内部封装但如果你的Embedding配置里用的模型和视觉模型维度不匹配可能在检索时报错这也是为什么我建议先按官方默认模型组合跑通再考虑换模型。6. 部署完成的收尾建议与扩展玩法整套部署完成之后有几个收尾细节值得做一下。第一件是把Ollama服务设置成开机自启因为Docker服务重启后WeKnora容器能自动恢复但Ollama不会得手动启动一下模型。在宿主机上把它配置成systemd服务开机就能自动拉起。第二件是建议给关键目录做定期备份。WeKnora的MySQL里存了知识库的元数据配置Elasticsearch里存了向量索引MinIO里存了原始文件。最稳妥的方式是把这几个容器的数据目录单独挂载出来然后定期打包备份。如果没有做持久化挂载容器一旦被删你辛辛苦苦建的知识库配置就全没了。部署完WeKnora这套系统我还有几个扩展玩法可以聊一下。目前是我个人觉得比较有价值的几个方向。第一个是接入企业微信群机器人或飞书机器人把WeKnora的API封装成对话服务这样团队成员直接在企业微信里提问就能查知识库不用打开浏览器操作这算是企业场景里落地最快的一步。第二个是给WeKnora配置多知识库隔离不同部门建不同知识库数据权限分开这在企业内部落地时非常实用。第三个是尝试用GraphRAG方式构建知识图谱WeKnora内置了对知识图谱的支持在文档量大、实体关系复杂的场景下用图谱配合向量检索能进一步提升回答的准确性。最后回到我个人的体会。WeKnora这套项目最大的价值不是它某个单一功能有多强而是腾讯把一条完整的多模态RAG流水线开源出来了。过去想做一套能处理扫描件、表格、图片的知识库需要自己拼装解析引擎、向量库、重排序模型光打通这些组件就要耗掉大量的时间。现在有了WeKnora配合Ollama的模型管理能力一台普通配置的开发机就能把整条链路跑起来。有一点我要提醒的是WeKnora目前迭代速度比较快版本升级频繁建议你部署后把镜像版本固定下来不要没事就docker compose pull避免升级后配置不兼容导致服务起不来。我在这两天的折腾里最大的感觉是本地部署大模型知识库的门槛已经比一年前低太多了。Docker解决了依赖问题Ollama解决了模型管理问题WeKnora解决了从文档解析到检索问答的全链路工程问题。这三者配合让一个普通开发者在一天之内就能搭建出企业级的多模态知识库底座。接下来就看你拿它装什么文档、配什么模型、接什么场景了。