现在位置: 首页 / AI技术 / AI / 正文

Ollama 最新使用指南：安装、模型管理、API 与常见问题

目录
[隐藏]

本文基于 Ollama 官方文档仓库 ollama/ollama 的 main/docs 及新版文档站整理，核对时间：2026-07-20。Ollama 的版本、模型标签和云端能力会继续变化；执行命令前，建议以官方文档和模型页面的当前内容为准。

本文按三段式组织：

  1. 快速上手：完成安装、启动模型、Docker 部署和基本模型管理。
  2. 进阶参数：配置存储、硬件、上下文长度、环境变量、API、Modelfile、网络访问、云端和第三方集成。
  3. 故障排查：处理下载、GPU、日志和 API 访问问题。

一、快速上手

Ollama 是什么

Ollama 是一个本地模型运行器和模型管理工具，提供命令行、HTTP API、模型导入、Modelfile、自定义参数以及多种兼容接口。它适合在个人电脑或自有服务器上运行开源模型，也可以通过 Ollama Cloud 使用不适合本机硬件的云端模型。

“使用 Ollama”不等于“所有请求都离线”：

  • 使用普通本地模型时，模型推理在本机执行。
  • 使用 Cloud 标签模型时，推理会卸载到 Ollama 云端。
  • 要实现仅本地模式，应关闭云功能，并避免使用 Cloud 模型。

1. 安装 Ollama

1.1 macOS 和 Windows

从官方页面下载桌面安装程序：

Windows 安装程序默认不需要管理员权限。当前 Windows 文档还说明了 CLI/服务模式的压缩包方式，以及 NVIDIA、AMD ROCm/HIP 和 Vulkan 相关选项。模型和配置通常位于：

Windows: %HOMEPATH%\\.ollama
日志:     %LOCALAPPDATA%\\Ollama
临时文件: %TEMP%

macOS 应用运行时，环境变量应通过 launchctl setenv 设置；设置后重启 Ollama 应用。

1.2 Linux

官方一键安装：

curl -fsSL https://ollama.com/install.sh | sh

安装后验证：

ollama --version

Linux 手动安装时，应根据架构选择官方发布包，例如 AMD64 或 ARM64；需要 AMD GPU 时选择对应 ROCm 包。若要安装指定版本，可使用：

curl -fsSL https://ollama.com/install.sh | OLLAMA_VERSION=<版本号> sh

以 systemd 服务运行时，常用管理命令为：

sudo systemctl enable ollama
sudo systemctl start ollama
sudo systemctl status ollama
journalctl -u ollama

Linux 服务的环境变量不要只写进当前用户的 .bashrc，因为 systemd 服务可能看不到它们。推荐使用：

sudo systemctl edit ollama

在覆盖配置中写入：

[Service]
Environment="OLLAMA_MODELS=/data/ollama/models"
Environment="OLLAMA_HOST=127.0.0.1:11434"

然后应用配置：

sudo systemctl daemon-reload
sudo systemctl restart ollama

2. Docker 部署

2.1 CPU 模式

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

运行模型：

docker exec -it ollama ollama run gemma4

2.2 NVIDIA GPU

先安装并配置 NVIDIA Container Toolkit：

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

然后启动：

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

验证容器能否看到显卡：

docker run --rm --gpus all ubuntu nvidia-smi

2.3 AMD GPU

Linux AMD GPU 使用官方 ROCm 镜像，并映射设备：

docker run -d \
  --device /dev/kfd \
  --device /dev/dri \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama:rocm

Vulkan 后端使用标准镜像，但同样需要映射相关设备：

docker run -d \
  --device /dev/kfd \
  --device /dev/dri \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

具体 GPU 支持取决于驱动和平台。官方当前 GPU 文档还覆盖 Apple Metal、Intel/其他设备的 Vulkan，以及多 GPU 选择变量，不应再用“只支持 NVIDIA CUDA”来概括 Ollama。

二、进阶参数

3. 模型存储、硬件和上下文长度

3.1 修改模型目录

跨平台都可以使用 OLLAMA_MODELS 指定模型存储位置。桌面应用需要在重启应用后生效；Linux systemd 服务需要写入服务环境；Docker 则优先使用卷挂载：

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

3.2 硬件如何估算

不要只看参数量。实际需要的内存/显存至少受到以下因素影响：

  • 模型权重格式和量化级别；
  • 上下文长度；
  • 并发请求数；
  • KV cache；
  • 是否有部分层卸载到 CPU；
  • GPU 后端和驱动。

