ollama

你会遇到什么

你下载了 ollama，跑 ollama pull qwen2.5，然后等了二十分钟还在转圈——官方 registry 国内直连超时。或者你压根没装成功：官方 install.sh 从 ollama.com 拉脚本，国内网络下慢到怀疑人生。ollama 本身是好东西：一条命令拉起本地模型，自带 OpenAI 兼容 API，改个 base_url 就能让脚本、Agent、IDE 插件全接上本地模型。但这个「装得上」在国产网络环境里有一道坎，这篇指南就是实测过的完整路径：二进制用 gh-proxy 拉 GitHub Release（1.42GB tar.zst，实测通过），模型用 ModelScope 下载 GGUF 再导入（491MB / 58 秒，实测通过），全程可复制。 什么时候用：

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

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

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

ollama 是单二进制 + 模型目录。ollama serve 拉起服务（默认端口 11434），ollama pull <模型> 下载模型，ollama run <模型> 交互式运行，API 兼容 OpenAI 格式（/api/version 等）。有 NVIDIA 卡自动启用 CUDA，无卡自动回退 CPU 推理（可用但慢）。 两个关键机制：

• OLLAMA_MODELS：模型目录环境变量（默认 ~/.ollama/models，可指到大分区——模型文件单个 4~70GB）；
• GGUF 导入：从 ModelScope 等源下载 GGUF 文件后用 ollama create 导入，绕开官方 registry——这就是国内拉模型的正解。

装完它动哪里：~/.ollama/（模型与配置；OLLAMA_MODELS 可改）；二进制在 /usr/local（本路径实测）。

一步步来

第 1 步：装二进制

讲解：官方 install.sh 从 ollama.com 拉安装脚本，国内直连可能很慢（推断）。实测路径是 gh-proxy 拉 GitHub Release 的 ollama-linux-amd64.tar.zst（1.42GB）解压到 /usr/local。需要 tar --zstd（zstd 1.5.7，apt 安装）或 zstd 工具。下载量大，校园网/代理切换时注意稳定性。

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 实测）

装好确认：

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

卡住怎么办：

• tar: unrecognized option --zstd → 先 apt-get install -y zstd（或系统自带 zstd 工具）；
• 下载中断 → 断点续传建议用 curl -C - 重试；下载 1.42GB 大文件，先确认磁盘（df -h /）与网络稳定性；
• Windows 用户 → 用官方安装器（建议 WSL2 内与 Linux 同路径）；macOS 用官方 dmg（Apple Silicon 原生）。

第 2 步：启动服务 + 导入第一个模型

讲解：ollama serve 启动服务（默认端口 11434）。模型拉取走官方 registry，国内实测超时——备选路径是 ModelScope 下载 GGUF + ollama create 导入（2026-08-29 实测：qwen2.5-0.5b-instruct-q4_k_m 491MB 下载 58.5s + create success + CPU 冒烟通过，实测复现日志（2026-08-29））。

OLLAMA_MODELS=~/.ollama/models ollama serve

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

curl -s http://127.0.0.1:11434/api/version

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

装好确认：

• serve 日志正常、无报错；
• /api/version 返回版本号；
• ollama list 能看到已导入模型（有模型后）。

卡住怎么办：

• serve 起不来/端口被占 → 默认 11434 被占用时改 OLLAMA_HOST（如 OLLAMA_HOST=127.0.0.1:11435）；
• ollama pull 超时 → 官方 registry 国内实测超时（serve 日志 cloud model cache 拉取失败，ollama.com:443）；走 ModelScope GGUF + create 导入路径；
• 模型目录空间不足 → OLLAMA_MODELS 指到大分区（模型 4~70GB，先 df -h 确认）。

怎么确认修好了

三步冒烟，全绿才算装好：

ollama --version

预期输出: ollama version 0.33.2

curl -s http://127.0.0.1:11434/api/version

预期输出: {"version":"0.33.2"}

ollama list

预期输出: NAME ID SIZE MODIFIED（有已导入模型时能看到行）

• 服务起来了：curl /api/version 返回版本号，说明 serve 正常监听 11434；
• 模型就绪：ollama list 里有模型行；
• 走 GGUF 导入的：ollama run qwen2.5:0.5b "你好" 能出字（CPU 冒烟，2026-08-29 实测输出正常）。

其它环境的表现（常见变体）

• Windows：用官方 Windows 安装器；若在 WSL2 里用，走本指南 Linux 路径（2026-08-29 环境为 WSL2 Ubuntu，实测即此路径）。
• macOS：官方 dmg（Apple Silicon 原生 MPS；Intel 走 CPU）。
• 无 NVIDIA 卡：自动回退 CPU 推理，可用但慢（0.5B 小模型冒烟无压力，大模型建议有卡）。
• AMD 卡：走 ROCm 资产（推断，未实测）。
• 端口被占：OLLAMA_HOST 可改（如 OLLAMA_HOST=127.0.0.1:11435）。
• 旧版本：< 0.30 的 API/模型兼容性差，建议直接用最新（本指南实测 0.33.2）。

常用场景（按用户目标）

场景按「你要做什么」组织，不是按命令面；每个场景的命令均实测，预期输出可对照。

场景 1：把服务跑起来

OLLAMA_MODELS=~/.ollama/models ollama serve

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

起来后两步验证：

curl -s http://127.0.0.1:11434/api/version

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

ollama list

预期输出: NAME ID SIZE MODIFIED（空表 exit 0；2026-08-29 实测）

场景 2：国内拉模型（绕开上游 registry）

ollama pull 走上游 registry，国内实测超时。正解 = ModelScope 下载 GGUF + ollama create 导入（2026-08-29 实测：491MB 下载 58.5s + create success + CPU 冒烟通过，实测复现日志（2026-08-29））：

