好多朋友在群里问我,腾讯开源的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 务必先装好Docker
Docker的安装这里不展开讲每个系统的细节,但有几个关键点想说一下。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/models,Windows在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文件,把里面的环境变量复制一份出来改成.env:
cp .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.yml
WeKnora的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_HOST=mysql - MYSQL_PORT=3306 - MYSQL_USER=weknora - MYSQL_PASSWORD=your_password - REDIS_HOST=redis - REDIS_PORT=6379 - EMBEDDING_MODEL_NAME=bge-m3 - EMBEDDING_API_BASE=http://host.docker.internal:11434 - LLM_API_BASE=http://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-m3;API地址要能通到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:7b
- Embedding模型地址:http://host.docker.internal:11434
- Embedding模型名称: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_count=262144如果想永久生效,把vm.max_map_count=262144写进/etc/sysctl.conf。另一个坑是内存不足,默认JVM堆设了2GB,如果机器只有8GB内存,建议改成1GB。
问题三:端口被占用
WeKnora的端口是9477,MySQL默认用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解决了从文档解析到检索问答的全链路工程问题。这三者配合,让一个普通开发者在一天之内就能搭建出企业级的多模态知识库底座。接下来就看你拿它装什么文档、配什么模型、接什么场景了。