官方当前上下文文档给出的默认策略是按显存分档：显存小于 24 GiB 时默认 4K，上限为 24–48 GiB 时默认 32K，至少 48 GiB 时默认 256K；云端模型默认使用其最大上下文长度。具体模型仍可能有自己的限制。

可以查看正在运行模型的处理器分配和上下文信息：

ollama ps

需要更长上下文时，可在启动服务时设置：

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

上下文越长，内存消耗通常越高；不要把上下文长度写成“越大越好”。

4. 下载、运行和管理模型

4.1 最短上手流程

# 运行模型；不存在时会先拉取
ollama run gemma4

# 查看帮助
ollama --help

# 退出交互式会话
/bye

也可以直接传入 prompt：

ollama run gemma4 "用一段话解释天空为什么是蓝色"

当前 CLI 还支持将图片路径传入多模态模型，以及用 """ 包裹多行输入。模型名称、标签和能力请以 Ollama 模型库 当前页面为准，不要把旧文章里的 deepseek-r1 标签当成永久不变的示例。

4.2 常用命令

命令 用途
ollama serve 启动服务
ollama run <model> [prompt] 运行模型或直接提问
ollama pull <model> 下载模型
ollama ls 列出本地模型
ollama show <model> 查看模型信息
ollama ps 查看正在运行的模型及处理器/上下文分配
ollama stop <model> 停止模型
ollama cp <src> <dst> 复制模型并创建新名称
ollama rm <model> 删除模型
ollama create <name> -f Modelfile 根据 Modelfile 创建模型
ollama push <model> 推送模型
ollama signin / ollama signout 登录/退出 Ollama 账户
ollama launch 配置或启动支持的外部集成

5. API 调用

本地 API 默认监听：

http://127.0.0.1:11434

本地访问不要求 API Key。最小的非流式生成请求：

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "用一句话介绍 Ollama",
  "stream": false
}'

聊天接口：

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    {"role": "user", "content": "你好，请介绍一下自己"}
  ],
  "stream": false
}'

默认情况下，生成和聊天接口以流式 JSON 返回；设置 "stream": false 才返回一个完整 JSON 对象。原生 API 还包括模型管理、模型状态、版本查询、Blob 上传以及嵌入接口：

  • POST /api/generate
  • POST /api/chat
  • POST /api/embed
  • GET /api/tags
  • GET /api/ps
  • POST /api/show
  • POST /api/pull
  • POST /api/create
  • POST /api/copy
  • DELETE /api/delete
  • GET /api/version

生成嵌入向量时优先使用 /api/embed；旧的 /api/embeddings 不应作为新项目的首选。

5.1 OpenAI 兼容接口

当前 Ollama 提供 OpenAI 兼容接口，Base URL 为：

http://localhost:11434/v1/

兼容接口通常要求提供 api_key 字段，但本地 Ollama 会忽略其值；官方示例建议可填写 ollama。例如 Python：

from openai import OpenAI

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

response = client.chat.completions.create(
    model="gemma4",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

当前兼容范围包括聊天补全、补全、模型列表、嵌入、视觉、工具调用、JSON 模式，以及实验性的图片生成和非有状态 Responses API。注意：

  • 使用前仍需在 Ollama 中 ollama pull <model>；
  • OpenAI 请求本身不能设置 Ollama 上下文长度，需通过 Modelfile 的 PARAMETER num_ctx 创建新模型；
  • 若第三方程序硬编码了 gpt-3.5-turbo 等名称，可用 ollama cp 创建对应别名；
  • /v1/responses 当前不支持 previous_response_id 或 conversation 状态。

5.2 Anthropic Messages API 兼容

Ollama 还提供 Anthropic Messages API 兼容层，适合连接支持 Anthropic SDK 或 Claude Code 的工具。Base URL 为：

http://localhost:11434

需要设置一个值为 ollama 的 ANTHROPIC_AUTH_TOKEN 或 API Key，但本地服务不会校验这个值。当前支持消息、多轮对话、流式、系统提示词、Base64 图片、工具调用和基础 thinking；不支持 count_tokens、batches、PDF document 块、提示词缓存、citations 等部分 Anthropic 能力。使用前应查看官方兼容性文档，而不要假设两套 API 完全等价。

6. 使用 Modelfile 定制模型

一个最小的 Modelfile：

FROM gemma4

PARAMETER temperature 0.3
PARAMETER num_ctx 8192

SYSTEM """
你是一个严谨的中文技术助手。回答时优先给出可执行步骤。
"""

创建并运行：

ollama create tech-assistant -f Modelfile
ollama run tech-assistant

当前 Modelfile 主要支持：

  • FROM：指定已有模型、GGUF 文件或受支持的 Safetensors 模型目录；
  • PARAMETER：设置 temperature、top_p、top_k、num_ctx、num_predict、stop 等；
  • SYSTEM：设置系统行为；
  • TEMPLATE：自定义 Go template；
  • MESSAGE：写入示例对话历史；
  • ADAPTER：加载 LoRA/QLoRA 适配器；
  • LICENSE：记录许可证；
  • REQUIRES：声明最低 Ollama 版本。

查看现有模型的 Modelfile：

ollama show --modelfile <model>

6.1 导入 GGUF

准备 GGUF 文件后，创建 Modelfile：

FROM /absolute/path/to/model.gguf

然后：

ollama create my-model -f Modelfile
ollama run my-model

6.2 导入 Safetensors 或适配器

官方导入流程也支持从受支持架构的 Safetensors 目录创建模型，或使用 ADAPTER 加载适配器。适配器必须与训练它时使用的基础模型匹配，否则可能出现不稳定或错误结果。建议严格按照导入文档确认模型架构、基础模型和量化方式。

6.3 量化

可以用 FP16/FP32 基础模型创建 Modelfile，再用 ollama create --quantize 生成量化模型：

ollama create --quantize q4_K_M my-model -f Modelfile

量化可以降低存储和运行内存，但会在一定程度上影响效果；量化等级、模型架构和任务类型应一起评估。

7. 局域网访问与安全

要允许其他设备访问，可修改绑定地址：

OLLAMA_HOST=0.0.0.0:11434

不同安装方式的配置方法不同：

  • macOS：launchctl setenv 后重启应用；
  • Windows：在账户环境变量中设置后重启应用；
  • Linux systemd：用 systemctl edit ollama 写入 [Service]；
  • Docker：通过容器端口映射和网络配置控制访问范围。

跨域访问另行配置 OLLAMA_ORIGINS，尽量填写明确的来源，不要长期使用 *。

重要：本地 Ollama API 默认没有认证。 不要把 11434 端口直接暴露在公网。更安全的做法是：

  1. 防火墙只允许可信网段访问；
  2. 使用 Nginx、Caddy 或网关做 TLS、认证、限流和访问日志；
  3. 将 Ollama 绑定在本机或内网地址，只让反向代理暴露；
  4. 云服务器上禁止直接开放 11434；
  5. 如使用隧道服务，配置身份认证和最小权限。

8. “离线”和 Ollama Cloud

如果只需要本地模型，可以在配置中关闭云功能：

OLLAMA_NO_CLOUD=1

官方 FAQ 也记录了在 ~/.ollama/server.json 中设置 "disable_ollama_cloud": true 的方式。关闭后不能使用云端模型和相关网页搜索能力。

如果希望在低配置设备上使用更大的模型，可以：

ollama signin
ollama pull <cloud-model>
ollama run <cloud-model>

Cloud 模型需要 Ollama 账户，并会把推理任务卸载到 Ollama 云端。涉及敏感数据时，应明确检查模型标签、云端设置、组织策略和数据处理要求，不要把“安装在本机”误认为“请求一定留在本机”。

9. 环境变量配置

Ollama 的环境变量主要用于配置服务监听、模型目录、上下文长度、并发调度、显存优化、代理和故障排查。以下变量均来自 Ollama 官方 FAQ、上下文长度、GPU 和故障排查文档。

9.1 常用服务配置

环境变量 默认值 作用
OLLAMA_HOST 127.0.0.1:11434 设置 Ollama HTTP 服务的监听地址和端口。
OLLAMA_MODELS 由平台和安装方式决定 修改模型文件的存储目录。
OLLAMA_ORIGINS 默认允许本机相关来源 配置允许访问 Ollama API 的跨域来源。
OLLAMA_NO_CLOUD 未设置 设置为 1 时关闭 Ollama Cloud，实现仅本地运行。
OLLAMA_CONTEXT_LENGTH FAQ 当前记录为 4096 设置默认上下文长度，单位为 token。
OLLAMA_KEEP_ALIVE 5 分钟 设置模型在内存中保持加载的时间。支持持续时间、秒数、0 和负数。

示例：

OLLAMA_HOST=127.0.0.1:11434
OLLAMA_MODELS=/data/ollama/models
OLLAMA_NO_CLOUD=1
OLLAMA_CONTEXT_LENGTH=32768
OLLAMA_KEEP_ALIVE=10m

其中，OLLAMA_KEEP_ALIVE=0 表示请求完成后卸载模型，负数表示持续保持加载。API 请求中的 keep_alive、options.num_ctx 等参数可以覆盖默认环境配置。

OLLAMA_HOST 只负责监听，不提供身份认证；OLLAMA_ORIGINS 只负责 CORS，也不能替代 API Key、网关认证或网络隔离。将地址改为 0.0.0.0 后，不要直接把 11434 暴露到公网。

9.2 并发、队列和模型调度

环境变量 默认值 作用
OLLAMA_MAX_LOADED_MODELS 通常为 GPU 数量 × 3；CPU 模式通常为 3 限制可同时加载到内存中的模型数量。
OLLAMA_NUM_PARALLEL 1 设置每个模型可同时处理的并行请求数。
OLLAMA_MAX_QUEUE 512 设置服务器繁忙时允许排队的最大请求数。

示例：

OLLAMA_NUM_PARALLEL=2 \
OLLAMA_MAX_LOADED_MODELS=2 \
OLLAMA_MAX_QUEUE=128 \
ollama serve

调高并发、模型数量或队列长度都会增加资源压力。建议先确认单请求稳定，再逐步提高并发，并观察内存、显存、响应延迟和排队情况。

9.3 Flash Attention 和 KV Cache

环境变量 可选值 作用
OLLAMA_FLASH_ATTENTION 1 / 0 强制启用或禁用 Flash Attention；默认由后端和设备自动决定。
OLLAMA_KV_CACHE_TYPE f16、q8_0、q4_0 设置 K/V Cache 类型；低精度通常可降低显存占用，但可能带来质量或兼容性权衡。 
OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q8_0 ollama serve

这类变量属于性能和显存调优项，只有在默认配置无法满足需求时再修改，并用实际任务验证输出质量。

9.4 代理、版本和临时目录

环境变量 作用 说明
HTTPS_PROXY 为模型拉取配置 HTTPS 代理。 例如 HTTPS_PROXY=http://proxy.example.com:7890 ollama pull <model>。
OLLAMA_VERSION 在 Linux 安装脚本中指定要安装的版本。 只影响安装脚本，不是运行时服务配置。
OLLAMA_TMPDIR 指定 Ollama 使用的临时目录。 遇到 noexec 临时目录错误时，可改为用户可写且允许执行的目录。

指定 Linux 安装版本：

curl -fsSL https://ollama.com/install.sh | OLLAMA_VERSION=<版本号> sh

9.5 调试和 GPU 排障

环境变量 适用场景 作用
OLLAMA_DEBUG 全平台排障 设置为 1，输出更详细的调试日志。
OLLAMA_LLM_LIBRARY 自动检测失败或 GPU 异常 覆盖自动检测，指定 LLM 库，例如 cpu、cpu_avx、cpu_avx2 等。
CUDA_ERROR_LEVEL Linux + NVIDIA CUDA 设置为 50，获取更多 CUDA 诊断日志。
AMD_LOG_LEVEL AMD HIP/ROCm 设置为 3，输出更详细的 AMD 库日志。 
OLLAMA_DEBUG=1 ollama serve
CUDA_ERROR_LEVEL=50 OLLAMA_DEBUG=1 ollama serve
AMD_LOG_LEVEL=3 OLLAMA_DEBUG=1 ollama serve

OLLAMA_LLM_LIBRARY 不应作为常规性能优化开关；强制使用 CPU 库通常意味着放弃 GPU 加速，建议只用于定位自动检测或驱动问题。

9.6 GPU 设备选择

环境变量 后端/平台 作用
CUDA_VISIBLE_DEVICES NVIDIA CUDA 指定 Ollama 可见的 NVIDIA GPU；可用 nvidia-smi -L 查询设备 UUID。
ROCR_VISIBLE_DEVICES AMD ROCm/HIP 指定可见的 AMD GPU；可用 rocminfo 查询设备标识。
GGML_VK_VISIBLE_DEVICES Vulkan 指定 Vulkan 后端使用的设备。
HSA_OVERRIDE_GFX_VERSION 部分 AMD GPU 强制指定 LLVM target，仅应按官方排障建议使用。
OLLAMA_VULKAN Vulkan 相关排障 用于控制或排查 Vulkan 后端，具体取值以当前版本文档为准。

若模型跑到了 CPU，先检查驱动、设备权限、容器参数以及 ollama ps 中的 PROCESSOR 信息；不要只依赖这些变量解决驱动问题。

9.7 各平台设置方法

macOS 应用：

launchctl setenv OLLAMA_HOST "127.0.0.1:11434"
launchctl setenv OLLAMA_MODELS "/Volumes/Models/ollama"
launchctl setenv OLLAMA_NO_CLOUD "1"

设置后重启 Ollama 应用。

Linux systemd：

sudo systemctl edit ollama.service

写入：

[Service]
Environment="OLLAMA_HOST=127.0.0.1:11434"
Environment="OLLAMA_MODELS=/data/ollama/models"
Environment="OLLAMA_NO_CLOUD=1"

然后执行：

sudo systemctl daemon-reload
sudo systemctl restart ollama

Windows： 在“编辑账户的环境变量”中新增或修改用户变量，设置后重启 Ollama 应用。

Docker： 使用 -e 传入：

docker run -d \
  -e OLLAMA_HOST=0.0.0.0:11434 \
  -e OLLAMA_NO_CLOUD=1 \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

9.8 配置优先级和验证

可以按以下顺序理解配置来源：

  1. 服务环境变量：提供 Ollama 服务的默认行为；
  2. API 请求参数：例如 options.num_ctx、keep_alive，可覆盖单次请求的默认值；
  3. Modelfile 参数：例如 PARAMETER num_ctx，用于创建具有固定默认行为的新模型。

修改变量后没有生效，通常是因为没有重启桌面应用、systemd 服务或 Docker 容器。可用以下命令验证服务状态：

curl http://127.0.0.1:11434/api/version
ollama ps

10. 接入 Web UI 和应用

Ollama 只负责模型运行和 API，不等于完整的聊天 Web 应用。可以按需求接入 Open WebUI、AnythingLLM、Cherry Studio、Chatbox、Dify 等第三方工具，但要注意：

  • 第三方项目的安装命令、环境变量和镜像标签不属于 Ollama 官方 API；
  • 使用 Docker 时，容器内的 localhost 指向当前容器，不一定指向 Ollama 容器；
  • 使用知识库/RAG 时，生成模型和嵌入模型需要分别选择并验证；
  • 开启联网搜索会把相关查询或内容发送给外部服务，和“纯本地”不是一回事；
  • 第三方 Web UI 的账户、日志和数据保留策略需要单独审查。

11. 官方参考

三、故障排查

1. 常见问题排查

1.1 模型下载失败或很慢

优先检查：

ollama pull <model>
ollama ls
ollama show <model>
df -h

确认模型标签、磁盘空间、代理和 DNS；不要使用来源不明的模型文件或修改后的脚本。需要离线导入时，优先选择可信来源的 GGUF/Safetensors，并按“使用 Modelfile 定制模型”一节创建模型。

1.2 模型跑到了 CPU

先查看：

ollama ps

确认 GPU 驱动、后端和容器设备映射。NVIDIA 检查 nvidia-smi；AMD 检查 ROCm 设备和 /dev/kfd、/dev/dri 权限；Intel/其他 Vulkan 环境检查发行版对应的 Vulkan/Mesa 组件。若上下文过大，也可能导致显存不足和部分卸载。

1.3 查看日志

macOS:  ~/.ollama/logs/server.log
Linux:  journalctl -u ollama
Windows: %LOCALAPPDATA%\\Ollama\\server.log
Docker: docker logs ollama

需要调试时可设置：

OLLAMA_DEBUG=1

某些 Linux 环境遇到 noexec 临时目录错误时，可设置 OLLAMA_TMPDIR 指向可执行且可写的临时目录。GPU 相关问题还应优先检查驱动版本、设备权限和容器运行时，而不是先反复删除模型。

1.4 API 访问不了

检查服务是否启动、监听地址和端口：

ollama ps
curl http://127.0.0.1:11434/api/version

如果本机可访问、局域网不可访问，再检查 OLLAMA_HOST、防火墙、容器端口映射和 OLLAMA_ORIGINS。如果是公网访问，先撤销 0.0.0.0 暴露，再通过反向代理增加认证和 TLS。

总结

新版 Ollama 使用不再只是“安装后执行 ollama run”。更完整的理解是：先选择本地或云端运行模式，再根据硬件和上下文长度选择模型；使用 ollama ls、ps、show 管理模型；通过原生 API、OpenAI 兼容接口或 Anthropic 兼容接口接入应用；需要定制时使用 Modelfile；对外开放前必须在 Ollama 外部补上网络隔离和认证。

对于“离线部署”场景，最重要的检查清单是：

  • 使用本地模型而非 Cloud 模型；
  • 设置 OLLAMA_NO_CLOUD=1；
  • 不把 11434 直接暴露到公网；
  • 关闭不必要的联网搜索和第三方外部服务；
  • 从可信来源导入模型并核对许可证；
  • 用日志、ollama ps 和 /api/version 验证运行状态。

相关参考：