WeKnora本地知识库部署实战：从硬件配置到Ollama接入全记录

1. 先算清楚三笔账：为什么知识库要放本地、凭什么敢放本地

1.1 知识库问答的本质：不是让模型更聪明，是让它能翻到对的那页书

我最早接触 WeKnora 这个项目，是在同事群里看到有人转 GitHub 链接，标题带"微信团队开源"几个字。当时手头正好在做一个内部文档问答的需求，前端聊天界面好做，难的是让大模型真正读懂几十份产品手册、运维规范和接口文档。说实话，市面上的知识库方案不少，但很多项目的问题不在功能少，而在链路长：从文档解析、切片、向量化、召回、重排到生成，每一环都有插件化的选择，配置起来像拼乐高，拼完才发现缝隙处处漏水。

WeKnora 吸引我的点，是它把这条链路收敛得比较完整。文档解析、切片策略、向量召回、引用溯源、对话管理、本地模型接入都做了，而且前后端是分开的，后端 FastAPI，前端 React，工程结构够清晰。更关键的是，它支持完全本地化部署，模型和知识库数据都在自己机器上跑，不用担心文档内容被第三方 API 拿去做了训练语料。对内部知识管理场景来说，数据不出内网这件事，有时候比模型效果还重要。

在开始部署前，我给自己列了三笔账：数据账、模型账、依赖账。数据账是要把自己有多少文档、什么格式、大概多大体量理清楚；模型账是决定用纯本地模型还是本地模型加 API 混合；依赖账则是确认部署环境里已有的 Python、Node、Docker 版本能不能直接开工。这三笔账算清楚，后面装起来就是顺着流程走一遍的问题，而不是走一步查一步的马拉松。

1.2 WeKnora 和 Dify、RAGFlow 的定位差异，我不建议盲目照搬对比结论

聊本地方案，绕不开 Dify 和 RAGFlow。Dify 最出名的是"工作流编排+一揽子 AI 应用"，它本质是个 AI 应用平台，知识库只是其中一个模块，适合要搭 ChatBot、Agent、多轮对话工作流的团队；RAGFlow 则主打"深度文档理解"，在复杂 PDF 解析上做得很重，尤其是版面分析和表格抽取。

WeKnora 的定位更纯粹：它就是知识库问答。没有那么多工作流节点，也没有复杂的 Agent 编排，它的核心链路就一条——文档进来，切碎，向量化，用户提问时召回相关片段，带着上下文送给大模型生成答案，最后把引用的原文位置标出来。对于"我就想把文档变成能回答问题的智能助手"这种需求，这种专注反而省心。不需要在画布上拖节点，不需要理解一大堆编排概念，界面里就是知识库、文档、问答会话三个核心模块。

我不建议看到社区里"Dify 完胜""RAGFlow 更强"之类的帖子就轻易站队。这类项目迭代速度快，不同版本的特性差异很大，而且"更好"要看你最痛的点是什么。如果你对文档版面解析要求极高，RAGFlow 值得评估；如果你要同时接多个人工智能应用，Dify 的工作流确实方便。但如果你和我一样，要的就是一套能自己控制、能离线运、能快速接入本地模型的知识库问答系统，WeKnora 的轻量专注就是实实在在的优势。

2. 部署前的硬条件：硬件清单、系统环境和小白最容易绕远的一个误区

2.1 硬件预算怎么切：推理、向量化和检索是三个不同的消耗点

本地部署大语言模型和知识库之后，机器的压力主要来自三块：大模型推理、向量化计算、检索与后端服务。很多人以为只要显卡够好就行，实际跑起来会发现，内存和磁盘 IO 同样能卡住整个系统。

