内网离线环境部署AI知识库怎么实现

文章导读
内网离线部署 AI 知识库,真正卡住人的通常不是“装哪个模型”,而是文档解析、向量化、检索、生成这四段链路能不能全部转成本地制品,并且启动时不去公网拉任何东西。判断可行性之前,先确认内网有没有可用的软件源镜像、目标机器的算力和显存、知识库规模与更新频率,这几项决定了后面是走容器化整包交付,还是只能做轻量单机方案。
📋 目录
  1. 壹 先确认当前场景和目标
  2. 贰 按这个顺序处理
  3. 叁 改完后怎么验证
  4. 肆 容易忽略的边界
A A

内网离线部署 AI 知识库,真正卡住人的通常不是“装哪个模型”,而是文档解析、向量化、检索、生成这四段链路能不能全部转成本地制品,并且启动时不去公网拉任何东西。判断可行性之前,先确认内网有没有可用的软件源镜像、目标机器的算力和显存、知识库规模与更新频率,这几项决定了后面是走容器化整包交付,还是只能做轻量单机方案。

适用场景是物理隔离或只放行极少出口的内网。操作动作是先盘点依赖——模型权重、embedding 模型、Python 包、基础镜像、系统库——全部提前下载并转成本地制品,再按“文档解析 → 向量库 → 推理服务 → 检索编排 → 前端”的顺序部署。验证方式是断网重启后跑一遍从上传文档到回答带出处的完整流程,并检查日志里没有对外重试。风险边界是模型体积、显存和许可证要先确认,任一不满足就回退到更小参数模型或缩减知识库范围,不要硬上。

先确认当前场景和目标

“离线”有三种常见形态,处理成本差别很大:完全物理隔离、只有内网 yum/apt/pip 镜像源、能临时带一台机器出去同步。如果内网已有 pip 和容器镜像仓库,离线工作量主要落在模型权重和系统库上;如果什么都没有,就要先把一套制品仓库搭起来,否则后面每加一个依赖都要重新搬介质。

建议在动手前把下面几项写清楚,作为是否继续的判断条件:

  • 推理算力:有没有 GPU、显存多少、驱动版本是什么。CPU 推理能跑,但响应时间需要提前和使用方对齐,不要事后解释。
  • 文档规模:几千份和几十万份,对向量库选型、分块策略、索引重建时间的影响完全不同。
  • 更新频率:知识库是每周增量更新还是几乎不变,决定要不要做双索引切换。
  • 权限:能否申请内网端口和域名、能否部署常驻服务、模型目录由哪个账号读写。
  • 合规:模型和 embedding 模型的使用许可是否覆盖内部使用,文档是否允许落盘到向量库。

这五项里如果有两项以上不明确,建议先做一个小范围试点,用几十份文档把链路跑通,而不是一次性把全量知识库导入。

按这个顺序处理

顺序错了最容易返工。建议按下面六步推进,每一步都有可检查的产出。

  1. 列依赖清单并做离线制品包。包括推理模型权重、embedding 模型、Python wheel(用 pip download 带上目标平台参数)、基础镜像(docker save 成 tar)、以及分词器、字体等系统级依赖。清单要写到版本号,不能只写包名。
  2. 在内网建最小制品仓库。私有容器镜像仓库加一个本地 PyPI 源即可,模型文件放共享存储挂载,不要塞进镜像层,否则镜像体积会失控。
  3. 按链路顺序部署。先文档解析(PDF/Word/HTML 转文本并分块),再向量库,再推理服务,最后检索编排和前端。每上一段就先单独验证,不要等全部装完再一起调。
  4. 切断所有隐式外联。多数推理框架默认会去模型仓库检查更新,需要显式关闭离线下载开关并去掉遥测,具体环境变量名要结合所用框架版本确认,不能照抄。同时确认容器内 DNS 解析不到外网时服务仍能正常启动。
  5. 固定检索参数并写进配置。分块大小、重叠长度、召回条数、相似度阈值这些参数要落在配置文件里,便于复现和调整,不要散落在代码常量中。
  6. 做一份离线安装手册。把制品清单、加载顺序、端口、挂载路径、回退步骤写成一页,交付给运维,避免只有一个人会装。

