MaxKB 本地模型运行教程：模型下载、路径设置与性能优化指南

为什么要在 MaxKB 中运行本地模型

MaxKB 是面向企业和个人团队的 AI知识库平台，常用于搭建内部问答、文档检索、客服助手、运维助手和业务知识查询系统。默认接入在线大模型虽然上手快，但在数据可控、网络稳定、成本管理和离线环境方面会受到限制。本地模型方案的优势在于：知识库文档、用户问题和推理过程可以留在自有服务器内；调用成本更容易预测；在内网、实验室、生产机房等环境中也能持续运行；同时可以根据业务场景选择更轻量或更强的模型。

本地模型并不等于“装好就快”。模型大小、量化格式、显卡显存、内存、磁盘速度、MaxKB 与模型服务之间的网络路径，都会影响最终体验。合理的安装流程应包括四件事：确认运行环境、下载并存放模型、配置模型服务路径、在 MaxKB 中接入并调优。

准备工作：硬件、系统与模型选择

在安装前，建议先确认服务器配置。仅用于测试时，8GB 到 16GB 内存的普通主机可以运行 1.5B、3B 或 7B 的量化模型，但回答速度有限。若要多人使用，建议使用带独立显卡的机器，显存 8GB 可尝试 7B 量化模型，16GB 及以上显存可获得更稳定的体验。CPU 推理也能使用，但更适合低并发、轻量问答或演示环境。

系统方面，Linux 服务器更适合长期部署；Windows 或 macOS 可用于本地测试。磁盘建议预留足够空间，7B 模型通常需要数 GB 到十几 GB，模型缓存、知识库向量文件和日志也会持续增长。目录规划建议单独建立模型目录，例如 /data/models 或 D:models，避免放在系统盘或临时下载目录。

模型选择要贴合用途。中文知识库问答建议优先选择中文能力较好的通用模型，如 Qwen 系列等；若机器配置有限，可选择小参数量或量化版本；若追求长文档理解，应关注上下文长度。不要盲目下载最大模型，参数越大并不必然代表知识库效果越好，检索质量、分段策略和提示词同样关键。

模型下载：来源、格式与校验

常见本地模型接入方式有两类：一类是通过 Ollama 这类模型运行工具拉取并启动模型；另一类是使用支持 OpenAI 兼容接口的本地推理服务，如 vLLM、LM Studio 或其他推理框架。对普通用户来说，Ollama 上手较简单，适合快速把模型接入 MaxKB；对工程团队来说，OpenAI 兼容接口更便于统一管理和扩展。

下载模型时应优先选择官方模型库、可信社区仓库或团队内部镜像源，避免使用来源不明的压缩包。下载完成后，要记录模型名称、版本、量化类型、文件大小和存放路径。若页面提供校验值，应完成校验，防止文件损坏导致加载失败。对于生产环境，建议固定模型版本，不要在业务高峰期随意替换模型。

如果使用 Ollama，常见流程是先安装 Ollama，再执行模型拉取命令，例如拉取某个中文模型。模型会被保存到默认目录。若希望改到数据盘，需要设置模型存储路径，例如在 Linux 服务配置中设置 OLLAMA_MODELS=/data/models/ollama，或在 Windows 环境变量中指定对应目录。修改后重启 Ollama 服务，再确认模型是否能正常列表显示和启动。

路径设置：让 MaxKB 找到本地模型服务

MaxKB 本身通常不直接读取模型文件，而是通过模型服务接口调用本地模型。因此，路径设置分两层：第一层是模型文件存放路径，供 Ollama 或其他推理服务使用；第二层是模型服务访问地址，供 MaxKB 使用。很多新手问题都出在把“模型文件路径”和“接口地址”混为一谈。

以 Ollama 为例，先确认服务正在运行，默认端口通常为 11434。在 MaxKB 后台进入模型设置，选择对应的模型供应方式，填写服务地址。如果 MaxKB 与 Ollama 在同一台宿主机且都不是容器部署，可使用 http://127.0.0.1:11434。若 MaxKB 运行在 Docker 容器中，而 Ollama 运行在宿主机上，容器内的 127.0.0.1 指向容器自身，不能直接代表宿主机，此时应使用宿主机局域网 IP，或使用 Docker 支持的 host.docker.internal 地址，具体以当前系统支持情况为准。

如果模型服务和 MaxKB 分别部署在两台机器上，应确保二者网络可达，并只开放必要端口。服务地址填写后，在 MaxKB 中配置模型名称，名称要与本地模型服务中可调用的名称一致。随后进行连通性测试，测试通过后再创建应用或知识库问答流程。

