Ollama：一条命令把大模型装进你的电脑

01

Ollama 是什么：本机的模型运行器 + 模型管理器

Ollama 是一个跑在你自己电脑上的大模型运行与管理工具，底层是 llama.cpp 推理引擎。它解决一个很具体的问题：想用开源模型，但既不想配环境，也不想把代码和文件发到别人的服务器上。装好之后，模型库里几千个模型都是一条 ollama pull 的事，拉下来就能在终端对话，也能通过本地 HTTP API 给别的程序用。

它对个人开发者最现实的三个用法：一是隐私敏感场景——代码、日志、私人文档不出本机；二是离线与省钱——下载一次反复用，不按 token 计费；三是给编码 Agent 当本地引擎——OpenCode、Claude Code、Codex 等工具都能把 Ollama 当模型后端（官方文档专门列了集成页）。

从工程视角看，Ollama 做的是「打包」的活：llama.cpp 本身是个需要自己编译、自己喂模型文件、自己调参数的推理库；Ollama 把编译产物、GPU 加速、量化加载、模型格式解析、API 服务全部封装好，再配上一个像 npm 一样的模型库。它不训练模型，只负责三件事：拉下来、跑起来、管起来。你不需要读 GGUF 文档，也不需要知道 CUDA 版本怎么匹配——除非你想，那是第 08 节的事。

出品方 / 仓库

GitHub: ollama/ollama

开源协议

MIT

推理底座

llama.cpp

平台

macOS（Sonoma 14+）/ Windows / Linux / Docker

默认服务地址

127.0.0.1:11434

模型存放（macOS）

~/.ollama/models

默认上下文长度

4096 token（可改）

单个模型体积

数 GB～数十 GB，先看磁盘空间

02

安装：三条路，选你系统对应的那条

macOS 和 Windows 推荐官网安装包，Linux 推荐官方脚本（会顺手把 systemd 服务配好）。装完的东西都一样：一个 ollama CLI + 一个后台服务。

# 方式一：Homebrew
brew install ollama

# 方式二：去 ollama.com/download 下载 Ollama.dmg，拖进 Applications
# 首次启动时它会问是否把 ollama 命令链接到 /usr/local/bin，点允许

# 验证
ollama -v

# 官方安装脚本：自动装二进制、建 ollama 用户与 systemd 服务
curl -fsSL https://ollama.com/install.sh | sh

# 想锁定某个版本（版本号见 GitHub Releases）
curl -fsSL https://ollama.com/install.sh | OLLAMA_VERSION=0.5.7 sh

# 验证：服务状态 + 版本
sudo systemctl status ollama
ollama -v

# 去 ollama.com/download 下载安装包，双击安装
# 装完后在 PowerShell / 终端里：
ollama -v
ollama run gemma4:e2b

装完之后，东西都在哪

模型存放（macOS）

~/.ollama/models

模型存放（Linux）

/usr/share/ollama/.ollama/models

模型存放（Windows）

C:\Users\你\.ollama\models

日志（macOS 桌面版）

~/.ollama/logs（app.log / server.log）

挪模型到别的盘

OLLAMA_MODELS 环境变量指定新目录

改服务地址

OLLAMA_HOST，如 0.0.0.0:11434（慎用）

03

十分钟上手：拉一个模型，聊一次天

# 只下载不对话
ollama pull gemma4:e2b

# 直接开聊（没下载过会自动先拉取）
ollama run gemma4:e2b

