【AI】本地跑大模型：Ollama 安装、选模型与 API 调用

问题背景

有些活不适合交给云端模型：写了一半的内部文档、还没公开的代码、需要反复调用几百次的小任务。这些场景下「本地跑一个模型」比想象中实用——数据不出机器，没有按次计费，断网也能用。

Ollama 是目前上手成本最低的一条路：一条命令装好，一条命令跑模型，还顺手提供了原生 HTTP API 和 OpenAI 兼容接口，现有代码基本不用改就能接上。

这篇文章把「装 → 选模型 → 调 API → 避坑」串成一条能照着走的线。文中所有命令与参数都来自 Ollama 官方文档（标注了出处），版本号与模型信息是 2026-11-01 的快照——这类信息变得很快，动手前请以官方页面为准。

1. 先认识它

项	值
官网 / 文档	https://ollama.com 、 https://docs.ollama.com
仓库	ollama/ollama（MIT）
最新版本（撰写时）	v0.40.13（2026-10-28）
默认监听	`127.0.0.1:11434`

有三件事值得先说清楚，因为它们决定了你后面怎么用它：

默认只监听本机。 官方文档原文是 127.0.0.1:11434。想让局域网里的别的机器访问，必须显式设 OLLAMA_HOST——这是安全默认值，别嫌麻烦。
本地 API 不需要鉴权。 官方原文：「The local API at http://localhost:11434 does not require authentication.」所以别把 11434 直接暴露到公网，那等于把你机器的算力送人。
它同时提供原生 API 和 OpenAI 兼容 API。 前者更贴近它自己的能力（嵌入、多模态、keep_alive 等），后者让你能复用现成的 OpenAI 客户端代码。

2. 安装

2.1 macOS

下载 Ollama.dmg，挂载后把 Ollama 拖进 /Applications 就行。

要求 macOS Sonoma（v14）或更新。Apple Silicon 用 CPU + GPU（Metal），Intel 机器只有 CPU。首次启动会检查 PATH，缺 CLI 时会问你要不要在 /usr/local/bin 建软链。

2.2 Linux

一行脚本：

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

要指定版本（生产环境建议锁版本）：

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

手动装 amd64：

curl -fsSL https://ollama.com/download/ollama-linux-amd64.tar.zst | sudo tar x -C /usr
# 升级前先清掉旧库
sudo rm -rf /usr/lib/ollama

ARM64 把文件名换成 ollama-linux-arm64.tar.zst；AMD 显卡额外装 ROCm 库：

curl -fsSL https://ollama.com/download/ollama-linux-amd64-rocm.tar.zst | sudo tar x -C /usr

看日志：journalctl -e -u ollama。

2.3 Windows

运行 OllamaSetup.exe 即可。两个反直觉的点：

不需要 WSL2。 官方原文是 “Ollama runs as a native Windows application”——它是原生 Windows 程序。（WSL2 只出现在 Docker GPU 加速、以及 WSL2 网络慢这两处语境里，跟主程序无关。）
不需要管理员权限，默认装进用户目录。

想改安装目录：OllamaSetup.exe /DIR="d:\some\location"；想改模型存放位置，设用户环境变量 OLLAMA_MODELS。

2.4 Docker

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

# NVIDIA（需先装 NVIDIA Container Toolkit 并配置 --runtime=docker）
docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

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

⚠️ Docker Desktop for macOS 拿不到 GPU，官方原文：「GPU acceleration is not available for Docker Desktop in macOS due to the lack of GPU passthrough and emulation.」——Mac 上想用 GPU，就别用 Docker，装原生应用。

2.5 装完先验证

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

两个都通，环境就没问题。

3. 第一个模型

官方 quickstart 用的例子是 gemma4:e2b（下载约 7.2GB，建议有 8GB 可用显存或统一内存）：

ollama run gemma4:e2b

首次运行会自动下载，然后进入交互式对话。退出用 /bye。

3.1 命令速查（这里有个流传很广的错误）

用途	命令
跑模型	`ollama run gemma4`
下载	`ollama pull gemma4`
删除	`ollama rm gemma4`
列出本地模型	`ollama ls`
列出已加载的模型	`ollama ps`
停止模型	`ollama stop gemma4`
查看模型信息	`ollama show --modelfile gemma4`
用 Modelfile 创建模型	`ollama create -f Modelfile`
启动服务	`ollama serve`
登录 / 登出（用云模型）	`ollama signin` / `ollama signout`

