Hermes-Agent与Ollama离线对接：大模型完全本地化运行指南

前阵子接了一个内部项目，要求把 Agent 的全部能力完整落到内网环境里，断网状态下也必须照常工作。调研一圈，最终敲定的组合就是 Hermes-Agent 对接本地 Ollama 大模型，完全离线运行。这套方案从安装到调通，前前后后踩了不少坑，今天把完整过程整理出来，给同样被离线部署折腾的朋友做个参考。文章会按环境准备、模型选型、对接配置、离线隔离、问题排查的顺序展开，既有可以直接抄的配置命令，也有我在实际环境里遇到的边界情况和取舍。默认你已经具备基础的 Python 环境，也大概知道 Agent 是干什么的，但对 Ollama 不需要有太深的研究，按步骤走基本能复现。

1. 先说结论：为什么是 Hermes-Agent + Ollama 这个组合

1.1 Hermes-Agent 在整个方案里负责什么

Hermes-Agent 本质上是一个以任务为中心的智能体框架，它解决的核心问题是"怎么把大模型的能力变成能完成实际任务的自动化流程"。你丢给它一个任务描述，它能自己拆解步骤、调用工具、汇总结果，最后输出一个可读的结论。和普通聊天机器人不同，Agent 的重点在于工具调用和流程编排，而这两者都极度依赖底层大模型的指令跟随能力和结构化输出稳定性。

在架构上，Hermes-Agent 对模型层做成了可插拔设计，支持通过标准的 OpenAI 兼容接口去对接不同的模型服务端。这一点是它最打动我的地方。正因为有兼容接口，我才能在几乎不动业务代码的情况下，把原来指向云端模型的配置，直接改成指向本地 Ollama 服务，这也是整篇博文所有操作的大前提。如果你手头的 Agent 框架也支持 OpenAI 兼容的 base_url 配置，那这套对接思路完全可以迁移过去。

1.2 推理底座为什么选 Ollama 而不是其他

选 Ollama 是综合权衡的结果。第一，它对硬件资源的管理做得比较到位，显存不够时会自动把部分层卸载到内存里继续跑，这在公司内部配置参差不齐的机器上特别重要。第二，模型管理足够省心，一条ollama pull就把下载、量化、目录组织全部搞定，不需要像 llama.cpp 那样手动折腾 GGUF 文件路径。第三，它默认提供 OpenAI 兼容的 API 端点，Agent 框架改两三个配置项就能接通。

对比一下其他方案就清楚了。vLLM 的吞吐和并发性能更强，但部署复杂度高，对显存规划要求严格，不太适合中小规模内网环境；llama.cpp 虽然灵活，但完整的服务化、并发管理、多模型切换都要自己搭建，开发成本太高。Ollama 正好卡在"够用"和"好用"之间。另外还有一点，Ollama 可以把模型目录单独指定，这在做多台机器批量离线部署时特别方便，后面章节会详细讲。

1.3 整套离线方案由哪几部分组成

整套系统可以拆成三个部分：Agent 框架、Ollama 服务、本地模型文件。数据流是这样的：Hermes-Agent 发起推理请求，走的是http://localhost:11434/v1这个本地端点，Ollama 收到请求后加载本地模型执行推理，整个过程不会触碰外网。

这里"完全离线"其实包含两层含义。第一层是运行时完全不依赖外网，模型文件、推理服务、Agent 进程全部在本地；第二层是准备阶段也尽量不依赖公网下载，用离线迁移的手段把模型包拷进目标机器。很多人只关注第一层，结果部署当天卡在网络准备上，我这次会把两层都讲透，尤其是模型迁移的细节。

提示：如果你只是临时体验，跑通一个联网下载模型的版本只需要半小时；如果要上生产环境，强烈建议把离线迁移的步骤提前规划好，别等部署当天才处理。

2. 环境准备：从零搭好 Ollama 底座

2.1 先评估硬件：不同配置怎么选模型

