闻达(wenda)本地搜索知识库实战:FESS 14.7 安装部署与接入配置指南

原创2026-10-14 11:18:351,888 阅读
文章标签:AI 应用大模型RAG后端

闻达(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,是最省事的路径。

  1. 在懒人包中下载 fess-14.7.0-with-jdk.7z;
  2. 解压到平时存放软件的磁盘分区(建议路径中避免中文字符,减少文件系统编码问题);
  3. 进入解压目录 fess-14.7.0-with-jdk\bin;
  4. 双击 fess.in.bat 完成初始化(首次运行会写入系统配置/索引目录);
  5. 双击 fess.bat,会弹出命令行运行框,这是 FESS 服务进程,将其最小化即可,不要关闭;
  6. 打开浏览器访问 http://localhost:8080/,进入 FESS 管理界面;
  7. 点击右上角 Log in,输入账号 admin、密码 wenda 登录;
  8. 点击侧边栏 Crawler(爬虫),选择 File System(文件系统抓取);
  9. 点击右上角 Create New 新建抓取配置;
  10. Name 输入便于记忆的资料库名称(例如 pdf search),该名称将作为后续 Job 标识的前缀;
  11. Paths 输入资料库的本地路径,格式为 file URI,示例:file:///E:/pdf(对应 Windows 的 E:\pdf 目录;Linux 下写法为 file:///home/user/docs);
  12. 其余选项保持默认,下滚至页面最下方点击 Create;
  13. 页面自动返回 File System 列表,点击刚才创建的条目(你输入的 Name)进入详情;
  14. 点击 Create new job,再点击 Create 生成抓取任务;
  15. 进入侧边栏 System 内的 Scheduler(调度器),可以看到任务列表;
  16. 找到以刚创建名称命名的任务(示例:File Crawler - pdf search),点击进入;
  17. 点击 Start now 立即触发抓取,刷新界面即可看到该任务状态变为 running;
  18. 此时 FESS 正在爬取文件的名字与内容,可以在资源管理器中观察到 CPU 出现负载;
  19. 挂机等待爬取完成,之后即可在 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 作为知识库还需两步:

  1. 在 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"
    
  2. 前端对话页面勾选右上角「知识库」开关(见 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 基于本地资料作答,兼顾内容私密性与检索实时性。

登录后查看全文
wenda