什么是Ollama — 使用Docker容器安装本地LLM并使用其API

当您想在自己的PC或服务器上直接运行大型语言模型，而不是调用ChatGPT或Claude等外部AI服务时，Ollama是您首先接触到的工具之一。因为它隐藏了复杂的推理引擎设置和模型文件管理，提供了简单的`ollama run`命令和HTTP API。

虽然Ollama可以直接安装在操作系统上，但作为Docker容器运行可以分离安装文件和执行环境，并以一致的方式管理版本更换、删除和恢复。另一方面，GPU连接、模型数据持久化和网络暴露需要在容器环境中单独理解。

本文将首先探讨Ollama的作用和内部结构，然后分步说明如何在CPU、NVIDIA GPU和AMD GPU环境下通过容器进行安装。我们将一次性整理模型下载、REST API、OpenAI兼容API、Docker Compose配置和操作安全。

什么是Ollama

Ollama是一个模型执行和管理工具，允许用户在本地或自己的服务器上下载并运行生成式AI模型。用户无需每次都组合详细的推理引擎选项，只需指定模型名称即可运行，并通过CLI或HTTP API进行对话。

Ollama的主要功能包括：

• 从模型Registry下载模型Manifest和Layer
• 本地模型文件和版本管理
• 选择适合硬件的CPU·GPU推理Backend
• 模型Load·Unload和内存保持时间管理
• 提供Text Generation, Chat, Embedding, Vision和Tool Calling API
• 利用Modelfile配置基于System Prompt和Parameter的用户模型
• 提供与部分OpenAI API兼容的Endpoint

Ollama本身不是像ChatGPT那样的完整Web聊天服务。它更接近于一个执行模型并提供API的模型运行时和模型服务器。如果需要浏览器UI，则需要连接单独的Web UI；如果需要RAG或Agent，则需要添加应用程序层。

图：Ollama的基本配置和请求处理流程 · 基于Ollama API、Docker安装文档重新配置

Ollama和vLLM是相同的工具吗

两者都运行模型，但侧重点不同。Ollama的优势在于为个人开发环境和小型自托管提供轻松获取和运行模型的体验。vLLM则更侧重于为大量用户请求提供高吞吐量的模型服务和GPU利用率优化。

分类	Ollama	vLLM
—	—	—
主要用途	本地开发，个人·团队模型运行	高吞吐量GPU模型服务
上手难度	仅凭模型名称即可轻松运行	需要设计模型·GPU·服务选项
模型管理	Pull·List·Run集成	以Hugging Face等外部模型路径为中心
API	Ollama Native API + 部分OpenAI兼容	OpenAI兼容服务中心
扩展性	适用于单主机和简单服务	适用于并行处理和服务器级操作

因此，如果“开发者想快速使用本地模型”，Ollama更方便；如果“需要运营供大量用户同时使用的GPU推理API”，则应同时比较vLLM或专用服务平台。

通过容器安装有什么不同

容器将Ollama可执行文件和库放入Image中，并与Host隔离运行。但是，如果模型文件也存储在容器的临时文件系统中，那么在更换容器时可能会丢失数GB到数十GB的模型。

因此，Ollama容器有三个核心连接：

Host의 11434 Port
→ Ollama Container의 11434 Port

Named Volume ollama_data
→ Container의 /root/.ollama

Host GPU Device 또는 GPU Runtime
→ Container의 추론 Backend

图：Ollama容器安装中必须连接的组件 · 基于Ollama Docker官方文档重新配置

即使删除了容器，如果Named Volume仍然存在，新容器也可以继续使用现有模型。相反，如果省略`-v ollama:/root/.ollama`，模型将依赖于容器的生命周期。

安装前准备事项

首先，必须安装Docker Engine或Docker Desktop。

docker version

如果计划使用GPU，请首先确认操作系统和GPU类型。

# NVIDIA GPU
nvidia-smi

# AMD ROCm环境
rocminfo

内存需求量根据模型的参数数量和量化程度而有很大差异。模型文件为4GB并不意味着VRAM也只需要精确的4GB。除了模型权重，还需要KV Cache和Runtime Buffer，并且增加Context Length会消耗额外的内存。