我拿自己这台机器举例：CPU 是十代 i7，显卡是 RTX 3060 12GB，内存 32GB，系统 Ubuntu 22.04。这个配置跑 WeKnora 后端加 7B 级别的模型微调过的量化版本，日常两三个并发问题，响应速度勉强够用。如果换成纯 CPU 推理，7B 模型量化后大概要 8GB 到 10GB 内存，生成速度会明显慢，但也可用；如果是 13B 甚至更大模型，建议单卡显存至少 16GB，或者直接用 CPU 加大量内存跑量化版本，否则长时间运行会有明显卡顿。

我把不同配置的参考建议列一下，方便你对照自己机器估算：

除了显存和内存，磁盘空间也要留够。模型文件动辄 4GB 到 10GB，向量库和文档解析的临时文件也会积累，建议至少留 50GB 可用空间，并且把数据目录放在 SSD 上。第一次做全量向量化的时候，SSD 和机械硬盘的差距能拉开两到三倍时间。

2.2 基础依赖版本：Python、Node.js、Docker 的坑位确认

WeKnora 后端基于 FastAPI，前端是 React 构建。部署前最该确认的是 Python 版本和 Node 版本。我在部署时踩过一个典型问题：系统自带的 Python 是 3.8，某些依赖的轮子在新版本里才能编译通过，最后切到 Python 3.10 才顺利装完。如果你是源码部署，建议直接准备 Python 3.10+，Node.js 18+。

Docker 部署的话，需要确认 Docker Compose 是 v2 版本，因为 v1 的docker-compose命令和 v2 的docker compose在解析部分语法时有差异，直接照搬网上的命令会报错。另外建议提前把镜像源配置成国内可访问的镜像源，否则拉取基础镜像时可能长时间卡住。这一步不需要什么高深技巧，但是真的能省掉大量等待时间。

2.3 一个常见的部署误区：不要一上来就直接 npm run build

很多人在源码部署时，习惯性地在前端目录里执行npm install && npm run build，然后等着看输出。但 WeKnora 前端构建之前，需要先拿到后端的 API 地址和必要的环境变量。如果后端还没起来、配置里的接口指向不对，前端构建既不会报错也不会正常连接，等你打开页面发现所有请求都超时，回头排查会多花很多时间。

我的建议是，源码部署严格按顺序走：先把纯后端的依赖和启动打通，验证 API 健康检查；再把前端跑起来配合测试。Docker Compose 部署则可以省掉这一步，因为编排文件里已经帮你把网络依赖和服务启动顺序处理好了。如果你第一次尝试，对项目结构不熟，我推荐先用 Docker 路线把系统整体跑起来，再深入研究源码和二次开发细节。

3. 两条安装路线的完整记录：源码编译和容器编排分别怎么落地

3.1 源码路线：后端依赖、前端构建和本地启动的完整步骤

源码部署适合想二次开发或者需要在特定环境里定制化配置的人。整体耗时主要在网络下载依赖和前端构建上，一次顺利的话半小时内部署完成。

先把项目克隆到本地：

git clone https://github.com/we-knora/weknora.git cd weknora

后端部分，先创建虚拟环境，激活后安装依赖：

python3 -m venv venv source venv/bin/activate pip install -r backend/requirements.txt

依赖装完后，需要准备配置文件。仓库里一般有.env.example之类的模板，我习惯的做法是复制一份出来，改成.env，然后逐一核对里面的配置项：数据库连接、Redis 地址、向量存储路径、模型接口地址。千万不要图省事直接跳过这一步，因为默认配置里很多路径是基于仓库作者的开发环境写的，直接跑起来大概率会报连接错误。

启动后端的命令是：

uvicorn main:app --host 0.0.0.0 --port 8000

如果你看到健康检查接口返回正常，说明后端已经起来了。这里有一个容易忽略的细节：默认端口可能是 8000 也可能写在配置里，具体以上下文环境变量为准，不要凭记忆猜。

前端构建前，先确认frontend目录里的 API 地址配置指向正确的后端地址。然后执行：

cd frontend npm install npm run build

