Ollama 本地大模型部署与故障排查

适用场景：在自有服务器/边缘设备上私有化部署 LLM，避免数据外泄、降低 API 调用成本、实现离线可用。

---

1. 快速部署（Docker Compose）

# docker-compose.yml
version: "3.8"
services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    restart: unless-stopped

volumes:
  ollama_data:

启动：

docker compose up -d
ollama list  # 确认服务就绪

---

2. NVIDIA GPU 加速配置

2.1 前置检查

# 验证驱动
nvidia-smi

# 验证 Docker GPU 支持
docker run --rm --gpus all nvidia/cuda:12.6-base-ubuntu22.04 nvidia-smi

若第二条命令无输出或报错，安装 nvidia-container-toolkit：

# Ubuntu/Debian
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

2.2 Docker Compose 中的 GPU 声明

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: 1          # 可用 GPU 数量
          capabilities: [gpu]

注意：若使用 Podman，需额外设置 --device /dev/dri:/dev/dri --device /dev/nvidia*:/dev/nvidia*。

---

3. 模型下载与管理

3.1 常用模型速查

模型	参数量	最低显存	适用场景
llama3.2:1b	1B	2 GB	边缘设备、低延迟
llama3.2:3b	3B	4 GB	通用对话
qwen2.5:7b	7B	8 GB	中文理解强
deepseek-r1:8b	8B	10 GB	推理增强
llama3.1:70b	70B	40 GB	高质输出

3.2 下载加速（国内）

方法一：环境变量

export OLLAMA_MODELS=/data/ollama/models
ollama pull llama3.2:3b

方法二：镜像配置（推荐）

编辑 /etc/ollama/config.json：

{
  "proxy": "https://ollama.myhloli.com"
}

方法三：手动导入 GGUF

# 下载 .gguf 文件到 ~/.ollama/models/blobs/
# 目录结构：~/.ollama/models/blobs/sha256-<hash>
ollama create my-model -f Modelfile

---

4. API 调试

4.1 基础调用

# 生成文本
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2:3b",
  "prompt": "解释 Docker volume 的生命周期",
  "stream": false
}'

# Chat 接口
curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2:3b",
  "messages": [
    {"role": "user", "content": "Kubernetes Pod 处于 Pending 状态的原因有哪些？"}
  ]
}'

4.2 OpenAI 兼容模式

Ollama 内置 OpenAI API 兼容端点：

curl http://localhost:11434/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "llama3.2:3b",
  "messages": [{"role": "user", "content": "hello"}]
}'

此特性允许 LangChain / LlamaIndex 等框架直接接入。

---

5. 常见问题排查（8 个坑）

问题 1：no CUDA-capable device is detected

# 检查 nvidia 运行时
docker info | grep -A5 "Runtime"

# 确认 nvidia-container-toolkit 已安装
nvidia-ctk runtime inspect --runtime docker | grep nvidia

解决：重新配置 Docker runtime：

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

---

问题 2：模型加载后推理极慢

原因：模型跑在 CPU 上而非 GPU。

# 检查 GPU 利用率
nvidia-smi

# 检查 Ollama 日志
docker logs ollama --tail 50 | grep -i gpu

解决：确保 Docker Compose 中 devices 配置正确，且宿主机已安装驱动。

---

问题 3：显存不足（OOM during load）

# 查看当前显存使用
nvidia-smi

# 查看模型需求
ollama show llama3.1:70b --modelfile

解决： - 换小模型（7B → 3B → 1B） - 启用量化：ollama pull llama3.2:3b:q4_K_M - 减少并发请求数

---

问题 4：API 响应超时

解决：调整超时参数：

# 启动时设置
OLLAMA_NUM_PARALLEL=2 OLLAMA_MAX_LOADED_MODELS=1 ollama serve

或在 Docker Compose 中添加：

environment:
  - OLLAMA_NUM_PARALLEL=2
  - OLLAMA_MAX_LOADED_MODELS=1
  - OLLAMA_HOST=0.0.0.0:11434

---

问题 5：多模型冲突

现象：同时加载多个大模型导致显存耗尽。

解决：限制并发模型数：

environment:
  - OLLAMA_MAX_LOADED_MODELS=1
  - OLLAMA_NUM_PARALLEL=1

---

问题 6：Windows WSL2 下 GPU 不可用

解决：确保 WSL2 版本 ≥ 5.15，且 NVIDIA 驱动支持 WSL2。在 Windows 侧运行 nvidia-smi 确认驱动正常，WSL2 内运行相同的命令验证。

---

问题 7：Docker 容器时间不同步

现象：某些模型推理结果异常。

解决：

services:
  ollama:
    # ...
    volumes:
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

---

问题 8：模型文件损坏

现象：pull 中断后模型无法加载。

解决：

# 删除损坏模型
ollama rm llama3.2:3b

# 重新下载
ollama pull llama3.2:3b

---

6. 生产环境加固

6.1 网络隔离

services:
  ollama:
    networks:
      - ai-internal
    # 不暴露端口到宿主机
    # ports 配置移除

networks:
  ai-internal:
    driver: bridge
    internal: true

通过反向代理（Nginx/Caddy）提供对外访问：

location /ai/ {
    proxy_pass http://ollama:11434/;
    proxy_set_header Host $host;
    limit_req zone=ai burst=5;
}

6.2 资源限制

services:
  ollama:
    deploy:
      resources:
        limits:
          memory: 16G
          cpus: '8'
        reservations:
          memory: 8G
          cpus: '4'
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

6.3 健康检查

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
  interval: 30s
  timeout: 10s
  retries: 3

---

7. 配套工具链

工具	用途
ollama CLI	模型管理、API 调用
ollama show <model>	查看模型元数据
ollama list	列出已安装模型
ollama cp	复制模型（跨实例迁移）
LangChain / LlamaIndex	应用开发框架
Open WebUI	可视化 Web 界面

---

8. 延伸阅读

• Ollama 官方文档
• LangChain + Ollama 集成指南
• GGUF 模型格式规范

---

FAQ

Ollama 提示 'no visible GPU' 怎么办？ 检查 nvidia-container-toolkit 是否安装、Docker 运行时是否设为 nvidia。运行 docker run --rm --gpus all nvidia/cuda:12.6-base nvidia-smi 验证 GPU 可见性。

模型下载速度极慢或超时？ 配置国内镜像：在 /etc/ollama/config.json 添加 "proxy": "https://ollama.myhloli.com"。或手动下载 .gguf 文件到 ~/.ollama/models/ 目录。

Ollama API 返回 401 / 403？ Ollama 默认无认证。如需鉴权，使用反向代理（Nginx/Caddy）加 Basic Auth 或 JWT，或在 Docker Compose 中配置环境变量 OLLAMA_ORIGINS 限制来源。

如何切换 Ollama 默认模型？ 运行 ollama list 查看已下载模型，ollama run <model> 启动交互，ollama pull <model> 下载新模型。API 调用时指定 model 字段即可切换。

Ollama 内存占用过高导致 OOM？ 限制并发请求数、使用 smaller 模型（如 llama3.2:1b）、启用 GPU offload、或增加 swap。检查 dmesg | grep -i oom 定位触发点。

---