最初，最好使用比您的RAM或VRAM小得多的模型来验证安装流程。具体的模型大小和标签可以在Ollama Model Library中查看。

第一步：运行CPU专用容器

如果想在没有GPU的情况下验证功能，可以使用以下命令启动：

docker run -d 
  --name ollama 
  --restart unless-stopped 
  -p 127.0.0.1:11434:11434 
  -v ollama_data:/root/.ollama 
  ollama/ollama:latest

官方文档使用`-p 11434:11434`，但这种格式可能会根据Docker设置将端口暴露给Host的所有网络接口。本文以本地使用为基础，因此仅绑定到127.0.0.1。

每个选项的含义如下：

选项	含义
—	—
-d	在后台运行容器
–name ollama	将容器名称指定为ollama
–restart unless-stopped	除非用户停止，否则Docker重启后自动运行
-p 127.0.0.1:11434:11434	将Host的Localhost端口连接到容器API端口
-v ollama_data:/root/.ollama	将模型和设置永久存储在Named Volume中
ollama/ollama:latest	使用官方Ollama镜像

在生产环境中，固定经过验证的Version Tag或Image Digest而不是`latest`更安全。因为`latest`在重新部署时可能会拉取不同的版本。

检查容器状态和日志。

docker ps --filter name=ollama
docker logs --tail 100 ollama

确认API是否响应。

curl http://localhost:11434/api/version

第二步：模型下载和首次运行

官方Docker文档指导如何在容器内运行CLI，如下所示：

docker exec -it ollama ollama run llama3.2

如果模型不存在，会先下载，下载完成后会立即打开对话提示。结束对话后，可以查看模型列表。

docker exec ollama ollama list

如果想分离模型下载和运行，可以这样使用：

docker exec ollama ollama pull llama3.2
docker exec -it ollama ollama run llama3.2

也可以通过API获取模型。

curl http://localhost:11434/api/pull 
  -H 'Content-Type: application/json' 
  -d '{"model":"llama3.2","stream":false}'

模型拉取会产生大量的网络流量和磁盘使用量。与其配置多个容器同时修改同一个模型卷，不如让一个Ollama实例管理该卷更简单。

第三步：调用Ollama Native API

Ollama的默认API Base URL是`http://localhost:11434/api`。在Chat Endpoint中设置`stream:false`可以接收一次JSON响应。

curl http://localhost:11434/api/chat 
  -H 'Content-Type: application/json' 
  -d '{
    "model": "llama3.2",
    "messages": [
      {"role": "user", "content": "컨테이너의 장점을 세 문장으로 설명해줘"}
    ],
    "stream": false
  }'

`stream`的默认值是`true`。在这种情况下，生成过程会以多个JSON对象顺序传输，而不是一个完整的JSON。在CLI中这很自然，但直接放入普通的JSON解析器可能会导致错误，因此需要根据应用程序的方式进行配置。

响应中不仅包含答案，还包括模型加载时间、Prompt Token数量、生成Token数量和推理时间。利用这些信息，可以计算出大致的生成速度，如下所示：

초당 생성 Token
= eval_count / (eval_duration / 1,000,000,000)

第四步：连接OpenAI SDK

Ollama还提供与部分OpenAI API兼容的`/v1` Endpoint。通过更改现有OpenAI Client的`base_url`，可以调用Ollama模型。

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",
)

response = client.chat.completions.create(
    model="llama3.2",
    messages=[
        {"role": "user", "content": "Ollama를 한 문장으로 설명해줘"}
    ],
)

print(response.choices[0].message.content)

官方文档示例中的`api_key=”ollama”`是OpenAI SDK要求的值的占位符，本地Ollama API不会验证此值。根据Ollama官方文档，`localhost:11434`的本地API不需要认证。

“OpenAI兼容”并不意味着所有功能都完全相同。您需要验证所使用的Endpoint、Tool Calling、Vision、Structured Output和Streaming是否在目标模型中实际工作。

使用NVIDIA GPU运行

在Linux或Windows WSL2中将NVIDIA GPU连接到容器，需要在Host上安装NVIDIA Driver和NVIDIA Container Toolkit。安装方法因操作系统而异，因此应遵循NVIDIA Container Toolkit官方安装文档。

安装Toolkit后，配置Docker Runtime并重启Docker。

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

