一、部署概述

本文要完成的部署任务是：在一台桌面操作系统主机上，搭建一套“完全本地化”的知识库问答系统。整套系统由三部分组成：

1. 容器引擎与容器编排组件：以容器方式承载知识库应用及其依赖的存储、检索等组件，保证环境一致、部署可重复；
2. 本地模型运行框架：一个开源的本地大模型管理工具，负责模型的下载、版本管理与推理服务暴露，本文用它同时承载向量化模型与对话大模型；
3. 开源知识库应用：负责文档解析、切片、向量化、检索与问答编排，通过配置对接上述本地模型服务。

部署完成后应达到的效果是：文档上传、向量化索引、检索问答的全部计算与数据都发生在本地主机，不依赖任何外部推理服务，数据不出内网。该部署方式适合开发者、运维人员、企业技术团队，以及对文档隐私敏感、需要在离线或内网环境使用知识问答能力的用户。

需要说明的是，完全本地化对本地硬件有一定要求；如果本地算力不足，也可以考虑将推理环节替换为百度智能云等云端模型服务，通过接口方式接入知识库，但本文聚焦“全本地”方案展开。

二、部署场景与整体架构

2.1 典型适用场景

• 企业内部文档问答：制度、规范、项目资料等不宜外发的文档，构建内部检索问答入口；
• 个人知识管理：将笔记、论文、技术文档沉淀为可提问的知识库；
• 内网/离线环境：无法访问外部网络或不允许数据外发的环境；
• 方案验证：在大模型服务上云前，先在本地验证检索增强问答的可行性。

2.2 组件与数据流拆解

从部署视角看，整套系统涉及以下组件：

组件	部署形态	作用	关键资源
容器引擎	桌面版容器运行时	运行知识库应用及其依赖容器	CPU、内存、磁盘
知识库应用	容器编排部署的多容器服务	文档解析、切片、检索、问答编排	端口、持久化卷
本地模型运行框架	宿主机原生安装	模型下载管理与推理API	内存/显存、模型磁盘空间
向量化模型	由模型框架加载	将文本切片转为向量	内存/显存
对话大模型	由模型框架加载	生成回答	内存/显存

数据流为：用户上传文档 → 知识库应用解析切片 → 调用本地向量化模型生成向量 → 向量与知识数据写入本地存储 → 用户提问 → 知识库检索相关切片 → 调用本地对话模型生成答案。整个链路只经过本地回环网络，理解这一点对后续的网络与安全配置非常重要。

三、前置准备

3.1 硬件与磁盘规划

• 内存：建议16GB起步，运行7B级别对话模型与容器服务时余量更充足；
• 磁盘：这是最容易踩坑的资源项。模型文件、容器镜像、向量与图谱数据都会占用大量空间，建议为文档与模型合计预留数十GB以上；
• 安装位置：本地模型运行框架的默认安装目录和模型下载目录通常落在系统盘。系统盘空间紧张会直接导致模型下载失败或系统卡顿，因此强烈建议在部署前就把安装目录与模型存储目录规划到非系统盘；
• GPU：可选。有独立显卡时推理速度明显提升，没有也能以CPU模式运行，只是生成速度较慢。

3.2 软件与网络准备

• 一台安装了某主流桌面操作系统的主机，具备管理员权限；
• 容器引擎桌面版安装包，从其官方网站下载对应操作系统版本；
• 本地模型运行框架安装包，从其官方网站下载；
• 知识库应用的官方文档与容器编排文件；
• 网络：下载镜像与模型阶段需要访问外网，运行阶段可完全离线。若内网环境受限，可先在有网环境下载再离线导入。

3.3 版本与兼容性确认

部署前应查阅知识库应用官方文档中的系统版本与软件要求，确认容器引擎版本、操作系统版本满足其最低要求。环境一致性是部署成功的隐性前提：验证环境与最终使用环境尽量使用同一套版本组合，避免“本地能跑、换机不行”的问题。

四、部署流程

按照“容器引擎 → 模型运行框架 → 知识库应用 → 模型准备 → 服务对接”的顺序执行，前两步相互独立，可并行准备。

4.1 安装容器引擎

从容器引擎官网下载与操作系统匹配的版本，按向导安装即可。桌面系统上容器引擎通常依赖虚拟化能力，若安装后无法启动，优先检查主机的虚拟化选项是否开启。安装完成后打开客户端，能看到本机镜像与容器列表即说明引擎就绪。后续知识库应用的所有服务都将以容器形式运行在这里。

4.2 安装本地模型运行框架

从官网下载安装包。这里有一个关键细节：直接双击安装，程序本体和后续下载的模型都会落到系统盘。如果系统盘空间紧张，应在安装阶段就改到其他盘。

做法是在安装包所在目录打开命令行终端，执行带路径参数的安装命令，例如：

<安装程序文件名> /DIR="D:\soft\model-runtime"

即通过安装器的目录参数，把程序指定安装到非系统盘的专用软件目录。安装完成后框架会自动启动。随后还需把“模型下载存储位置”也指向非系统盘，可通过框架的设置项或环境变量实现。这一步与安装目录同等重要——模型文件体积远大于程序本体，是磁盘占用的主要来源。

4.3 部署知识库应用

打开命令行终端，参照知识库应用官方文档执行两步操作：

第一步，获取容器编排文件。使用常见的命令行下载工具，将官方文档提供的编排文件保存到本地：

<命令行下载工具> <官方文档提供的编排文件地址> -o compose.yaml

