Ollama：面向个人计算机和小型服务的本地 LLM 推理

Ollama 将模型获取、本地推理、命令行界面、桌面应用程序和 HTTP API 集成到一个工具中。无需先组装 Python 环境、推理引擎、分词器、提示词模板和 GPU 运行时，它就是下载开放权重模型并在开发者工作站上运行的最简单方式之一。

最小会话如下：

ollama pull qwen3:8b
ollama run qwen3:8b

Ollama 会选择合适的本地运行器，存储模型，在需要时启动模型，并应用模型的聊天模板。这种便利性使 Ollama 适合个人计算机、应用程序开发、演示和小型内部服务。但它不会自动将笔记本电脑变成高吞吐量或高可用的生产推理集群。

Ollama 能做什么 #

Ollama 可以：

• 下载、列出、检查、运行、复制和删除模型；
• 提供交互式文本聊天和文本生成；
• 运行受支持的视觉语言、嵌入、工具调用和推理模型；
• 将受支持模型的输出约束为结构化 JSON；
• 导入受支持的模型权重或 GGUF 文件，并通过 Modelfile 定制模型行为；
• 通过原生 REST API 提供本地模型；
• 提供与 OpenAI API 的部分兼容性；
• 在可用 RAM 或 VRAM 范围内，让一个或多个模型驻留内存并处理并发请求；以及
• 可选地使用 Ollama 托管的云模型，而不是本地硬件。

这些是运行时功能，并不是每个模型都具备的能力。纯文本模型不会因为请求采用视觉端点的格式就能理解图像；未针对工具使用进行训练的模型也可能生成质量较差的工具调用。在基于模型构建系统之前，请检查 Ollama model library 中的模型卡片、许可证、上下文限制和标签。

本地服务器通常监听 http://127.0.0.1:11434。CLI、桌面应用、API 客户端、编辑器扩展和第三方聊天界面都是该服务的客户端：

Ollama 不是什么 #

Ollama 不是：

• LLM，也不是模型权重本身的来源；
• 模型训练或完整微调框架；
• 对模型准确、安全、无偏或适用于特定用途的保证；
• 检索增强生成系统、向量数据库、智能体框架或工具沙箱；
• 对每个 OpenAI API 端点和选项的完整实现；
• 本地 API 的认证、授权、配额或计费网关；
• 带有自动故障转移的多节点调度器；也不是
• 容量规划、监控、备份和受控升级的替代品。

Ollama 可以作为 RAG 或智能体应用中的一个组件，但应用仍需负责文档摄取、检索、会话状态、工具执行、访问控制和错误处理。工具调用尤其重要：模型只负责提出调用，受信任的应用代码必须对其进行验证并执行。

在本地运行模型并不意味着每项操作都处于离线状态。拉取模型需要网络访问，云模型或网页搜索功能会向远程服务发送请求。如果必须仅使用本地操作，请设置 OLLAMA_NO_CLOUD=1，或在 ~/.ollama/server.json 中设置 disable_ollama_cloud。

Ollama 与 vLLM 的比较 #

vLLM 同样是推理引擎和服务器，但优化重点不同。它的 PagedAttention、连续批处理、前缀缓存、并行化和分布式服务功能，目标是高效地为大量请求提供共享服务。Ollama 则优化从没有运行时到在一台机器上运行模型的路径。

比较并不是简单的“开发与生产”之分。当 Ollama 在一台机器上服务于受限的内部工作负载，并且外围系统提供身份验证、TLS、监控和恢复时，它可以适用于生产环境。同样，vLLM 也可以在一台开发服务器上运行。决定因素是工作负载：

• 当需要个人助手、私密实验、本地应用开发、支持离线的工作流、课堂使用或轻量共享的单主机服务时，选择 Ollama。
• 当并发用户数、每个加速器每秒生成的 token 数、可预测的排队、Prometheus 指标、分布式 GPU 或基于 Kubernetes 的扩展足以证明额外运维复杂性的合理性时，选择 vLLM。
• 当目标服务处于两者之间时，分别进行基准测试。测量首 token 时间、每秒输出 token 数、尾延迟、内存使用量，以及在预期并发数和上下文长度下的行为。

Ollama 的优势是运维摩擦低，并且广泛支持工作站。缺点是放弃了专用集群服务引擎所期待的许多控制能力和优化。vLLM 的优势是加速器利用率和服务规模；缺点是设置路径更复杂、对硬件更敏感，并且没有面向消费者的桌面体验。

部署 #

选择部署方式 #

最简短且可靠的规则如下：

