Ollama 是本地大模型底座：一条命令下载并运行开源权重模型，自带 OpenAI 兼容 API（默认端口 11434），数据不出机器。典型用法是把脚本、Agent、IDE 插件的 base_url 指到本地服务，实现离线推理、多模型热切换、无按量费用。

什么时候用：

• 你要本地推理：数据不出机器、离线可用、无按量费用；
• 你要多模型并行与热切换；
• 你要搭本地大模型环境（配 open-webui 做界面、配 LLaMA-Factory 做微调）——见组合包 combo-local-llm-finetune；
• 你要做本地知识库 RAG——见组合包 combo-local-rag（ollama + MaxKB）。

什么时候别用：需要云端大模型能力（超大模型/高并发/免运维）时，本地底座不是替代品。

国内网络的关键：装二进制（GitHub Release 1.42GB）和拉模型（官方 registry）都可能卡。本指南给出实测过的两条绕行路径：二进制走 gh-proxy 拉 GitHub Release；模型走 ModelScope 下载 GGUF 再 ollama create 导入。

下面一条命令完成下载、解压、验证（国内实测路径，合并成一段可整体复制）：

# 来源: Trove 详细指南 · 验证于 2026-08-29
curl -fsSL -o /tmp/ollama.tar.zst https://gh-proxy.com/https://github.com/ollama/ollama/releases/latest/download/ollama-linux-amd64.tar.zst
tar --zstd -xf /tmp/ollama.tar.zst -C /usr/local
ollama --version

预期输出: ollama version 0.33.2（2026-08-29 实测）

跑完看到版本号就装好了。三个注意点：

1. tar --zstd 需要 zstd（apt-get install -y zstd，实测 zstd 1.5.7）；
2. 下载 1.42GB 大文件，先 df -h / 确认磁盘，下载中断用 curl -C - 续传；
3. Windows 用户建议在 WSL2 内走本路径（与 Linux 一致）；纯 Windows 用官方安装器；macOS 用官方 dmg。

装好确认：

• ollama --version 输出 ollama version 0.33.2；
• ollama list 能跑（空模型表 exit 0）。

Ollama 是单二进制 + 模型目录架构。ollama serve 拉起常驻服务（默认监听 127.0.0.1:11434），ollama pull <模型> 从官方 registry 下载模型到模型目录，ollama run <模型> 交互式运行，ollama create 从 GGUF 文件导入模型。有 NVIDIA 卡自动启用 CUDA，无卡自动回退 CPU 推理（可用但慢）。

两个关键机制：

• OLLAMA_MODELS 环境变量：模型目录位置（默认 ~/.ollama/models）。模型单文件 4~70GB，系统盘不够时指到大分区——2026-08-30 隔离实测通过（实测复现日志（2026-08-30））。
• GGUF 导入：ollama create <名字> -f Modelfile 把本地 GGUF 文件导入模型库，绕开官方 registry——这是国内拉模型的正解（2026-08-29 实测：qwen2.5-0.5b-instruct-q4_k_m 491MB 下载 58.5s + create success + CPU 冒烟通过，实测复现日志（2026-08-29））。

写面：模型目录 ~/.ollama/models（或 OLLAMA_MODELS 指向的目录）+ 首次 serve 生成的 ~/.ollama/id_ed25519（SSH 密钥，日志实测会提示 generating new private key）。服务监听 127.0.0.1:11434，不对外暴露（默认）。

与容器里工具的连通：bridge 网络容器访问宿主机 Ollama 用 172.17.0.1:11434，但 Linux 上 snap/apt 装的 Ollama 默认只监听 127.0.0.1，容器访问不到——需要 sudo snap set ollama host=0.0.0.0:11434 + restart（MaxKB 组合包实测坑，见 combo-local-rag）。

第 1 步：启动服务（serve）

为什么是这一步：Ollama 是常驻服务形态，所有 API 调用都走它；不启动 serve，curl /api/version 连不上。

# 来源: Trove 详细指南 · 验证于 2026-08-29
OLLAMA_MODELS=~/.ollama/models ollama serve

预期输出: server 配置日志正常（ssh key 生成、blobs: 0；默认端口 11434；2026-08-29 实测）

