Ollama 本地大模型：安装、API、Docker 与 OpenAI 兼容指南

Ollama 可在个人电脑或服务器上运行本地模型，并提供可由应用调用的 API。本文按“先本地运行、再接应用、最后考虑远程访问”的顺序，介绍安装、模型管理、HTTP API、OpenAI 兼容接口、Docker 与安全边界。

资料核对日期：2026-10-22。 模型名称、平台支持和 GPU 能力更新较快，安装与硬件细节以 Ollama 官方文档及模型页为准。

本地模型与 Cloud Models 的区别

对比项	本地模型	云端模型
推理位置	自己管理的设备	云端服务
网络依赖	本地服务可在设备内调用；下载模型仍需网络	请求需发送到云服务
认证	本地 API 端点不应视为带认证	按服务方配置账户与 API Key
主要运维	磁盘、设备资源、更新和网络暴露	凭证、用量、供应商条款与数据策略

Ollama 同时支持本地模型和云端模型。使用本地模型时，模型推理由自己的设备承担；云端模型则需要账户和 API Key，推理请求会发送到云服务。二者的隐私边界、网络要求和资源成本不同。安装了 Ollama 并不等于所有请求都会留在本机，接入前先确认模型类型和请求实际去向。

本地运行适合离线实验、内部原型、私有数据处理以及学习模型服务；但要考虑内存、存储、模型下载时间和并发性能。小型模型通常更适合作为第一次验证对象，具体能否流畅运行取决于模型、量化、上下文长度、系统余量和 GPU，不应用参数规模简单推算速度。

安装与第一次运行

官方提供 macOS、Windows 和 Linux 的下载方式。按 Ollama Quickstart 下载并完成安装提示，然后在终端运行 CLI。模型名应先从官方 Library 确认；以下仅演示命令形式：

ollama run gemma4

首次运行会按需获取模型。退出交互可使用 /bye。常用管理命令包括：

ollama list
ollama ps
ollama --version

如果命令不可用，先确认安装成功、终端已重新加载以及程序路径正确；如果模型无法加载，检查磁盘空间、设备内存和当前模型页要求，不要先假定一定是 GPU 驱动问题。

本地 API：生成与对话

本地服务通常在 http://localhost:11434 提供 API。对话接口为 /api/chat。以下示例关闭流式输出，便于先检查完整 JSON 响应：

curl http://localhost:11434/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemma4",
    "messages": [
      {"role": "user", "content": "解释 Docker volume 的用途。"}
    ],
    "stream": false
  }'

把模型名替换为本机已安装且当前可用的模型。响应会包含模型生成的消息内容。若应用使用流式响应，应按官方 API 文档逐段读取，不能把每一段 JSON 当成最终完整对象。

兼容 OpenAI 客户端

Ollama 提供部分 OpenAI API 兼容端点，本地服务 Base URL 可设为 http://localhost:11434/v1/。例如：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # 本地兼容示例需要此参数；本地服务会忽略它
)

result = client.chat.completions.create(
    model="替换为本机模型名",
    messages=[{"role": "user", "content": "给我一个排错步骤。"}],
)
print(result.choices[0].message.content)

“兼容”指有一部分 API 形状可供现有客户端使用，不代表 OpenAI 的每个参数和能力都支持。需要 Responses、工具调用、视觉或结构化输出时，先对照当前兼容文档并用小请求验证。示例中的 api_key 字段也不是给本地服务加上了认证。

Docker 运行

官方 Docker 文档提供 CPU-only 容器示例。命名 volume 用于持久化模型文件：

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

启动后可在容器中运行模型：

docker exec -it ollama ollama run llama3.2

确认模型标签和下载内容符合需求。删容器不等于删掉命名 volume；反过来，删除 volume 会丢失其中的数据，因此清理前先确认目标。