第二步，使用容器编排命令在后台拉起全部服务：

<容器编排命令> -f compose.yaml up -d

编排文件中定义了知识库应用运行所需的多个容器（应用服务、存储、检索等组件）。首次执行会拉取全部镜像，耗时与网络状况相关，需要耐心等待。执行完成后回到容器引擎客户端查看，可以看到一组新容器处于运行状态，这代表知识库应用的服务端已经启动。

4.4 在模型框架中准备两个模型

知识库应用需要两类模型，缺一不可：

1. 向量化模型：负责把文档切片转成向量，直接决定检索质量；
2. 对话大模型：负责阅读检索结果并生成回答，决定回答质量。

在命令行中分别拉取：

<模型运行工具> pull <向量化模型名称>
<模型运行工具> pull <对话大模型名称>

选型上有两点建议：向量化模型优先选择对中文支持好、维度适中的版本；对话模型根据内存/显存选择参数规模，资源有限时选择量化版本，在质量与资源间取平衡。拉取完成后，可先在命令行直接与对话模型交互一轮，确认模型本体可用，再进入对接环节。

4.5 配置知识库应用对接本地模型

进入知识库应用的模型配置界面（或按官方文档修改配置文件），完成三件事：

1. 将模型服务地址指向本地模型运行框架监听的本地回环地址与端口（具体端口以官方文档为准）；
2. 分别填写向量化模型与对话大模型的模型名称，必须与上一步拉取的名称完全一致；
3. 保存并执行连接测试，确认知识库应用可以正常调用本地推理服务。

配置逻辑上，知识库应用把模型框架当作一个标准的本地推理服务来调用，因此“地址+端口+模型名”三项中任何一项不一致，都会在后续向量化或问答环节报错。

五、上线验证

部署是否成功，要用可观察的证据确认，而不是“页面能打开就行”。建议按以下清单逐项验证：

1. 容器状态：知识库相关容器全部处于运行状态，无反复重启的容器；
2. 端口监听：知识库应用与模型框架的本地端口均在监听，浏览器可正常打开知识库页面；
3. 模型推理：命令行或模型框架自带界面对话模型能正常返回内容；
4. 向量化链路：上传一份样例文档，观察解析、切片、向量化过程无报错；
5. 问答效果：针对样例文档内容提问，答案能命中文档内容并给出引用；
6. 日志检查：容器日志与模型框架日志中无持续报错。

六项全部通过，才可认为部署完成并进入日常使用。

六、常见问题与排查

• 镜像拉取缓慢或失败：多为网络问题，可配置镜像加速、更换时段重试，或离线导入镜像；
• 容器启动失败或反复重启：优先查看对应容器日志，常见原因是端口被占用、内存不足或编排文件版本不匹配；
• 模型下载中断：重新执行拉取命令即可续传；若提示磁盘不足，回到3.1检查模型存储目录是否已迁移到非系统盘；
• 知识库连不上模型服务：核对地址、端口、模型名三项配置，确认模型框架进程在运行，检查本地防火墙是否拦截了回环端口；
• 向量化或问答报错：多为模型名称填写不一致，或资源不足导致推理进程被终止，可先降低模型规模验证链路；
• 系统盘空间持续告警：通常是模型目录未迁移或容器镜像堆积，清理无用镜像并迁移模型目录。

七、本地模型API的复用与扩展

本地模型运行框架除了服务知识库应用，本身还是一个标准的本地推理服务：它在本地端口暴露通用的推理API，任何支持自定义模型服务地址的应用都可以接入。这带来两个实用的扩展方向：

1. 二次开发：业务系统可以把对话、摘要、向量化等能力直接调用本地API，构建内网智能应用；
2. 辅助编程：部分AI编程助手类工具支持自定义模型供应商，将其模型地址配置为本地模型框架的监听地址与本地模型名后，即可在编码场景中调用本地大模型，实现代码补全与生成不出本机。

需要注意的是，接入编程助手后推理负载会明显上升，应结合内存/显存余量评估并发，必要时降低模型规模。

八、运维与优化建议

• 监控与告警：持续关注内存、显存、磁盘水位与容器健康状态，磁盘是本方案最常见的故障源；
• 数据备份：定期备份原始文档、向量与图谱数据的持久化卷，以及编排文件与模型配置，做到可重建；
• 版本升级与回滚：升级前保留当前镜像与编排文件副本，升级失败时可快速回退到旧版本组合；
• 安全控制：默认所有服务只监听本地回环地址；如需局域网内他人访问，应在网络层做访问控制，并为知识库应用启用身份认证；
• 性能优化：有条件时启用GPU推理，选择量化模型，控制同时加载的模型数量，避免内存互换导致响应骤降；
• 成本治理：定期清理不再使用的模型与镜像，评估文档增量，为存储预留生命周期策略。

九、总结

本文完整走通了“容器引擎 + 本地模型运行框架 + 开源知识库应用”的完全本地化部署：先完成容器引擎与模型框架的安装，并重点做好安装目录与模型目录的非系统盘规划；再通过编排文件一键拉起知识库容器服务；随后在模型框架中准备向量化模型与对话大模型，并在知识库应用中完成“地址、端口、模型名”三项对接；最后通过容器状态、端口监听、推理测试、向量化与问答链路六项验证确认上线。部署完成后的重点运维方向是磁盘与内存水位监控、数据持久化卷备份、版本升级回滚以及本地回环之外访问的安全控制。按此路径执行，即可获得一套数据不出本地、可长期使用的私有知识问答系统。