⚠️ 注意 ollama ls 这一行。 网上大量文章（包括一些 AI 生成的）写的是 ollama list，但官方 CLI 文档里没有 ollama list 这个命令。这不是小事——照着抄的命令如果根本不存在，说明那篇文章没被验证过。

另外两个有官方出处但容易被写错的地方：

ollama show --modelfile <model> 才是官方给的用法（出现在 Modelfile 文档里），完整子命令官方没单列。
ollama cp（复制模型）出现在 import 与兼容性文档中，不在 CLI 参考里。

3.2 怎么知道模型真的跑在 GPU 上

ollama ps

看 PROCESSOR 列：

显示	含义
`100% GPU`	全在显卡上
`100% CPU`	掉回 CPU 了，慢得明显
`48%/52% CPU/GPU`	部分卸载，显存不够

看到 100% CPU 就是显存不足或驱动有问题，先去查驱动（见第 7 节）。

4. 选模型

模型库在 https://ollama.com/library 。按用途分四类，下面是从模型页抓的真实数据（2026-11-01，参数量与体积会变）：

4.1 中文 / 通用对话

模型	可选 tag（参数量，体积）	说明
qwen3.5	0.8b(752M, ~1.2GB)、2b(1.88B, ~3.1GB)、4b(4.21B, 4.0GB)、9b(8.95B, 6.6GB)、27b(26.9B, 17–20GB)、122b(125B, 81GB)	多模态，256k 上下文，Apache-2.0
deepseek-r1	1.5b(1.1GB)、7b(4.7GB)、8b(5.2GB)、14b(9.0GB)、32b(20GB)、70b(43GB)、671b(404GB)	开放推理模型
glm-4.7-flash	单模型 29.9B：q4_K_M(19GB) / q8_0(32GB) / bf16(60GB)	30B 档
gemma4	e2b(4.65B, ~3.5–4.6GB)、e4b(7.52B)、12b(11.9B)、26b(25.2B)、31b(30.7B)	官方 quickstart 用它举例
gpt-oss	20b(20.9B, ~14GB)、120b(117B, ~65GB)	OpenAI 开放权重推理模型
llama3.2	1b(1.3GB)、3b(2.0GB)	小体量，适合试水

4.2 代码向

模型	可选 tag（体积）
qwen3-coder	30b(19GB)、480b(290GB)
qwen2.5-coder	0.5b(398MB) → 32b(20GB)
deepseek-coder-v2	16b / 236b
granite-code	3b(2.0GB) → 34b(19GB)
devstral	24b(14GB / 32GB)

4.3 嵌入模型（做检索/记忆用）

模型	体积
`embeddinggemma`（300m）	622MB
`nomic-embed-text`（137M）	274MB

嵌入模型是本地部署里性价比最高的一环：体积小、跑得快、向量数据不外传。像 AstrBot 那类带长期记忆的机器人，记忆检索就是靠本地嵌入模型做的（比如 bge-m3）。

4.4 云端模型（本地不下载）

有些大模型的 tag 只有 cloud，本地不下载、需要 ollama signin 登录后调用，例如 glm-5.3、kimi-k3、minimax-m3。用 gemma4:31b-cloud 这种名字调用。

4.5 显存：官方给了规则，没给公式

这是最容易踩的认知坑。很多人把”模型文件体积”直接当成”显存需求”，官方从来没这么说过。

官方给的是一条上下文自动规则：

可用显存	默认上下文
< 24 GiB	4k
24–48 GiB	32k
≥ 48 GiB	256k

也就是说，同一张卡跑同一个模型，上下文越长占得越多。can 用 OLLAMA_CONTEXT_LENGTH 覆盖（agent / 编码工具官方建议 ≥ 64000）：

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

⚠️ 官方没有提供“某模型需要多少显存”的换算公式。要判断能不能跑，最实际的方法是跑起来看 ollama ps 的 PROCESSOR 列。

5. 调 API

5.1 原生 API

真实存在的端点（官方 API 文档，全部核实过）：/api/generate、/api/chat、/api/create、/api/tags、/api/show、/api/copy、/api/delete、/api/pull、/api/push、/api/embed、/api/ps、/api/version，以及 blobs 的两个端点。

生成文本：

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "为什么天空是蓝色的？"
}'

对话（推荐，带消息结构）：

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "为什么天空是蓝色的？"}],
  "stream": false
}'

做向量：

curl http://localhost:11434/api/embed -d '{
  "model": "all-minilm",
  "input": "为什么天空是蓝色的？"
}'

⚠️ /api/embeddings 已被 /api/embed 取代——官方在旧端点上标了 “This endpoint has been superseded by /api/embed”。新写的代码直接用 /api/embed。