Ollama 通过让本地推理变得平常而成功：安装一个应用程序，拉取一个模型，然后从聊天窗口、终端、编辑器或程序中使用同一个运行时。这种简单性是它的主要特性。不过，需要明确边界。Ollama 负责运行模型；可靠的产品仍必须在模型周围提供安全性、状态管理、评估、可观测性和运维控制。

使用 Docker 安装到 Linux 主机 #

Docker 是 Linux 推理主机上的自然部署方式，因为容器可以访问 Linux GPU 设备接口。首先，在主机上安装可用的 GPU 驱动程序。对于 NVIDIA GPU，还要安装并配置 NVIDIA Container Toolkit：

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

使用持久化模型卷启动 Ollama。将发布端口绑定到回环地址，可以避免意外暴露未经身份验证的 API：

docker run --detach \
  --name ollama \
  --restart unless-stopped \
  --gpus all \
  --publish 127.0.0.1:11434:11434 \
  --volume ollama:/root/.ollama \
  ollama/ollama

拉取模型并验证推理是否正常：

docker exec ollama ollama pull qwen3:8b
docker exec -it ollama ollama run qwen3:8b
curl http://127.0.0.1:11434/api/version
docker exec ollama ollama ps

ollama ps 会报告已加载模型位于 CPU、GPU，还是在两者之间分配。不要假定存在 GPU 就意味着模型正在使用它。

仅使用 CPU 推理时，省略 --gpus all。这适用于小型模型、功能测试以及没有受支持加速器的机器：

docker run --detach \
  --name ollama \
  --restart unless-stopped \
  --publish 127.0.0.1:11434:11434 \
  --volume ollama:/root/.ollama \
  ollama/ollama

对于受支持的 AMD GPU，使用 ROCm 镜像并传入 GPU 设备：

docker run --detach \
  --name ollama \
  --restart unless-stopped \
  --device /dev/kfd \
  --device /dev/dri \
  --publish 127.0.0.1:11434:11434 \
  --volume ollama:/root/.ollama \
  ollama/ollama:rocm

在选择主机之前，请查看 Ollama 当前的 Docker 和 GPU 兼容性页面。GPU 系列、驱动程序、容器运行时和镜像必须相互匹配。对于受控部署，请固定经过测试的 Ollama 发布标签或镜像摘要，而不是通过 latest 隐式升级。

如果必须从另一台机器访问服务，不要只是将发布地址改为 0.0.0.0 并打开防火墙。应将 Ollama 放在经过身份验证的反向代理或 API 网关之后，由其提供 TLS、请求大小限制、超时、速率限制和审计日志。

在 macOS 上原生安装 #

在 Mac 上，原生安装是正确路径：

1. 从官方 macOS installation page 下载 ollama.dmg。
2. 将 Ollama 拖到 Applications 中并启动。
3. 出现提示时，允许应用将 ollama CLI 链接放置到 /usr/local/bin。
4. 拉取并运行模型：

ollama pull qwen3:8b
ollama run qwen3:8b

当前版本要求 macOS Sonoma 14 或更高版本。Apple M 系列系统可以通过原生运行时同时使用 CPU 和 GPU；Intel Mac 使用 CPU 推理。模型和配置存储在 ~/.ollama 下，模型可能占用几十或数百 GB。

桌面应用通常负责后台服务器。需要前台服务时，可以在终端中显式运行 ollama serve 来启动服务器。

macOS 与 Docker 不适合组合使用的原因 #

Docker Desktop for macOS 上的 Linux 容器不会直接运行在 macOS 内核上，而是运行在 Linux 虚拟机中：

Apple 的 Metal GPU 接口可供原生 macOS 应用程序使用，但 Docker Desktop 不会将该 GPU 直通，也不会将其模拟为 Ollama 容器支持的 Linux 加速器。因此，Ollama 无法在 macOS 上的 Docker Desktop 中使用 GPU 加速。

容器在技术上可以仅使用 CPU 运行，因此“Mac 上无法在 Docker 中运行 Ollama”这一说法过于绝对。实际问题在于，Linux 虚拟机增加了开销，却放弃了 Mac 的主要推理优势：GPU 和统一内存。原生 Ollama 可以使用 Metal，文件系统和网络路径更简单，并提供桌面应用。推理应使用 macOS 加原生 Ollama；Linux 容器应保留给 Linux 主机。单独的 Web UI 仍可以在容器中运行，并调用原生 Ollama 服务器。

Ollama 管理 CLI #

管理 CLI 负责管理 Ollama 服务器、模型和账户会话。桌面应用或系统服务通常会启动服务器；只有在手动运行服务器时才使用 ollama serve。