下面是容器编排的服务清单骨架,镜像地址替换成内网仓库地址,挂载路径按实际机器修改,只用于表达服务划分,不涉及具体版本:

内网离线环境部署AI知识库怎么实现
services:
  doc-parser:
    image: registry.intra.local/rag/parser:<tag>
    volumes: ["/data/kb/raw:/data/raw", "/data/kb/chunks:/data/chunks"]
  vector-db:
    image: registry.intra.local/rag/vector-db:<tag>
    volumes: ["/data/kb/vectordb:/var/lib/vectordb"]
  llm:
    image: registry.intra.local/rag/llm-server:<tag>
    volumes: ["/data/models:/models"]
    environment:
      MODEL_PATH: /models/<your-model>
      OFFLINE_MODE: "true"
  rag-api:
    image: registry.intra.local/rag/api:<tag>
    environment:
      VECTOR_DB_URL: http://vector-db:<port>
      LLM_URL: http://llm:<port>
      TOP_K: "5"
      SCORE_THRESHOLD: "0.3"

检索编排这一层建议单独定义一个请求结构,把“检索到什么”和“模型怎么答”分开,方便验证时单独定位问题:

{
  "question": "用户的原始问题",
  "top_k": 5,
  "score_threshold": 0.3,
  "answer_rule": "仅依据检索片段回答,无相关内容时回复:知识库中未找到相关说明",
  "need_citation": true
}

这段配置放在 rag-api 的请求模板里,替换 top_k 和阈值后即可用于不同知识库的调试;need_citation 打开后,前端要能展示来源文件名和片段位置,否则无法判断是检索错了还是模型答偏了。

改完后怎么验证

验证的核心是断网后仍能完整跑通,而不是“服务起来了”。建议按下面的动作逐项确认:

  • 断网重启。把出站流量全部拦住后重启所有服务,观察日志里是否出现连接模型仓库、检查更新、上报遥测之类的重试记录。预期信号是启动日志干净,没有超时重试。
  • 问一个只有某份文档能回答的问题。预期信号是回答内容与该文档一致,并且出处指向正确文件。如果答对但出处错乱,通常是分块或元数据写入有问题。
  • 问一个知识库范围外的问题。预期信号是明确说明未找到相关内容。这一条比答对更能说明检索链路没有退化成纯模型自由发挥。
  • 核对数量。向量库中的记录条数与解析后的分块数应当能对上,对不上时先查解析失败的文件,而不是调检索参数。
  • 多用户同时提问。观察推理服务的内存和显存占用是否稳定,是否出现进程被杀。预期信号是持续可用,而不是某次请求后服务无响应。
  • 重建一次索引。确认从原始文档到可检索状态的流程可以重复执行,这是后续更新知识库的前提。

容易忽略的边界

以下几处在内网环境里翻车频率较高,建议在部署前逐条确认,并准备对应的回退方式。

  • 版本匹配。离线镜像里的 CUDA 或系统库版本如果高于目标机器驱动支持的范围,推理服务会直接起不来,且报错信息往往不直观。可以先用一个最小镜像在目标机器上跑一次加载测试,再决定是否批量部署。
  • 目录权限。模型目录和向量库目录需要容器内运行账号可读写,挂载后写入失败通常表现为“上传成功但检索不到”,排查时先看挂载点权限。
  • 静态资源外链。部分前端页面会引用外部字体或图标库,断网后样式缺失但功能正常,容易被误判为部署失败。建议把静态资源一并本地化。
  • 许可证。模型权重和 embedding 模型的开源许可范围不同,有的对商用或再分发有额外要求,需单独确认,不能只看仓库是否公开。
  • 回退方案。显存不足时优先回退到更小参数的模型或降低分块与召回数量,不建议用 swap 或临时缓存顶替,那只会把问题推迟到并发时暴露。知识库更新如果需要全量重建,应提前预留时间窗口,或采用新旧两套索引切换的方式。
  • 不适用条件。如果内网既没有可用的镜像仓库,也不允许部署常驻服务,那么完整 RAG 方案并不合适,可以先退回“离线文档检索 + 人工阅读”的轻量形态,等基础条件具备再推进。