curl -sL -o /tmp/qwen2.5-0.5b-instruct-q4_k_m.gguf https://modelscope.cn/models/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/master/qwen2.5-0.5b-instruct-q4_k_m.gguf
printf 'FROM /tmp/qwen2.5-0.5b-instruct-q4_k_m.gguf\n' > Modelfile-qwen
ollama create qwen2.5:0.5b -f Modelfile-qwen
ollama run qwen2.5:0.5b "你好"

预期输出: 下载完成（491MB/58.5s）→ create 显示 copying file → success → run 出字（2026-08-29 实测）

换更大模型：ModelScope 搜同名 GGUF（如 Qwen2.5-7B-Instruct-GGUF），替换 URL 与模型名即可。

场景 3：接 open-webui 界面（含知识库 RAG）

ollama 只提供 API；要网页聊天界面 + 文档知识库，用组合包 combo-local-llm-finetune（2026-08-30 实测全链路：docker run 3 env + embedding nomic-embed-text 768 维 + 建库检索命中）：

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway \
-v open-webui:/app/backend/data --name open-webui --restart always \
-e ENABLE_SIGNUP=true \
-e RAG_EMBEDDING_ENGINE=ollama \
-e RAG_EMBEDDING_MODEL=nomic-embed-text \
ghcr.nju.edu.cn/open-webui/open-webui:main

预期输出: docker run 打印容器 ID；docker ps 里 open-webui 为 Up（2026-08-30 实测；镜像 7.16GB，ghcr 国内镜像前缀）

RAG 实测关键坑：

• embedding 模型名不能带 ollama/ 前缀（open-webui 原样传给 ollama 会 404），必须裸名 nomic-embed-text；
• 已有数据卷时 DB 持久化配置优先于 env——改 embedding 引擎走管理员面板 → 设置 → 检索，或 POST /api/v1/retrieval/embedding/update；
• 聊天层建议 ≥7B 支持函数调用模型（0.5B 不触发自动工具检索，实测会瞎编）。

数据与目录

• 模型与配置：默认 ~/.ollama/（snap 安装在 /var/snap/ollama/common/models）；OLLAMA_MODELS 可指到大分区。
• 迁移目录（verified 2026-08-30）：停 serve → 模型目录整体 mv 到新位置 → OLLAMA_MODELS=<新路径> ollama serve 重启。实测目录换位后 list/run 均正常，模型从新路径读取；系统服务（snap/systemd）改环境变量的方式未逐一实测（实测复现日志（2026-08-30））。
• 释放磁盘（verified 2026-08-30）：ollama rm <模型> 删除模型与对应 blobs。隔离实测：pull 274MB 模型后 blobs 274302450 字节 → rm 后归 0，list 收敛回空，字节级释放成立（实测复现日志（2026-08-30））。
• 模型文件单个 4~70GB，长期使用注意磁盘水位；ollama list 查看占用、ollama rm <模型> 释放。

卸载与清理

note: 删除二进制目录与模型目录；先停 serve 进程

pkill -f 'ollama serve' 2>/dev/null || true
rm -rf /usr/local/lib/ollama /usr/local/bin/ollama ~/.ollama

预期输出: 命令面消失（ollama 不存在）

手动确认清单（如需彻底清理）：

• 模型目录（默认 ~/.ollama/models，或 OLLAMA_MODELS 指定路径；模型 4~70GB，确认后删）
• 监听端口进程（默认 11434，lsof -i :11434 查看）

依赖警告

• 版本：[0.33.2, 0.33.2]（2026-08-29 实测最新；旧版本 < 0.30 的 API/模型兼容性差，建议直接最新）。
• 环境：Linux x86_64（本路径实测）；无 NVIDIA 卡走 CPU 推理（可用但慢）；AMD 卡用 ROCm 资产（推断）；Apple Silicon 走 MPS。
• 磁盘：模型 4~70GB 级，装前 df -h / 确认；OLLAMA_MODELS 可指大分区。
• 网络：二进制下载走 gh-proxy（实测）；模型拉取官方 registry 国内超时（实测）→ ModelScope GGUF 导入备选。
• 端口：默认 11434（OLLAMA_HOST 可改）。
• 写面：~/.ollama/（模型与配置）。
• 共装：与 open-webui / LLaMA-Factory 判定 possible-compatible（写面不重叠：ollama 写 ~/.ollama/；open-webui 写 Docker volume；LLaMA-Factory 写项目目录），组合包见 站内文档。

FAQ（常见问题）

• 问：模型拉不下来（国内网络）？答：ollama pull 走官方 registry，国内实测超时（serve 日志 cloud model cache 拉取失败，ollama.com:443）；备选 = ModelScope 下载 GGUF + ollama create 导入（2026-08-29 实测：qwen2.5-0.5b-instruct-q4_k_m 491MB 下载 58.5s + ollama create success + CPU 冒烟输出正常，实测复现日志（2026-08-29））。
• 问：需要显卡吗？答：NVIDIA 驱动 + CUDA 自动启用；无卡自动回退 CPU（速度慢）；AMD 卡用 ROCm 资产（推断）；Apple Silicon 走 MPS。
• 问：端口冲突？答：默认 11434，OLLAMA_HOST 可改；与占用 11434 的服务冲突时改环境变量。
• 问：模型存哪？答：默认 ~/.ollama/models（OLLAMA_MODELS 可指定大分区路径，模型 4~70GB 建议先 df -h 确认）。
• 问：和 open-webui / LLaMA-Factory 一起用？答：判定 possible-compatible——写面不重叠（ollama 写 ~/.ollama/ + 模型目录；open-webui 写 Docker volume；LLaMA-Factory 写项目目录），组合包见 站内文档。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。