# Show available commands and global options.
ollama --help

# Show the installed Ollama version.
ollama --version

# Show options for a particular command.
ollama run --help

# Start the Ollama server in the foreground.
ollama serve

# Download a model, or update the local copy of an existing tag.
ollama pull qwen3:8b

# List models stored on this machine.
ollama list

# Use the shorter alias for `ollama list`.
ollama ls

# Show a model's metadata, parameters, template, and capabilities.
ollama show qwen3:8b

# List models currently loaded into memory and their CPU/GPU placement.
ollama ps

# Unload a model and release its memory.
ollama stop qwen3:8b

# Create a custom model from a Modelfile.
ollama create my-model --file ./Modelfile

# Copy a model to another local name or tag.
ollama cp qwen3:8b qwen3:project

# Delete a local model.
ollama rm qwen3:project

# Publish a namespaced model after authenticating with ollama.com.
ollama push account/my-model

# Sign in to ollama.com for cloud models and model publishing.
ollama signin

# End the ollama.com session.
ollama signout

运行 ollama <command> --help 可查看特定命令的选项。模型名称包含标签：qwen3:8b 和 qwen3:14b 是不同的工件，而省略标签通常会解析为 latest。图像和 WAV 输入要求模型具备相应的多模态能力。CLI 不能直接读取视频、PDF 或办公文档；在将这些内容发送给兼容模型之前，应先进行转录、提取或转换。

Web/GUI 前端 #

多个独立前端可以连接到已经运行的 Ollama 服务。它们不会取代 Ollama 的模型运行时，而是增加会话存储、文档工作流、用户账户或桌面界面。

根据应用边界进行选择：

• Chatbox 为单个用户提供所需的最少额外基础设施。
• Open WebUI 为以本地模型为中心的共享浏览器界面提供直接路径。
• LibreChat 或 LobeChat 适合需要将 Ollama 与多个模型提供商结合的部署。
• AnythingLLM 将界面重点放在文档集合和检索上。

容器网络会改变 localhost 的含义：在前端容器内部，它指向该容器自身，而不是 Ollama 主机。根据情况使用 Docker 主机别名、Compose 服务名或私有服务器地址。如果浏览器直接连接 Ollama，请通过 OLLAMA_ORIGINS 仅配置必需的来源；避免使用 *，因为它允许所有 Web 来源。

每个前端都会独立于 Ollama 存储额外状态。备份其会话数据库和上传的文档，配置身份验证，并确认可选云功能是否会将提示词或文件发送到远程服务。不要仅为了让前端可访问而暴露 Ollama 的未认证端口；应暴露经过身份验证的前端，并将 Ollama 保留在内部网络中。

使用原生 API #

原生 API 位于 http://localhost:11434/api。非流式聊天请求如下：

curl http://localhost:11434/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3:8b",
    "messages": [
      {"role": "user", "content": "Explain copy-on-write in two paragraphs."}
    ],
    "stream": false
  }'

生成和聊天默认启用流式传输，服务器会在生成 token 时返回一系列以换行分隔的 JSON 对象。应用程序应增量解析流，处理断开连接和非 2xx 响应，并设置自己的截止时间。

重要的端点组包括：

Ollama 提供官方的 Python 和 JavaScript 库。Python 客户端保持相同的基本数据模型：

from ollama import chat

response = chat(
    model="qwen3:8b",
    messages=[
        {"role": "user", "content": "Why does context length use memory?"}
    ],
)
print(response.message.content)

使用 OpenAI 兼容 API #

已经使用 OpenAI 客户端编写的应用程序，可以将受支持的操作指向 http://localhost:11434/v1/：

from openai import OpenAI

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

response = client.chat.completions.create(
    model="qwen3:8b",
    messages=[
      {"role": "user", "content": "Give me three names for a backup tool."}
    ],
)
print(response.choices[0].message.content)

本地服务器会忽略 API 密钥，但 OpenAI SDK 要求提供非空值。受支持的兼容端点包括 Chat Completions 和 Responses，但兼容性是有意保持部分实现的。请求格式被接受，并不意味着所有参数、事件、usage 字段、模型行为或未来的 OpenAI 功能都得到支持。测试应用程序实际使用的确切操作；需要 Ollama 特定控制能力时，优先使用 Ollama 的原生 API。

上下文管理 #

由于 Ollama 不拥有持久化的会话数据库，上下文管理横跨客户端和服务器。CLI、GUI 或应用程序负责组装每个请求；Ollama 负责渲染请求并强制执行模型的上下文限制。

因此，即使使用相同模型和 Ollama 服务器，不同前端也可能产生不同结果，因为它们的系统提示词、历史选择、摘要、检索文档和生成参数可能不同。