几个约定值得记住：

模型名格式 model:tag，tag 省略时默认 latest。
所有 duration 字段的单位是纳秒，别当成毫秒。
流式响应是 NDJSON（每行一个 JSON），{"stream": false} 关掉。
用量字段在 done: true 那一块返回：total_duration、load_duration、prompt_eval_count、prompt_eval_cached_count、eval_count、eval_duration。

5.2 OpenAI 兼容接口

这是最实用的一部分——你现有的 OpenAI 客户端代码改个 base_url 就能跑：

curl -X POST http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss:20b",
    "messages": [{ "role": "user", "content": "Say this is a test" }]
  }'

from openai import OpenAI

client = OpenAI(base_url='http://localhost:11434/v1/', api_key='ollama')  # 必填但会被忽略
resp = client.chat.completions.create(
    model='gpt-oss:20b',
    messages=[{'role': 'user', 'content': 'Say this is a test'}],
)
print(resp.choices[0].message.content)

支持的能力：流式、JSON mode、可复现输出（seed）、视觉、Tools、推理强度控制。

不支持：tool_choice、logit_bias、user、n，以及 Logprobs。messages 里的图片只支持 base64，不支持传图片 URL。

⚠️ 它是 OpenAI API 的子集，不是超集。把线上代码整段搬过来之前，先核对用到的字段在不在支持列表里。

还有个实用技巧：有些工具写死了要 gpt-3.5-turbo 这个名字，你可以给本地模型起个别名：

ollama cp llama3.2 gpt-3.5-turbo

5.3 鉴权：本地和云端是两回事

场景	要不要 key
本地 `http://localhost:11434`	不要
云端 `https://ollama.com/api` 或 `/v1`	要，用 `OLLAMA_API_KEY` + `Authorization: Bearer <key>`

云端 key 在 https://ollama.com/settings/keys 创建，不过期。注意官方托管端点上 x-api-key 单独用是不被接受的。

6. Modelfile：自己拼一个模型

想固定一套系统提示词、调整默认参数，就用 Modelfile：

FROM qwen3.5:9b

SYSTEM """你是一个简洁的中文技术助手。回答优先给结论，再给理由。"""

PARAMETER temperature 0.3
PARAMETER num_ctx 8192

ollama create my-assistant -f Modelfile
ollama run my-assistant

指令（FROM / PARAMETER / TEMPLATE / SYSTEM / LICENSE / MESSAGE / REQUIRES / CAPABILITY）不区分大小写，顺序任意，只有 FROM 是必需的。

FROM 的写法有四种：

FROM llama3.2                 # 基于已有模型
FROM <model directory>        # Safetensors 目录
FROM ./ollama-model.gguf      # 单个 GGUF 文件（相对路径按 Modelfile 位置解析）
FROM ./model-*.gguf           # 分片 GGUF

⚠️ 最容易写错的是 PARAMETER。 官方参数表只有这 11 个：

参数	类型	默认值
`num_ctx`	int	2048
`repeat_last_n`	int	64（0 = 禁用，-1 = 用 num_ctx）
`repeat_penalty`	float	1.0（= 禁用）
`temperature`	float	0.8
`seed`	int	0
`stop`	string	可多条
`num_predict`	int	-1（无限）
`draft_num_predict`	int	独立 draft 模型默认 4，0 = 禁用推测解码
`top_k`	int	40
`top_p`	float	0.9
`min_p`	float	0.0

那些 num_gpu、num_thread、use_mmap、numa 之类的参数名，在当前官方文档里并不存在——网上的老教程里有，照抄会直接报错。

7. 常见坑

每条都能在官方文档里找到出处：

1）局域网访问要显式设 OLLAMA_HOST。 默认只绑 127.0.0.1，别的机器连不上是正常的。各平台设环境变量的方式不同（macOS 用 launchctl setenv、Linux 改 systemd override、Windows 设用户环境变量）。

2）代理只设 HTTPS_PROXY，不要设 HTTP_PROXY。 官方警告原文：「Ollama does not use HTTP for model pulls, only HTTPS. Setting HTTP_PROXY may interrupt client connections to the server.」——设错反而会把本地连接弄断。

3）浏览器扩展调用要配 CORS。 默认只允许 127.0.0.1 与 0.0.0.0 来源；扩展需要显式放行：

OLLAMA_ORIGINS=chrome-extension://*,moz-extension://*,safari-web-extension://* ollama serve

4）上下文和并发是内存杀手。 官方原文举的例子很直观：「a 2K context with 4 parallel requests will result in an 8K context and additional memory allocation」。OLLAMA_NUM_PARALLEL 调大，内存线性放大。

