内网离线部署 AI 知识库,真正卡住人的通常不是“装哪个模型”,而是文档解析、向量化、检索、生成这四段链路能不能全部转成本地制品,并且启动时不去公网拉任何东西。判断可行性之前,先确认内网有没有可用的软件源镜像、目标机器的算力和显存、知识库规模与更新频率,这几项决定了后面是走容器化整包交付,还是只能做轻量单机方案。
适用场景是物理隔离或只放行极少出口的内网。操作动作是先盘点依赖——模型权重、embedding 模型、Python 包、基础镜像、系统库——全部提前下载并转成本地制品,再按“文档解析 → 向量库 → 推理服务 → 检索编排 → 前端”的顺序部署。验证方式是断网重启后跑一遍从上传文档到回答带出处的完整流程,并检查日志里没有对外重试。风险边界是模型体积、显存和许可证要先确认,任一不满足就回退到更小参数模型或缩减知识库范围,不要硬上。
先确认当前场景和目标
“离线”有三种常见形态,处理成本差别很大:完全物理隔离、只有内网 yum/apt/pip 镜像源、能临时带一台机器出去同步。如果内网已有 pip 和容器镜像仓库,离线工作量主要落在模型权重和系统库上;如果什么都没有,就要先把一套制品仓库搭起来,否则后面每加一个依赖都要重新搬介质。
建议在动手前把下面几项写清楚,作为是否继续的判断条件:
- 推理算力:有没有 GPU、显存多少、驱动版本是什么。CPU 推理能跑,但响应时间需要提前和使用方对齐,不要事后解释。
- 文档规模:几千份和几十万份,对向量库选型、分块策略、索引重建时间的影响完全不同。
- 更新频率:知识库是每周增量更新还是几乎不变,决定要不要做双索引切换。
- 权限:能否申请内网端口和域名、能否部署常驻服务、模型目录由哪个账号读写。
- 合规:模型和 embedding 模型的使用许可是否覆盖内部使用,文档是否允许落盘到向量库。
这五项里如果有两项以上不明确,建议先做一个小范围试点,用几十份文档把链路跑通,而不是一次性把全量知识库导入。
按这个顺序处理
顺序错了最容易返工。建议按下面六步推进,每一步都有可检查的产出。
- 列依赖清单并做离线制品包。包括推理模型权重、embedding 模型、Python wheel(用 pip download 带上目标平台参数)、基础镜像(docker save 成 tar)、以及分词器、字体等系统级依赖。清单要写到版本号,不能只写包名。
- 在内网建最小制品仓库。私有容器镜像仓库加一个本地 PyPI 源即可,模型文件放共享存储挂载,不要塞进镜像层,否则镜像体积会失控。
- 按链路顺序部署。先文档解析(PDF/Word/HTML 转文本并分块),再向量库,再推理服务,最后检索编排和前端。每上一段就先单独验证,不要等全部装完再一起调。
- 切断所有隐式外联。多数推理框架默认会去模型仓库检查更新,需要显式关闭离线下载开关并去掉遥测,具体环境变量名要结合所用框架版本确认,不能照抄。同时确认容器内 DNS 解析不到外网时服务仍能正常启动。
- 固定检索参数并写进配置。分块大小、重叠长度、召回条数、相似度阈值这些参数要落在配置文件里,便于复现和调整,不要散落在代码常量中。
- 做一份离线安装手册。把制品清单、加载顺序、端口、挂载路径、回退步骤写成一页,交付给运维,避免只有一个人会装。
下面是容器编排的服务清单骨架,镜像地址替换成内网仓库地址,挂载路径按实际机器修改,只用于表达服务划分,不涉及具体版本:

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 方案并不合适,可以先退回“离线文档检索 + 人工阅读”的轻量形态,等基础条件具备再推进。