自建企业知识库实录：Ubuntu 部署 Halogen 与 6.4 万文档的清洗调优

公司里攒了大几年的知识文档，散落在 Wiki、网盘、钉钉群和售后同事的聊天记录里，总数大概 6.4 万块——我们内部习惯管一条文档叫一块，加起来就是 6.4 万块知识。之前员工找资料基本靠"人肉搜索引擎"：先问 IT 群，再问老同事，最后翻网盘，运气好十分钟，运气不好半天。后来我决定在 Ubuntu 上部署 Halogen，把这座知识库真正跑起来，前后折腾了大概两周，今天把整个过程复盘一下，包括选型理由、部署细节、数据清洗的坑和线上调优经验，希望能给同样在做私有化知识库的同行一点参考。

1. 为什么我放着商业知识库不用，非要自己部署 Halogen

1.1 6.4 万块知识条的背后是不堪回首的"人肉搜索"

先交代一下背景。我们的知识库不是一天建成的：产品文档、操作手册、售后工单、研发接口说明、销售话术，各种格式都有，PDF、Word、Markdown、Excel 导出的 CSV，甚至还有扫描件。过去几年大家都是往共享盘里丢，目录越来越深，文件名越来越随意，到了今年一季度统计的时候，光重复命名的文档就有上千份。

员工的真实使用状态是这样的：市场部想查某款产品的最新参数，售后同事想翻三年前一个类似故障的处理记录，研发想确认某个接口的返回字段格式，全部要靠人问人。有一个很有意思的数据：我们内部 IM 群里被 @ 次数最多的几个同事，全都是干了五六年以上的老员工，因为他们脑子里装着大半个公司的知识。这种状态持续下去，老员工一旦休假，业务流转就变慢，更别说知识全跟着人走的风险了。

所以老板批了预算，要求搞一个全公司可检索的知识库。目标很朴素：所有文档集中索引，支持模糊搜和语义搜，谁能搜到谁用，不用再问人。

1.2 商业 SaaS 知识库的三个劝退点

一开始我的方案是先看市面上的商业知识库产品，毕竟企业采购走流程比自研省事。联系了三家，试用下来各有各的问题，但对我们的场景来说有三个方面是绕不过去的：

第一是数据出域。公司知识文档里有大量内部定价、未公开产品信息，直接传到 SaaS 厂商的云上，合规这关就过不了。我们法务明确表态，核心文档不允许存到第三方平台。这一条几乎否掉了所有的公有云知识库方案。

第二是成本结构不友好。商业知识库大多数按"用户数 + 存储量"收费，6.4 万条文档索引起来，存储和向量化资源开销不小，按年续费算下来是一笔长期支出。我们自己本来就有 GPU 服务器（跑着内部大模型），如果自建，边际成本几乎为零。

第三是定制空间小。我需要对接内部 OA 的权限体系、需要自定义数据清洗流程、需要把检索接口嵌入到我们自己的客服工作台，SaaS 产品在这些场景下能提供的开放能力非常有限，API 文档翻几页就到头了。

基于这三点，自建成为必然选择。市面上开源的检索框架我大概对比了五六个，最终留下的是 Halogen。

1.3 Halogen 是什么，它是怎么匹配我需求的

Halogen 是一个开源的私有化知识库检索框架，定位很明确：把文档解析、文本切分、向量化、混合检索、大模型问答串成一条完整的流水线，对外提供 Web 管理界面和 REST API。它不是某个大厂出品，社区也不算特别火爆，但设计上很克制——核心功能就做知识库，没有塞一堆花里胡哨的功能，这在自建场景里反而是加分项。

我选它的几个理由：

• 支持混合检索。既做关键词匹配（BM25），又做向量语义检索，最后融合排序。企业知识库的真实查询往往包含大量专有名词和型号，纯向量检索碰到型号这种"精确词"容易飘，混合检索明显更稳。
• 模型接入灵活。它不绑定某个大模型，可以对接 Ollama、vLLM 起的本地模型，也可以接 OpenAI 兼容接口。我们内部本来就有 GPU 服务器跑代码大模型，直接把 Halogen 接过去就行。
• 部署清爽。官方提供 Docker Compose 编排，依赖项收敛得比较好，没有那种"装个 A 还要再装 B 和 C，B 和 C 又起冲突"的连锁反应。
• 数据管道可定制。文档切分、清洗、向量化这些环节都提供了配置入口，不是黑盒。