构建完产物在dist目录，通过 Nginx 或者项目自带的静态服务器托管都行。我在实际部署里直接用 Nginx 把静态文件指过去，同时把/api路径反向代理到本机的 8000 端口，省去跨域配置的麻烦。

3.2 Docker 路线：一套编排文件省掉八成环境问题

如果不想折腾 Python 虚拟环境和 Node 构建，Docker Compose 是最省心的路径。这套方式把数据库、缓存、后端、前端容器一次性编排起来，最明显的优势是环境一致性——你在自己机器上跑通的样子，复制到服务器上部署，基本不会因为系统库版本差异出现玄学报错。

使用方式很简单：

docker compose up -d

首次启动会拉镜像、初始化数据库、构建服务。看到所有容器状态是running，然后访问前端映射的端口。这个过程中我遇到过两次典型问题，都值得记下来：

第一次是端口冲突。本机 8000 和 80 端口被其他服务占用导致容器启动失败。排查方式很直接，看docker compose ps的输出和日志就能定位。第二次是容器内时区和宿主机不一致，导致文档创建时间和日志时间差八个小时。这个不影响核心功能，但排查问题看日志时会带来困惑，建议在编排文件里挂载/etc/localtime并设置TZ=Asia/Shanghai之类的时区环境变量。

3.3 部署完成后第一件事：验证健康检查，不要急着传文档

无论哪条路线，部署完成后我都建议先做三件事，再开始导入知识库。第一步，确认后端健康检查返回正常，这代表服务进程活着。第二步，确认前端页面能打开，并且登录或初始化管理员账号能完成。第三步，在系统设置里确认向量库的存储路径可写，模型接口能连通。

很多人忽略第三步直接传文档，结果传了几十份之后才发现向量化任务全部失败，再回头看日志，发现是存储路径没有权限。这种坑一旦批量导入之后再来排查，定位成本高很多。顺序反过来做，每步确认再往前走，整个部署过程是平滑的。

4. 接入 Ollama 本地大模型：让生成问答真正离线运转

4.1 为什么我坚持用 Ollama 而不是一把梭接云端 API

WeKnora 本身支持多种模型接入方式，Ollama 是我当时第一选择，原因很实际：它把模型下载、量化、启动服务、接口兼容这些环节都简化了，而且对离线环境非常友好。你只需要在装了 Ollama 的机器上把模型拉下来，它就跑出一个本地兼容 OpenAI 接口的服务，WeKnora 后端只需要把模型接口地址指过去就能用。

有人会说，既然 WeKnora 支持 OpenAI 兼容接口，为什么不直接接云端 API？这里要分场景。如果只是自己试用，云端 API 确实更省事，效果通常也更好。但如果你的文档里有未公开的接口规范、内部运维流程、商务方案这些敏感信息，送出去之后你完全无法控制数据去向。本地部署的核心诉求就是让文档和问答过程留在内网。搭配 Ollama，整套链路从模型到数据全部在可控边界内，这是云端 API 给不了的确定性。

4.2 Ollama 服务安装、模型拉取和自定义模型文件

Ollama 安装方式很开放，Linux 上用官方安装脚本或者直接下载二进制都行。装好之后先确认服务状态：

ollama serve

然后拉取模型。

我当时的模型选择逻辑很简单：推理速度优先，参数规模适中，中文效果不能太差。最终选了 qwen 系列的 7B 量化版本。拉取命令大概是：

ollama pull qwen2.5:7b-instruct-q4_K_M

拉下来之后，可以用命令行直接验证：

ollama run qwen2.5:7b-instruct-q4_K_M "你好，请简要介绍你自己"

如果这一步能正常回复，说明 Ollama 侧已经通了。

这里有个进阶配置值得提一下：通过 Modelfile 做自定义模型。比如你想让模型在知识库问答时更收敛，不随意发挥，可以在 Modelfile 里写系统提示词，设置温度参数和上下文长度，然后创建一个自定义模型：

