前阵子接了一个内部项目要求把 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 量化的模型推理速度每秒几十个 token8GB 显存也能跑但建议优先考虑 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 或更大。以下是常见的模型选择参考模型参数量推荐显存中文能力工具调用适用场景qwen2.5:7b7.6B约8GB强中中文 Agent 任务llama3.1:8b8B约8GB中强英文、代码、Tool Callingqwen2.5:14b14B约16GB强中复杂推理mistral:7b7B约8GB弱中长上下文场景拉取命令以 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 做业务测试。我第一次实际踩过的坑就是漏了/v1Agent 报404 Not Found当时还以为是框架配置有问题后来用 curl 一探立刻定位到了前后省了至少两小时排查时间。4. 完全离线运行的关键设置4.1 网络隔离与局域网访达配置离线环境里最常见的部署形态是Agent 和 Ollama 在同一台机器上请求走 localhost或者 Agent 部署在多台机器上Ollama 独立跑在模型服务器上。后一种情况需要把 Ollama 的监听地址从默认的127.0.0.1改出来export OLLAMA_HOST0.0.0.0:11434改成0.0.0.0之后Ollama 会监听所有网卡。这时必须在防火墙层面把 11434 端口限定在内网网段只允许 Agent 所在机器访问避免同一内网里的其他机器也能随意调用模型服务。如果安全要求更严格可以在系统防火墙里只放行指定来源 IP其他请求一律拒绝。另外要提醒一个细节如果你在离线机器上做容器化部署别把宿主机的网络环境变量透传进容器以免请求被带到外部网络。Ollama 服务只需要本地回环和指定的内网地址多余的网络出口路径都不要留这样完全离线才是真的离线而不是表面上的配置离线。4.2 模型离线迁移把模型包搬进去离线部署最核心的环节是把模型弄进去。Ollama 的模型文件默认存放在~/.ollama/modelsLinux/macOS或C:\Users\用户名\.ollama\modelsWindows。迁移思路很简单就是整个目录拷贝。在联网机器上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_HOST0.0.0.0:11434 export OLLAMA_KEEP_ALIVE-1 export OLLAMA_MAX_LOADED_MODELS1 export OLLAMA_NUM_PARALLEL4 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 高频故障排查表把部署过程中最常遇到的现象、原因、解法整理成一张表方便直接对照。这些内容基本覆盖了内部团队接手这套系统后可能遇到的问题现象可能原因解决办法Connection refusedOllama 服务没启动执行ollama serve或systemctl start ollama404 Not Foundbase_url 少了/v1改成http://localhost:11434/v1请求超时模型冷启动加载慢调大 timeout设置OLLAMA_KEEP_ALIVE-1CUDA out of memory模型过大或并发过高换小模型OLLAMA_NUM_PARALLEL1模型找不到模型没拉好或目录不对ollama list确认核对OLLAMA_MODELS局域网无法访问监听地址仍是回环OLLAMA_HOST0.0.0.0:11434并放行防火墙工具调用 JSON 格式乱采样随机性太高temperature调到 0.3 以下Windows 下模型装到 C 盘没指定模型目录系统环境变量设置OLLAMA_MODELSD:\ollama\models后重启服务6.2 环境变量速查顺手整理一份 Ollama 常用环境变量部署时可以对照使用环境变量作用我常用的值OLLAMA_HOST监听地址0.0.0.0:11434OLLAMA_MODELS模型存储目录/opt/ollama/modelsOLLAMA_KEEP_ALIVE模型驻留时间-1OLLAMA_NUM_PARALLEL并行请求数2~4OLLAMA_MAX_LOADED_MODELS最多加载模型数1OLLAMA_DEBUG调试日志开关1还有一个细节值得提Windows 下 Ollama 默认作为后台服务运行改环境变量之后必须重启服务才生效否则改了等于没改。Linux 下如果通过 systemd 管理也需要systemctl restart ollama重新加载环境变量。我见过不止一次同事改完配置没重启然后跑来问为什么没变化。6.3 多机批量部署的离线包思路如果内网里不止一台机器要装别一台台手动配效率太低还容易漏。建议做一次基准机设置在一台标准机器上装好 Ollama拉好模型把所有环境变量写进统一的.env文件或 systemd 配置然后把安装目录、模型目录、配置文件一起打包分发到其他机器解压再跑一个初始化脚本完成目录创建、权限设置和服务注册。基准机上的验证流程越完整批量部署就越稳。我实际操作下来的体会是离线批量部署最怕的不是模型体积而是环境变量不统一。只要OLLAMA_MODELS和监听地址在每台机器上保持一致后续维护和模型更新都简单很多。初始化脚本里建议加上版本校验防止有的机器解压的是旧包排查起来非常抓狂。我最大的体会是离线环境的调试成本远高于在线环境所以所有验证动作都要前置。模型能不能跑、工具调用稳不稳定、并发能扛多高这些必须在联网开发机上测完再搬去离线环境否则在断网机器上发现问题改起来会非常痛苦。另一个经验是把目录和变量从一开始就固定下来别用 Ollama 的默认路径否则一旦涉及模型更新或多机同步路径不一致会让你白白加班。最后再分享一个实用技巧把整套环境变量写进一个文件里由 systemd 或运维平台统一加载这样重启后配置不会丢也避免人工 export 出错。按这条路子来Hermes-Agent 完全离线对接 Ollama 其实就是一个下午能搞定的事。