当然它也有局限，最明显的是 UI 比较朴素，没有商业产品那种华丽的权限工作台，Web 界面只适合做配置和简单搜索，真正的问答界面需要自己写前端对接 API。但对我来说这不算减分项，反正我们本来就要嵌到内部系统里。

2. Ubuntu 侧的基础环境准备：四类坑提前踩平

2.1 系统选型：Ubuntu 22.04 LTS 更省心

部署目标是一台 4 核 16G 内存的机架服务器，没有 GPU，只跑 Halogen 和向量库，大模型放在另一台 GPU 机器上。系统我选了 Ubuntu 22.04 LTS，没犹豫。原因很简单：Halogen 的 Docker 镜像、依赖库都是基于主流 LTS 版本测试的，Ubuntu 22.04 的 apt 源、内核和 Docker 版本兼容性都比较省心。如果你手头是 Ubuntu 20.04 也不是不行，但 22.04 是当前最不用折腾的选项。

安装的时候有一个小建议：如果服务器有多个磁盘，系统盘和数据盘建议分开。我见过同事把系统和业务数据全放一个盘，后期日志一涨把磁盘挤爆，整个服务直接 hang 住。Ubuntu 安装时用"手动分区"把/var/lib/docker放到独立数据盘，后续扩容会舒服很多。我当时这台机器只有一块 500G 的系统盘加一块 2T 的数据盘，所以主要数据路径都挂在了数据盘上。

2.2 Docker 与编排工具的安装

Halogen 依赖 Docker 和 Docker Compose，这两步安装本身不难，但有几个细节值得提一下：

Docker 的安装直接用官方源，或者用国内镜像站的源都行，关键是安装完要验证一下docker run hello-world能正常跑通。我遇到过一种情况：Docker 装好了，但是 daemon 启动失败，查了一圈是overlay2驱动和旧内核不兼容，升级内核后解决。如果你在安装时就遇到类似问题，优先检查内核版本和 Docker 版本是否匹配，不要盲目重装。

Docker Compose 我直接用插件版（docker compose子命令），比单独的docker-compose二进制少一层兼容性烦恼。确认版本：

docker --version docker compose version

Compose 文件里用到的version字段在新版 Compose 里其实已经废弃了，如果你拉到的示例配置还写着version: '3.8'，删掉也不影响运行，留着反而会弹警告。

镜像加速的问题也提前说一句：国内访问 Docker Hub 有时候会超时，建议在/etc/docker/daemon.json里配一个国内可用的镜像加速地址，然后重启 Docker。这一步能避免拉镜像拉一个小时的尴尬。

2.3 磁盘和目录规划

我的目录规划是这样的：

/opt/halogen # 部署编排和配置文件 /var/lib/halogen/data # 内置数据库、索引、日志 /var/lib/halogen/models # 如果有需要缓存模型文件的话

Halogen 的默认数据目录在容器内，但持久化必须挂载到宿主机。在 Compose 里把./data挂进容器的时候，要注意挂载点的属主和权限。容器内的进程一般以非 root 用户运行，如果宿主机目录权限不对，容器会报Permission denied，表现是服务起不来或者写入失败。解决办法很粗暴：

mkdir -p /var/lib/halogen/data chown -R 1000:1000 /var/lib/halogen/data

为什么是 1000？因为很多容器镜像内部默认用户 uid 是 1000。如果你不确定，用docker exec进容器执行id看一眼就清楚了。

2.4 防火墙、端口与内网访问

Ubuntu 默认用 ufw 管理防火墙。Halogen 的 Web 管理界面默认监听 8000 端口，API 监听 8080 端口，这两个端口不需要暴露到公网。我的做法是只允许内网网段访问，而且建议用反向代理（比如 Nginx 或 Caddy）再加一层访问控制，后面接统一登录认证。

ufw allow from 10.0.0.0/8 to any port 8000 ufw allow from 10.0.0.0/8 to any port 8080

这里有一个我踩过的坑：Halogen 内部会产生心跳检测和回调请求，如果 Halogen 所在服务器需要主动访问其他内网服务（比如对接 Ollama、访问 OA 数据库），记得在出口方向也放通，不要在防火墙规则里把出站全禁掉。我同事配了一圈之后进不去管理界面，查了半天才发现是出站默认 DROP 了。