FROM qwen2.5:7b-instruct-q4_K_M SYSTEM "你是一个严谨的知识库助手，回答时优先依据提供的上下文，不要编造事实。" PARAMETER temperature 0.3 PARAMETER num_ctx 8192

保存后执行：

ollama create my-rag-assistant -f ./Modelfile

这样在 WeKnora 配置模型服务时，可以指定my-rag-assistant作为生成模型，让问答行为的稳定性更好。我试过直接用原版模型，同样的知识库问题，原版偶尔会多了些额外展开，自定义提示词版本明显更贴合"只回答文档相关内容"的预期。

4.3 WeKnora 与 Ollama 的对接配置：模型服务地址和模型名不要填反

在 WeKnora 的管理界面里配置模型服务时，通常分两步：先添加模型服务，填服务地址，比如http://127.0.0.1:11434；再在具体的问答应用里选择要用哪个模型。这里的坑在于，很多人的 Ollama 服务跑在 Docker 容器里，而 WeKnora 跑在宿主机上，两边网络是隔离的。如果你用 Docker 部署 Ollama，需要把端口映射出来，让 WeKnora 能通过宿主机的映射端口访问。如果 WeKnora 也在容器里，要小心不能写127.0.0.1，而要用宿主机在容器网络里的地址或者编排服务名。

模型名也容易填错。Ollama 拉取的模型带 tag，比如qwen2.5:7b-instruct-q4_K_M，在 WeKnora 里填模型名时要完整带上 tag，只填qwen2.5会提示模型不存在，这个报错信息有时候不直观，需要看后端日志才能定位。建议记一个容易混淆的点：模型服务地址是 Ollama 的地址，填入的是接口地址而不是模型名；模型服务名称和模型名是两个不同字段，可以用一个方便识别的名称，比如ollama-local，但实际的模型标识要对应到具体的模型 ID。

5. 文档导入、切片策略与检索召回：知识库核心链路的实测细节

5.1 创建知识库和导入第一批文档时，我建议从 PDF 和 Markdown 混合开始

知识库构建的第一步是创建知识库，然后批量导入文档。我第一次导入时直接扔了二十几个 PDF 进去，后来发现有些 PDF 是扫描件，纯图片没有文字层，解析出来几乎全是空内容，检索效果自然惨不忍睹。这里给一个实操建议：第一批测试文档别全用 PDF，混合放几个结构良好的 Markdown 文件、Word 文档和带文本层的 PDF，这样能快速摸清系统对不同格式的支持程度，而不是一上来就被坏数据干扰判断。

WeKnora 的文档解析环节会把原始文件转成可检索的文本内容，再进入切片处理。如果是纯文本类的 Markdown，解析干净利落；Word 文档基本靠内置转换能力，只要表格不过于复杂，效果都还行；扫描版 PDF 需要配合 OCR 能力，这一步会额外消耗资源。我在实际使用中的经验是，能转成 Markdown 的文档优先转成 Markdown，结构越清晰，后续切片和召回的效果越稳定。这不是 WeKnora 独有的偏好，而是几乎所有 RAG 系统的普遍规律。

5.2 切片策略：别默认用一套参数走天下

切片是决定检索效果的关键环节。很多人上来就用默认的固定长度切片，比如每 512 个字符切一块，重叠 50 个字符，结果文档里的小节标题和正文被切开，用户提问时召回的内容经常是半截话。

我用的策略很简单：优先按文档结构切片。WeKnora 在文档解析后能识别标题层级，切片时按标题边界切分，每个章节单独成为一个切片段落，再补充上下文信息。这样用户问到某个小标题下的内容时，召回的是完整的章节，而不是从上一章末尾硬切出来的一段残句。

对于结构不明显的文档，再退回固定长度切片，但长度我会调小一点，控制在 300 到 500 字之间，重叠部分保留 80 字左右。太长的切片会让向量表示的精度下降，太短则上下文丢失严重。你可以用同一个文档，试两套参数各召回一次，对比结果后再确定全库的策略。这个过程花不了十分钟，但直接影响问答质量。

