大语言模型的本地化部署已成为许多开发者和企业的重要需求——既能保护数据隐私，又能降低对云端服务的依赖和成本。Ollama 作为目前最流行的本地大模型运行工具，极大地简化了部署流程。

本教程将从零开始，指导你在 macOS 宿主机上通过 Docker Compose 一站式部署 Ollama 服务、Qwen 2.5 大模型、Open WebUI 图形界面以及 Hermes 自治代理（可选）。

一、为什么选择 Docker Compose

在部署多个容器（Ollama、Open WebUI、Hermes）时，有两种主流方式：

• Docker 命令行：逐条执行 docker run，适合单容器或临时测试。配置分散在终端命令中，需手动管理启动顺序，容器间需用 host.docker.internal 连接，维护脚本较复杂。
• Docker Compose：通过 docker-compose.yml 统一声明所有服务，适合多容器长期部署。支持服务名自动通信，一条 docker compose up -d 启动全家桶，资源限制统一配置，升级只需 pull && up -d，配置文件可版本控制。

二、Ollama的定义和作用

Ollama 是一款开源的本地大语言模型运行框架，旨在简化大模型在本地设备的部署和运行。它支持跨平台运行，兼容 Windows、macOS 和 Linux 系统，通过极简的命令行操作即可实现模型的一键启动、下载与管理。

从技术架构来看，Ollama 由三层核心组件构成：模型加载引擎负责解析 GGML/GGUF 等量化格式；内存管理模块实现动态显存分配；API 服务层提供标准化的 REST 接口。

简单来说，Ollama 就是在大模型时代装在电脑里的“运行环境”——它能帮你快速拉取模型文件、让模型在本地直接运行，并通过标准接口开放给其他程序调用。

三、Hermes 自治代理是什么

3.1 定义与作用

Hermes Agent 由 Nous Research 推出，是一款轻量级的自治 AI 代理，能执行终端命令、读写文件、搜索网页、调用外部工具。其核心特性是 “自我进化”（Self-Improving） ：在完成任务后，自动将成功经验、失败教训提炼成可复用的技能（Skills）和记忆（Memory），越用越懂你的偏好。

3.2 Hermes（养马）vs OpenClaw（养虾）

Hermes（养马）是自我进化型代理，自动学习成长、越用越懂你；OpenClaw（养虾）是网关连接型代理，侧重多平台集成与社区技能生态。

它与自我进化型代理的核心差异在于：网关型代理通过一个核心网关连接所有“感官”与“工具”，而自我进化型代理则像一个经验丰富的个人助手，其核心并非“连接”能力，而是通过在每一次互动中学习和总结经验，来逐步成长并适配你的个人习惯。

四、硬件配置要求

以本机硬件环境为例（macOS Ventura 13.7，13英寸，512G SSD，16G内存，2.3 GHz 双核Intel Core i5），建议满足以下配置：

组件	最低配置	推荐配置
CPU	4 核处理器	8 核（M1/M2/M3 芯片更佳）
内存	8 GB	16 GB 及以上（本机满足）
存储空间	20 GB 可用空间	50 GB+（模型文件约 15-35 GB）
操作系统	macOS 12.0 Monterey 及以上	macOS 13 Ventura 或更新版本

五、安装与配置教程（全部使用 Docker Compose）

步骤一：宿主机 macOS 安装 Docker（若安装直接跳过）

1. 访问 Docker 官网，下载适用于 macOS 的 Docker Desktop 安装包。
2. 安装完成后，打开终端，执行以下命令验证 Docker 是否正常运行

#（macOS终端执行）

docker --version

3. Docker Desktop 自带 docker compose 命令（无需额外安装），验证：

#（macOS终端执行）

docker compose version

步骤二：创建 docker-compose.yml 配置文件

在工作目录（例如 ~/）创建文件夹（例如ollama-deploy），并在其目录里创建一个 docker-compose.yml 文件，内容如下：