3. Halogen 本体的部署：从开发机到生产机的迁移经验

3.1 拉取镜像与启动编排

基础环境就绪后，部署 Halogen 本体其实是整个项目里最顺利的环节。操作路径如下：

cd /opt/halogen git clone <halogen_repo_url> . docker compose pull docker compose up -d

如果拉镜像卡住，优先检查镜像加速配置；如果up -d起来之后容器反复重启，别急着删容器，先看日志：

docker compose logs -f --tail=200

日志里最常出现的几类问题：端口占用（8000 或 8080 被其他服务占了，改端口映射就行）、数据库初始化失败（数据目录权限不对，参考 2.3）、内存不足（16G 内存跑默认配置勉强可以，但索引构建阶段内存会猛涨）。

我当时的部署配置是 2 个服务各分配内存上限：核心服务限 8G，检索服务限 6G。如果你的机器内存更小，可以把并发索引线程数调低，否则索引构建时内存直接打满，OOM 之后容器反复重启，数据又得重新索引，非常折磨。

3.2 环境变量与模型接入

Halogen 的核心配置都通过环境变量注入，我把关键的几项整理成一张表：

模型接入这一步最关键的是向量化模型和生成模型的区别。很多人以为知识库里所有模型只需要一个，其实这里至少要两个角色：embedding 模型负责把文档切成向量，问答模型负责读检索结果生成答案。bge-m3 是我们实测下来中文分块向量效果比较稳的模型，在告警、工单这些混合中英文的文档上表现不错。生成模型选了 qwen2.5:14b，因为 GPU 机器显存有限，14B 的量化版本在质量和资源之间相对平衡。

3.3 迁移生产机时踩过的三个小坑

从开发机（一台 16G 内存的笔记本）迁到生产机（4 核 16G 内存服务器）的时候，我踩了三个比较典型的坑。

第一个坑是配置里写死了开发机的 IP。Compose 文件、.env 文件里凡是涉及回调地址、内部 API 地址的，全部要用生产机的内网 IP，而且要确保其他服务能访问到这个 IP。我当时在开发机用 localhost 配通了，迁过去之后忘记改，导致管理界面能打开，但后台任务全部失败。排查方法很简单，看日志里有没有connection refused指向旧 IP。

第二个坑是数据目录的迁移。开发机上的数据目录包含已经索引好的向量文件和数据库元数据，直接 rsync 到生产机后，容器启动时报"版本不兼容"。原因是开发机和生产机的镜像版本不一致（开发机是旧版镜像），索引文件格式里带版本号。解决办法是把生产机的镜像版本固定成开发机的版本，重新docker compose pull之后数据就认了。这里要提醒一句：数据迁移前一定要看版本，docker compose pull到相同版本再搬数据。

第三个坑是系统时区。容器默认 UTC 时区，如果不把宿主机/etc/localtime挂进容器，日志时间会比本地时间慢 8 小时。看起来是小问题，但排查高峰期日志的时候非常难受。在 Compose 里加一行：

volumes: - /etc/localtime:/etc/localtime:ro

4. 数据导入这一步才是灵魂：6.4 万块知识条目的清洗与索引

4.1 数据来源比想象中杂得多

部署只花了一个下午，真正花掉我大半周的是数据导入。6.4 万块知识条目听起来不算海量，但它的来源乱到超出预期：

• 文件服务器上的 PDF 和 Word 文档，约 1.8 万份；
• 内部 Wiki 导出的 HTML 和 Markdown，约 2.2 万块；
• 客服系统导出的工单 CSV，约 1.5 万行；
• 同事网盘里零零散散的.md、.txt、.xlsx，约 9 千份。

最麻烦的不是数量，而是格式和编码。有扫描版 PDF（没有文字层），有 Word 里嵌 Excel 表格的，有 HTML 里带着大量导航噪音的，还有 CSV 里字段错位的。如果直接一股脑塞进去，检索质量会非常差，因为索引里全是垃圾，搜啥都搜不准。

4.2 清洗与切分：chunk 大小不能拍脑袋

清洗流程我分三步走：