交互式 ollama run #

ollama run MODEL 维护两种不同的历史记录：

1. 提示词输入历史 允许用户使用方向键调出之前的输入。/set history 和 /set nohistory 控制此 readline 功能。提示词输入历史只包含用户输入，而不是完整的用户和助手轮次，因此它不是发送给模型的会话。
2. 会话历史 是运行中的 CLI 进程持有的 system、user 和 assistant 消息有序数组。每次响应后，CLI 会追加助手消息。在下一轮中，它会将累积的消息数组发送给聊天 API。

因此，会话历史会在同一个 ollama run 进程的多次提示之间持续存在，但进程退出后不会自动恢复。/clear 会移除当前会话上下文，同时保留活动的系统消息。

/save <model-name> 通过创建一个新的 Ollama 模型来提供显式持久化，其定义包含当前消息、参数和系统消息。之后使用 /load <model-name> 可加载保存的模型及其初始消息历史。保存的工件是派生模型定义，而不是可搜索的转录数据库。请避免保存机密信息，因为嵌入的消息会成为模型工件的一部分，并且可以被检查或复制。

每一轮都会到达模型吗 #

CLI 会在每个新提示中发送完整的累积消息数组。推理服务器随后渲染聊天模板，并将结果放入配置的上下文窗口。当渲染后的历史超过 num_ctx 时，服务器会从前面移除较旧的消息，同时保留系统消息和最新的用户消息。因此：

• API 请求可以包含 CLI 保留的每一轮；
• 模型只能看到系统消息和能放入上下文窗口的最新后缀；
• 某个旧事实可能从有效上下文中消失，但仍存在于 CLI 的内存数组中；以及
• 增大 num_ctx 会保留更多历史，但会增加 KV 缓存内存使用量，并可能降低并发能力。

使用以下命令设置和检查会话上下文：

# Change the context window for the current interactive session.
/set parameter num_ctx 16384

# Clear accumulated conversation messages.
/clear

# Persist the conversation as a derived model.
/save project-session

# Load a saved session or another model.
/load project-session

这种行为是截断，而不是持久化记忆或语义召回。CLI 不会在丢弃旧轮次之前总结旧会话。需要持久会话状态的应用程序应自行存储消息，应用明确的摘要策略，并通过聊天 API 发送选定的历史。

前端和 API 客户端策略 #

Ollama 的聊天 API 处理当前请求中的 messages 数组；它不会通过会话 ID 检索之前的会话。API 客户端必须存储已完成的轮次，并重新发送维持连续性所需的历史。

前端可以实现比 ollama run 更高级的策略：

• 在自己的数据库中保留完整转录；
• 在请求接近上下文限制之前发送所有消息；
• 保留第一条系统消息和最近的轮次；
• 用生成的摘要替换较早轮次；
• 为用户偏好、决策或工具状态维护单独的摘要；
• 根据嵌入相似度检索相关的历史消息；或
• 注入 RAG 管道选出的文档块。

前端设置还可以通过发送 num_ctx 来改变 Ollama 的有效上下文长度。更大的值不会强制前端发送更多历史，只会为组装后的请求提供更多空间。相反，前端可能在 Ollama 达到该限制之前很久就丢弃或总结历史。

当确切行为很重要时，请检查前端文档或出站请求。GUI 中可见的会话历史不能证明每条可见消息都已发送给模型。Open WebUI、LibreChat、AnythingLLM、LobeChat 和 Chatbox 独立于 Ollama 管理会话和检索策略，而这些策略可能在不同版本之间发生变化。

背景文档和 RAG #

Ollama 服务器不包含文档集合、分块器、向量索引或检索策略。因此，它不提供完整的 RAG 系统。可以采用以下几种集成级别：

1. 直接上下文： 将文档文本粘贴到提示词中，或将提取的文本通过管道传给 ollama run。只有当文本仍处于上下文窗口内时，模型才能使用它。图像和音频路径要求模型具有匹配的多模态能力；PDF 和办公文档必须先转换为文本或图像。
2. 静态模型上下文： 将简短且稳定的指令或事实放入 Modelfile 的 SYSTEM 或 MESSAGE 条目中。这些条目会被包含在提示词中而不是建立索引，因此会消耗上下文，并且无法扩展到文档语料库。
3. 应用程序管理的 RAG： 使用 Ollama 的嵌入 API 嵌入文档块，将向量和来源元数据存储在向量数据库中，为每个问题检索相关文档块，并将其包含在聊天请求中。Ollama 提供嵌入和生成模型；应用程序代码负责摄取、检索、引用、访问控制和会话持久化。
4. 第三方界面： 使用 Open WebUI 等实现知识库或 RAG 工作流、并将 Ollama 作为模型运行时的客户端。界面的检索行为、存储、权限和备份均独立于 Ollama。