# 来源: Trove 详细指南 · 验证于 2026-08-29
curl -s http://127.0.0.1:11434/api/version

预期输出: {"version":"0.33.2"}（2026-08-29 实测）

卡住怎么办：

• serve 起不来/端口被占 → 默认 11434 被占用时改 OLLAMA_HOST（如 OLLAMA_HOST=127.0.0.1:11435）；
• 容器里访问不到 → 容器用 172.17.0.1:11434；snap 版 Ollama 需 sudo snap set ollama host=0.0.0.0:11434 + restart（见「为什么会这样」）。

第 2 步：导入第一个模型（国内正解）

为什么走 GGUF：ollama pull 走官方 registry，国内实测超时（serve 日志 cloud model cache 拉取失败，ollama.com:443）。ModelScope 国内可直连，下载 GGUF 后导入。

# 来源: Trove 详细指南 · 验证于 2026-08-29
# 1) ModelScope 下载 GGUF（示例：qwen2.5-0.5b-instruct Q4_K_M，491MB）
pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple
modelscope download --model Qwen/Qwen2.5-0.5B-Instruct-GGUF qwen2.5-0.5b-instruct-q4_k_m.gguf --local_dir /tmp/qwen-gguf
# 2) 写 Modelfile
echo "FROM /tmp/qwen-gguf/qwen2.5-0.5b-instruct-q4_k_m.gguf" > /tmp/Modelfile
# 3) 导入
ollama create qwen2.5:0.5b -f /tmp/Modelfile

预期输出: create 输出 model manifest 摘要 + success（2026-08-29 实测：491MB 下载 58.5s + create success + CPU 冒烟通过）

# 来源: Trove 详细指南 · 验证于 2026-08-29
ollama run qwen2.5:0.5b "你好"

预期输出: 模型输出正常中文回答（CPU 冒烟，2026-08-29 实测）

卡住怎么办：

• modelscope 下载慢 → 换国内源重试；GGUF 文件也有多个量化档（q4_k_m 是体积/质量均衡档）；
• create 报错 → 确认 Modelfile 的 FROM 路径指向实际下载的 gguf 文件；
• run 无输出 → 确认 serve 在跑、模型已 create 成功（ollama list 能看到行）。

第 3 步：日常用起来

# 来源: Trove 详细指南 · 验证于 2026-08-29
ollama list                          # 看已装模型
ollama ps                            # 看当前加载中的模型
ollama rm <model>                    # 删除模型释放磁盘（实测见 models-rm-v3）
curl -s http://127.0.0.1:11434/api/version   # 服务健康检查

预期输出: list 输出模型表格（NAME/ID/SIZE/MODIFIED）；ps 输出已加载模型与显存占用；rm 删除后 list 不再显示；version 返回 {"version":"0.33.2"}

模型目录迁移（系统盘不够时）：

# 来源: Trove 详细指南 · 验证于 2026-08-29
mkdir -p /data/ollama/models
OLLAMA_MODELS=/data/ollama/models ollama serve

预期输出: serve 在新目录初始化（blobs: 0；2026-08-30 隔离实测通过，证据）

卡住怎么办：

• 迁移后原模型看不见 → 模型按目录存储，切目录后需要重新 pull/create；迁移时应整体复制原目录内容；
• rm 释放不了空间 → 确认模型未被加载（先 ollama stop 或等推理结束再 rm）。

与工具页矩阵同源；完整对子、状态与证据见 冲突对子（共装矩阵）。已知关联：

• open-webui × ollama = compatible（实测 verified）：2026-09-01 open-webui 收录时全链路实测（open-webui 容器连宿主机 ollama 推理成功）；
• MaxKB × ollama = compatible（实测 verified）：2026-09-01 combo-local-rag 实测（容器 172.17.0.1 连通 + 开卷问答命中知识库事实）；
• 与 LLaMA-Factory / 其他 CLI 工具：写面不重叠（各自目录），静态判定可共存。