5.3 向量化与召回链路：嵌入模型选型直接决定"能不能找对"

文档切片完成之后，要经过嵌入模型做向量化，把文本转成向量存进向量库。这一步的模型选型相当关键。我在首次部署时图省事，用了一个通用的小型嵌入模型，结果发现检索结果非常飘，问"服务器部署流程"，返回的片段却是介绍产品架构的段落。换成一个针对中文优化且向量维度更高的嵌入模型之后，召回质量立刻上了一个台阶。

嵌入模型的速度和效果是矛盾的。小模型向量化快，内存占用低，但对语义理解粗浅；大模型效果好，但全库文档重新向量化时要占用不少计算资源。我采用的折衷方式是：知识库测试阶段先用轻量嵌入模型跑通全流程，确认链路没问题后再切换高精度嵌入模型对整个知识库重新向量化。切换嵌入模型之后，一定要触发全库重新向量化，否则新旧向量混在同一个向量库里，检索时维度不一致或者语义空间不统一，结果会非常怪。

想要验证召回效果，最直接的方法是在知识库的检索测试界面里输入几个有代表性的问题，看返回的文本片段是不是真的对上了问题。比如你问"超时时间怎么配置"，如果召回的是具体配置章节而不是整个手册开头，说明切片和向量化配合得很好。这个步骤我每次调整参数后都会做一轮，建议你也养成习惯。

6. 跑起来之后遇到的高频坑：资源飙升、解析失败和检索返祖

6.1 内存持续走高：原因不在 WeKnora，而在模型常驻和向量化并发

部署完成前两周，我的机器出现了一个反复出现的问题：运行几天后内存占用逼近 95%，系统明显卡顿，最后只能重启容器。第一次排查时我怀疑是 WeKnora 后端有内存泄漏，看了几个小时的日志也没找到明显异常。后来发现问题出在一个容易被忽视的地方：Ollama 服务默认会把常用模型常驻内存，加上向量化任务并发执行，多个进程叠加占内存，机器 32GB 内存在高负载时确实吃力。

解决方式是做资源限制。我用 systemd 给 Ollama 配置了内存限制上限，同时把 WeKnora 的向量化并发数调低。具体操作上，在 Ollama 的服务环境变量里设置并发请求上限，避免同时多个向量化任务挤压内存。调整之后，系统内存稳定在 70% 以下，再也没有出现跑几天就卡死的情况。

6.2 文档导入失败：日志里最容易被忽略的"解析进程退出"提示

文档导入失败是使用中碰到最多的问题。有次我导入一份几百页的项目验收文档，状态栏一直显示"处理中"，过一会儿变成"失败"。第一次遇到时我习惯性去找后端日志，结果日志里只有一行简短的process exited unexpectedly，没有任何堆栈信息。这种提示很容易让人误判成代码 bug，其实多半是文档格式导致的解析进程异常退出。

我排查后确认，是那份文档里嵌入了大量宏和动态字段，转换器在解析时无法处理，进程直接崩溃。这种问题没有一键修复的办法，我的做法是把源文档先另存成标准 docx 或者 PDF，再做导入。如果 PDF 由工具生成且文字层正常，一般没问题；如果是超复杂的表格和文本框混排，就得考虑拆分成多个小文档，或者先转成 Markdown 再导入。数据准备阶段多花一点时间，比后面跟解析器较劲划算得多。

6.3 检索不准确：先别怀疑模型，按切片、嵌入、重排三个环节排查

检索不准确是知识库问答最让人头疼的问题。用户问"支付接口超时"，系统却召回"系统架构总览"的内容。遇到这种情况，我的排查顺序是固定的：先看切片是否把相关文字完整保留了，再看嵌入模型是否适合当前文档的语言和领域，最后才考虑是不是需要加重排环节。