services:
  # Ollama 服务 - 大模型运行核心
  ollama:
    image: ollama/ollama:latest
    container_name: ollama-service
    restart: unless-stopped
    ports:
      - "11434:11434"                # 暴露 API 端口给宿主机
    volumes:
      - ollama-data:/root/.ollama    # 持久化模型文件
    deploy:
      resources:
        limits:
           memory: 6G      # 运行 Qwen2.5:7b（~5.5G 实际占用）足够，留有余量          
           cpus: '2.0'     # memory和cpus请根据需要修改

  # Open WebUI - 图形化对话界面
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: unless-stopped
    ports:
      - "3000:8080"                  # 宿主机访问 http://localhost:3000
    volumes:
      - open-webui-data:/app/backend/data   # 持久化对话记录和配置
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434  # 通过服务名连接 Ollama
    depends_on:
      - ollama
    deploy:
      resources:
        limits:
          memory: 512M    # Web UI 内存占用很低          
          cpus: '0.5'     # memory和cpus请根据需要修改
    extra_hosts:
      - "host.docker.internal:host-gateway"  # 将 host.docker.internal 解析为宿主机的网关地址

  # Hermes Agent - 自治代理（可选，按需启用）
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"                  # Hermes API 端口
    volumes:
      - ~/.hermes:/opt/data          # 持久化配置和记忆
      - ~/Documents/HermesWS:/workspace       # 挂载宿主机文档目录（请根据需要修改路径）
    environment:
      - OLLAMA_HOST=http://ollama:11434
      - API_SERVER_ENABLED=true
      - API_SERVER_HOST=0.0.0.0
      - API_SERVER_PORT=8642
    depends_on:
      - ollama
    deploy:
      resources:
        limits:
          memory: 1.5G    # 自治代理日常任务足够          
          cpus: '0.5'     # memory和cpus请根据需要修改
    # 如果不想使用 Hermes，可以注释掉整个 hermes 服务

volumes:
  ollama-data:
  open-webui-data:

关键说明：

• 服务名称 ollama、open-webui、hermes 用于容器间内部通信（如 http://ollama:11434）
• 数据卷 ollama-data 和 open-webui-data 由 Docker 管理，位于 /var/lib/docker/volumes/
• Hermes 挂载的 ~/Documents 可根据实际需要更改为其他目录（如博客文章所在文件夹）
• 资源限制（memory/cpus）可根据本机环境配置微调

步骤三：启动所有服务

若跳过步骤一，需先启动 Docker 桌面软件（Docker Desktop），双击运行小海豚图标，再执行命令：

#（macOS终端执行）

cd ～/ollama-deploy
docker compose up -d

该命令会：

• 自动拉取所需的镜像（ollama、open-webui、hermes）
• 创建容器并按照依赖顺序启动（先 ollama，后 open-webui 和 hermes）
• 在后台运行所有服务

首次启动可能需要几分钟下载镜像。完成后，检查状态：docker compose ps，输出应显示所有服务的状态为 Up。

步骤四：验证服务运行

验证 Ollama API：

#（macOS终端执行）

curl http://localhost:11434
# 应返回 {"version":"x.x.x"}

查看日志：

#（macOS终端执行）

# 查看所有服务日志
docker compose logs

# 仅查看某个服务
docker compose logs ollama
docker compose logs open-webui

步骤五：部署 Qwen 2.5 大模型

1.大模型对比

模型	参数	核心特色	性能基准	量化内存需求	综合推荐指数 (满分5星)
Qwen2.5 (通义千问)	7B	中文理解顶流，专为中文优化，知识库更新	MMLU 85+ HumanEval 85+	~5.5 GB (Q4_K_M)	⭐⭐⭐⭐⭐
Llama 3.1	8B	综合实力标杆，全球最活跃的生态与微调版本	通用能力强，适应范围广，有128K的长下文能力	~6 GB (Q4_K_M)	⭐⭐⭐⭐⭐
DeepSeek-R1	7B	逻辑推理专精，擅长复杂逻辑、数学与代码分析	更适合深度分析与复杂逻辑	~14.5 GB (FP16)	⭐⭐⭐⭐
Gemma 4	4-31B	极致能效比，参数量小却拥有越级性能，但中文能力相对较弱	在超小参数量下实现强推理	内存需求随版本变化较大	⭐⭐⭐