5）返回 503 是过载，不是坏了。 用 OLLAMA_MAX_QUEUE（默认 512）调整排队上限；同时加载的模型数由 OLLAMA_MAX_LOADED_MODELS 控制（默认 3 × GPU 数，CPU 推理时为 3）。

6）模型不会立刻释放内存。 默认保留 5 分钟。要立即卸：

ollama stop gemma4

或者调 API 时传 keep_alive（"10m"、秒数、负数表示永久、0 表示用完即卸）；全局用 OLLAMA_KEEP_ALIVE。

7）省内存的隐藏开关：K/V cache 量化。

OLLAMA_KV_CACHE_TYPE=q8_0 ollama serve   # 约省一半
# q4_0 约省 3/4，但需要 Flash Attention

官方提醒：高 GQA 的模型（如 Qwen2 系列）精度损失会更明显，别盲目开最激进的档。

8）AMD 显卡掉回 CPU，先看驱动。 日志里出现 failure during GPU discovery 或 bootstrap discovery took 30s，通常就是 ROCm 内核驱动太旧（内置 ROCm 7 库需要 ROCm 7 驱动）。

9）Linux 休眠唤醒后 GPU 不见了。

rmmod nvidia_uvm && modprobe nvidia_uvm

10）容器里用 AMD 显卡要加组权限。 需要 video / render 组和 --group-add（按 ls -lnd /dev/kfd /dev/dri 的实际 GID）；SELinux 下还要 sudo setsebool container_use_devices=1。

11）Docker 跑一会儿掉回 CPU。 给 /etc/docker/daemon.json 加：

{ "exec-opts": ["native.cgroupdriver=cgroupfs"] }

12）模型放哪、怎么搬家。 macOS ~/.ollama/models、Linux /usr/share/ollama/.ollama/models、Windows C:\Users\<用户名>\.ollama\models。换位置设 OLLAMA_MODELS（Linux 下记得给 ollama 用户 chown）。

8. 和别的方案怎么选

只说各项目官方页面的自述，不做实测性能对比：

方案	官方自述定位
Ollama	下载即用 + 一条命令跑模型 + 本地/云统一 API + OpenAI/Anthropic 兼容
llama.cpp	“LLM inference in C/C++”（自建 `llama-server` 提供 REST API）
LM Studio	桌面 GUI + agent（主页定位是 “Agent for Work and Code”），也提供 CLI 与 SDK
vLLM	“Easy, fast, and cheap LLM serving for everyone”，卖点是服务端吞吐（PagedAttention、连续批处理）

粗略的心智模型：个人本机试模型 → Ollama；要极限控制/嵌入到 C++ 项目 → llama.cpp；要图形界面 → LM Studio；要给一群人提供推理服务、追求吞吐 → vLLM。

⚠️ 需要说明：本文不比较实测性能。想让”哪个更快”有结论，得在自己的硬件上跑自己的任务——任何没有硬件和任务前提的横评都是噪音。

9. 小结

把这条线压成几句：

装：Mac 拖 dmg、Linux 一行脚本、Windows 原生安装（不需要 WSL2）、Docker 分 CPU/NVIDIA/ROCm 三种。
跑：ollama run gemma4:e2b。列模型用 ollama ls，不是 ollama list。
判断跑没跑在 GPU 上：ollama ps 看 PROCESSOR 列。
显存：官方只给上下文规则和体积，没给换算公式——跑起来看实际占用。
调：原生 /api/chat / /api/embed（不是废弃的 /api/embeddings），或 OpenAI 兼容的 /v1（是子集，注意不支持的字段）。
Modelfile 只有 11 个官方参数，老教程里的 num_gpu / num_thread 已经不在文档里了。
安全：默认只监听本机、本地 API 不要鉴权——所以千万别把 11434 暴露到公网。

最后重复一次开头的提醒：本文的版本号与模型 tag 是 2026-11-01 的快照。模型生态变化很快，动手前先到官方页面核对当前值——包括那个有点反直觉的 ollama ls。

参考来源

Ollama 官网 / 文档站
ollama/ollama（README、CLI Reference、pyproject、Releases）
安装文档：macOS / Linux / Windows / Docker
API 文档、鉴权说明、用量字段
OpenAI 兼容、Modelfile、FAQ、Troubleshooting、GPU 支持
模型页：https://ollama.com/library （qwen3.5 / deepseek-r1 / gemma4 / gpt-oss / qwen3-coder / embeddinggemma 等，数据抓取于 2026-11-01）