• 症状：ollama pull 长时间转圈/超时 → 官方 registry 国内直连超时；走 ModelScope GGUF + create 导入（见第 5 节第 2 步）
• 症状：容器里 curl 172.17.0.1:11434 connection refused → snap 版只监听 127.0.0.1；sudo snap set ollama host=0.0.0.0:11434 + restart listener
• 症状：tar: unrecognized option --zstd → 先 apt-get install -y zstd（实测 zstd 1.5.7）
• 症状：serve 日志 cloud model cache 拉取失败（ollama.com:443）→ 官方 registry 不可达的正常表现，走 GGUF 导入路径
• 症状：模型目录空间不足 → OLLAMA_MODELS 指到大分区（2026-08-30 实测迁移通过）
• 症状：端口 11434 被占 → OLLAMA_HOST=127.0.0.1:11435 改端口

四段式全文（症状→原因→解法→验证证据）：站内文档

# 来源: Trove 详细指南 · 验证于 2026-08-29
ollama stop 2>/dev/null || true
rm -rf /usr/local/lib/ollama /usr/local/bin/ollama /usr/local/bin/ollama-app 2>/dev/null || true
rm -rf ~/.ollama

预期输出: 命令无报错；ollama --version 提示 command not found；~/.ollama 不存在即为清理干净

注意：~/.ollama 含全部模型（几十 GB 级），删除前确认不需要保留；模型目录被 OLLAMA_MODELS 改过位置的，删 ~/.ollama 不会清到新目录，需要一并处理。

• 问：为什么 pull 总是超时？答：官方 registry（ollama.com:443）国内直连实测超时。正解是 ModelScope 下载 GGUF + ollama create 导入（2026-08-29 实测 491MB/58s 下载 + 导入成功）。这是「国内拉模型」的既定路径，不要反复重试 pull。
• 问：模型装在哪、多大？答：~/.ollama/models（默认）；模型单文件 4~70GB，用 OLLAMA_MODELS 指到大分区（2026-08-30 实测迁移通过）。
• 问：能同时装多个模型吗？答：能。ollama pull/create 多个模型互不影响，ollama run <名字> 指定运行，ollama ps 看当前加载。
• 问：open-webui/MaxKB 怎么连 ollama？答：都是 OpenAI 兼容，配置 base_url=http://172.17.0.1:11434（容器场景）；宿主直接 http://127.0.0.1:11434。容器连不上时检查 snap host 设置（见第 5 节）。
• 问：无 NVIDIA 卡能用吗？答：能，自动回退 CPU 推理（可用但慢）；0.5B 小模型冒烟无压力，大模型建议有卡（RTX 5070 Ti 本环境实测）。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

• 版本：0.33.2（manifest 锁定；本环境实测 2026-08-29）。
• 环境：Linux x86_64（WSL2 Ubuntu 实测）；Windows 走 WSL2 同路径或官方安装器；macOS 官方 dmg。
• 网络：GitHub Release 走 gh-proxy（实测）；模型走 ModelScope GGUF 导入（实测）；官方 registry 直连超时（实测）。
• 写面：~/.ollama/（模型目录 + id_ed25519）；OLLAMA_MODELS 可迁移。
• 端口：11434（OLLAMA_HOST 可改）；容器互通用 172.17.0.1。

• 条目签名：ollama/ollama（MIT，原样收录 0.33.2）

• 实测：实测复现日志（2026-08-29）（gh-proxy 1.42GB 下载 + 版本冒烟）；实测复现日志（2026-08-29）（ModelScope GGUF 导入全流程）；实测复现日志（2026-08-30）（模型目录迁移）；实测复现日志（2026-08-30）（rm 释放磁盘）；实测复现日志（2026-08-30）（本地 RAG 全链路，combo-local-rag 补强）；实测记录（本地留存）（服务启动日志）
• 未实测：Windows 官方安装器 / macOS dmg / AMD ROCm（无对应环境，如实标注）

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

• 官方文档层（docs.ollama.com，v0.33.2）：Ollama 完整用法 [官方文档 · Ollama 官方 · 2026-08-31（guide 收录版本 0.33.2）]
  官方用法全解——安装（Linux/macOS/Windows）、ollama serve/pull/run 核心命令、模型管理（OLLAMA_MODELS 目录、模型拉取）、OpenAI 兼容 API、GGUF 模型导入、多模型并行与热切换