---

Docker Ollama 深度指南：从安装到使用

引言

在人工智能飞速发展的今天，大语言模型（LLM）已成为核心驱动力。然而，运行这些模型往往需要特定的环境、依赖项以及对硬件的精细配置。这使得许多开发者和爱好者望而却步。Ollama 的出现极大地简化了在本地机器上运行 LLM 的过程。它提供了一个统一的框架，可以轻松地拉取、运行和管理各种开源模型。

进一步地，将 Ollama 与 Docker 结合，能够带来前所未有的便利性和可移植性。Docker 容器化技术提供了隔离、标准化的运行环境，彻底解决了“在我机器上能跑”但“在你机器上就报错”的痛点。通过 Docker 运行 Ollama，你可以：

1. 简化安装与依赖管理： 无需担心系统库冲突或复杂的安装步骤，Docker 镜像包含了 Ollama 及其所有必要的依赖。
2. 环境隔离： Ollama 及其模型在一个独立的容器中运行，不会污染宿主系统环境。
3. 可移植性与一致性： 无论在 Linux、Windows 还是 macOS 上，只要安装了 Docker，Ollama 的运行环境都是一致的。轻松在不同机器或服务器之间迁移。
4. 资源管理： Docker 提供了基本的资源限制能力（虽然对于GPU资源需要额外配置），有助于管理 Ollama 运行时对系统资源的消耗。
5. 版本控制与回滚： 可以轻松拉取特定版本的 Ollama 镜像，并在需要时回滚到旧版本。

本指南将带你深入了解如何在 Docker 中安装、配置和使用 Ollama，从基础命令到高级技巧，助你充分发挥两者的优势。

前置条件

在开始之前，请确保你的系统满足以下条件：

1. 安装 Docker： 你需要在你的操作系统上安装 Docker Desktop (Windows/macOS) 或 Docker Engine (Linux)。可以访问 Docker 官方网站获取详细的安装指南：https://www.docker.com/get-started。
2. 硬件要求：
   • CPU： Ollama 本身对 CPU 要求不高，但运行模型需要足够的内存。小型模型可能需要 8GB+ RAM，而更大的模型可能需要 16GB、32GB 甚至更多。
   • GPU (推荐)： 虽然 Ollama 可以在 CPU 上运行模型，但使用 GPU 可以极大地加速推理过程。NVIDIA GPU（需要支持 CUDA）是主流选择，AMD 和 Apple Silicon GPU 也受支持。确保你的 GPU 驱动已正确安装，并且 Docker 能够访问到 GPU（这通常需要额外的配置，我们将在后续章节详细介绍）。模型的大小直接影响所需的显存 (VRAM) 容量。

Docker Ollama 安装与启动

运行 Ollama 的 Docker 镜像由 Ollama 官方提供，是 ollama/ollama。启动一个 Ollama 容器非常简单。最基本的方式是使用 docker run 命令：

bash
docker run -d -p 11434:11434 --name ollama ollama/ollama

让我们逐一解释这条命令的各个部分：

• docker run: 这是启动一个新容器的 Docker 命令。
• -d: 表示以“detached”模式运行容器，即在后台运行，不会占用当前终端。
• -p 11434:11434: 这是端口映射。它将宿主机器的 11434 端口映射到容器内部的 11434 端口。Ollama 默认在其 API 端口 11434 上监听请求，通过这个映射，我们可以从宿主机器或网络中的其他设备访问容器内部的 Ollama 服务。
• --name ollama: 为这个容器指定一个易于识别的名称，这里我们命名为 ollama。之后我们可以使用这个名称来管理容器（启动、停止、查看日志等）。
• ollama/ollama: 这是要运行的 Docker 镜像名称。Docker 会检查本地是否有这个镜像，如果没有，就会从 Docker Hub（或其他配置的镜像仓库）自动拉取。

运行这条命令后，Docker 会在后台启动一个名为 ollama 的容器，并在宿主机的 11434 端口上提供 Ollama 服务。

持久化模型数据

上面的命令虽然启动了 Ollama 服务，但容器是无状态的。这意味着如果你删除并重新创建容器，之前下载的模型会丢失。为了避免这种情况，我们需要将容器内部存储模型和配置的目录 (/root/.ollama) 映射到宿主机器上的一个持久化位置。这可以通过数据卷 (Volume) 实现。

推荐使用 Docker 的命名卷 (Named Volume)。命名卷由 Docker 管理，易于备份和迁移。

bash
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