# 对话里：三引号包多行输入，/bye 退出
>>> """把这段 Python 重构成列表推导式，
for x in xs:
    if x > 0:
        ys.append(x * 2)
>>> /bye

• 01

  选个和内存匹配的模型

  模型页会标参数规模（2b、9b、27b…）。官方对上面这个模型的建议是 8 GB 显存/统一内存。拿不准就先从小模型开始，跑顺了再上大的。

• 02

  run 之后就是普通聊天

  提示符变成 >>>，你输入、它回答，流式输出；/bye 退出。

• 03

  验证它真的在本地跑

  另开一个终端敲 ollama ps：能看到正在运行的模型、占用多少内存、在 GPU 还是 CPU 上。断网再问一句，它照样回答——这就是本地。

日常维护三板斧

ollama ls                 # 本地都有什么模型，各占多少磁盘
ollama stop gemma4:e2b    # 立刻卸载正在运行的模型，释放显存/内存
ollama rm 旧模型名         # 不要了就删，模型动辄几个 GB

# 装多了想批量清理？先 ls 看列表，再逐个 rm —— 没有按住 Shift 全选这种好事

进对话之后还能干嘛

# 三引号之间写多行输入
>>> """把下面三段话各自缩写成一句，再合成一段总结……"""

# 视觉模型：直接给本地文件路径，让它看图
ollama run <视觉模型> ./报错截图.png "这张图里的报错是什么"

# 嵌入模型：一句话输出向量，喂给 RAG / 语义搜索
ollama run embeddinggemma "Hello world"

能看图的模型在模型库用 vision 筛、嵌入模型用 embedding 筛；每个模型支持哪些能力，以模型页标注为准。

04

核心概念：模型、规模、量化、Modelfile

模型名与标签

Ollama 的模型名是「名字:标签」形式，标签通常就是参数规模，比如 gemma4:e2b、qwen3.5:9b。同一个名字下往往挂着多个规模的版本——小模型快、大模型聪明。完整目录在 ollama.com/search（支持按 coding / vision / embedding / reasoning 筛选），模型更迭很快，一切以模型库页面为准。

llama

Meta 的 Llama 家族，社区生态最全

qwen

阿里通义千问，中文与代码任务口碑好

deepseek

DeepSeek 家族，推理与代码见长

gemma

Google 家族，小尺寸模型多、门槛低

glm

智谱 GLM，旗舰版多走云端（cloud）

embeddinggemma 等

嵌入与多模态模型，做 RAG / 看图用

ollama pull qwen3.5:9b      # 指定参数规模
ollama pull deepseek-v4.1-flash   # 不带标签时用模型页的默认版本
ollama ls                   # 看本地已有模型和体积

注意：库里部分旗舰模型标了 cloud（如 glm-5.3、deepseek-v4.1-flash 的旗舰版），它们只在 ollama.com 云端跑，需要账号密钥，下载不到本地；本地能跑的版本以模型页标注为准。

参数规模与内存对照

跑多大模型要多少内存，取决于参数量和量化格式，无法一概而论。两个有用的锚点：官方对入门模型（下载约 7.2 GB）的建议是 8 GB 显存/统一内存；官方 FAQ 里 ollama ps 的示例显示 llama3:70b 加载后占约 42 GB、100% GPU。中间档（9B、14B、27B、32B）大致逐级往上翻，具体以模型页与你自己 ollama ps 的实测为准。

ollama ps
# NAME          ID            SIZE      PROCESSOR
# llama3:70b    bcfb190ca3a7  42 GB     100% GPU
# PROCESSOR 列出现 CPU/GPU 混合，说明显存装不下、溢到了内存，速度会掉

量化：用一点精度换一大半内存

量化指用更少的比特存模型权重——常见的是把 16 位浮点压到 4 比特级，内存占用大幅下降，代价是质量略降。Ollama 的模型页默认就提供量化好的版本，你下载即用，不用自己处理。你能动手的是 KV 缓存的量化：f16（默认）→ q8_0（约省一半）→ q4_0（约省四分之三）：

OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q8_0 ollama serve

Modelfile：给模型定人设与参数

Modelfile 类似 Dockerfile：从一个基础模型出发，写死系统提示词和运行参数，ollama create 一下就得到你自己的模型。指令不区分大小写，常用的有 FROM（基础模型，必填）、PARAMETER（运行参数）、SYSTEM（系统提示词）、MESSAGE（示例对话）。

FROM llama3.2
PARAMETER temperature 1
PARAMETER num_ctx 4096
SYSTEM """你是一个只说中文的代码评审助手，回答尽量简短。"""

ollama create my-reviewer -f ./Modelfile
ollama run my-reviewer
ollama show --modelfile llama3.2   # 反推任意模型的 Modelfile

05

速查表：命令、API、Modelfile 一张表

这块能搜。忘了命令名直接搜 pull、chat、上下文 这样的词。

06

实战：把 Ollama 变成编码 Agent 的本地引擎

这条流水线是 Ollama 最常见的进阶用法：先让它在本地起一个 API 服务，再用 OpenAI 兼容协议接进你顺手的工具。四步，每步都能单独验证。

第一步：确认服务在跑

curl http://localhost:11434
# 输出：Ollama is running

# 没在跑就手动起一个（Linux 手动安装场景）
ollama serve

第二步：用 REST 直接调

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4:e2b",
  "messages": [
    {"role": "user", "content": "Why is the sky blue?"}
  ],
  "stream": false
}'

stream 设为 true（默认）会逐 token 流式返回；调试时设 false 更好读。响应的正文取 message.content。

第三步：当 OpenAI 兼容端点用

# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # 必填，但本地服务不校验
)
resp = client.chat.completions.create(
    model="gemma4:e2b",
    messages=[{"role": "user", "content": "一句话解释 REST 是什么"}],
)
print(resp.choices[0].message.content)

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

所有按 OpenAI 协议写的工具都能这样接。如果某工具写死了要 gpt-3.5-turbo 这个名字，ollama cp gemma4:e2b gpt-3.5-turbo 就地解决。

彩蛋：同一套 API 也能调云端大模型

本机跑不动的旗舰模型可以走 ollama.com 的云端 API——请求格式不变，换地址、加密钥：

export OLLAMA_API_KEY="你的密钥"   # Windows PowerShell: $env:OLLAMA_API_KEY = "..."

curl https://ollama.com/api/chat \
  -H "Authorization: Bearer $OLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma4:31b",
       "messages": [{"role": "user", "content": "Why is the sky blue?"}],
       "stream": false}'

哪些模型只在云端提供、计费方式如何，以 ollama.com 当前页面为准。日常不想管密钥的话，ollama signin 登录后经本地服务转发也可以。

第四步：一条命令接进编码 Agent

# 让 OpenCode / Claude Code / Codex / VS Code / Droid 用 Ollama 模型
ollama launch opencode
ollama launch claude --model qwen3.5

# 只写配置、不立刻启动
ollama launch claude --config

第五步（可选）：自定义模型走同一条链路

把第 04 节的 Modelfile 知识用起来：造一个只干活的「评审专用模型」，让 Agent 调它时行为更稳定。

FROM qwen3.5:9b
PARAMETER temperature 0.3
PARAMETER num_ctx 8192
SYSTEM """你是代码评审助手：只列问题与修改建议，每条不超过两行，不说客套话。"""

ollama create reviewer -f ./Modelfile
ollama run reviewer

>>> 评审：def add(a, b): return a + b
# 退出后，同一个名字立刻能从 API 调：
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "reviewer",
       "messages": [{"role": "user", "content": "评审 def add(a, b): return a + b"}]}'

自定义模型只是「基础模型 + 你的配置」的一层封装，不占额外磁盘（权重与基础模型共享）。想看某个内置模型的完整配置，ollama show --modelfile 模型名 直接抄作业。

07

避坑：四个最常见的问题

坑一：ollama: command not found

十有八九是 PATH 没刷新或服务没起。先重开终端——macOS 桌面版首次启动时询问「是否把 ollama 链接到 /usr/local/bin」，如果当时点了拒绝，命令就一直不在。再确认安装方式对应的路径。

which ollama                       # 找不到 → PATH 问题
# macOS 桌面版：CLI 在 Ollama.app/Contents/Resources/ollama，可自行链到 /usr/local/bin
# Linux：sudo systemctl status ollama 看服务；journalctl -e -u ollama 看日志
curl http://localhost:11434        # 服务本身活着吗

坑二：模型拉得下、跑不动

下载成功不等于跑得动。先用 ollama ps 看 PROCESSOR 列：出现 CPU/GPU 混合就是显存溢出，速度明显下降。解法按顺序试：换更小参数规模的标签、确认没有同时加载多个模型（OLLAMA_MAX_LOADED_MODELS）、开 KV 缓存量化。给 Linux 用户的额外提醒：OLLAMA_NUM_PARALLEL 与上下文长度相乘才是真实内存需求，调并发前先算这笔账。

还有一类「假跑不动」：第一次 ollama run 卡在加载很久——那是模型在往内存里搬，8 GB 内存搬 7 GB 模型本来就要一会儿。第二次运行就快了（默认保留 5 分钟）。判断标准看 ollama ps 有没有 SIZE 在涨，而不是看终端有没有输出。

坑三：长文档喂进去，答案答非所问

默认上下文只有 4096 token，超出的部分模型根本看不到。长文场景记得显式调大：

OLLAMA_CONTEXT_LENGTH=8192 ollama serve    # 全局
>>> /set parameter num_ctx 8192            # 对话内
# 或 API 请求里带 "num_ctx": 8192 —— 单次调用

代价是内存：上下文越大，KV 缓存越大，和 OLLAMA_NUM_PARALLEL 相乘后更是成倍涨。别一步到位开满。

坑四：OLLAMA_HOST=0.0.0.0 之后的裸奔

08

进阶方向与官方资源

• ollama.com/download — macOS / Windows / Linux 安装包总入口
• docs.ollama.com — 官方文档（CLI、API、Modelfile、GPU、FAQ）
• github.com/ollama/ollama — 源码仓库与 Releases
• ollama.com/search — 模型库，按 coding / vision / embedding / reasoning 筛选
• ollama-python — 官方 Python 库
• ollama-js — 官方 JavaScript 库
• Integrations 文档 — 各编码 Agent / IDE / 框架的接入指南

09

收尾：照着勾一遍

0 / 5