第一步，统一转文本。PDF 先跑一遍 OCR 工具（有文字层的直接提取），Word 用转换工具转成 Markdown，HTML 用解析库去掉标签和导航，CSV 按固定模板补全字段名。

第二步，去重和合并。用文档标题加 MD5 做粗去重，发现完全一样的文档直接丢弃；内容相似、只是版本不同的文档，保留最新的，把旧的标记为归档。这一步下来，6.4 万块缩到了约 5.6 万块。

第三步，切块（chunk）。这是整个数据管道里对检索质量影响最大的参数。切得太小，语义不完整，检索容易找错上下文；切得太大，向量化的特征被稀释，且超过模型上下文窗口之后问答阶段会截断。我一开始用了固定 512 字符滑窗，检索出来的结果里有很多"半截话"，后来改成中文按段落切，段落过长的再按 256 字符重叠切分（重叠 32 字符）。效果好了不止一个档次，合规的规则是"尽量避免在句子中间切断"。

这个切分逻辑因人而异、因文档而异，强烈建议你拿自己的真实数据做小范围对照测试，不要照抄别人的参数。

4.3 向量化与索引构建的关键参数

清洗好的 5.6 万块知识，还要经过向量化才能被语义检索到。我用的 embedding 模型是 bge-m3，输出向量维度是 1024 维，所有文档切块跑完之后大约生成 18 万个向量片段——比原始条数多，因为一篇长文档会切成很多块。

向量化之前还有两个参数值得关注：

• batch_size：向量化是 GPU 密集操作，如果 GPU 机器显存有限，batch_size 设 32 比 64 更稳，速度慢一点但不容易 OOM。
• index_type：推荐 HNSW，检索速度快、精度也够。构建时设置M=16、ef_construction=200，内存占用和检索召回平衡得不错。我实测过把 M 调到 32，召回率略有提升，但内存占用直接翻倍，16G 的机器会有点吃力。

索引构建完成后，做了一次抽样验证：从 5.6 万块里随机抽出 500 条，用真实业务问题去检索，统计 Top-10 是否包含正确答案所在的文档，准确率约 87%。这个数值不算顶尖，但配合重排序和问答模型，实际使用体感已经相当能打。

4.4 导入耗时实测与并发建议

这里给一组真实耗时数据供参考：

整体从 0 到 1 用了一晚上加半个白天。如果你导入的数据量在百万级，强烈建议分批次导入，别一次性灌进去，索引构建期间检索服务会被拖到不可用。

5. 跑起来只是开始：线上检索变慢时我做的几件事

5.1 现象与影响面

知识库上线第一周，效果很不错，同事们都觉得"终于不用问人了"。但第二周开始陆续有人反馈：检索变慢了，有时候一个查询要等 4 秒才出结果，偶尔还会超时。我先自己复现了一下，在管理后台查询一个包含产品型号的精确问题，延迟在 1.2 秒到 4 秒之间波动，在线用户一多就明显卡顿。

影响面不是全部查询。纯关键词搜索还正常，慢的是带语义检索的混合查询。这说明问题可能出在向量检索或融合排序环节，而不是基础查询接口。

5.2 排查链路的完整复盘

我按下面这个链路一步步排查，这一步值得详细写，因为类似的性能问题大部分都能套用这个思路：

第一步，看系统资源。top一看，内存使用率 92%，CPU 正常。向量检索本身吃内存，内存不够就会频繁换页，延迟飙升。初步结论和资源有关，但这还解释不了为什么"在线用户一多就明显卡顿"。

第二步，看慢查询日志。Halogen 在管理界面有查询统计页，能看到每个查询的耗时分布。我导出一看，慢查询集中在两类：一是语义检索候选数多的查询（TOP_K_SEARCH设为 10 后，重排序阶段要对 10 个候选逐条打分）；二是带大量专有名词的长查询，向量化后需要对比的向量范围更大。

第三步，确认瓶颈在哪。我分别用 "仅关键词检索" 和 "仅向量检索" 跑同一个查询，前者 200ms，后者 2.8 秒。实锤了向量检索是瓶颈。为什么？因为 18 万个向量片段全部放在内存里做暴力遍历，虽然用了 HNSW 索引，但ef_search参数设得过高（默认 100），导致查询耗时翻倍。

5.3 三项优化动作与效果对比