• -v ollama:/root/.ollama: 这是数据卷挂载。ollama 是宿主机上的一个命名卷（如果不存在，Docker 会自动创建），/root/.ollama 是容器内部 Ollama 存储模型和配置的默认路径。这样，模型数据就会存储在宿主机的 ollama 命名卷中，即使容器被删除，数据仍然保留。当创建新的 Ollama 容器并再次挂载同一个命名卷时，这些模型会再次可用。

你也可以使用绑定挂载 (Bind Mount) 将容器目录映射到宿主机文件系统的特定路径：

“`bash

假设你希望将模型数据存储在宿主机的 /path/to/your/ollama_data 目录下

docker run -d -v /path/to/your/ollama_data:/root/.ollama -p 11434:11434 –name ollama ollama/ollama
“`

• -v /path/to/your/ollama_data:/root/.ollama: 将宿主机上的 /path/to/your/ollama_data 目录（请替换为你实际的路径）绑定挂载到容器内部的 /root/.ollama 目录。你需要确保宿主机上的 /path/to/your/ollama_data 目录存在，并且 Docker 有权限读写该目录。

推荐使用命名卷，因为它更符合 Docker 的数据管理哲学，且路径由 Docker 内部管理，避免了宿主机路径问题。

启用 GPU 加速

如果你的系统有 GPU，强烈建议启用 GPU 加速以获得更好的性能。这通常是 Docker 中运行机器学习应用的关键，也是配置上相对复杂的地方。

1. NVIDIA GPU (Linux)

在 Linux 上使用 NVIDIA GPU 加速需要安装 NVIDIA Container Toolkit。这是 NVIDIA 提供的一套工具，使得 Docker 容器能够访问宿主机的 NVIDIA GPU。

• 安装 NVIDIA Container Toolkit: 请参照 NVIDIA 的官方文档安装。通常涉及添加 NVIDIA 仓库、安装 nvidia-container-toolkit 包并重启 Docker 服务。例如 (适用于 Debian/Ubuntu):
  bash
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
&& curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add - \
&& curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

• 启动 Ollama 容器 (带 GPU): 安装完工具包后，启动容器时需要添加 --gpus all 标志。

  bash
docker run -d --gpus all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
--gpus all: 这个标志告诉 Docker 将所有可用的 GPU 暴露给容器。你也可以指定特定的 GPU，例如 --gpus '"device=0,1"' 或 --gpus 'device=GPU-UUID'。

2. NVIDIA/AMD/Apple Silicon (Docker Desktop – Windows/macOS)

如果你使用 Docker Desktop (Windows 或 macOS)，它通常已经集成了 GPU 支持（例如在 Windows WSL2 中集成 NVIDIA GPU，在 macOS 上支持 Apple Silicon 的 Metal）。你通常只需要确保你的 GPU 驱动已正确安装在宿主机（或 WSL2 环境中），并在 Docker Desktop 设置中启用相关 GPU 支持。

在 Docker Desktop 环境中启动 Ollama 容器 (带 GPU) 的命令与 Linux 类似，Docker Desktop 会负责将 GPU 资源传递给容器：

“`bash

对于 Windows (WSL2) 和 macOS (Apple Silicon)

docker run -d –gpus all -v ollama:/root/.ollama -p 11434:11434 –name ollama ollama/ollama
``
确保你的 Docker Desktop 版本支持–gpus all` 标志，并且宿主机环境（尤其是 Windows WSL2）已正确配置以支持 GPU 直通。

验证 GPU 是否启用：
启动容器后，你可以通过查看容器日志或进入容器内部运行 Ollama 命令来验证 GPU 是否被识别。

bash
docker logs ollama # 查看启动日志，有时会显示 GPU 信息

或者，进入容器内部，运行 ollama 命令（需要先拉取一个模型，比如 ollama pull llama2），如果推理速度很快且 GPU 占用率升高，说明 GPU 正常工作。

验证 Ollama 服务

容器成功启动后，你可以通过多种方式验证 Ollama 服务是否正常运行：

1. 检查容器状态：
   bash
docker ps
   你应该能看到一个名为 ollama 的容器，状态是 Up ...。

2. 查看容器日志：
   bash
docker logs ollama
   查看 Ollama 的启动日志，确认没有明显的错误信息。你可能会看到 Ollama 正在启动服务并监听在 11434 端口。

3. 访问 Ollama API：
   Ollama 启动后会提供一个 REST API。你可以使用 curl 或浏览器访问其根路径，理论上应该返回一个 404 Not Found 错误，因为根路径没有特定资源，但这证明服务正在响应。
   bash
