【LLM】Ollama：容器化并加载本地 GGUF 模型

本教程将完整演示如何在支持多 GPU 的环境下，通过 Docker 实现 Ollama 的本地化部署，并深度整合本地 GGUF 模型。我们将构建一个具备生产可用性的容器化 LLM 服务，包含完整的存储映射、GPU 加速配置和模型管理方案。

---

前提与环境准备

1. 操作系统
   Linux（推荐 Ubuntu 20.04+ / CentOS 7+），已安装 Docker 与 Docker Compose（≥1.27）。
   推荐使用 LTS 版本系统以获得长期内核支持

2. Docker 验证

   docker --version
   docker compose --version
   

   若未安装，请参考 Docker 官方安装指南 和 Docker Compose 安装文档

3. NVIDIA Container Toolkit（GPU 加速）

   • 安装指南：官方安装文档

   • 验证 GPU 可见性：

     docker run --gpus all nvidia/cuda:11.0-base nvidia-smi
     

     若输出包含 GPU 信息，则配置成功。常见问题可参考 NVIDIA 容器工具包故障排查

4. 本地 GGUF 模型目录
   推荐目录结构：

   ~/models/mymodel/
   ├─ model.gguf      # GGUF 格式模型文件（支持 llama.cpp 系列模型）
   └─ Modelfile       # Ollama 模型定义文件
   

   GGUF 模型获取推荐平台：HuggingFace Hub

---

目录布局

~/
├── models              # 独立模型与 Modelfile 目录（只读挂载）
│   └── mymodel
│       ├── model.gguf  # GGUF 模型文件
│       └── Modelfile   # 使用相对路径的 Modelfile
└── ollama-deploy└── docker-compose.yml  # 部署配置

说明：模型目录设置为只读（ro）可防止容器意外修改模型文件，确保模型完整性

---

编写 Modelfile

在 ~/models/mymodel/Modelfile 中，使用相对路径 FROM ./models（容器内部 /models 挂载点）：

# 显式指定模型文件路径（相对于当前 Modelfile 所在目录）
# Modelfile 的参数语法类似 KEY VALUE，不能在同一行写注释FROM ./model.gguf# 模型元数据模板
TEMPLATE """[INST] {{ .System }} {{ .Prompt }} [/INST]"""# 推理参数配置# 控制生成随机性（值范围：0.0 - 1.0，越小越确定）
PARAMETER temperature 0.7# 核采样阈值（建议 0.7 - 0.95）
PARAMETER top_p 0.9# 上下文长度（需与模型训练参数一致）
PARAMETER num_ctx 4096

参数详解

• temperature：值越大生成越随机，值小则更确定（技术文档推荐 0.2-0.8）
• top_p：动态词表裁剪，与 temperature 配合使用效果更佳
• 更多参数参考：Ollama Modelfile 官方文档

---

编写 docker-compose.yml

在 ~/ollama-deploy/docker-compose.yml 配置：

services:ollama:image: ollama/ollama:latestcontainer_name: ollamacommand: serve  # 启动服务模式ports:- "11434:11434"  # API 端口restart: unless-stoppedvolumes:# ✅ 请根据实际 home 目录修改为绝对路径（例如 /home/touken）- /home/username/models:/models:ro        # 只读挂载模型目录（包含 Modelfile）- /home/username/.ollama:/root/.ollama    # 持久化模型缓存及配置deploy:  # 多 GPU 分配配置resources:reservations:devices:- driver: nvidiacount: all  # 使用全部可用 GPUcapabilities: [gpu]

配置解析

• command: serve：启动服务模式而非 CLI 交互模式
• ~/.ollama 目录存储模型运行时数据（建议 SSD 存储以获得更好性能）
• GPU 分配策略可参考 Docker GPU 管理文档

---

启动 Ollama 服务

cd ~/ollama-deploy
docker compose up -d  # 后台启动服务

状态检查：

docker logs ollama  # 查看实时日志
lsof -i :11434      # 验证端口监听状态

---

注册并加载模型

# 创建模型实例（名称自定义）
docker exec ollama ollama create mymodel -f /models/mymodel/Modelfile# 查看已注册模型
docker exec ollama ollama list

常见错误处理：若提示模型路径错误，请检查容器内路径是否匹配 /models/mymodel/Modelfile

---

验证与测试

# 基础 API 测试
curl http://localhost:11434/api/generate \-X POST -H "Content-Type: application/json" \-d '{"model": "mymodel","prompt": "Hello, Ollama! How are you?","stream": false}'# 使用 ollama-python 客户端测试（需额外安装）
from ollama import Client
client = Client(host='http://localhost:11434')
print(client.generate(model='mymodel', prompt='AI 的未来是什么？'))

推荐工具：ollama-python 客户端库

---

性能优化建议

1. GPU 资源分配

   deploy:resources:reservations:devices:- driver: nvidiadevice_ids: ['0', '1']  # 指定 GPU 设备号capabilities: [gpu]
   

2. 量化策略

   • 优先选择 Q4_K_M 或 Q5_K_S 量化版本（量化等级说明）
   • 使用 llama.cpp 进行自定义量化

3. 显存管理

   # Modelfile 添加
   PARAMETER num_gpu 2          # 指定 GPU 数量
   PARAMETER main_gpu 0         # 主 GPU 设备号
   

---

总结

本文通过以下关键技术点实现生产级部署：

1. 目录隔离设计：模型与配置的只读挂载确保系统可靠性
2. GPU 动态分配：支持多卡推理和显存优化
3. 服务化部署：通过 Docker Compose 实现一键启停