1. 为什么要在 Ubuntu 上自建企业知识库把 6.4 万份文档塞进一个能对话的知识库这件事我在 Ubuntu 上折腾了差不多三周。最开始的想法很简单公司内部文档散落在各种网盘、邮件附件和共享目录里找一份三年前的合同模板要翻半天于是想搭一个能语义检索、能问答的内部知识库。选 Ubuntu 作为底座没什么悬念服务器上跑的就是 Ubuntu 22.04 LTS稳定、包管理成熟、社区资料多出问题好查。真正让我决定写这篇总结的是部署 Halogen 之后踩的一连串坑。Halogen 这套东西本身不算复杂它把 embedding 生成、向量检索、文档切分这几块串起来了但跑起来和真正能用之间隔着一条很宽的沟。6.4 万块文档我这里说的块是指切分后的 chunk不是原始文件数在测试环境里检索延迟能到 8 秒以上召回结果还经常答非所问。后来一步步调优把延迟压到 400 毫秒以内召回准确率也上来了才算真正跑起来。这篇内容适合两类人看一类是手上有一批内部文档、想自建知识库但还没动手的另一类是已经部署了 Halogen 或者类似方案但发现效果不达预期、不知道从哪调起的。我会把整个链路拆开讲——从 Ubuntu 环境准备、embedding 模型选型、llama.cpp 的编译参数到向量库的索引策略和检索调优尽量把每个为什么这么选讲清楚。涉及具体参数的地方我会给出实测数据方便你直接抄作业。需要提前说明的是下面所有操作都基于 Ubuntu 22.04 LTS硬件是一台 32 核 CPU、128GB 内存、一张 24GB 显存的机器。如果你的配置差一些我会在对应位置标注降级方案。2. Ubuntu 底座的环境准备与那些容易翻车的地方2.1 系统版本和基础依赖的选择逻辑Ubuntu 22.04 LTS 是我强烈建议的版本不是因为它最新而是因为它的 glibc 版本、Python 版本和 CUDA 驱动兼容性最成熟。我试过在 24.04 上编译 llama.cpp遇到过一次 gcc 版本导致的编译报错虽然能解决但没必要给自己找麻烦。22.04 的 apt 源里 Python 默认是 3.10这个版本对绝大多数 embedding 相关的库都友好。基础依赖这块很多人上来就apt install一堆东西结果装到一半报错。我的建议是按顺序来先确认系统架构uname -m lsb_release -a确认是 x86_64 之后再装编译工具链。这里有个坑Ubuntu 安装 gcc 失败的情况我遇到过两次一次是 apt 源被改乱了一次是磁盘空间不足导致 dpkg 中断。所以装之前先看一眼磁盘df -h至少留 20GB 空间给编译和模型文件。然后按这个顺序装sudo apt update sudo apt install -y build-essential cmake git python3-pip python3-venv sudo apt install -y libcurl4-openssl-dev libssl-devbuild-essential里包含了 gcc、g、make这是编译 llama.cpp 的基础。cmake版本要注意22.04 自带的 cmake 是 3.22够用但如果你要开某些新特性可能需要手动升级。我实测 3.22 编译 llama.cpp 没问题。2.2 显卡驱动和 CUDA 的安装顺序这块是重灾区。我见过太多人先把 CUDA 装了结果显卡驱动版本对不上最后卸载驱动卸载不掉只能重装系统。正确的顺序是先装显卡驱动再装 CUDA Toolkit。先看显卡型号lspci | grep -i nvidia然后装驱动。Ubuntu 22.04 可以用ubuntu-drivers自动推荐sudo ubuntu-drivers devices sudo ubuntu-drivers autoinstall装完重启用nvidia-smi验证。如果这个命令能正常输出显卡信息说明驱动没问题。这里有个经验如果你之前手动装过驱动nvidia-smi报错说版本不匹配别急着卸载先试试sudo apt purge nvidia-*再重装比手动删文件干净得多。CUDA Toolkit 我装的是 12.1因为 llama.cpp 对 12.x 支持最好。装的时候不要用 apt 装nvidia-cuda-toolkit那个版本太老。去官网下 runfile 或者用官方源wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update sudo apt install -y cuda-toolkit-12-1装完配置环境变量。这里就是热词里提到的ubuntu环境变量配置错误的高发区。不要直接改/etc/profile容易把系统搞崩。我的做法是在~/.bashrc末尾加export PATH/usr/local/cuda-12.1/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH然后source ~/.bashrc。验证nvcc --version能输出版本号就对了。如果报command not found八成是 PATH 没生效检查一下你改的是不是当前用户的 bashrc。2.3 Python 虚拟环境的隔离策略知识库这套东西依赖的 Python 包不少而且版本敏感。我强烈建议用 venv 隔离不要往系统 Python 里装python3 -m venv ~/kb-env source ~/kb-env/bin/activate pip install --upgrade pip虚拟环境建好之后后面所有 pip 安装都在这个环境里做。这样做的好处是万一某个包版本冲突把环境搞坏了直接删掉 venv 重建不影响系统。我踩过一次坑在系统 Python 里装了一个版本的 numpy结果和另一个工具依赖的版本冲突系统里好几个脚本都跑不了了最后只能重装。从那以后我所有项目都用 venv。3. Halogen 的部署与 embedding 模型选型3.1 Halogen 到底解决了什么问题在讲部署之前先说清楚 Halogen 在这个链路里的位置。一个完整的知识库问答系统核心链路是文档解析 → 文本切分 → embedding 生成 → 向量入库 → 检索 → 重排 → 喂给大模型生成答案。Halogen 主要管的是中间那段——把切分好的文本块批量生成 embedding并管理向量库的写入和检索。它不是一个一键部署的成品更像是一个编排层。你需要自己提供 embedding 模型、自己决定向量库用什么。这种设计的好处是灵活坏处是配置项多新手容易懵。我一开始就是被它的配置文件绕晕了后来理清楚每个字段对应链路里哪一环就顺了。部署本身不复杂从仓库拉下来装依赖git clone halogen-repo cd halogen pip install -r requirements.txt但requirements.txt里的依赖版本有时候会和你的 CUDA 版本打架。我遇到过一次torch版本和 CUDA 12.1 不匹配报错说找不到libcudart.so.11.0。解决办法是手动指定 torch 版本pip install torch --index-url https://download.pytorch.org/whl/cu121这个细节很关键很多人卡在这里以为是 Halogen 的问题其实是 torch 装错了。3.2 embedding 模型选型的实测对比embedding 模型的选择直接决定检索质量。热词里embedding模型排行是个高频搜索但排行榜上的模型不一定适合你的场景。我实测对比了几个主流的中文 embedding 模型数据如下模型维度6.4万块生成耗时检索准确率显存占用bge-large-zh-v1.51024约 22 分钟89%约 3GBbge-base-zh-v1.5768约 9 分钟84%约 1.5GBtext2vec-large-chinese1024约 25 分钟86%约 3GBm3e-base768约 10 分钟82%约 1.5GB准确率是我用 200 条人工标注的问答对测出来的衡量的是 top-5 召回里包含正确答案的比例。最后我选了 bge-large-zh-v1.5因为企业知识库对准确率的要求高于对速度的要求22 分钟的生成耗时是一次性的可以接受。这里有个经验不要盲目追求维度高的模型。维度高意味着向量库存储和检索开销都大。1024 维和 768 维在存储上差 33%6.4 万块的话1024 维 float32 大概占 250MB768 维占 190MB单看不大但检索时的距离计算量是实打实的。如果你的文档量到百万级这个差异就很明显了。模型下载下来之后用 Halogen 的配置指向本地路径不要每次从网上拉。配置大概长这样embedding: model_path: /data/models/bge-large-zh-v1.5 batch_size: 64 device: cuda max_length: 512batch_size这个参数要根据显存调。24GB 显存跑 bge-largebatch_size 给 64 很稳给 128 会 OOM。如果你显存小降到 16 或者 8慢一点但不会崩。3.3 文本切分策略对检索质量的影响这块是最容易被忽视、但对效果影响最大的环节。我一开始用的是固定长度切分每 512 个字符一刀切结果检索出来的块经常是半句话答非所问。后来改成按语义切分效果好很多。具体做法是先按段落切如果段落超过 512 字符再按句子切句子之间保留一定的重叠overlap。overlap 我设的是 64 字符这样跨块的语义不会断。Halogen 的配置里可以指定切分器splitter: type: semantic chunk_size: 512 chunk_overlap: 64 separators: [\n\n, \n, 。, , ]separators的顺序很重要优先按双换行段落切其次单换行最后按中文句号、感叹号、问号切。这样切出来的块语义完整度高。6.4 万块就是这么来的——原始文档大概 8000 多份平均每份切出 7-8 块。还有一个细节文档里的表格和代码块要特殊处理。表格如果被切开检索出来就是残缺的。我的做法是在切分前先把表格转成 Markdown 格式并给表格块打上标记检索时如果命中表格块优先返回完整表格。4. llama.cpp 的编译与推理加速4.1 为什么用 llama.cpp 而不是直接上大框架知识库的最后一环是把检索到的内容喂给大模型生成答案。这里有两个选择用 transformers 直接加载模型或者用 llama.cpp。我选 llama.cpp 的原因是它对量化模型支持好显存占用低推理速度快而且部署简单不依赖一堆 Python 框架。热词里llama.cpp android 版说明这东西跨平台能力确实强不过我们这里跑在 Ubuntu 服务器上用的是 CUDA 后端。编译 llama.cpp 的时候关键是开对编译选项git clone https://github.com/ggerganov/llama.cpp cd llama.cpp mkdir build cd build cmake .. -DLLAMA_CUDAON -DLLAMA_CUBLASON -DCMAKE_CUDA_ARCHITECTURES86 make -j32CMAKE_CUDA_ARCHITECTURES要填你显卡的计算能力。86 对应的是 RTX 30 系如果你用的是 40 系填 89。填错了编译能过但跑起来会用不了 GPU 加速性能差好几倍。查自己显卡的计算能力nvidia-smi --query-gpucompute_cap --formatcsv-j32是并行编译的核数按你 CPU 核数填能快不少。4.2 量化模型的选择与实测速度llama.cpp 支持多种量化格式从 Q4 到 Q8。量化越低模型越小、越快但质量损失越大。我实测了同一个 7B 模型的不同量化版本量化模型大小生成速度质量主观评分Q4_K_M约 4.1GB45 tokens/s7.5/10Q5_K_M约 4.8GB38 tokens/s8.2/10Q6_K约 5.5GB32 tokens/s8.6/10Q8_0约 7.2GB24 tokens/s9.0/10知识库问答场景对生成质量要求高因为答案要准确。我最后选了 Q6_K速度和质量的平衡点。45 tokens/s 和 32 tokens/s 在体感上差别不大但质量从 7.5 到 8.6 是能感觉出来的。启动推理服务./llama-server -m /data/models/qwen2-7b-q6_k.gguf \ --host 0.0.0.0 --port 8080 \ -c 4096 -ngl 99 -t 16-ngl 99是把所有层都放到 GPU 上-c 4096是上下文长度-t 16是 CPU 线程数。上下文长度这个参数要注意设太大显存会爆设太小检索到的内容塞不下。4096 对知识库场景够用因为检索出来的内容一般控制在 2000 token 以内。4.3 推理服务的稳定性处理llama-server 跑久了偶尔会卡死尤其是并发请求多的时候。我的做法是加一个健康检查脚本定时探测服务是否响应不响应就重启#!/bin/bash while true; do if ! curl -s http://localhost:8080/health /dev/null; then pkill -f llama-server sleep 2 nohup ./llama-server -m /data/models/qwen2-7b-q6_k.gguf \ --host 0.0.0.0 --port 8080 -c 4096 -ngl 99 -t 16 /var/log/llama.log 21 fi sleep 30 done这个脚本用nohup挂后台配合 systemd 做成服务更稳。我一开始没做这个结果半夜服务挂了第二天早上同事反馈知识库用不了才发现。后来加上健康检查再没出过问题。5. 向量库的选型与检索调优5.1 向量库到底选哪个热词里向量库检索需要什么数据库是个很实际的问题。我对比了几个主流方案向量库部署复杂度6.4万块检索延迟过滤能力适用场景FAISS低约 50ms弱纯向量检索无元数据过滤Chroma低约 120ms中小规模快速原型Milvus高约 80ms强大规模需要复杂过滤Qdrant中约 60ms强中等规模过滤需求多我最后选了 Qdrant。原因是它部署比 Milvus 简单过滤能力比 FAISS 强6.4 万块的规模用单机版完全够。Chroma 虽然更简单但它的索引结构在数据量上去之后性能下降明显我测到 5 万块的时候延迟就上到 300ms 了。Qdrant 用 Docker 部署最省事docker run -d --name qdrant \ -p 6333:6333 -p 6334:6334 \ -v /data/qdrant:/qdrant/storage \ qdrant/qdrant-v挂载数据目录很重要不然容器一删数据就没了。我踩过一次坑没挂载重建容器的时候 6.4 万块向量全没了只能重新生成白白浪费 20 多分钟。5.2 索引参数对检索速度的影响Qdrant 默认用的是 HNSW 索引这个索引有几个关键参数m、ef_construct、ef。m是每个节点的连接数越大索引越精确但越占内存ef_construct是建索引时的搜索范围越大索引质量越高但建得越慢ef是检索时的搜索范围越大越准但越慢。我的配置{ hnsw_config: { m: 16, ef_construct: 200, ef: 128 } }m16是默认值对 6.4 万块够用。ef_construct200比默认的 100 高建索引慢一点但检索质量好。ef128是检索时的参数这个值可以在查询时动态调我一般设 128延迟和准确率平衡得比较好。实测数据ef64时延迟 40ms召回率 82%ef128时延迟 60ms召回率 89%ef256时延迟 110ms召回率 91%。从 128 到 256召回率只涨 2%延迟翻倍不划算。所以 128 是甜点值。5.3 混合检索与重排的实战效果纯向量检索有个问题对关键词匹配不敏感。比如用户搜2023年Q3财报向量检索可能返回一堆财报相关的块但年份和季度对不上。解决办法是混合检索——向量检索和关键词检索各出一批结果然后融合。我的做法是用 Qdrant 的向量检索出 top-50同时用 BM25 关键词检索出 top-50然后用 RRFReciprocal Rank Fusion融合。融合后再用一个轻量级重排模型比如 bge-reranker-base对 top-20 重排最后取 top-5 喂给大模型。这套流程下来检索准确率从纯向量的 89% 提到了 94%。重排模型会增加约 80ms 延迟但值得。重排模型的部署和 embedding 模型类似也是用 Halogen 配置指向本地路径。这里有个经验重排模型的输入长度要控制。如果检索出来的块太长重排会慢。我的做法是重排前先把块截断到 512 token重排完再把完整块返回。这样既保证了重排速度又不丢失信息。6. 6.4 万块知识库跑起来之后的调优心得6.1 检索延迟从 8 秒降到 400 毫秒的完整过程最开始检索延迟 8 秒我一度以为是向量库的问题后来一步步排查发现瓶颈在好几个地方。完整排查链路是这样的第一步用curl直接打 Qdrant 的检索接口测出来延迟只有 60ms说明向量库本身没问题。第二步测 embedding 生成发现每次查询都要重新加载模型耗时 3 秒多。原因是 Halogen 默认配置里模型是懒加载的每次请求都重新初始化。改成常驻内存后这部分降到 50ms。第三步测重排发现重排模型也是每次重新加载又去掉 2 秒。第四步测大模型生成发现上下文塞了太多内容生成慢。把检索返回的块从 top-10 降到 top-5每块截断到 512 token生成时间从 2 秒降到 800ms。最后剩下的延迟主要在混合检索的 BM25 部分我用了 Elasticsearch 做关键词检索网络往返有开销。把 ES 和 Qdrant 部署在同一台机器上走本地回环延迟从 200ms 降到 30ms。全部优化完端到端延迟稳定在 400ms 左右。这个过程中最大的教训是不要一上来就怀疑最复杂的组件往往瓶颈在最不起眼的地方。6.2 内存和显存的监控与扩容判断6.4 万块跑起来之后内存和显存占用要盯着。我的监控脚本watch -n 5 free -h nvidia-smi --query-gpumemory.used,memory.total --formatcsv实测下来embedding 模型常驻占 3GB 显存重排模型占 1.5GB大模型 Q6_K 占 5.5GB加起来 10GB24GB 显存还有富余。内存方面Qdrant 占约 2GBElasticsearch 占约 4GBPython 服务占约 3GB总共不到 10GB128GB 内存绰绰有余。如果你的机器配置低比如只有 16GB 显存可以把 embedding 和重排模型换成 base 版本显存占用能降到 3GB 左右。大模型换成 Q4_K_M显存降到 4GB。这样总共 7GB16GB 显存能跑。6.3 文档更新与增量索引的处理知识库不是一次性的文档会更新。我的做法是给每个文档算一个哈希存到 Qdrant 的 payload 里。更新时先算新文档的哈希和库里比对一样就跳过不一样就删掉旧块、插入新块。这样避免全量重建索引。增量更新的代码逻辑大概是这样def update_document(doc_id, content): new_hash hashlib.md5(content.encode()).hexdigest() old qdrant.scroll(filter{doc_id: doc_id}, limit1) if old and old[0].payload[hash] new_hash: return qdrant.delete(filter{doc_id: doc_id}) chunks splitter.split(content) vectors embedder.encode(chunks) qdrant.upsert(points[...])这个逻辑看起来简单但有个坑删除和插入之间有时间窗口如果这时候有查询进来可能查不到这个文档。我的做法是加一个版本号查询时只查最新版本旧版本在后台异步删除。6.4 几个让我印象深刻的坑第一个坑是中文编码问题。有些文档是 GBK 编码的直接读进来是乱码embedding 出来全是噪声。解决办法是读文件时用chardet检测编码转成 UTF-8 再处理。第二个坑是 PDF 解析。有些 PDF 是扫描件直接解析出来是空的。这种要用 OCR我用的 PaddleOCR效果不错但慢。6.4 万块里有大概 500 块是扫描件OCR 花了两个多小时。第三个坑是向量维度不一致。我中途换过一次 embedding 模型从 768 维换到 1024 维结果 Qdrant 报错说维度不匹配。解决办法是换模型时必须重建 collection不能直接往旧 collection 里插。这个坑让我白白折腾了一下午。第四个坑是并发写入。批量生成 embedding 的时候如果多个进程同时往 Qdrant 写会偶发冲突。我的做法是写入串行化生成可以并行写入用一个队列排队。7. 关于这套方案的一些个人体会这套知识库从部署到真正跑顺前后花了三周多。回头看技术上的难点其实都不算难难的是每个环节都有细节细节没处理好整体效果就上不去。embedding 模型选对了切分策略不对检索还是不准检索准了重排没做答案还是偏重排做了大模型上下文塞太多生成又慢。我现在维护这套系统的日常工作是每周检查一次服务健康状态每月更新一次文档索引每季度评估一次检索准确率看是否需要调整模型或参数。6.4 万块的规模单机完全扛得住暂时没有分布式扩展的需求。如果你也在 Ubuntu 上折腾类似的东西我的建议是先把链路跑通哪怕用最小的模型、最少的文档先让整个流程走一遍。跑通之后再逐步替换成更好的模型、更大的数据量。一上来就追求完美配置很容易在某个环节卡住然后放弃。另外所有配置和参数都记下来包括为什么这么设过两个月你自己都会忘。