硬件配置直接决定模型选型。有 NVIDIA GPU 的情况下，16GB 显存以上可以很舒服地跑 7B~8B 参数量、4bit 量化的模型，推理速度每秒几十个 token；8GB 显存也能跑，但建议优先考虑 3B 参数的模型，或者 7B 的 Q4_K_M 量化版，而且要控制并发。完全没有 GPU 的纯 CPU 机器也能跑，不过 7B 模型每秒大概只有 2~5 个 token，做 Agent 的多轮工具调用会等到怀疑人生，适合做功能验证，不适合生产。

我这次实际部署用了一台 Ubuntu 22.04 的服务器，NVIDIA 驱动已经装好，一张 24GB 显存的 GPU，跑 Qwen2.5 7B 非常轻松。如果你的目标场景是更边缘的设备，比如 Jetson Orin 这类小盒子，Ollama 官方也有对应的安装方式，但显存、内存的规划要更保守，模型优先选 3B 级别，并且把上下文长度调短一些，否则容易触发内存交换。总之，硬件评估先做，模型选择跟着硬件走，别反过来。

2.2 安装 Ollama 的两种方式

如果部署机器能访问外网，安装非常简单，官方提供了一键脚本：

curl -fsSL https://ollama.com/install.sh | sh

装完检查版本：

ollama --version

服务默认由 systemd 托管，查看状态和启动命令：

systemctl status ollama systemctl start ollama

如果想调试，可以直接前台执行ollama serve，日志会直接打到终端，排查问题非常方便。这个方式我在初期排查服务异常时用得最多。

如果目标机器完全隔离，那就提前下载好对应发行版的 DEB/RPM 安装包再拷进去安装。还有更省事的办法：在一台网络通畅的机器上装好 Ollama 并把模型拉好，然后把整个安装目录和模型目录一起打包带走，只要目标机器的系统依赖库版本差异不大，解压后基本能直接跑。要注意的是，这种方式对 glibc 版本和 CUDA 驱动版本有一定要求，最好先在一台测试机上试跑再批量分发。

2.3 拉模型太慢怎么破：离线迁移兜底

"ollama 下载慢"是我在社区里看到频率最高的问题之一。我个人的建议是：不要在慢的问题上反复折腾，直接把"离线迁移"作为主线方案。具体操作分三步：先在一台网络好的机器上把需要的模型一次性拉全，然后把~/.ollama/models整个目录打包，最后拷贝到目标机器解压到位。模型文件打包通常有几个 GB 到十几 GB，用内网传输或者 U 盘拷贝都很快，比公网断断续续下载快得多。

这里有个非常关键的点：一次要把任务涉及的模型全拉齐，不要缺一个拉一个。我第一次部署时就只拉了对话模型，后来 Agent 要用的工具调用模型没拉，又等了大半天，非常被动。所以动手之前先想清楚：是中文为主还是英文为主，需不需要支持代码生成，这些都会影响模型清单。另外，拉模型时可以在ollama pull后面直接指定带标签的量化版本，比如qwen2.5:7b-q4_K_M，下载体积会比默认版本更小。

2.4 模型怎么选：按任务类型匹配

模型选型是整个项目里最容易返工的决定。我的选择逻辑是：中文理解和生成是刚需的场景，优先选 Qwen2.5 系列，它在中文指令跟随和内容生成上普遍比同体积的国外模型稳；偏英文、代码生成、工具调用密集的场景，可以考虑 Llama 3.1/3.2 系列，Llama 的 Tool Calling 格式非常规整；希望上下文更长、指令跟随更细的，Mistral 系模型也值得一试，但在中文上弱一些。

选模型不要盲目追参数。Agent 框架最依赖的是模型对结构化 JSON 输出的稳定性和工具调用的准确率，这两点 7B/8B 量级模型已经能打得不错。我建议先把 7B 规格跑通一条完整链路，再根据任务复杂度决定要不要上 14B 或更大。以下是常见的模型选择参考：