在 MaxKB 中完成模型配置

进入 MaxKB 管理界面后，通常需要配置两类模型：对话模型和向量模型。对话模型负责生成回答，向量模型负责把文档与问题转换为可检索的向量表示。只接入对话模型而忽略向量模型，可能导致知识库检索效果不稳定；只配置向量模型而不配置对话模型，则无法形成完整问答。

配置对话模型时，重点检查供应方式、接口地址、模型名称、最大输出长度、温度等参数。知识库问答通常不建议温度过高，较低温度能让回答更稳定。最大输出长度要结合显存和业务需求设置，过大可能拖慢响应。配置向量模型时，应选择适合中文语义检索的嵌入模型，并保持文档入库与查询时使用同一个向量模型，避免向量空间不一致。

完成模型配置后，建议先用少量文档建立测试知识库。上传文档后观察解析、分段、向量化是否完成，再用典型问题测试召回结果。若回答与文档不一致，应先查看检索片段是否命中，而不是直接怀疑大模型能力。

性能优化：从模型、检索到部署一起调整

性能优化应分层进行。第一是模型层。配置一般的机器可选择 4bit 或 8bit 量化模型，速度和资源占用更友好；高显存机器可选择更高精度模型提升表达能力。上下文长度不要无上限增大，知识库问答更依赖精准检索，过长上下文会增加计算时间。

第二是服务层。若使用显卡，确保推理服务正确识别显卡驱动和运行库。并发用户较多时，可以限制单次最大生成长度、设置合理超时时间，并根据硬件能力控制并发数。日志中若频繁出现加载模型耗时，说明模型没有常驻或内存压力过大，需要减少模型数量或增加资源。

第三是知识库层。文档分段过短会丢失上下文，过长会降低检索精度。通用建议是按标题、段落和语义结构切分，并设置适当重叠。TopK 不宜过大，通常先从 3 到 6 调试；相似度阈值过低会引入无关片段，过高又可能召回不足。对于制度、手册、产品说明等结构化文档，保留标题层级能明显提升回答准确率。

第四是提示词层。建议在应用提示词中明确要求“仅基于知识库内容回答，无法确认时说明未找到依据”，这样可以减少模型自由发挥。涉及操作步骤、版本差异、配置项时，可要求模型列出依据片段或提示用户核对版本。

常见问题与排查方法

问题一：MaxKB 连接本地模型失败。优先检查模型服务是否启动、端口是否正确、容器内是否能访问宿主机地址、防火墙或安全组是否阻断。不要只在宿主机浏览器测试，容器部署时应从容器网络视角验证。

问题二：模型名称填写后仍提示不存在。通常是 MaxKB 中填写的名称与模型服务中的实际名称不一致，或模型尚未拉取完成。可在模型服务侧查看模型列表，复制完整名称再填写。

问题三：回答很慢。原因可能是模型过大、CPU 推理、上下文过长、TopK 过高、并发过多或磁盘读取慢。先用单轮简单问题测试基础速度，再逐步加入知识库检索，定位瓶颈。

问题四：知识库命中了文档但回答不准确。可调整提示词，降低温度，优化分段，并检查文档是否存在过期内容。若多个文档结论冲突，应增加版本字段或在文档标题中标明适用范围。

问题五：上传文档后一直处理中。可能是向量模型未配置、模型服务不可用、文档过大或格式解析异常。建议先用小文件测试，再分批导入大型资料。

安全边界与维护建议

本地部署并不代表没有风险。模型文件应来自可信来源，服务端口不要面向无关网络开放，管理后台应设置强密码并限制访问范围。知识库中若包含内部资料，应明确权限边界，避免把所有文档放进同一个公开应用。

升级模型或 MaxKB 前，建议备份配置、知识库数据和模型清单。生产环境不要直接覆盖旧模型，可先在测试环境验证回答质量、速度和兼容性，再安排切换。若升级后效果变差，应保留回退路径，例如保留旧模型目录、旧服务配置和旧版应用参数。

日常维护可关注三项指标：响应时间、检索命中率和用户反馈。响应变慢时检查资源占用；命中率下降时检查文档更新和分段策略；反馈集中在某类问题时，优先补充高质量文档，而不是单纯更换更大的模型。只要把模型、路径、检索和提示词这几层配置理顺，MaxKB 本地模型方案就能稳定支撑多数知识库问答场景。