curl http://localhost:11434/
   或者尝试访问一个不存在的 API 端点，例如 /api/pull：
   bash
curl http://localhost:11434/api/pull
   如果服务正常，你会收到一个 JSON 格式的错误响应，而不是连接失败。

使用 Docker Ollama

一旦 Ollama 容器运行并对外暴露 11434 端口，你就可以通过多种方式与其交互。

1. 在宿主机上使用 Ollama 客户端 (推荐方式)

最方便的方式是在宿主机上安装 Ollama 命令行客户端，并将其配置为连接到运行在 Docker 中的 Ollama 服务。这样你就可以像直接安装 Ollama 一样，使用 ollama run, ollama pull, ollama list 等命令。

• 安装 Ollama 客户端： 根据你的操作系统，从 Ollama 官网下载并安装 Ollama。安装包通常会包含命令行客户端。
  • 下载地址：https://ollama.com/download

• 配置客户端连接 Docker 容器： Ollama 客户端默认连接 127.0.0.1:11434。由于我们将 Docker 容器的 11434 端口映射到了宿主机的 11434 端口，客户端应该能够直接连接。如果容器运行在不同的 IP 或端口，你需要设置 OLLAMA_HOST 环境变量来指向它。例如：
  “`bash
  # 在 Linux/macOS 终端
  export OLLAMA_HOST=http://localhost:11434

  在 Windows 命令提示符

  set OLLAMA_HOST=http://localhost:11434

  在 Windows PowerShell

  $env:OLLAMA_HOST=”http://localhost:11434″
  ``
将上述命令添加到你的shell配置文件（如~/.bashrc,~/.zshrc,~/.profile` 或 Windows 的环境变量设置）中，可以使其永久生效。

• 拉取模型 (使用宿主机客户端): 现在你可以使用宿主机的 ollama 客户端拉取模型了。模型会被下载到 Docker 容器内部，并存储在你挂载的命名卷或绑定目录中。
  bash
ollama pull llama2
ollama pull mistral
ollama pull yi:34b
  你可以访问 https://ollama.com/library 查看可用的模型列表。

• 运行模型 (使用宿主机客户端):
  bash
ollama run llama2 "你好，请介绍一下你自己。"
  这会启动与模型的交互会话。

• 列出已下载模型 (使用宿主机客户端):
  bash
ollama list

• 删除模型 (使用宿主机客户端):
  bash
ollama rm llama2

2. 直接与容器内的 Ollama 交互 (非主流方式)

你也可以直接在 Docker 容器内部执行 Ollama 命令。这通常用于调试或执行一次性任务，不推荐作为日常使用方式。

• 进入容器内部：
  bash
docker exec -it ollama bash
  这会打开一个连接到 ollama 容器的交互式 Bash shell。

• 在容器内拉取模型：
  bash
ollama pull llama2
  注意，模型仍然会存储在容器内部的 /root/.ollama 目录，该目录已挂载到宿主机的数据卷。

• 在容器内运行模型：
  bash
ollama run llama2
  这会在容器内部启动一个交互会话。

• 在容器内执行命令并退出：
  bash
docker exec ollama ollama list
docker exec ollama ollama run llama2 "请简单介绍下 Docker。"

3. 通过 REST API 交互

Ollama 提供了完整的 REST API，允许你通过编程方式与模型交互。这对于构建应用或集成到其他服务中非常有用。Docker 容器将 Ollama API 暴露在宿主机的 11434 端口。

• 生成文本 (Generate API):
  bash
curl http://localhost:11434/api/generate -d '{
"model": "llama2",
"prompt": "Tell me a short story.",
"stream": false
}'
  这将发送一个请求到 /api/generate 端点，让 llama2 模型生成一个非流式（一次性返回）的故事。

• 拉取模型 (Pull API):
  bash
curl http://localhost:11434/api/pull -d '{
"name": "mistral",
"stream": true
}'
  这将通过 API 拉取 mistral 模型，并以流式方式返回拉取进度。

• 查看模型列表 (Tags API):
  bash
curl http://localhost:11434/api/tags
  这将返回一个 JSON 列表，包含所有已下载的模型及其信息。

完整的 API 文档可以在 Ollama 的 GitHub 仓库中找到或通过访问容器内的 /api 端点（例如 http://localhost:11434/api，虽然不是一个标准文档页面，但可以作为起点）。

高级用法与技巧

定制 Ollama 容器

虽然 ollama/ollama 镜像是官方推荐的，但你可能需要基于它构建自己的镜像来预装特定模型、配置或依赖。