拉取命令以 Qwen 为例：

ollama pull qwen2.5:7b ollama pull llama3.1:8b

拉完用ollama list确认模型已经就位。这一步做完，Ollama 侧就算准备好了。

3. 核心对接：Hermes-Agent 与 Ollama 怎么接

3.1 先找到 Hermes-Agent 的模型配置入口

对接的第一步是找到配置入口。不同版本的 Hermes-Agent 命名可能不一样，但思路一致：要么在项目根目录的.env环境变量文件里，要么在config目录的 YAML 配置里，会有一块专门描述大模型接入的配置段，字段通常是provider、model、base_url、api_key、temperature这几个。你只要把这里的值改成 Ollama 对应信息即可。

打开配置文件后，不要急着改，先看一眼现有配置指向哪里。如果原来用的是云端模型，那 base_url 大概率是一长串外网地址，后面我们会把它替换成本地地址。注意只改关键字段，别把整段配置删了，因为 Agent 的其他参数，比如人设提示词、工具列表、回调地址，都还在这份配置里，删错了又要重写。

3.2 关键字段怎么写：base_url 是最大的坑

这是全篇最核心的一段，直接给可用配置：

# Hermes-Agent 模型配置段（示例） model: provider: openai model: qwen2.5:7b base_url: http://localhost:11434/v1 api_key: ollama temperature: 0.7 max_tokens: 2048 timeout: 120

逐项解释一下这样写的理由。provider填openai，是因为 Hermes-Agent 通过 OpenAI 兼容接口调用模型，而 Ollama 原生实现了这套接口。model的值必须和ollama list里看到的名称完全一致，包括标签，很多对接失败都是因为模型名写错了一个冒号。base_url必须带/v1后缀，Ollama 的兼容接口挂在这个路径下，少了它就会出现 404。

api_key可以随便填，Ollama 不校验 key，但客户端库一般不允许空字符串，所以填ollama或local都行。timeout建议设置到 120 秒以上，因为首次请求时 Ollama 需要把模型从磁盘加载到显存，冷启动可能耗时十几秒甚至更久，如果框架默认超时只有 30 秒，就很容易误报超时。temperature先保持默认，后面工具调用不稳定时再去调低。

3.3 用 curl 快速验证链路通不通

配置改完别着急启动整个 Agent，先用 curl 把底座探一遍，方便把问题定位在"框架侧"还是"Ollama 侧"。

# 查看 Ollama 当前可用的模型列表 curl http://localhost:11434/v1/models # 直接触发一次生成 curl http://localhost:11434/api/generate \ -d '{"model": "qwen2.5:7b", "prompt": "ping"}'

如果第一条命令能返回模型列表，说明 Ollama 服务和模型都已就绪；第二条命令能返回生成结果，说明模型真的能推理。这两条都通了，再启动 Hermes-Agent 做业务测试。我第一次实际踩过的坑就是漏了/v1，Agent 报404 Not Found，当时还以为是框架配置有问题，后来用 curl 一探立刻定位到了，前后省了至少两小时排查时间。

4. 完全离线运行的关键设置

4.1 网络隔离与局域网访达配置

离线环境里最常见的部署形态是：Agent 和 Ollama 在同一台机器上，请求走 localhost；或者 Agent 部署在多台机器上，Ollama 独立跑在模型服务器上。后一种情况需要把 Ollama 的监听地址从默认的127.0.0.1改出来：

export OLLAMA_HOST=0.0.0.0:11434

改成0.0.0.0之后，Ollama 会监听所有网卡。这时必须在防火墙层面把 11434 端口限定在内网网段，只允许 Agent 所在机器访问，避免同一内网里的其他机器也能随意调用模型服务。如果安全要求更严格，可以在系统防火墙里只放行指定来源 IP，其他请求一律拒绝。