首先确认GPU在容器中是否可见。

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

然后，使用GPU选项运行Ollama。

docker run -d 
  --name ollama 
  --restart unless-stopped 
  --gpus all 
  -p 127.0.0.1:11434:11434 
  -v ollama_data:/root/.ollama 
  ollama/ollama:latest

如果只想使用多个GPU中的一部分，可以检查Host的GPU UUID并限制`CUDA_VISIBLE_DEVICES`。Ollama官方硬件文档建议使用UUID而不是数字索引，以获得更好的稳定性。

在模型运行一次后，检查GPU Offload情况。

nvidia-smi -L

检查PROCESSOR是否100%使用GPU，或者是否发生了一些CPU Offload。如果模型和Context大于VRAM，部分计算可能会转移到CPU，从而大大降低速度。

使用AMD GPU运行

使用AMD ROCm时，传递官方的`rocm`标签和GPU设备。

docker exec ollama ollama ps

支持的GPU和所需的ROCm Driver版本应在Ollama的Hardware Support文档中查看。某些Linux发行版可能会有SELinux阻止容器访问GPU设备，因此如果出现权限错误，请检查Audit Log和Container Device策略。

最近的官方Image还包含一个Vulkan Backend，可在存在可访问设备时使用。Vulkan和ROCm哪个更稳定取决于GPU和驱动程序的组合，因此应使用相同的模型和Prompt比较实际性能和错误。

图：不同容器环境下的Ollama加速路径 · 基于Ollama Docker、Hardware Support文档重新配置

macOS Docker可以使用GPU吗

有一个重要的限制。Ollama官方FAQ指出，由于GPU直通和模拟的限制，macOS的Docker Desktop无法使用Ollama GPU加速。

要利用Apple Silicon的Metal GPU，使用Ollama macOS App或原生安装更合适。如果容器隔离是必需的，Docker将以CPU模式运行，您可以考虑在Host上运行原生Ollama Server，并让其他容器通过`host.docker.internal:11434`访问。

此时，如果原生服务器绑定到外部，未经认证的API可能会暴露在网络中。需要同时设计Host防火墙和反向代理认证。

使用Docker Compose管理

为了重复执行和配置管理，可以使用如下的`compose.yaml`：

docker run -d 
  --name ollama 
  --restart unless-stopped 
  --device /dev/kfd 
  --device /dev/dri 
  -p 127.0.0.1:11434:11434 
  -v ollama_data:/root/.ollama 
  ollama/ollama:rocm