NVIDIA GPU 容器需要按官方文档安装并配置 NVIDIA Container Toolkit，然后运行时传入 GPU 设备；AMD Docker 示例使用 ROCm 镜像和设备映射。驱动、容器运行时、宿主系统和 GPU 型号都影响兼容性，照抄命令不保证所有机器都可用。优先按硬件厂商和 Ollama 文档核对版本，不要通过关闭安全机制来绕过设备问题。

远程访问与安全

本地 API 的开发地址应尽量保持在回环接口。把端口直接映射到公网，会让未经授权的人有机会消耗你的硬件和资源。Docker 的 -p 11434:11434 可能将端口发布到宿主机网络；在共享服务器或不可信网络中，应明确绑定地址并检查防火墙，而不是默认认为它仅本机可见。

跨设备使用时，优先选可信私网或 VPN；若必须通过 HTTPS 反向代理或 Cloudflare Tunnel 提供访问，还要单独设置认证、访问策略、限流和日志脱敏。Tunnel 只建立流量路径，不自动替应用增加登录保护。不要把只需本机访问的模型 API 作为公开服务发布。

从安装到应用接入：建议工作流

第一次部署可按这个顺序缩小问题范围：

在官方 Model Library 查看模型标签、许可证说明和系统要求；按模型页面选择具体型号，不要因为名称相似就认为能力、量化和资源要求相同。
先用 CLI 拉取并交互验证模型：

ollama pull gemma4
ollama run gemma4

保持默认本机服务，仅从本机调用 localhost:11434。先运行本文的 /api/chat 示例，再接入 SDK。切换到云端 API 时应按云服务文档配置真实凭证；本地示例中的占位 key 不适用于云端认证。
最后再尝试 Docker、GPU 和跨设备访问。每次只改一个条件，记录宿主机系统、容器版本、模型标签与错误信息（脱敏后），便于定位问题。

SDK 返回错误时，先核对 Base URL 是否仍指向本地服务、模型名是否已下载、Ollama 服务是否运行，以及所用 API 能力是否属于当前兼容范围。工具调用、视觉输入、结构化输出等功能要逐项以兼容文档和模型支持为准，不能从“支持 OpenAI API”推断所有参数都可用。

Docker 网络与数据

Docker 容器的 localhost 只代表当前容器。另一个应用容器要访问 Ollama 时，应把服务放在受控的共同网络中并使用 Ollama 容器名及内部端口；具体网络名称按自己的 Compose 配置设置。不要为了省事把模型端口绑定到所有网卡。若只供宿主机使用，可评估将宿主机映射绑定到回环地址，并通过防火墙确认实际暴露范围。

模型文件保存在持久化目录或 volume 中，会占用磁盘。升级镜像通常不等同于升级或删除模型，但删 volume 会删除持久化数据。更新前确认 Docker volume 与备份策略；日志、提示词和应用客户端也可能记录敏感输入，需要分别检查。

常见问题

运行模型一定需要独立显卡吗？

不一定。能否运行以及响应速度取决于模型、量化、设备内存和硬件支持。先用较小模型验证，再参考模型页面和系统监控调整。

本地 API 的 api_key 参数代表有认证吗？

不是。兼容客户端示例中的占位值可能被本地服务忽略，不能作为网络访问控制。远程访问必须另行设计认证。

为什么 Docker 里访问不到 Ollama？

容器里的 localhost 指该容器本身。若调用方与 Ollama 分属不同容器，应配置共同网络并使用服务名；连接宿主机服务则按目标系统选正确的网关地址。先从调用方所在网络测试端口连通性。

本地推理真的完全私密吗？

本地模型推理可在设备上进行，但下载、遥测设置、应用日志和云端模型会涉及网络。逐项确认运行模式、客户端配置和请求目的地，避免把“本地软件”误当成端到端隐私保证。

官方资料

从小模型和本机请求开始，逐步确认模型、API、客户端与访问边界，再考虑 GPU、容器化和多人使用。