另外要提醒一个细节：如果你在离线机器上做容器化部署，别把宿主机的网络环境变量透传进容器，以免请求被带到外部网络。Ollama 服务只需要本地回环和指定的内网地址，多余的网络出口路径都不要留，这样"完全离线"才是真的离线，而不是表面上的配置离线。

4.2 模型离线迁移：把模型包搬进去

离线部署最核心的环节是把模型弄进去。Ollama 的模型文件默认存放在~/.ollama/models（Linux/macOS）或C:\Users\用户名\.ollama\models（Windows）。迁移思路很简单，就是整个目录拷贝。

在联网机器上：

ollama pull qwen2.5:7b tar -czf ollama-models.tar.gz ~/.ollama/models

把压缩包通过内网拷贝（scp、U 盘、内部 NFS 都可以）传到目标机器后：

tar -xzf ollama-models.tar.gz -C ~

然后启动 Ollama，执行ollama list验证模型是否识别。这里最容易踩的坑是路径不匹配：如果目标机器的用户主目录和源机器不同名，模型就找不到。更稳妥的做法是用OLLAMA_MODELS环境变量把模型目录固定下来，例如统一放到/opt/ollama/models，这样迁移的路径完全可控：

export OLLAMA_MODELS=/opt/ollama/models

提前用这个变量指定目录，后续做模型备份、多机批量部署都会省很多事。我第一次就是没固定目录，后来要同步到第二台机器时才发现路径对不上，只能重新导一遍，白白浪费了一个晚上。

注意：修改OLLAMA_MODELS之后，记得把原目录下的模型文件移动到新目录，或者在新目录里重新执行ollama pull。Ollama 启动时会以该变量为准扫描模型目录，而不是自动迁移旧文件。

4.3 长时间运行的稳定性参数

Agent 服务一旦上线就是常驻进程，Ollama 的行为受几个环境变量控制，用好了能让稳定性提升一个档次。OLLAMA_KEEP_ALIVE控制模型在显存/内存中的驻留时间，默认 5 分钟。Agent 任务触发频繁的话，设成-1让模型永久驻留，后续请求的首 token 延迟会大幅降低；缺点是一直占着显存，不能再加载其他大模型。OLLAMA_MAX_LOADED_MODELS控制同时最多加载几个模型，同一个 Agent 通常只用一个模型，保持默认 1 即可，设大了反而会频繁换入换出。OLLAMA_NUM_PARALLEL控制并行请求数量，默认 4，工具调用场景并发高时可以提高，但显存占用也会上去。

我自己的生产配置长这样：

export OLLAMA_HOST=0.0.0.0:11434 export OLLAMA_KEEP_ALIVE=-1 export OLLAMA_MAX_LOADED_MODELS=1 export OLLAMA_NUM_PARALLEL=4 export OLLAMA_MODELS=/opt/ollama/models

这套配置适合"单模型常驻、中等并发"的 Agent 服务。实测下来连续跑了一周，没有出现模型加载抖动，请求响应速度也稳定在比较理想的范围。如果你的机器显存偏小，可以把OLLAMA_NUM_PARALLEL调成 1 或 2，优先保证不 OOM。

5. 实操记录：从对话到工具调用的完整测试

5.1 先测基础对话，再测多轮上下文

对接完成后不要只问一句"你好"就宣布成功，我建议按四层来测。第一层是基础问答，中英文混合问几个问题，验证模型基本生成能力。第二层是多轮对话，连续追问上下文，比如先让模型记住一个事实，几轮之后再引用它，验证 Agent 的会话管理是否正常。第三层是工具调用，真正检验 Agent 框架的关键。第四层是并发测试，同时发 4 个请求，观察排队、显存占用和错误率。

前两层主要暴露的是 base_url、模型名、超时这类基础配置问题。跑到第三层，才能真正看出模型和框架的配合度。我在这个环节就发现过工具调用格式不稳定的问题，后面通过调低 temperature 解决了，这个细节单独放在下一节说。

