数据不出电脑、不花一分钱:手把手搭一个本地 AI 知识库
Ollama + WeKnora 零基础教程|全程可复制粘贴|实测版本 WeKnora 0.7.2 / Ollama 0.33.2|含 8 个新手坑详解
适合谁:没写过代码、没配过 Docker,但想给自己搞一个"能读懂我的文档"的 AI 助手。
不适合谁:想深入排查 Docker 网络问题的(那请看我的另一篇排坑实录)。全程不需要花钱、不需要 API Key、文档不会离开你的电脑。
先搞明白:这东西到底能干嘛
在动手之前,先花两分钟搞清楚你要做的是什么。不然后面每一步都像在念咒语。
一句话版本
你把一堆 PDF / Word 丢进去,然后像聊天一样问它问题,它只根据你给的文档回答,还会告诉你答案出自哪一段。
它和普通 ChatGPT 有什么区别
| 普通 ChatGPT | 你搭的这个 | |
|---|---|---|
| 数据来源 | 训练时学的互联网知识 | 只有你上传的文档 |
| 会不会编造 | 会(“幻觉”) | 大幅减少,且给出处 |
| 你的文档去哪了 | 上传到别人的服务器 | 留在你自己电脑上 |
| 花钱吗 | 付费版才好用 | 完全免费 |
| 断网能用吗 | 不能 | 能 |
那"RAG"是什么
你肯定听过这个词。说人话就是:
开卷考试。
普通 AI 是闭卷考试——全靠脑子里记住的东西答,记错了就瞎编。
RAG 是开卷考试——先把你的文档翻一遍,找到相关的段落,然后照着那段话回答你,顺便告诉你"我是从第三页第二段抄的"。
整个流程长这样
【准备阶段:你只做一次】 你的 PDF / Word / TXT │ ▼ ┌─────────────┐ │ 1. 拆成小块 │ 比如按段落切开,每块几百字 └─────────────┘ │ ▼ ┌─────────────┐ │ 2. 转成数字 │ 用"向量模型"把每段话变成一串数字 │ (向量化) │ 意思相近的话,数字也接近 └─────────────┘ │ ▼ ┌─────────────┐ │ 3. 存进数据库│ 存在你电脑上的 Postgres 里 └─────────────┘ 【使用阶段:每次提问】 你问:"年假怎么算?" │ ▼ ┌─────────────┐ │ 问题也转数字 │ └─────────────┘ │ ▼ ┌──────────────────────────────┐ │ 4. 找最像的几段话(检索) │ │ · 按意思找(向量) │ │ · 按关键词找(BM25) │ │ 两种方式一起用,不容易漏 │ └──────────────────────────────┘ │ ▼ ┌──────────────────────────────┐ │ 5. 把这几段话 + 你的问题 │ │ 一起交给大模型 │ └──────────────────────────────┘ │ ▼ 答案 + "我参考了《员工手册》第3页第2段"两个主角分别是谁
- WeKnora:腾讯开源的知识库框架。上面那张图里除了"跑大模型"以外的活,全是它干。它是主角。
- Ollama:一个让你在自己电脑上跑大模型的工具。装好之后一条命令就能下载模型,不花钱。它是配角,负责提供"大脑"。
它们的关系:
┌─────────────────────────────────────────┐ │ 浏览器(你看到的界面) │ │ http://localhost │ └─────────────────┬───────────────────────┘ │ ┌─────────────────▼───────────────────────┐ │ WeKnora(跑在 Docker 里,5 个容器) │ │ │ │ 前端界面 ──> 后端 ──┬─> 数据库 │ │ │ (存向量) │ │ ├─> 文档解析 │ │ └─> 缓存 │ └─────────────────┬───────────────────────┘ │ 需要"思考"时 ┌─────────────────▼───────────────────────┐ │ Ollama(装在你电脑上,不在 Docker 里) │ │ │ │ qwen2.5:7b → 负责组织语言 │ │ bge-large-zh:v1.5 → 负责理解中文 │ └─────────────────────────────────────────┘💡为什么 Ollama 要单独装?因为它要直接调用你的显卡。Docker 容器里访问显卡比较麻烦,装在你自己电脑上最简单。
开工前:你的电脑够不够
最低要求
| 项目 | 要求 | 怎么查 |
|---|---|---|
| 系统 | Windows 10 21H2+ / Windows 11,或 macOS 12+ | — |
| 内存 | 8GB 能跑(但慢),16GB 舒服 | 任务管理器 → 性能 |
| 硬盘 | 至少30GB 空闲(模型+镜像占地方) | 此电脑 |
| 显卡 | 没有也能跑,有 N 卡更好(6GB 显存很舒服) | 设备管理器 → 显示适配器 |
关于速度,给你个心理预期
| 你的配置 | 大概多快 | 体验 |
|---|---|---|
| 有 6GB+ 显存的 N 卡 | 每秒 20+ 字 | 流畅,跟聊天一样 |
| 只有 16GB 内存、没独显 | 每秒 5-10 字 | 能用,等几秒 |
| 只有 8GB 内存 | 每秒 2-3 字 | 很慢,但能跑通 |
第一次回答会慢一些(模型要从硬盘加载到内存),之后就快了。
第一步:装 Docker
Docker 可以理解成"一个能一键启动整套软件的工具"。WeKnora 由 5 个程序组成,靠 Docker 一次性全起来。
Windows
- 打开 https://www.docker.com/products/docker-desktop/ 下载 Docker Desktop
- 双击安装,一路下一步
- 安装过程中如果提示开启 WSL2,选"是"(这是 Windows 跑 Docker 必需的)
- 装完重启电脑
- 重启后 Docker Desktop 会自动启动,任务栏出现小鲸鱼图标,等它变成"Running"
验证一下。打开PowerShell(开始菜单搜"PowerShell"):
docker--version# ✅ 看到 Docker version 29.x.x 就对了docker compose version# ✅ 看到 Docker Compose version v5.x.x 就对了⚠️如果报错说命令不存在:Docker Desktop 没启动完。打开它,等小鲸鱼不转圈了再试。
macOS
去官网下载.dmg,拖进 Applications,打开它,等顶部菜单栏鲸鱼图标变稳定。然后在「终端」里跑上面两条命令验证。
国内用户必看:配置镜像加速
Docker 默认从国外下载,国内很可能连不上。一定要先配镜像源,否则第二步就会卡死。
打开 Docker Desktop → 右上角齿轮(Settings)→Docker Engine,看到一个大文本框,改成这样:
{"builder":{"gc":{"defaultKeepStorage":"20GB","enabled":true}},"experimental":false,"features":{"buildkit":true},"registry-mirrors":["https://docker.xuanyuan.me","https://docker.1ms.run","https://docker.m.daocloud.io"]}点Apply & Restart,等它重启完。
📌以上三个镜像源 2026-08-31 实测可用。镜像源失效很快,如果哪天连不上了,去搜"Docker 镜像加速器 2026"找新的,别死磕。
特别提醒:中科大、清华、网易的镜像源已经停止服务了,网上很多老教程还在推荐,别用了。
第二步:装 Ollama 并下载模型
安装
Windows(PowerShell 里执行):
winget install Ollama.Ollama装完重启一下终端,验证:
ollama--version# ✅ 看到 ollama version 0.x.x 就对了如果你没有 winget,或者上面命令失败:去 https://ollama.com/download 下载 Windows 安装包,双击安装。
macOS:去 https://ollama.com/download 下载,或用brew install ollama。
下载两个模型
模型一:负责"说话"的(对话模型)
ollama pull qwen2.5:7b这是阿里的通义千问,中文能力不错,约 4.7GB,下载时间看网速。
💾电脑比较弱?换成小一点的
ollama pull qwen2.5:3b(约 2GB),能跑但没那么聪明。
模型二:负责"理解中文"的(向量模型)
ollama pull dztech/bge-large-zh:v1.5这个只有 190MB,专门用来把中文转成数字。别看它小,少了它整个系统跑不起来。
下载完检查一下:
ollama list# ✅ 应该能看到这两个:# qwen2.5:7b# dztech/bge-large-zh:v1.5⚠️ 一个必须做的设置(否则后面连不上)
Ollama 默认只让自己本机的程序访问,Docker 容器访问不到它。必须改成允许:
Windows:
- 右键「此电脑」→ 属性 → 高级系统设置 → 环境变量
- 在「系统变量」点「新建」
- 变量名填
OLLAMA_HOST,变量值填0.0.0.0:11434 - 一路确定
- 完全退出 Ollama 再重开(右下角托盘找到 Ollama 图标,右键 Quit,然后重新打开)
验证:
netstat-ano|findstr 11434# ✅ 必须看到 "0.0.0.0:11434 LISTENING"# ❌ 如果只看到 "127.0.0.1:11434",说明上面没配好,回去重做macOS / Linux:
launchctl setenv OLLAMA_HOST"0.0.0.0:11434"# macOS# 然后退出 Ollama 应用重新打开这一步很多人卡住。如果你的 WeKnora 后面提示"连不上模型",十有八九是这里。
第三步:下载 WeKnora
打开终端(Windows 用 PowerShell),挑一个你喜欢的目录:
gitclone https://github.com/Tencent/WeKnora.gitcdWeKnora没有 git?去 https://github.com/Tencent/WeKnora 点绿色 “Code” 按钮 → “Download ZIP”,解压后进入解压出来的文件夹。
然后复制一份配置文件:
cp.env.example .env# macOS / Linuxcopy .env.example .env# Windows CMD💡
.env就是所有设置的集中地。WeKnora 给了个模板.env.example,我们复制一份出来改,原模板留着做备份。
第四步:告诉 WeKnora 用你的模型(最容易卡的一步)
先说清楚一个反直觉的设计
你可能会想:打开.env,找到模型那几行,填上名字,完事。
不是的。这是 WeKnora 最容易让人懵的地方:
┌──────────────────────────┐ ┌────────────────────────────┐ │ .env │ │ config/builtin_models.yaml │ │ (只提供"变量值") │ │ (真正的模型清单) │ │ │ │ │ │ LLM_MODEL_NAME= │ ${ENV}│ name: ${LLM_MODEL_NAME} │ │ qwen2.5:7b │ ────> │ base_url: ${LLM_BASE_URL} │ │ LLM_BASE_URL=... │ 占位符│ dimension: 1024 ← 手写! │ └──────────────────────────┘ 替换 └────────────────────────────┘ │ │ 启动时写入 ▼ 界面上看到的模型列表两个文件都要改,少一个就不生效。下面一步一步来。
4.1 改.env
用记事本(或 VS Code)打开WeKnora文件夹里的.env,搜索D2.或者直接跳到约 351 行,找到这一段:
# 内置对话模型# LLM_MODEL_NAME=# LLM_BASE_URL=# LLM_API_KEY=# LLM_PROVIDER=openai## 内置向量模型# EMBEDDING_MODEL_NAME=# EMBEDDING_BASE_URL=# EMBEDDING_API_KEY=# EMBEDDING_PROVIDER=openai把注释符号#去掉,并填上值,改成这样:
# 内置对话模型LLM_MODEL_NAME=qwen2.5:7bLLM_BASE_URL=http://host.docker.internal:11434/v1LLM_API_KEY=ollamaLLM_PROVIDER=openai# 内置向量模型EMBEDDING_MODEL_NAME=dztech/bge-large-zh:v1.5EMBEDDING_BASE_URL=http://host.docker.internal:11434/v1EMBEDDING_API_KEY=ollamaEMBEDDING_PROVIDER=openai逐行解释一下(不想看可以跳过):
| 行 | 值 | 为什么 |
|---|---|---|
LLM_MODEL_NAME | qwen2.5:7b | 跟你ollama list里看到的名字必须一字不差 |
LLM_BASE_URL | ...11434/v1 | host.docker.internal是固定写法,意思是"宿主机(你电脑)"。写localhost或127.0.0.1会失败,因为那指的是容器自己 |
LLM_API_KEY | ollama | Ollama 不校验密钥,随便填一个非空值即可 |
LLM_PROVIDER | openai | Ollama 兼容 OpenAI 的接口格式,所以选这个 |
4.2 新建config/builtin_models.yaml
在WeKnora/config/文件夹里,新建一个文件叫builtin_models.yaml,内容如下(可以直接复制):
builtin_models:# 对话模型:负责组织语言回答问题-id:builtin-llm-qwen25-7btype:KnowledgeQA# KnowledgeQA = 对话模型source:remoteis_default:true# 设为默认,建知识库时不用手动选name:${LLM_MODEL_NAME}# 这里会自动读 .env 里填的值parameters:base_url:${LLM_BASE_URL}api_key:${LLM_API_KEY}provider:${LLM_PROVIDER}# 向量模型:负责把中文转成数字-id:builtin-embedding-bge-large-zhtype:Embedding# Embedding = 向量模型source:remoteis_default:truename:${EMBEDDING_MODEL_NAME}parameters:base_url:${EMBEDDING_BASE_URL}api_key:${EMBEDDING_API_KEY}provider:${EMBEDDING_PROVIDER}embedding_parameters:dimension:1024# ⚠️ 见下方说明truncate_prompt_tokens:0⚠️
dimension: 1024这个数字不能瞎填它必须等于你的向量模型实际输出的维度。填错了不会报错,但检索结果会莫名其妙地不准——这是最阴险的坑。
模型 dimension 填多少 来源 dztech/bge-large-zh:v1.51024 本文实测 nomic-embed-text768 本文实测 其他模型 ? 别猜,用下面的命令实测 一条命令查出维度。Windows PowerShell 里执行(把模型名换成你的):
$body= @{model ="dztech/bge-large-zh:v1.5";input ="测试"}|ConvertTo-Json(Invoke-RestMethod-Uri"http://localhost:11434/v1/embeddings"`-Method Post-Body$body-ContentType"application/json").data[0].embedding.Count✅ 直接输出一个数字,比如
1024——填进 YAML 就行。macOS / Linux 用 curl:
curl-shttp://localhost:11434/v1/embeddings\-H"Content-Type: application/json"\-d'{"model":"dztech/bge-large-zh:v1.5","input":"测试"}'\|python3-c"import sys,json; print(len(json.load(sys.stdin)['data'][0]['embedding']))"⚠️PowerShell 用户注意:PowerShell 里的
curl其实是Invoke-WebRequest的别名,
参数跟真正的 curl 不一样,网上很多教程照抄会报错。上面用的是 PowerShell 原生写法,可以直接跑。
想用真 curl 的话,把命令写成curl.exe ...。
4.3 启用这个配置文件(最容易忘的一步!)
打开docker-compose.yml,找到app服务的volumes部分(约第 39-48 行),把最后那行的#去掉:
services:app:volumes:-data-files:/data/files-docreader-tmp:/tmp/docreader:ro-./config/config.yaml:/app/config/config.yaml-./skills/preloaded:/app/skills/preloaded# Optional: declarative built-in models...-./config/builtin_models.yaml:/app/config/builtin_models.yaml:ro# ← 把这行开头的 # 删掉忘了这步的后果:
builtin_models.yaml根本进不了容器,界面上一个模型都看不到。
我第一次就栽在这,查了十分钟。
第五步:启动!
回到终端(确保你在WeKnora目录下):
dockercompose up-d--no-build参数解释:
up= 启动-d= 后台运行(关掉终端也不会停)--no-build=直接用现成的镜像,不要自己编译。这个很重要——不加的话它会尝试本地编译(含 Rust 组件),几十分钟还可能失败
第一次会下载镜像,大概几个 GB,耐心等。看到 5 个Started或Running就成了。
检查状态:
dockerps# ✅ 应该看到 5 个 WeKnora- 开头的容器,STATUS 都是 Up看看有没有报错:
dockerlogs WeKnora-app# ✅ 重点看有没有这两行(说明模型注册成功了):# [builtin-models] upserted: id=builtin-llm-qwen25-7b name=qwen2.5:7b type=KnowledgeQA# [builtin-models] upserted: id=builtin-embedding-bge-large-zh name=... type=Embedding🎉打开浏览器,访问 http://localhost
打不开?如果提示端口被占用(比如你装过其他东西占了 80 端口),打开
.env把FRONTEND_PORT=80改成FRONTEND_PORT=8081,然后重新docker compose up -d,访问 http://localhost:8081注意:只改
FRONTEND_PORT,APP_PORT保持 8080 不要动。
第六步:开始用
6.1 注册账号
第一次打开会让你注册。第一个注册的账号自动成为管理员,随便填邮箱密码就行(存在你本地,不会发到任何地方)。
6.2 确认模型已经就位
进「模型管理」,应该能看到两个模型:
| 名称 | 类型 | 状态 |
|---|---|---|
qwen2.5:7b | 对话 | 默认 ✓ |
dztech/bge-large-zh:v1.5 | 向量 | 默认 ✓ |
如果一个都没有:回到 4.3 检查挂载那行有没有取消注释,然后
docker compose restart app,再看docker logs WeKnora-app。
6.3 建知识库
点「新建知识库」,填:
- 名称:随便起,比如"我的工作手册"
- 对话模型:选
qwen2.5:7b - 向量模型:选
dztech/bge-large-zh:v1.5 - 重排模型:可以不选(选了更好,但要再下载一个模型)
其他保持默认,保存。
6.4 上传文档
点进知识库,把你的 PDF / Word / 文本文件拖进去。
支持的格式:PDF、Word(.docx)、Markdown、TXT、图片(会 OCR 识别文字)
上传后会看到状态从「待处理」→「处理中」→「已完成」。第一次会慢一点,因为要下载文档解析组件。
💡建议:第一次先传一个小文件(比如一个 2 页的 TXT)试试水,跑通了再传大的。
6.5 提问
处理完成后,直接在对话框里问:
这份文档讲了什么? XX 政策是哪一年发布的? 帮我总结一下第三章的要点关键体验:回答下面会列出"参考来源",点开能看到它引用了哪一段原文。这就是 RAG 的价值——可追溯。
6.6 几个实用技巧
| 想做的事 | 怎么做 |
|---|---|
| 让它更严谨 | 提问时加"请只根据文档内容回答,不确定的地方说不知道" |
| 答案不准 | 试试问得更具体,或者直接引用文档里的关键词 |
| 想换模型 | 「模型管理」里加新模型,然后在知识库设置里切换 |
| 文档更新了 | 重新上传,或者删掉旧的再传 |
| 想清空重来 | 删掉知识库重建(向量数据会一起清掉) |
常见报错对照表
出问题先查这张表,90% 能解决:
| 报错 / 现象 | 原因 | 怎么解 |
|---|---|---|
docker: command not found | Docker 没启动或没装好 | 打开 Docker Desktop,等小鲸鱼稳定 |
| 镜像下载卡住不动 | 没配镜像源 | 回到第一步配registry-mirrors |
ports are not available | 端口被别的程序占了 | 改FRONTEND_PORT(如 8081);若提示 8080 被占,原样再跑一次就好,那是 Docker 的假警报 |
| 界面上没有任何模型 | 三处配置缺一 | 检查 4.1 / 4.2 /4.3(最容易漏) |
| 上传文档一直"处理中" | 解析组件在下载 | 等第一次的几分钟;或看docker logs WeKnora-docreader |
| 提问报错"模型连接失败" | Ollama 没监听 0.0.0.0 | 回到第二步检查OLLAMA_HOST和netstat |
| 能提问但答案很离谱 | dimension 填错了 | 检查builtin_models.yaml的dimension |
| 容器启动后马上退出 | 内存不够 | 关掉其他程序;或换qwen2.5:3b小模型 |
| 重启电脑后网页打不开 | Docker 和 Ollama 都没启动 | 按顺序启动,见下方坑六 |
ollama list变成空的 | Ollama 正在自动升级 | 等升级完再看一次,多半自己回来;见下方坑七 |
| 想彻底重来 | — | docker compose down -v然后重新up -d(会清空所有数据) |
小白最容易踩的坑,一个一个说
上面那张表是"速查",这里挑最坑人的几个展开讲清楚:它长什么样、为什么会这样、具体怎么救。
每个都是我(或我帮忙排查的读者)真实踩过的,不是编的。
坑一:改了.env和 yaml,界面上还是没有模型
现象:docker ps五个容器都正常跑着,打开 http://localhost 也能登录,但「模型管理」里空空如也,建知识库时没模型可选。
原因:WeKnora 的模型声明要过三道关——.env填变量、builtin_models.yaml建清单、docker-compose.yml挂载这行文件进容器。三处少一处,模型都进不来。而挂载那行默认是注释掉的,官方模板里没有任何提示。
解决:
- 确认 4.1(
.env注释去掉了)、4.2(yaml 文件建了)、4.3(docker-compose.yml那行#删了)三处都做了 - 改完必须重启让配置生效:
dockercompose restart app- 看日志确认模型注册成功(有两行
upserted就对了):
dockerlogs WeKnora-app|findstr upserted我第一次就漏了 4.3,来回查了十分钟。如果你只记一件事,就记这个坑。
想深入了解 WeKnora 为什么设计成"
.env只管变量、模型声明要单独写 YAML"这种反直觉结构,以及我是怎么从源码里揪出这个设计的,可以看我的排坑实录:《0B/s 卡了 40 分钟,我扒开 OCI manifest 揪出了 Docker pull 的真凶》(里面坑一有详细拆解)。
坑二:提问时报"模型连接失败"(Ollama 那个环境变量)
现象:知识库建好了,文档也传了,一提问就报错,提示连不上模型。
原因:Ollama 默认只监听127.0.0.1(只有本机程序能访问)。而 WeKnora 跑在 Docker 容器里,对容器来说"127.0.0.1"是容器自己,不是你的电脑——所以它根本够不着 Ollama。
解决:回到第二步,设置系统环境变量OLLAMA_HOST=0.0.0.0:11434,完全退出 Ollama 再重开(托盘图标右键 Quit,不是关窗口)。然后验证:
netstat-ano|findstr 11434# ✅ 必须是 0.0.0.0:11434 LISTENING# ❌ 如果是 127.0.0.1:11434,说明变量没生效(重启电脑试试)这个坑的本质是"容器网络和宿主机网络是隔离的",理解了这一点就不会再写错地址。我的排坑实录里有更详细的容器网络原理讲解,以及怎么用
docker exec从容器内部验证连通性的方法,感兴趣可以去看。
坑三:dimension 填错——最阴险的坑,不报错但答案全是错的
现象:系统能跑、能提问、有回答,但答案驴唇不对马嘴,引用的段落跟问题毫无关系。
原因:builtin_models.yaml里的dimension填的数字和向量模型实际输出的维度不一致。这个错没有任何报错提示,数据照常写入,只是检索的时候"对不上暗号",找回来的全是错误段落。
解决:用 4.2 里那条 PowerShell 命令实测维度,把查出来的数字原样填进去。记住:换向量模型必查维度,bge-large-zh 是 1024,nomic-embed-text 是 768,换模型不换数字必踩这坑。
坑四:PowerShell 里的curl是假的
现象:从网上抄了一条curl -H ... -d ...命令到 PowerShell,报一堆奇怪的参数错误。
原因:PowerShell 里curl是Invoke-WebRequest的别名,参数格式和真正的 curl 完全不同。网上教程(macOS/Linux 居多)默认你是真 curl。
解决:要么用 PowerShell 原生写法(本文 4.2 的Invoke-RestMethod版本,可直接跑),要么把命令写成curl.exe ...——加.exe强制调用真 curl。
坑五:镜像下载卡在 0B/s 不动
现象:docker compose up时进度条显示Pulling fs layer,但字节数一直是 0,等半小时都不动。
原因:这不一定是网络问题。有一种情况是 Docker 按标签(tag)拉取时会卡在镜像清单里的一个"证明文件"(attestation manifest)上,国内网络环境下经常卡死。
解决:先按第一步配好镜像源重试;还不行的话,有一个更硬核的办法是绕过 tag、直接按镜像的 digest 编号拉取。这个操作步骤较多,我写在另一篇排坑实录里了:《0B/s 卡了 40 分钟,我扒开 OCI manifest 揪出了 Docker pull 的真凶》。
坑六:重启电脑后,一切"全没了"
现象:昨天明明跑得好好的,今天开机打开 http://localhost,浏览器直接拒绝连接;或者 WeKnora 界面能打开,但提问报错。
原因:这不是数据丢了。Docker 和 Ollama 都是普通程序,关机后自然就停了。你的知识库、文档、向量数据都在硬盘上,完好无损。
解决:每次开机后按这个顺序启动(顺序很重要):
1. 启动 Docker Desktop(等小鲸鱼图标稳定) 2. 启动 Ollama(开始菜单搜 Ollama 打开) 3. 到 WeKnora 目录执行: docker compose start 4. 再打开 http://localhost💡 顺手一提:
docker compose stop停掉的容器,下次用docker compose start就能原样恢复,不用重新up。
坑七:Ollama 自动升级时,模型"集体失踪"(我今天就踩了)
现象:用得好好的,某天打开发现提问报 404 “model not found”,跑ollama list一看——空的,模型全没了。
原因:Ollama 有自动升级机制。升级过程中,新版程序还没把模型目录挂回来,这期间ollama list会显示为空,调用也报"model not found"。看起来像数据全丢,实际是暂时的(我 2026-08-31 实测:0.32.4 启动时自动升级到 0.33.2,中途ollama list为空、调接口 404,升级彻底完成后模型原样回来了,一个都没丢)。
解决:先别慌着重下,等两三分钟让升级跑完,再ollama list看一次。真丢了的话再重新下载:
ollama pull qwen2.5:7b ollama pull dztech/bge-large-zh:v1.5两个额外提醒:
- 升级期间 WeKnora 的提问会报错,不用动 WeKnora 任何配置,模型回来后自动恢复
- 想彻底躲开这个坑,可以关掉自动升级(Ollama 设置里
auto-update关掉),手动控制在方便的时间升级
坑八:8080 端口"被占用"——多半是假警报
现象:docker compose up报错说 8080 端口不可用,但你明明没装过占 8080 的东西。
原因:Docker Desktop 自己的端口转发进程有时会短暂占住这个口,报"冲突"其实是它自己跟自己打起来。
解决:原样再执行一次docker compose up -d,第二次往往就过了。真被占的话再改.env里的端口。
这个"假警报"在我的排坑实录里也提到了,当时我还误以为是 Dify 的 nginx 占了端口,后来用
netstat查 PID 才发现是 Docker 自己的端口代理进程在重整状态。想了解完整排查过程的可以去看那篇。
日常运维
# 停止(数据保留)dockercompose stop# 启动dockercompose start# 重启某个服务(改完配置后)dockercompose restart app# 看实时日志dockercompose logs-fapp# 升级到新版本dockercompose pulldockercompose up-d# 彻底删除(连数据一起,慎用!)dockercompose down-v下一步可以玩什么
跑通之后,你可以:
- 换更强的模型:
ollama pull qwen2.5:14b(需要更多内存),在界面里加进去 - 加一个重排模型(Rerank):在知识库设置里配上,能让检索结果排序更准。
模型名去 https://ollama.com/search 搜rerank找当前可用的(这类模型更新快,
别直接抄文章里的名字——等你看到这篇的时候可能已经换了)。装法一样是ollama pull <名字>,
然后在「模型管理」里新增一个Rerank类型的模型 - 用 ReACT Agent 模式:让 AI 自己拆解复杂任务、多轮检索
- 接网络搜索:在设置里配 DuckDuckGo,让它在本地文档找不到时上网查
- 用 API 集成:WeKnora 有完整的 REST API,可以接到你自己的程序里
写在最后
这套东西最让我满意的一点,不是技术多先进,而是:你的文档从头到尾没离开过你的电脑。
对个人的工作笔记、学习资料来说,这比"更好用的在线 AI"重要得多。而且它是真的免费——不花钱、不注册第三方服务、断网也能用。
整个搭建过程顺利的话 30 分钟,卡在某个坑上可能一整天。所以上面「小白最容易踩的坑」那一章,建议装完先通读一遍再动手——尤其是坑一(挂载注释)、坑二(OLLAMA_HOST)和坑六(重启后的启动顺序),这三个坑躲过去,至少省你半天。
⚠️时效提醒:本文实测环境为 WeKnora0.7.2、Ollama0.32.4 → 0.33.2(当天踩到了自动升级时模型暂时消失,见坑七)、Docker29.3.1(2026-08-31)。
镜像源地址、配置项名称、模型名称都会随时间变化,动手前请以官方最新文档为准:
- WeKnora 仓库:https://github.com/Tencent/WeKnora
- Ollama 官网:https://ollama.com
如果你卡在 Docker 镜像下载这一步(比如一直显示
Pulling fs layer但字节数不动),
那是个比较深的问题,可以看我的排坑实录:《0B/s 卡了 40 分钟,我扒开 OCI manifest 揪出了 Docker pull 的真凶》