闻达(wenda)本地搜索知识库实战:FESS 14.7 安装部署与接入配置指南
闻达(wenda)本地搜索知识库实战:FESS 14.7 安装部署与接入配置指南
本文以闻达(wenda)LLM 调用平台官方安装文档 docs/install_fess.md 为主线,完整讲解如何在 Windows 与 Linux 环境中部署开源全文搜索引擎 FESS,并将其作为闻达的「本地搜索引擎型知识库」接入对话系统。读完本文,你将掌握 FESS 的两种部署路径、Crawler 爬取本地文档的完整操作流程,以及闻达知识库配置项 librarys.fess 的字段语义与底层查询管线,真正做到「装得上、配得通、查得准」。
一、为什么 wenda 需要 FESS:本地搜索型知识库的定位
闻达的知识库体系采用「搜索后注入提示」的机制:系统在收到用户问题时,先调用知识库检索相关内容,再把检索结果作为提示信息插入对话,让 LLM 基于本地资料作答。按 README.md 的说明,闻达目前支持 rtst(离线向量库)、bing(在线搜索)、bingsite(站内搜索)与 fess 四种知识库方案,其中 fess 模式相当于自建本地搜索引擎:
fess模式,本地部署的 fess 搜索,并进行关键词提取。
与需要向量模型、GPU 资源的 rtst 模式相比,FESS 是纯 Java 实现的全文搜索引擎,对硬件要求低、部署简单,特别适合已有大量本地文档(PDF、Office、网页等)且希望私密化检索的场景——文档不出内网,检索结果直接作为知识注入对话。在闻达中启用它只需三步:装好 FESS → 在配置文件中填入服务地址 → 在知识库策略里启用 fess 类型。
二、Windows 系统:懒人包一键部署
闻达的 Windows 懒人包中内置了带 JDK 的 FESS 压缩包,无需单独安装 Java,是最省事的路径。
- 在懒人包中下载
fess-14.7.0-with-jdk.7z; - 解压到平时存放软件的磁盘分区(建议路径中避免中文字符,减少文件系统编码问题);
- 进入解压目录
fess-14.7.0-with-jdk\bin; - 双击
fess.in.bat完成初始化(首次运行会写入系统配置/索引目录); - 双击
fess.bat,会弹出命令行运行框,这是 FESS 服务进程,将其最小化即可,不要关闭; - 打开浏览器访问 http://localhost:8080/,进入 FESS 管理界面;
- 点击右上角 Log in,输入账号
admin、密码wenda登录; - 点击侧边栏 Crawler(爬虫),选择 File System(文件系统抓取);
- 点击右上角 Create New 新建抓取配置;
- Name 输入便于记忆的资料库名称(例如
pdf search),该名称将作为后续 Job 标识的前缀; - Paths 输入资料库的本地路径,格式为 file URI,示例:
file:///E:/pdf(对应 Windows 的E:\pdf目录;Linux 下写法为file:///home/user/docs); - 其余选项保持默认,下滚至页面最下方点击 Create;
- 页面自动返回 File System 列表,点击刚才创建的条目(你输入的 Name)进入详情;
- 点击 Create new job,再点击 Create 生成抓取任务;
- 进入侧边栏 System 内的 Scheduler(调度器),可以看到任务列表;
- 找到以刚创建名称命名的任务(示例:
File Crawler - pdf search),点击进入; - 点击 Start now 立即触发抓取,刷新界面即可看到该任务状态变为
running; - 此时 FESS 正在爬取文件的名字与内容,可以在资源管理器中观察到 CPU 出现负载;
- 挂机等待爬取完成,之后即可在 FESS 搜索框中测试关键词,验证索引是否建立成功。
以上步骤与官方文档一一对应,重点是把「建爬虫 → 建 Job → Start now」这条链路走通:File System 配置决定「爬什么」,Job 决定「何时爬」,Start now 手动触发。首次使用建议先用一个小目录(几十个文件)验证流程,再扩大到完整资料库。
三、Linux 系统:手动安装 JDK 与 FESS
Linux 部署分为两步:安装 JDK 17,再安装 FESS 14.7。
3.1 安装 JDK 17
wget https://download.java.net/java/17/latest/jdk-17_linux-x64_bin.tar.gz
sudo tar xvf jdk-17_linux-x64_bin.tar.gz -C /usr/local/
解压后,JDK 17 将被安装到 /usr/local/jdk-17 目录。接下来把 JDK 写入系统 PATH,官方文档给出的做法是直接替换 alternatives 软链并追加环境变量到 /etc/profile:
rm -f /etc/alternatives/java
ln -s /usr/local/jdk-17.0.6/bin/java /etc/alternatives/java
echo export JAVA_HOME=/usr/local/jdk-17.0.6 >>/etc/profile
echo export PATH='$PATH':'$JAVA_HOME'/bin >>/etc/profile
echo export CLASSPATH=.:'$JAVA_HOME'/lib/dt.jar:'$JAVA_HOME'/lib/tools.jar >>/etc/profile
source /etc/profile
注意:
ln -s的目标路径jdk-17.0.6是文档写作时的实际版本目录名,若你解压后的目录名不同(例如jdk-17.0.x),请按实际目录调整软链与环境变量路径。
验证安装是否成功:
java -version
正常输出形如:
openjdk version "17.0.1" 2021-10-19
OpenJDK Runtime Environment (build 17.0.1+12-39)
OpenJDK 64-Bit Server VM (build 17.0.1+12-39, mixed mode, sharing)
3.2 下载并启动 FESS
unzip fess-14.7.0.zip
cd bin
./fess -d
-d 参数表示以守护(daemon)方式后台运行,日志输出到服务端控制台。启动成功后,同样访问 http://localhost:8080/,使用 admin / wenda 登录,后续的 File System 爬虫、Job、Scheduler 配置与 Windows 完全一致(见上一节步骤 8~19)。需要确认服务是否就绪时,可执行 curl http://localhost:8080/json/?q=test 看是否返回 JSON 响应。
四、将 FESS 接入 wenda:配置文件与启用方式
FESS 装好后,需要让闻达知道「去哪里查」。闻达的配置加载入口在 plugins/common.py:启动时读取命令行 --Config 指定的 config.yml(默认回退到 example.config.yml),并通过 dotdict 转成嵌套对象供各知识库插件使用。fess 相关配置段定义在 example.config.yml:
librarys:
fess:
count: 1
#最大抽取数量
fess_host: "127.0.0.1:8080"
#fess搜索引擎的部署地址
各字段语义如下:
| 配置项 | 默认值 | 含义 |
|---|---|---|
librarys.fess.count |
1 |
单次问答最多从 FESS 抽取的文档条数,越大知识注入越多但占用上下文越长 |
librarys.fess.fess_host |
127.0.0.1:8080 |
FESS 服务地址(不含 http:// 前缀,源码在拼接 URL 时自动补全),FESS 装在其他机器时改为 IP:端口 |
librarys.fess.version |
未配置 | FESS 版本号。不配置时按 >=14.8 的新版 API 调用;配置且小于 14.8 时走旧版 /json/ 接口(详见下文源码剖析) |
按 README.md 的说明:在本机使用默认端口安装 FESS 后可直接运行,无需改动任何配置;若端口或地址不同,把 fess_host 的 127.0.0.1:8080 改成实际值即可。
启用 FESS 作为知识库还需两步:
-
在
library.strategy中加入fess:N(N为抽取条数)。该字段定义在 example.config.yml,格式为「库类型:条数」的空格分隔列表,默认示例为"calc:2 rtst:5 agents:0",其中#fess fess搜索引擎的注释明确列出了 fess 类型。例如:library: strategy: "fess:2 rtst:5 agents:0" -
前端对话页面勾选右上角「知识库」开关(见 README.md),让检索注入生效。
知识库插件的加载与调度由 plugins/zhishiku.py 完成:它按 strategy 中的类型名动态 import_module('plugins.zhishiku_'+type) 加载对应插件,调用各插件的 find() 取回结果,再按各类型配额与 library.count 上限汇总。因此只要配置里出现 fess,就会加载 plugins/zhishiku_fess.py。
五、源码剖析:zhishiku_fess.py 的查询管线
FESS 知识库插件的完整实现在 plugins/zhishiku_fess.py,整个查询流程可分四个阶段,理解它有助于排查「搜不到、结果乱」等实际问题。
5.1 关键词提取:jieba 分词 + 停用词过滤
闻达对 FESS 的定位是「本地搜索引擎 + 关键词提取」。find() 首先用结巴分词把用户问题切词,再对照 plugins/stopwords_txt 停用词表过滤:
search_query = jieba.cut(search_query)
search_query = remove_stopwords(search_query)
remove_stopwords 会把命中停用词的词替换为 ######## 占位符,随后按该占位符把整句切成多个子查询块,逐块向 FESS 发起检索,最后合并结果——这样既能去除「的、了、是」等无信息量词,又能保留核心关键词的多个查询维度。从源码结构看,这是一种轻量的查询改写策略,无需额外模型。
5.2 版本适配:14.8 前后两套 REST API
FESS 14.8 前后搜索 API 有破坏性变更,插件用 settings.librarys.fess.version 判断走哪套接口(zhishiku_fess.py):
if settings.librarys.fess.version is not None and settings.librarys.fess.version < 14.8:
url = 'http://' + settings.librarys.fess.fess_host + '/json/?q={}&num=10&sort=score.desc&lang=zh_CN'.format(i)
else:
# adapt for >fess14.8
url = 'http://' + settings.librarys.fess.fess_host + '/api/v1/documents/?q={}&num=10&sort=score.desc&lang=zh_CN'.format(i)
- 旧版(如本文部署的 14.7.0):
GET /json/?q=关键词,结果在r["response"]["result"]; - 新版(≥14.8):
GET /api/v1/documents/?q=关键词,结果在r["data"]。
两类请求都固定使用 num=10、sort=score.desc(按相关度分数降序)与 lang=zh_CN(中文语言环境)。关键提醒:如果你按本文部署的是 14.7.0,务必在 librarys.fess 下补充 version: 14.7.0,否则 version 为 None 会走新版 API,而 14.7 并无 /api/v1/documents/ 接口,导致查询失败返回空列表。这是从配置默认值与分支逻辑可直接推出的结论。
5.3 结果后处理:去高亮、去重、限量
搜索结果中的关键词会被 FESS 用 <strong> 标签高亮,插件通过 replace_strong() 正则剔除标签;removeduplicate() 依据文档 _id 对多路子查询的结果去重(zhishiku_fess.py);最终按 settings.librarys.fess.count 截取条数:
return [{'title': r[i]['title'], 'content': replace_strong(r[i]['content_description'])}
for i in range(min(int(settings.librarys.fess.count), len(r)))]
取回的结构为 title + content_description,与闻达知识库统一的 {'title','content'} 约定一致,由 plugins/zhishiku.py 汇总后注入对话。
5.4 接口与异常兜底
插件还暴露了 POST /find_fess_zhishiku 路由(zhishiku_fess.py)供前端或其他脚本调用。从源码看,该路由的 upload_zhishiku() 函数体内引用了未定义的循环变量 i(第 99~103 行),实际使用时可能触发异常并回退到 json.dumps([])——主查询流程 find() 不受影响,日常问答走的是 find()。这一细节提示:以 find() 为准,接口路由部分在 14.7 部署场景下仅作参考。无论哪条路径,请求失败都会打印 fess读取失败 并返回空列表,不会影响主对话流程。
六、常见问题排查
- 搜索无结果 / 报
fess读取失败:先确认 FESS 服务在运行(浏览器可打开 8080 管理页)、fess_host地址端口正确、且已按 14.7 版本补上version: 14.7.0配置。 - 任务显示 running 但 CPU 无负载:检查 Crawler 的 File System 配置中 Paths 是否填写为合法的 file URI(如
file:///E:/pdf),并确认目录存在且 FESS 进程有读取权限。 - 索引已建但搜不到预期文档:回到 FESS 管理界面用关键词手动测试,确认索引本身可用;再检查闻达侧
library.strategy是否包含fess:N、页面右上角知识库开关是否勾选。 - 想限制注入量:调小
librarys.fess.count(如1)即可,避免长上下文挤占模型窗口。
七、小结
闻达将 FESS 定位为可私密部署的本地搜索引擎知识库:Windows 走懒人包、Linux 手动装 JDK 17 + FESS 14.7,两者殊途同归;接入只需在 example.config.yml 的 librarys.fess 段填对地址与版本,并在 strategy 中加入 fess:N。底层查询管线由 plugins/zhishiku_fess.py 承担——结巴分词、停用词过滤、14.8 前后 API 适配、去重与限量一应俱全。按本文步骤完成部署后,即可让 LLM 基于本地资料作答,兼顾内容私密性与检索实时性。