切片没问题的判断标准是：在知识库里搜索一个精确短语，看它是否落在一个语义完整的片段里。如果片段边界就是截断的句子，那就说明切片参数要改。嵌入模型的判断方法是召回的片段虽然对得上，但相关度排序明显不合理，最相关的片段排在后面，这通常说明嵌入模型对领域术语的区分度不够。重排环节的做法是在检索拿到候选片段后，再用一个重排模型按和问题的匹配度重新打分排序。这一步会小幅增加响应耗时，但对答案质量的提升非常明显。

我还用一个土办法辅助排查：直接在前端检索测试里输入同一个问题的不同问法。比如"怎么配置超时时间"和"超时时间在哪里设置"，看召回的片段是否基本一致。如果两次识别到的片段差异过大，说明小问法对语义理解影响大，这时候优先考虑提升嵌入模型能力，而不是调切片参数。

7. 稳定跑起来之后的调参心得和日常维护清单

7.1 我最终落地的参数组合：温度、上下文长度、切片大小和并发数

整套系统稳定运行后，我沉淀了一套用得比较顺的参数组合，可以作为参考起点。生成模型用的自定义模型my-rag-assistant，温度 0.3，上下文长度 8192，切片长度按文档结构调整，固定长度兜底时用 400 字加 80 字重叠，向量化并发设置为 2，Ollama 服务做了内存限制。这套组合在我的机器上兼顾了响应速度、资源占用和答案质量。

需要说明的是，这些参数不是搬过去就能直接照用的。不同文档集、不同模型、不同量化方式都会影响最优参数。我把它们写出来，是给你一个经过验证的初始值，在这个基础上做单变量调整，比从零摸索省很多时间。调参时一次只动一个变量，改完跑一遍召回测试，记录结果再动下一个，避免多个参数同时调整导致无法定位到底哪个变好或者变坏。

7.2 知识库维护最重要的三个习惯：备份、增量导入、定期验证

部署完成只是开始，知识库的长期维护比部署更有挑战。我养成了三个习惯。第一个是定期备份，主要备份向量库数据、文档源文件和配置文件。向量库重建成本最高，重新导入再向量化的时间能到几个小时，备份好数据目录就可以避免这种灾难性操作。

第二个是文档增量导入要讲究顺序。新文档导入前，先做格式检查，尽量统一成标准格式再进入知识库。如果新文档和旧文档在内容上有逻辑关联，比如补充了操作说明里的新版本，可以把它和旧文档放在同一个知识库里对比验证，确保召回结果不会因为内容覆盖出现混乱。

第三个是定期做问答效果回归测试。我会维护一个包含十几个典型问题的测试列表，每个月跑一遍，记录答案是否有明显变化。因为更新模型、调整切片参数或导入大量新文档后，检索结果可能悄悄变差，定期测试能及时发现问题，而不是等用户投诉了才去排查。

7.3 从一个部署项目到企业内部能力，还需要考虑的扩展方向

这篇文章写到这里，核心部署过程已经全部记录完毕。如果你只是个人试用，跑到这一步就能直接使用了。但如果是给团队或者企业内部搭知识库，有几个方向值得进一步考虑：一是结合企业现有的身份认证系统做接入控制，WeKnora 部署指南和相关社区讨论里都有人提到这个问题，接入统一账号体系后管理成本会明显下降；二是探索多知识库隔离，不同部门维护各自的库，避免权限混乱；三是如果要接入更多模型做效果对比，可以在 Ollama 上同时拉取多个模型，在 WeKnora 的模型配置里分别添加服务，按场景切换，这也是我目前在用的方式。

最后再分享一点个人体会。整套系统跑通之后，最让我满意的不是它的部署过程有多顺，而是知识库问答这个场景终于形成了一个完整闭环：文档在本地，模型在本地，问答结果带出处，数据边界完全受控。过程中踩过一些坑，也试错过一些配置，但每一步排查都让后面更顺。如果你正准备在本地部署一套 AI 知识库，希望这份记录能帮你省掉一些试错的时间。