• 创建 Dockerfile：
  “`dockerfile
  # 基于官方 Ollama 镜像
  FROM ollama/ollama

  (可选) 复制自定义模型文件或 ModelFile

  COPY ./my_model.bin /root/.ollama/models/my_model.bin

  COPY ./MyModelFile /app/MyModelFile

  (可选) 在构建时拉取模型 (会增加镜像大小，不推荐生产环境)

  RUN ollama pull llama2

  RUN ollama pull mistral

  (可选) 在构建时创建自定义模型

  RUN ollama create my-custom-model -f /app/MyModelFile

  如果你希望容器启动时自动运行某个模型或脚本，可以修改 ENTRYPOINT 或 CMD

  例如，启动后立即进入 llama2 交互模式 (通常不需要)

  CMD [“ollama”, “run”, “llama2”]

  保持官方镜像的默认 ENTRYPOINT，让容器作为服务运行

  ENTRYPOINT [“/bin/ollama”, “serve”]
  * **构建镜像：**bash
  docker build -t my-ollama .
  * **运行自定义镜像：**bash
  docker run -d –gpus all -v ollama:/root/.ollama -p 11434:11434 –name my-ollama my-ollama
  “`

通常，更推荐使用官方镜像并在运行时通过 ollama pull 或 API 拉取模型，因为模型文件通常很大，频繁重建镜像效率不高。定制镜像更适合包含额外的工具或特定的启动脚本。

创建自定义模型 (ModelFile)

Ollama 允许你使用 ModelFile 文件来创建或定制模型，例如基于现有模型调整参数、添加系统指令、加载 LoRA 权重等。

• 创建 ModelFile： 在宿主机上创建一个文件，例如 MyModelFile。
  “`dockerfile
  FROM llama2 # 基于 llama2 模型

  添加一个系统指令

  SYSTEM “””你是一个乐于助人的 AI 助手。请用中文回答我的问题。”””

  (可选) 调整参数

  PARAMETER temperature 0.8
  PARAMETER top_k 40
  PARAMETER top_p 0.9
  PARAMETER num_ctx 4096

  (可选) 加载 LoRA 适配器 (需要将 LoRA 文件复制到容器可访问的位置，或挂载)

  ADAPTER ./my_lora_adapter.safetensors

  “`

• 将 ModelFile 复制到容器内（一次性）或挂载目录：

  • 复制： docker cp ./MyModelFile ollama:/tmp/MyModelFile (如果容器正在运行)
  • 挂载 (推荐)： 在 docker run 命令中添加一个绑定挂载，将包含 ModelFile 的目录挂载到容器内部。
    bash
# 假设 MyModelFile 在宿主机的 /path/to/model_files 目录下
docker run -d --gpus all -v ollama:/root/.ollama -v /path/to/model_files:/app/model_files -p 11434:11434 --name ollama ollama/ollama
    这样，MyModelFile 在容器内部的路径就是 /app/model_files/MyModelFile。

• 在容器内创建模型 (使用 docker exec):
  “`bash
  # 如果使用复制的方式
  docker exec ollama ollama create my-custom-model -f /tmp/MyModelFile

  如果使用挂载的方式

  docker exec ollama ollama create my-custom-model -f /app/model_files/MyModelFile
  “`

• 使用自定义模型： 创建成功后，你就可以像使用官方模型一样使用 my-custom-model 了（通过宿主机客户端或 API）。
  bash
ollama run my-custom-model "你好"

运行多个 Ollama 容器

你可能希望同时运行不同配置或不同版本的 Ollama 服务。只需为每个容器指定不同的名称和端口映射即可。

“`bash

运行第一个 Ollama 容器 (默认端口 11434)

docker run -d –gpus all -v ollama-main:/root/.ollama -p 11434:11434 –name ollama-main ollama/ollama

运行第二个 Ollama 容器 (映射到宿主机端口 11435)

docker run -d –gpus all -v ollama-exp:/root/.ollama -p 11435:11434 –name ollama-exp ollama/ollama
``
注意，这里为每个容器使用了不同的命名卷 (ollama-main和ollama-exp`)，以避免模型数据混淆。如果你希望它们共享模型数据，可以挂载同一个命名卷。

通过不同的端口，你可以访问不同的 Ollama 实例。宿主机客户端可以通过设置 OLLAMA_HOST=http://localhost:11435 来连接第二个实例。

集成到其他应用