针对本机硬件配置（16GB 内存，双核 i5），推荐选择 Qwen2.5:7b，它在中文理解、内存占用和推理速度上取得了最佳平衡。

2.拉取 Qwen 2.5 模型

使用 docker compose exec 在 ollama 容器中执行命令：

#（macOS终端执行）

#ollama(第一个)：定义的服务名称，对应 docker-compose.yml 中 services.ollama
#ollama(第二个)：在容器内执行的完整命令：调用 Ollama CLI 工具，拉取 qwen2.5:7b 模型
docker compose exec ollama ollama pull qwen2.5:7b

3.启动交互式对话

#（macOS终端执行）

#ollama(第一个)：定义的服务名称，对应 docker-compose.yml 中 services.ollama
#ollama(第二个)：在容器内执行的完整命令：调用 Ollama CLI 工具
docker compose exec ollama ollama run qwen2.5:7b

在 >>> 提示符后输入问题，例如请用 Python 实现一个快速排序算法，输入 /bye 或按 Ctrl+D 退出

步骤六：访问 Open WebUI 图形界面

1. 确保服务已启动：docker compose ps
2. 打开浏览器，访问 http://localhost:3000
3. 首次访问需要注册管理员账号（任意邮箱和密码，本地存储）
4. 登录后，在左上角模型下拉菜单中选择 qwen2.5:7b
5. 开始对话！Open WebUI 会自动识别 Ollama 中已安装的模型

⚠️ 注意：由于我们在 docker-compose.yml 中已通过环境变量 OLLAMA_BASE_URL=http://ollama:11434 配置了连接，Open WebUI 无需额外设置即可与 Ollama 通信。

步骤七：部署 Hermes 自治代理（可选）

Hermes Agent 是一个能够执行终端命令、读写文件、搜索网页的自治 AI 代理。注意：此组件非必需，仅适合需要自动化操作系统的进阶用户。

为什么装在 Docker 里？

• 安全性：容器隔离，避免 Hermes 直接修改 macOS 系统文件
• 权限可控：可通过挂载卷精确控制可访问的目录
• 统一管理：与 Ollama、Open WebUI 使用相同的 Docker 环境

1.使用 Hermes

1）启动 Hermes 服务

确保 hermes 服务在 docker-compose.yml 中未被注释，然后启动：

#（macOS终端执行）

#启动并检查是否运行
docker compose up -d hermes
docker compose logs hermes

2）在 Open WebUI 中添加 Hermes 作为模型

• 生成 Hermes 的 API Key 并复制保存

#（新窗口：macOS终端执行）

openssl rand -base64 32

• 浏览器访问 http://localhost:3000 或 http://127.0.0.1:3000，注册/登录后
• 进入左下角头像或名称→ 选择“管理员面板” → 点击“设置” → 点击“外部连接” → “管理 OpenAI 接口连接”最右边点击“+”，添加连接

• 添加 OpenAI 兼容接口：URL 为 http://host.docker.internal:8642，认证方式选择密钥并粘贴刚保存的字符串，模型ID可任意填写（如 hermes-agent）

• 回到主页，选择hermes-agent模型，开启对话
  

2.问题排查

当我与它进行测试对话时，始终未收到回复消息（如图），以下是排查过程：

• 检查 Hermes 服务：

#（macOS终端执行）

#1.检查 Docker 容器内 Hermes 服务
docker exec -it hermes curl http://localhost:8642/health
#{"status": "ok", "platform": "hermes-agent", "version": "0.16.0"}
#2.检查本机 Hermes 服务
curl http://localhost:8642/health
#不返回{"status": "ok", "platform": "hermes-agent", "version": "0.16.0"}