执行和状态检查如下：

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - "127.0.0.1:11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    environment:
      OLLAMA_KEEP_ALIVE: "5m"
    healthcheck:
      test: ["CMD", "ollama", "list"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  ollama_data:

要在Compose中预留NVIDIA GPU，可以向`ollama`服务添加以下设置。您需要首先确认您的Docker Compose版本是否支持GPU设备预留。

docker compose up -d
docker compose ps
docker compose logs -f ollama

如果同一Compose网络中的其他服务调用Ollama，则无需在Host上公开端口。

    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

在这种情况下，删除`ports`并在内部网络中使用服务名称`ollama`可以减少攻击面。

理解模型和内存操作

Ollama默认会在模型使用结束后，将其在内存中保留一段时间，以减少下次请求的加载时间。官方FAQ的默认值是5分钟，可以通过`OLLAMA_KEEP_ALIVE`或API的`keep_alive`参数进行调整。

Web UI Container
→ http://ollama:11434
→ Ollama Container

始终保持在内存中可以减少首次Token延迟，但可能会导致其他模型VRAM不足。在频繁切换多个模型的小型GPU上，应保持较短时间；如果请求集中在一个模型上，则可以延长保持时间。

Context Length也对内存有很大影响。Ollama根据VRAM设置不同的默认Context，并且设置更长的Context会使KV Cache变大。当为了Agent或编码任务增加Context时，不要只看模型是否加载，而应在实际长Prompt中测量VRAM和Token速度。

environment:
  OLLAMA_KEEP_ALIVE: "10m"

更新和备份

如果使用了Named Volume，即使更换Container Image，模型数据也会保留。在Compose中，可以按以下顺序进行更新：

docker exec ollama ollama ps
docker stats ollama

在生产环境中，应首先在单独的环境中验证新版本，然后更改Version Tag或Digest。尽管API通常旨在向后兼容，但Ollama官方文档解释说API并非严格版本化。

Volume本身应包含在备份策略中。但是，可以随时从公共Registry重新下载的模型层与自己创建的Modelfile·Private Model的重要性不同。如果需要缩短恢复时间，请备份整个Volume；如果需要降低存储成本，请优先保留用户自定义资产和配置信息。

外部公开前必须了解的安全事项

本地Ollama API没有默认认证。因此，应避免以下配置：

docker compose pull
docker compose up -d

如果攻击者访问API，他们可以重复调用模型以消耗CPU·GPU和内存，通过模型拉取使用磁盘和网络，或者访问操作员不希望访问的模型。

如果需要向外部或内部网络提供服务，应在Ollama前面放置反向代理或API网关，并应用以下控制：

• TLS和用户·服务认证
• IP·网络白名单
• 每个用户的速率限制和并发请求数限制
• 允许的模型列表和Endpoint限制
• 请求体大小和超时限制
• Prompt·Response日志中的个人信息掩码
• 分离Model Pull·Create·Delete等管理API
• 监控容器CPU·内存和GPU使用量

简单地设置`OLLAMA_HOST=0.0.0.0:11434`只会扩大访问范围，而不会增加认证。

常见问题

API已打开，但响应太慢

可能正在CPU上运行，或者某些层已卸载到CPU。

Internet
→ 0.0.0.0:11434
→ 인증 없는 Ollama API

减少模型或降低Context Length，并确认GPU Runtime和Driver是否正常传递到容器。

重新创建容器后模型消失了

很可能没有将Volume挂载到`/root/.ollama`，或者使用了不同的Volume名称。

docker exec ollama ollama ps
docker stats ollama

在删除之前，应检查当前的挂载和Volume名称。

其他容器无法连接到localhost:11434

容器内的`localhost`指的是该容器自身。在同一个Docker网络中，应使用Ollama服务名称。

docker volume ls
docker inspect ollama

如果Docker Desktop容器需要访问在Host上运行的Ollama，可以使用`host.docker.internal`。

浏览器中出现CORS错误

Ollama允许通过`OLLAMA_ORIGINS`添加允许的Origin。不应无条件允许所有Origin，而应仅指定实际Web UI的Origin。CORS是浏览器策略，不能替代API认证。

Ollama容器适用与不适用的情况

Ollama容器非常适合以下情况：

• 在开发人员PC或团队服务器上快速测试多个模型时
• 使用本地模型处理难以发送到外部API的文档时
• 开发RAG·Agent·AI Gateway需要内部模型Endpoint时
• 在多个Linux服务器上重现相同配置时

相反，如果以下要求是核心，则应比较其他服务堆栈：

• 大量并发用户的高吞吐量
• 使用多个GPU和多个节点的分布式服务
• 自动扩展、滚动更新和精细的请求调度
• 严格的多租户和每个模型的SLA
• 基于Kubernetes的大规模GPU池运营

在Ollama前面放置API网关可以补充认证和速率限制，但这并不能将运行时本身转变为大规模分布式服务平台。

总结

Ollama是一个通过将模型下载、执行、内存管理和API提供捆绑到一个用户体验中，从而降低本地LLM入门门槛的工具。通过Docker运行时的核心并不复杂。

http://ollama:11434

最简单的CPU安装只需一行命令，但在实际操作中，有三点不容忽视：持久化模型卷、确认GPU是否实际使用，以及不直接将未经认证的11434端口暴露到外部。

在macOS上使用Docker时，GPU加速不可用这一点也很重要。要利用Apple GPU，应使用原生Ollama应用程序，而在Linux·WSL2的NVIDIA环境中，则需要配置NVIDIA Container Toolkit。

最初，最安全的方法是使用小型模型和Localhost绑定来验证功能，然后根据模型大小、Context、并发请求和安全要求，扩展到适合您环境的配置。

参考资料

• Ollama Docker官方文档
• Ollama API介绍
• Ollama Chat API
• Ollama Model Pull API
• Ollama OpenAI兼容API
• Ollama认证指南
• Ollama硬件支持
• Ollama上下文长度
• Ollama模型库