我做了三个动作，按收益从高到低列一下：

第一，调整ef_search。这是 HNSW 索引的查询参数，控制搜索时的候选集大小。从 100 降到 40，检索耗时直接降到 1.1 秒。代价是召回率有一点点下降，但配合重排序，实际结果质量几乎没有影响。

第二，给热数据做缓存。把过去 7 天访问最多的 2000 条知识片段放到 Redis 缓存里，命中缓存的查询直接在秒回范围内。这一步对"大家都问同一个问题"的场景特别有效，把高频查询挡在向量检索之外。

第三，扩充内存。把另外一台闲置服务器的 16G 内存条拔过来加上，总共 32G。内存宽裕之后，索引全部进内存，查询延迟进一步降到 400ms 左右。

对比效果：

5.4 运维层面的兜底措施

优化完延迟后，我又补了几项兜底措施，避免下次再被同类问题打蒙：

一是监控告警。写了个简单脚本，每两分钟探测一次核心接口延迟，超过 2 秒就在内部群告警。告警阈值不能设太低，否则高峰期天天被吵醒，我试过 1 秒的阈值，一天被踢醒三次，后来改成 2 秒就安静多了。

二是定时做增量索引。知识库每天都有新文档进来，我用 cron 每天凌晨触发一次增量索引任务，把当天新增的文档清洗、切块、向量化后合并进索引。全量索引一周只做一次，放在周末凌晨。

三是备份策略。向量索引文件和数据目录每天凌晨打包备份到 NFS，保留最近 7 天。这里有个教训：向量索引文件不小（我们的大概 4.3G），如果只备份在本地磁盘，服务器挂了一样全丢，NFS 这种跨机备份还是必要的。

6. 给想自建企业知识库的同行几句实在话

6.1 什么样的企业/场景适合自建

跑了两个月，冷静下来看，自建 Halogen 这套方案不是万能的，它有明显的适用边界。如果你的团队小于 20 人、文档总量在几千块以内、对数据合规没有强制要求，直接买商业 SaaS 产品的体验确实更好——你不用管服务器、不用调参、不用处理文档格式，检索效果也不会差太多。

但如果你和我们一样，文档量上万、涉及核心业务数据、还想对接内部系统和模型，自建的收益就很明显了。尤其是公司有 GPU 服务器、本来就在跑本地大模型的前提下，Halogen 的边际部署成本几乎可以忽略。所以我的建议是：先做预算对比，再做数据合规评估，最后才选技术方案，别一上来就陷入"技术选型"的兴奋里。

6.2 数据安全、备份与权限

企业知识库最怕的不是检索不到，而是权限越界。我们当时的权限策略是：先按部门粗分，再按文档标签细控。Halogen 的 API 支持传用户上下文，我通过内部的统一登录网关，把用户所属部门映射到查询参数里，实现"按部门隔离检索范围"。这个思路参考了 RAG 系统里的元数据过滤，实现起来不复杂，但必须尽早设计，等所有文档都索引完再去翻权限模型会非常痛苦。

补充一个细节：索引文件本身也是敏感数据，它存储了所有文档的向量表示，虽然没有原文完整，但结合关键词检索可以还原大量信息，所以备份访问权限要和源文档一样严格。

6.3 我的真实体会与后续扩展方向

踩完这一圈，最深的体会是：部署 Halogen 本身只占整个项目的两成工作量，剩下八成都在数据清洗、参数调优和运维保障上。6.4 万块知识，真正你搜的时候能精准找到的那一块，靠的是前面无数不起眼的清洗规则和索引参数。

目前我手上还在推进两件事：一是把文档的"更新时间"纳入排序因子，让最新的文档在结果里优先展示，避免老文档长期霸占前排；二是把销售和客服的高频问题整理成标准的行业问答对，单独建一个 FAQ 索引，和全文知识库分开检索、分层返回。如果你也在做类似的事，这两点建议尽早加进设计里，越晚改越费劲。

最后想说的是，企业知识库不是一次性的项目，它更像一个需要持续投喂和修剪的花园。索引建完只是开始，数据的质量、模型的效果、检索的策略，都需要在实际使用中不断调整。好在方向是对的——当你看到同事第一次自己搜到了答案，而不是在群里 @ 老员工的时候，前面所有的折腾就都值了。