5.2 工具调用环节的实测现象

工具调用是 Agent 区别于普通聊天机器人的核心能力。Hermes-Agent 和模型的配合方式大致是：模型输出结构化 JSON，指示要调用哪个函数以及参数，框架解析后执行函数，把结果回填给模型，模型再生成最终回答。实测里，Qwen2.5 7B 在中文场景下的工具调用格式稳定性大约在 85% 到 90%，Llama 3.1 8B 在英文场景下表现更好一些。

如果你的 Agent 频繁出现"工具调用解析失败"或"模型乱输出"的情况，先别怀疑框架，大概率是采样参数的问题。把temperature从 0.7 调到 0.3 以下，JSON 输出稳定性能明显改善。我遇到过最典型的故障是模型回答里带着解释性文本，导致 JSON 解析失败，把温度调低后这类问题几乎消失。另一个技巧是在人设提示词里明确写一句"你只能输出 JSON，不要输出任何解释"，对部分模型很管用。

5.3 性能数据参考

最后放一组实测数据供参考，硬件是 RTX 4090 24GB，模型 Qwen2.5 7B Q4_K_M 量化版：首 token 延迟约 1.5 秒，平均生成速度约 60 token/s，一个包含 3 次工具调用的完整 Agent 任务大约 20 秒完成。对于内部系统来说，这个速度完全可以接受。如果你用的是 CPU 机器，同模型速度会是 2~5 token/s，单个 Agent 任务可能要几分钟，建议只做验证用。

这里还想强调一个优化方向：很多 Agent 任务其实不需要每次都全量调用大模型，把一些高频操作做成固定规则模板，只在需要理解语义时才触发模型推理，能大幅降低平均响应时间。这也是我后续准备优化这套离线系统的主要方向。

6. 常见问题与排查速查表

6.1 高频故障排查表

把部署过程中最常遇到的现象、原因、解法整理成一张表，方便直接对照。这些内容基本覆盖了内部团队接手这套系统后可能遇到的问题：

6.2 环境变量速查

顺手整理一份 Ollama 常用环境变量，部署时可以对照使用：

还有一个细节值得提：Windows 下 Ollama 默认作为后台服务运行，改环境变量之后必须重启服务才生效，否则改了等于没改。Linux 下如果通过 systemd 管理，也需要systemctl restart ollama重新加载环境变量。我见过不止一次同事改完配置没重启，然后跑来问为什么没变化。

6.3 多机批量部署的离线包思路

如果内网里不止一台机器要装，别一台台手动配，效率太低还容易漏。建议做一次"基准机设置"：在一台标准机器上装好 Ollama，拉好模型，把所有环境变量写进统一的.env文件或 systemd 配置，然后把安装目录、模型目录、配置文件一起打包，分发到其他机器解压，再跑一个初始化脚本完成目录创建、权限设置和服务注册。基准机上的验证流程越完整，批量部署就越稳。

我实际操作下来的体会是，离线批量部署最怕的不是模型体积，而是环境变量不统一。只要OLLAMA_MODELS和监听地址在每台机器上保持一致，后续维护和模型更新都简单很多。初始化脚本里建议加上版本校验，防止有的机器解压的是旧包，排查起来非常抓狂。

我最大的体会是：离线环境的调试成本远高于在线环境，所以所有验证动作都要前置。模型能不能跑、工具调用稳不稳定、并发能扛多高，这些必须在联网开发机上测完再搬去离线环境，否则在断网机器上发现问题，改起来会非常痛苦。另一个经验是把目录和变量从一开始就固定下来，别用 Ollama 的默认路径，否则一旦涉及模型更新或多机同步，路径不一致会让你白白加班。最后再分享一个实用技巧：把整套环境变量写进一个文件里，由 systemd 或运维平台统一加载，这样重启后配置不会丢，也避免人工 export 出错。按这条路子来，Hermes-Agent 完全离线对接 Ollama 其实就是一个下午能搞定的事。