许多 AI 应用、框架和库（如 LangChain, LlamaIndex, LiteLLM 等）都支持通过 REST API 连接到 Ollama。当你使用 Docker 运行 Ollama 并暴露端口后，这些应用就可以通过 http://localhost:11434 (或你配置的其他地址和端口) 与其通信。无需在应用所在的容器或环境中再次安装 Ollama，只需配置正确的 OLLAMA_HOST 或 API URL 即可。

故障排除

在使用 Docker Ollama 过程中，可能会遇到一些问题。以下是一些常见问题及其解决方案：

1. 容器无法启动或立即退出：

   • 检查容器日志：docker logs ollama。查找错误信息。
   • 检查端口是否已被占用：宿主机的 11434 端口可能已被其他程序占用。尝试映射到其他端口 -p 11435:11434。
   • 检查数据卷或绑定挂载的路径是否存在或权限是否正确。
   • 如果是 GPU 容器，检查 NVIDIA Container Toolkit (Linux) 或 Docker Desktop GPU 设置是否正确。

2. GPU 未被识别或无法使用 GPU：

   • Linux + NVIDIA: 确认已正确安装 NVIDIA 驱动和 NVIDIA Container Toolkit，并重启了 Docker 服务。使用 docker run --rm --gpus all ubuntu nvidia-smi 测试 Docker 是否能访问 GPU。
   • Windows + WSL2 + NVIDIA: 确认已安装最新的 NVIDIA 驱动，WSL2 版本正确，并在 WSL 中安装了 CUDA 工具包。Docker Desktop 设置中应启用 WSL2 集成和 GPU 支持。
   • macOS + Apple Silicon: 确认 Docker Desktop 版本较新，通常无需额外配置，Docker 会自动使用 Metal。
   • 确保 docker run 命令中使用了 --gpus all 标志。
   • 检查 Ollama 容器日志，看是否有关于 GPU 的错误或警告信息。

3. 无法从宿主机访问 Ollama 服务：

   • 确认容器正在运行：docker ps。
   • 确认端口映射正确：docker port ollama。
   • 检查宿主机防火墙是否阻止了对 11434 端口的访问。
   • 确认你连接的 IP 地址和端口是正确的 (localhost:11434 或宿主机的 IP:端口)。

4. 模型下载失败或中断：

   • 检查网络连接。
   • 检查宿主机挂载的数据卷是否有足够的磁盘空间：docker volume inspect ollama (对于命名卷) 或 df -h /path/to/your/ollama_data (对于绑定挂载)。模型文件通常很大，需要几十 GB 甚至上百 GB。
   • 尝试重新拉取。Ollama 支持断点续传。

5. 宿主机 Ollama 客户端无法连接：

   • 确认 Ollama 容器正在运行且端口映射正确。
   • 确认宿主机客户端没有错误配置 OLLAMA_HOST 环境变量。如果设置了，它应该指向 Docker 容器暴露的地址和端口。如果未设置，它默认连接 127.0.0.1:11434，这依赖于你 Docker 端口映射是否正确。

Docker Ollama 的优势总结

通过 Docker 运行 Ollama 带来了诸多好处：

• 标准化环境： 无论在哪里运行，环境都是相同的，避免了“works on my machine”的问题。
• 依赖隔离： Ollama 的依赖与宿主系统隔离，避免库冲突。
• 简化部署： 一条 docker run 命令即可启动服务，无需复杂的安装步骤。
• 易于管理： 使用标准的 Docker 命令即可管理 Ollama 服务（启动、停止、重启、删除）。
• 资源控制： Docker 提供了基本的资源限制能力（CPU、内存）。
• 持久化数据： 利用数据卷确保模型数据在容器生命周期外持久存储。
• GPU 跨平台部署： Docker 抽象了底层 GPU 访问机制（通过 NVIDIA Container Toolkit 或 Docker Desktop 集成），使得在不同系统上部署 GPU 加速的 Ollama 更加一致。

结论

Docker 与 Ollama 的结合为在本地或服务器上运行大语言模型提供了一个强大、灵活且易于管理的解决方案。通过本指南，你应该已经掌握了如何在 Docker 中安装、配置 Ollama，并了解了如何利用数据卷进行数据持久化以及如何启用 GPU 加速。无论是进行模型实验、本地开发 LLM 应用，还是在生产环境中部署，Docker Ollama 都是一个值得优先考虑的选择。

现在，开始你的 AI 探索之旅吧！拉取你感兴趣的模型，在 Docker 容器中体验本地运行 LLM 的强大能力。随着 Ollama 和 Docker 生态系统的不断发展，更多便捷的功能和集成也将不断涌现。

---