WeKnora 本地部署实录：用腾讯微信团队的开源 AI 知识库搭一套问答系统

起因

团队内部文档散在飞书、Confluence、几个 Git 仓库里，新人问问题永远是同一批。我想搭一个能自己部署、数据不出内网的知识库问答系统。

试过几个方案：Dify 功能全但偏重，RAGFlow 解析能力强但依赖多。后来看到 WeKnora，腾讯微信团队开源，定位就是文档理解 + 语义检索 + 问答，代码量不算大，适合拿来改。

这篇记录我从零部署到跑通的全过程。包括 Docker Compose 起服务、配模型、传文档、调检索参数。踩到的坑我都写清楚，没验证的地方我会标出来。

环境准备

我的机器：Ubuntu 22.04，16 核 32G 内存，一张 4090（24G 显存）。

WeKnora 官方仓库在 GitHub 上，直接 clone：

bash 复制代码

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora

仓库根目录有 docker-compose.yml 和 .env.example。我实际用的版本是主分支某次提交，没有打 tag。这一点我建议你 clone 后先 git log -1 记一下 commit hash，因为主分支变动挺快。

复制环境变量文件：

bash 复制代码

cp .env.example .env

.env 里需要关注的几类配置：

配置项	作用	我的取值
数据库相关	PostgreSQL / 向量库连接	用 compose 默认
模型 API 地址	LLM 和 Embedding 的 endpoint	指向本地 vLLM
模型名称	具体调用的模型	见下文
存储路径	上传文档落盘位置	默认卷

具体变量名我就不逐字抄了，因为不同 commit 之间命名改过，你以自己 clone 到的 .env.example 为准。我踩的第一个坑就是照着某篇博客的变量名改，结果那个版本根本没有这个字段，服务起不来。

起服务

bash 复制代码

docker compose up -d

第一次拉镜像比较慢，主要是几个基础镜像体积大。起来之后：

bash 复制代码

docker compose ps

正常的话能看到数据库、后端、前端几个容器都是 running。前端默认映射到某个端口，我在 .env 里改成了 8080，浏览器打开 http://localhost:8080 能看到界面。

如果容器反复重启，先看日志：

bash 复制代码

docker compose logs -f backend

我遇到过一次后端起不来，日志里是连不上数据库。原因是我本地 5432 端口已经被另一个项目的 PostgreSQL 占了，compose 的端口映射冲突。改掉宿主机映射端口就好。这个坑很常见，建议起服务前先 ss -lntp | grep 5432 看一眼。

配置模型

WeKnora 的问答链路需要两类模型：

LLM：负责最终生成回答
Embedding：负责把文档切片和 query 转成向量

我用本地 vLLM 起了一个 OpenAI 兼容接口的服务。LLM 用 Qwen2.5-7B-Instruct，Embedding 用 bge-m3。

bash 复制代码

# 起 LLM
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --port 8000

# 起 Embedding
python -m vllm.entrypoints.openai.api_server \
  --model BAAI/bge-m3 \
  --port 8001

然后在 WeKnora 界面或者 .env 里把 endpoint 填进去。填的时候注意：vLLM 的 OpenAI 兼容接口路径是 /v1，base url 要写到 /v1 这一层。

验证模型通不通，最直接的办法是 curl：

bash 复制代码

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "你好"}]
  }'

能返回 JSON 就说明 LLM 侧没问题。Embedding 同理，打 /v1/embeddings。

这一步我卡了挺久。一开始 Embedding 一直报错，后来发现是 bge-m3 的输出维度和我之前用的模型不一样，而在建知识库的时候维度是写死在索引里的。如果你中途换 Embedding 模型，已经建好的知识库索引大概率要重建，因为维度对不上。这一点我是踩了才反应过来。

上传文档与解析

界面上建知识库，然后上传文档。我传了一堆 Markdown 和 PDF。

解析环节是这类系统最容易出问题的地方。WeKnora 支持多种格式，但 PDF 的解析质量取决于它内部用的解析器。我传的几份带表格的 PDF，解析出来的文本表格结构基本丢了，变成一堆挤在一起的文字。

Markdown 和纯文本解析得很干净，切片也合理。

所以我的实际做法是：能把源文档转成 Markdown 的，先转再传。 PDF 里如果是扫描件，那还得先 OCR，WeKnora 这块我没测，不确定它内部有没有集成 OCR。这一点我没有验证。

切片参数可以在界面上调，主要是 chunk size 和 overlap。我用的是一组比较常见的值：

参数	取值	说明
chunk size	512	字符数，不是 token
overlap	50	相邻切片重叠

这两个值我调过几轮，512/50 对我的文档效果还行。但这跟文档类型强相关，代码文档和技术手册的最优值不一样，你得自己试。

检索与问答调参

WeKnora 走的是 RAG 常规流程：query 向量化 → 向量检索 top-k → 拼上下文 → LLM 生成。

界面上能调的参数主要是 top-k 和相似度阈值。我一开始 top-k 设 3，发现回答经常漏信息，因为相关内容被切在好几个 chunk 里，只取 3 个不够。后来调到 8，回答完整度明显好了，但噪声也进来了一些。

最后我稳定在 top-k=5，阈值 0.5 左右。这个阈值是余弦相似度还是别的度量，我没去翻源码确认，不同向量库的默认度量可能不一样，你调的时候最好先确认一下。

一个实际观察：bge-m3 对中文技术文档的召回还不错，但同一个问题换个问法，召回结果差异挺大。所以我在实际用的时候，会引导同事尽量把问题问具体一点。

完整验证脚本

想确认整条链路通不通，可以绕过前端直接打后端接口。以下是我用的 curl（接口路径以你部署版本的文档为准，我这里的路径在不同 commit 间改过）：

bash 复制代码

# 先登录拿 token（如果开了鉴权）
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}'

# 用 token 提问
curl -X POST http://localhost:8080/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_token>" \
  -d '{
    "knowledge_base_id": "your_kb_id",
    "question": "部署流程是什么？"
  }'

返回里应该能看到生成的回答和引用的文档片段。如果引用的片段是空的但回答正常，说明检索没生效，LLM 在硬答------这是 RAG 系统最坑的失败模式，看着有回答，其实是幻觉。

所以一定要看返回里的引用来源，不要只看回答文本。

踩坑清单

整理一下我实际遇到的问题：

问题	原因	解决
后端容器反复重启	宿主机端口冲突	改映射端口
Embedding 报维度错误	换了模型，索引维度不匹配	重建知识库
PDF 表格解析乱	解析器对复杂版面支持有限	先转 Markdown
回答有内容但无引用	检索阈值过高或 top-k 太小	调大 top-k 降阈值
照抄博客变量名失败	版本间配置字段改名	以本地 .env.example 为准

结论

WeKnora 能用，部署门槛不高，Docker Compose 一把起。适合想自己掌控数据、又不想从零写 RAG 链路的团队。

它的强项在文档解析和检索这套流程的封装，弱项是文档格式兼容性------PDF 复杂版面会丢结构，这个得靠预处理补。

几个建议：

模型用本地部署，数据不出内网，这也是选它的主要原因之一
Embedding 模型定了就别随便换，换一次要重建索引
上线前一定要验证引用来源，别被"看起来对"的回答骗了
主分支变动快，部署时记下 commit hash，方便回滚

最后再强调一次：文中涉及的具体参数名、接口路径、模型版本，请以你实际 clone 到的版本为准。我写的是我这次部署时的状态，不确定的地方已经标出来了，没有验证的我没有编。