经过以上两步验证，说明容器内的服务运行完全正常（docker exec 成功），问题出在宿主机无法通过 localhost:8642 访问到容器内的服务。这通常是因为容器内的服务只监听了 127.0.0.1，而不是 0.0.0.0。

——> a）在~/.hermes/config.yaml文件启用服务，监听0.0.0.0地址和端口：

#（macOS终端执行）

#1.启用 API 服务器
hermes config set platforms.api_server.enabled true
#2.设置监听地址和端口
hermes config set platforms.api_server.host 0.0.0.0
hermes config set platforms.api_server.port 8642

——> b）在docker-compose.yml 需同步配置：

——> c）重启并验证宿主机上的 Hermes 服务：

#（macOS终端执行）

#1.重启服务
docker compose down && docker compose up -d
#2.验证
curl http://localhost:8642/health
#{"status": "ok", "platform": "hermes-agent", "version": "0.16.0"}

• 检查 open-webui 容器能否访问到宿主机上映射的 Hermes 服务

# 方式一：在 Docker Desktop 内执行
#（在 open-webui 容器）

curl http://host.docker.internal:8642/health

#方式二：宿主机macOS终端执行
#（macOS终端执行）

docker exec open-webui curl -s http://host.docker.internal:8642/health
#{"status": "ok", "platform": "hermes-agent", "version": "0.16.0"}

从返回结果来看，说明 docker-compose.yml 配置 extra_hosts: - "host.docker.internal:host-gateway" 正确，域名被正确解析到了 Docker 的网关地址。

• 以上均测试成功，但 Open WebUI 对话框仍无响应。如果直接发送消息呢？

#（macOS终端执行）

curl -X POST http://localhost:8642/v1/chat/completions \
   -H "Authorization: Bearer sYi74OEsc1HgI*************ARPYTGnM=" \
   -H "Content-Type: application/json" \
   -d '{
     "model": "qwen2.5:7b",
     "messages": [{"role": "user", "content": "你好"}]
   }'
#{"error": {"message": "Internal server error: No inference provider configured. Run 'hermes model' to choose a provider and model, or set an API key (OPENROUTER_API_KEY, OPENAI_API_KEY, etc.) in ~/.hermes/.env.", "type": "server_error", "param": null, "code": null}}

错误信息明确指出：Hermes 没有配置推理提供者。Hermes 本身只是一个代理框架，它需要连接到一个实际的 LLM（无论是云端 API 还是本地 Ollama）才能工作。

——> a）在宿主机的 ~/.hermes/.env 文件中写入配置：

#（macOS终端执行）

#1.写入配置
echo "MODEL=qwen2.5:7b" >> ~/.hermes/.env
echo "OLLAMA_HOST=http://ollama:11434" >> ~/.hermes/.env
#2.必须彻底重建容器（而不是 restart）
docker compose down && docker compose up -d

——> b）验证结果：

#（macOS终端执行）

#1.检查环境变量是否已更正
docker compose exec hermes env | grep OLLAMA_HOST
#2.测试 Hermes 能否访问 Ollama
docker compose exec hermes curl -s http://ollama:11434/api/tags
#3.再次发送聊天请求
curl -X POST http://localhost:8642/v1/chat/completions \
   -H "Authorization: Bearer sYi74OEsc1HgI*************ARPYTGnM=" \
   -H "Content-Type: application/json" \
   -d '{
     "model": "qwen2.5:7b",
     "messages": [{"role": "user", "content": "你好"}]
   }'
#{"error": {"message": "Internal server error: Model qwen2.5:7b has a context window of 32,768 tokens, which is below the minimum 64,000 required by Hermes Agent.  Choose a model with at least 64K context, or set model.context_length in config.yaml to override.", "type": "server_error", "param": null, "code": null}}