最小 RAG 请求路径如下：

直接粘贴整个语料库属于提示词填充，而不是 RAG，因为没有检索步骤来选择相关证据。正确的 RAG 还应在文档块旁保留来源标识符，以便应用程序显示引用，并在内容到达模型之前执行文档级授权。

选择模型并确定机器规格 #

模型选择对使用体验的影响大于 Ollama 的安装方式。请考虑：

• 任务： 通用聊天、代码、嵌入、视觉、工具或特定领域工作；
• 许可证： 商业使用、再分发和生成输出的权限；
• 参数量和量化： 更小或量化程度更高的模型占用更少内存，但可能损失质量；
• 上下文长度： 更长的提示词和 KV 缓存会消耗更多内存；
• 语言覆盖范围： 对用户需要的语言和术语进行基准测试；以及
• 提示词模板和能力： 使用正确的 Ollama 模型标签，不要假设两个变体可以互换。

模型在磁盘上的大小不足以估算所需内存。推理还需要运行时缓冲区和 KV 缓存；KV 缓存会随着上下文长度、并发量、模型架构和精度增长。在 Apple Silicon 上，CPU 和 GPU 共享统一内存，但 macOS 及其他应用程序仍需要占用一部分内存。在独立 GPU 主机上，溢出到系统 RAM 的权重通常运行得慢得多。

Ollama 的默认上下文策略在不同版本之间发生过变化，并且可能取决于可用 VRAM。应明确设置所需上下文，然后使用 ollama ps 验证已分配的上下文以及 CPU/GPU 分配：

OLLAMA_CONTEXT_LENGTH=16384 ollama serve
ollama ps

上下文越大并不一定越好。它会增加内存压力，降低并发能力，或导致 CPU 卸载。还要测试质量：模型宣称的最大上下文并不能保证在整个窗口中都具有同等良好的注意力表现。

生产和安全检查清单 #

在将 Ollama 作为共享服务之前：

1. 保护 API。 本地 API 没有身份验证。将其保持在回环地址或私有网络中，或者在前面放置经过身份验证的 TLS 代理。不要依赖虚假的 OpenAI API 密钥来提供安全性。
2. 固定运行时和模型。 记录 Ollama 版本、确切的模型标签或摘要、Modelfile、提示词模板、上下文和生成参数。可变标签或运行时升级可能改变输出。
3. 规划存储。 在更换容器后保留模型卷。当模型数据需要位于其他磁盘时，使用 OLLAMA_MODELS。备份自定义 Modelfile 和配置；大型注册表模型通常可以重新拉取。
4. 设置容量限制。 OLLAMA_NUM_PARALLEL、OLLAMA_MAX_LOADED_MODELS、OLLAMA_MAX_QUEUE、上下文长度和 keep_alive 都会影响内存和延迟。过载服务器可能以 HTTP 503 拒绝请求。
5. 预热重要模型。 第一个请求可能包含模型加载延迟。空的 generate 或 chat 请求可以预加载模型，而 keep_alive 控制模型保持驻留的时间。
6. 观察服务。 收集容器或服务日志、请求延迟、队列失败、磁盘使用量、内存、加速器利用率和应用程序错误率。Ollama 的基本检查命令不是完整的监控系统。
7. 限制请求和输出。 应用请求体大小限制、截止时间、输出限制、并发限制和取消机制。将生成文本和模型提出的工具参数视为不受信任的输入。
8. 测试故障和恢复。 验证发生内存不足、磁盘损坏或已满、模型拉取中断、进程重启和客户端断开时的行为。如果停机不可接受，则需要第二台主机或备用服务。
9. 控制出站流量。 决定是否允许模型拉取、云模型、网页搜索、代理和第三方 UI。只有当整个请求路径保持本地时，本地推理才能保护提示词。
10. 审查两种许可证。 Ollama 的许可证与模型的许可证相互独立。部署运行时并不会授予使用其模型库中每个模型的权利。

参考资料 #

• Ollama documentation
• Ollama Docker installation
• Ollama macOS installation
• Ollama API reference
• Ollama OpenAI compatibility
• Ollama CLI reference
• Ollama context length
• Ollama embeddings
• Ollama Modelfile reference
• Ollama FAQ
• Ollama interactive CLI source
• Ollama chat-prompt truncation source
• vLLM documentation
• vLLM project repository