错误信息明确指出：Hermes Agent 要求模型至少具有 64K 上下文长度（64,000 tokens），而 qwen2.5:7b 只有 32,768 tokens，因此拒绝使用。

——> 修改 ~/.hermes/config.yaml，在 model: 部分下添加 context_length 字段并重启仍无效，解决思路：

1）hermes 新版本可能不是 context_length 属性；

2）使用支持 64K 上下文的模型，如qwen2.5:14b；

3）手动修改代码来跳过检查，在run_agent.py文件中，找到第1550行附近的检查代码，添加if not getattr(...) 来判断用户是否配置；

4）从 Ollama 层面，Modelfile 修改模型的启动参数，用 num_ctx 强行扩大上下文窗口；

下面将逐一解释：

1）❌，原因：查看 GitHub 官网，确实使用 context_length 属性。但使用的场景是将大模型从128K限制在64K，而目前的情况是 hermes 最低限制64K，使用的qwen2.5:7b 是32k，不满足 hermes 最低要求（使用 context_length 测试成功，链接：https://blog.kofj.net/post/2025-08/ollama-qwen3-coder-ctx）。另外考虑 hermes 是不是有优先级，在 docker-compose.yml 文档 hermes 配置 environment: MODEL_CONTEXT_LENGTH 同样无效；

2）✅，原因：目前本机硬件环境不支持，安装后运行效果不佳。可升级硬件设备，并调整 docker-compose.yml 文件中的 memory 和 cpus 的值；

3）❌，原因：手动修改源码不推荐，且代码更新后原代码会被覆盖；

4）❌，原因：qwen2.5:7b 模型原生窗口是32K，强行将模型修改为符合 hermes 要求，可能会导致模型不可用，这种方式本身就不合理，不提倡不推荐；

• 以下命令可辅助定位问题：

#（macOS终端执行）

#查看 ollama 正在运行的模型
docker compose exec ollama ollama ps
#检查 hermes 容器内的配置文件中的指定信息（如 model 信息）
docker exec hermes cat /opt/data/config.yaml | grep -A 4 "^model:"
#查看 hermes 前 50 行错误信息
docker compose logs hermes --tail 50 | grep -i error
#验证 Hermes 是否被正确配置的最直接方法
docker exec hermes hermes chat -q "你好，请用中文简单自我介绍"

六、进阶使用：多模型管理

1.查看已下载模型

#（macOS终端执行）

#ollama(第一个)：定义的服务名称，对应 docker-compose.yml 中 services.ollama
#ollama(第二个)：在容器内执行的完整命令：调用 Ollama CLI 工具
docker compose exec ollama ollama list

2.下载其他模型（例如 DeepSeek-R1:7b）

#（macOS终端执行）

#ollama(第一个)：定义的服务名称，对应 docker-compose.yml 中 services.ollama
#ollama(第二个)：在容器内执行的完整命令：调用 Ollama CLI 工具
docker compose exec ollama ollama pull deepseek-r1:7b

3.删除模型

#（macOS终端执行）

#ollama(第一个)：定义的服务名称，对应 docker-compose.yml 中 services.ollama
#ollama(第二个)：在容器内执行的完整命令：调用 Ollama CLI 工具
docker compose exec ollama ollama rm deepseek-r1:7b

4.查看本地运行中模型列表

#（macOS终端执行）

#ollama(第一个)：定义的服务名称，对应 docker-compose.yml 中 services.ollama
#ollama(第二个)：在容器内执行的完整命令：调用 Ollama CLI 工具
docker compose exec ollama ollama ps

5.管理整个服务栈

操作	命令
启动所有服务	docker compose up -d
停止所有服务	docker compose down
重启某个服务（如 Hermes）	docker compose restart hermes
查看实时日志	docker compose logs -f
更新所有镜像并重启	docker compose pull && docker compose up -d
进入 Ollama 容器内部	docker compose exec ollama /bin/bash
清理所有数据（删除容器和卷）	docker compose down -v