Ollama：本地运行开源大模型的极简利器｜部署与使用全指南

Ollama —— 一条命令在本地一键运行开源大模型

适用环境：Windows 10/11 原生、Windows 10/11 + WSL2（Ubuntu 24.04）、带 NVIDIA RTX 3070 8GB / RTX 4090 24GB，或 Linux 云服务器。 信息口径：本章所有命令、路径、环境变量、模型标签与体积均来自 Ollama 官方仓库、官方文档站与官方模型库；核验日期 2026-10-25。

项目定位与基本信息

官方图片

下图为 Ollama 官方 GitHub README 顶部 Logo（非 AI 生成、非第三方图）。

• 图片来源 URL：https://github.com/ollama/ollama/assets/3325447/0d0b44e2-8f4a-4e99-9b52-a5c1c741c8f7（官方仓库 README 内嵌图片，2026-10-25 用 curl -L 下载）。
• 本地保存路径：https://zhouruolin.cn/upload/01_ollama_logo.png；file 校验结果：PNG image data, 844 x 844, 8-bit/color RGBA，体积 92,041 字节（>20KB）。

环境要求

下列硬性要求来自官方 Windows 文档、官方 GPU 支持页与官方 FAQ；Ollama 官方未公布统一的“最低内存/磁盘”数字，内存与磁盘占用随模型权重、上下文长度与并行度变化（官方 FAQ “How does Ollama handle concurrent requests?” 说明：并发时内存按 OLLAMA_NUM_PARALLEL × OLLAMA_CONTEXT_LENGTH 扩张）。

RTX 3070 8GB 显存参考选型（标签与体积来自官方模型库 tags 页面）：

最详细部署步骤（Windows 原生 与 WSL2 两种视角）

依赖安装

A. Windows 10/11 原生

1. 确认系统为 Windows 10 22H2 或更新（设置 → 系统 → 关于 → 版本）。
2. NVIDIA 显卡驱动：Windows 官方系统要求 551.61 或更新（https://docs.ollama.com/windows）；GPU 支持页通用口径为驱动 ≥550，算力 5.0–6.2 的老卡需 570+（https://docs.ollama.com/gpu）；RTX 30/40 系建议安装当前最新 Game Ready / Studio 驱动，可在 NVIDIA 控制面板或 nvidia-smi 中查看驱动版本。
3. 官方安装包内置 GPU 推理运行时，官方文档未要求单独安装 CUDA Toolkit。

B. WSL2（Ubuntu 24.04）

1. Windows 已启用 WSL2，发行版内核匹配 *icrosoft*WSL2（WSL1 不受支持，可在 PowerShell 执行 wsl --set-version Ubuntu-24.04 2 转换）。
2. NVIDIA GPU 直通由 Windows 侧 NVIDIA 驱动提供；进入 WSL2 后执行 nvidia-smi，能看到显卡并显示 CUDA Version 即直通成功（官方安装脚本正是用 nvidia-smi | grep -o "CUDA Version: [0-9]*\.[0-9]*" 判断 GPU 是否可用，见 install.sh 第 254–257 行）。
3. 在 Ubuntu 内安装脚本所需基础工具：

sudo apt-get update
sudo apt-get install -y curl awk grep sed tee xargs zstd

提示：若要让 WSL2 内的 systemd 服务自动管理 Ollama，需先在 /etc/wsl.conf 中启用 systemd（官方安装脚本对“systemd 未运行的 WSL2”会给出链接 https://learn.microsoft.com/en-us/windows/wsl/systemd#how-to-enable-systemd）；不启用 systemd 时可手动 ollama serve 启动。

项目下载 / 安装（两条官方路径）

路径一：Windows 原生官方安装包

• 图形化安装包（官方下载页 https://ollama.com/download）：
• 安装包直链：https://ollama.com/download/OllamaSetup.exe（2026-10-25 核验 HTTP 200）。
• 下载后双击安装；安装目录为 %LOCALAPPDATA%\Programs\Ollama（官方排错文档给出该路径），安装器会把 ollama 加入用户 PATH。
• 官方 PowerShell 一键脚本（来源：https://docs.ollama.com/windows 与 https://ollama.com/install.ps1）：

# 安装最新稳定版（PowerShell）
irm https://ollama.com/install.ps1 | iex

# 可选：指定版本 / 指定安装目录（环境变量机制来自脚本头部官方示例；版本号取当前最新 release）
$env:OLLAMA_VERSION = "0.40.11"; irm https://ollama.com/install.ps1 | iex
$env:OLLAMA_INSTALL_DIR = "D:\Ollama"; irm https://ollama.com/install.ps1 | iex

路径二：Linux / WSL2 官方一键脚本（来源：https://docs.ollama.com/linux、https://ollama.com/install.sh）

# 安装最新稳定版（脚本自动识别 amd64 / arm64、下载 .tar.zst、创建 ollama 用户与 systemd 服务）
curl -fsSL https://ollama.com/install.sh | sh

# 可选：指定历史版本（官方 FAQ “Installing older or pre-release versions on Linux” 示例）
curl -fsSL https://ollama.com/install.sh | OLLAMA_VERSION=0.5.7 sh

脚本官方行为（源码核对）：

• 下载 https://ollama.com/download/ollama-linux-${ARCH}.tar.zst 解压到系统二进制目录，软链到 /usr/local/bin/ollama；
• 创建系统用户 ollama，加入 render、video 组；
• 写入 systemd 服务 /etc/systemd/system/ollama.service，ExecStart=ollama serve、Restart=always、RestartSec=3；
• 安装成功后提示 API 位于 127.0.0.1:11434。

安装完成后，新开终端执行 ollama --version 确认客户端可用；Linux 下服务状态：

systemctl status ollama          # 查看服务状态（官方 Linux 文档命令）
journalctl -e -u ollama           # 官方 Linux 日志查看命令（最新日志）

模型 / 权重下载（官方链接 + 国内加速与离线方案）

A. 官方直连拉取（官方模型库 https://ollama.com/library）

# 拉取并运行 Qwen3 8B（官方库标签 qwen3:8b）
ollama pull qwen3:8b

# 拉取 DeepSeek-R1 蒸馏 7B
ollama pull deepseek-r1:7b

# 直接运行（未拉取时会自动先下载）
ollama run qwen3:8b

• 模型默认存储位置（官方 FAQ “Where are models stored?”）：
• Linux：/usr/share/ollama/.ollama/models
• Windows：C:\Users\%username%\.ollama\models
• macOS：~/.ollama/models

B. 代理环境变量（官方 FAQ “How do I use Ollama behind a proxy?”）

仅使用 HTTPS_PROXY 转发模型拉取；不要设置 HTTP_PROXY（Ollama 拉模型只走 HTTPS，设置 HTTP_PROXY 可能打断客户端到服务端的本地连接）。代理证书需安装为系统证书。

# Linux / WSL2（systemd 方式写入服务环境变量，见 01.4.4）
export HTTPS_PROXY=https://proxy.example.com:7890

C. 离线导入官方 GGUF（下载慢 / 无法访问官方仓库时的可验证替代方案）

Ollama 官方 “Importing a Model” 文档支持直接从本地 GGUF 文件创建模型：在 Modelfile 中用 FROM 指定本地 GGUF 绝对路径（或相对 Modelfile 的路径），分片模型用通配符 FROM ./model-*.gguf。来源：https://docs.ollama.com/import、https://docs.ollama.com/modelfile。

第 1 步：从 ModelScope 镜像下载官方 Qwen3 GGUF（镜像页 https://modelscope.cn/models/Qwen/Qwen3-8B-GGUF，2026-10-25 核验 200；文件体积与 Hugging Face 官方一致，Q4_K_M 为 5.03GB，详见 03 章）：

# 安装 ModelScope SDK（官方文档：https://modelscope.ai/docs/Models/Download-Model）
pip install modelscope

# 旧版 SDK CLI（官方文档：--model 仓库 ID，--include 文件名通配，--cache_dir 缓存目录）
modelscope download --model Qwen/Qwen3-8B-GGUF \
  --include 'Qwen3-8B-Q4_K_M.gguf' --cache_dir ./qwen3-gguf

# 新版 modelscope-hub CLI（--local-dir 直存目录；--include 通配过滤）
# modelscope download Qwen/Qwen3-8B-GGUF Qwen3-8B-Q4_K_M.gguf --local-dir ./qwen3-gguf

第 2 步：新建 Modelfile（示例，路径按实际修改；PARAMETER num_ctx、SYSTEM 指令格式来自官方 Modelfile 参考 https://docs.ollama.com/modelfile）：

# Modelfile（离线导入本地 GGUF）
# 本地 GGUF 绝对路径（官方要求：绝对路径，或相对本 Modelfile 的路径）
FROM /home/user/models/qwen3-gguf/Qwen3-8B-Q4_K_M.gguf

# 上下文窗口（8GB 显存建议先设小一些，例如 8192）
PARAMETER num_ctx 8192

# 系统提示词
SYSTEM """You are a helpful, concise assistant."""

第 3 步：创建并运行本地模型：

ollama create qwen3-8b-local -f ./Modelfile
ollama run qwen3-8b-local

# 查看模型实际使用的 Modelfile（官方命令）
ollama show --modelfile qwen3-8b-local

说明：离线导入只完成“权重挂载”，Ollama 不会在导入时对 GGUF 重新量化（官方 Importing a Model 文档明确说明量化需使用外部工具，如 llama.cpp 的 llama-quantize，链接 https://github.com/ggml-org/llama.cpp/tree/master/tools/quantize）。

关键配置（环境变量 / 配置项表）

下列变量均来自官方 FAQ “How do I configure Ollama server?” 及各专项 FAQ 页面；修改后需重启 Ollama 服务生效。

设置环境变量的官方方式（FAQ “How do I configure Ollama server?”）：

• Linux / WSL2（systemd）：sudo systemctl edit ollama.service，在 [Service] 段加入：

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_MODELS=/data/ollama/models"
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"

然后：

sudo systemctl daemon-reload
sudo systemctl restart ollama

• Windows：先从托盘退出 Ollama → 设置（Win11）/ 控制面板（Win10） 搜索“环境变量” → 编辑用户账户的 OLLAMA_HOST、OLLAMA_MODELS 等 → 保存后从开始菜单重新启动 Ollama（Windows 继承用户与系统环境变量）。
• 前台手动启动时临时生效：

OLLAMA_HOST=0.0.0.0:11434 OLLAMA_DEBUG=1 ollama serve

启动

• Windows 原生：安装后托盘常驻，后台服务自动运行；命令行可直接 ollama run <模型名>。
• Linux / WSL2（systemd）：

sudo systemctl enable --now ollama     # 启用并启动服务
ollama ps                               # 查看当前已加载模型与 GPU/CPU 占用

• 手动前台启动（调试用）：

ollama serve
# 官方启动日志显示：Ollama 正在运行，监听 http://127.0.0.1:11434

使用方法

启动方式

命令行操作步骤（带示例）

官方 CLI 参考：https://docs.ollama.com/cli。

# 1. 拉取模型
ollama pull qwen3:8b

# 2. 交互式对话（进入后直接输入文字；多行用 """ 包裹）
ollama run qwen3:8b

# 3. REPL 内常用斜杠命令（官方 FAQ 与官方 Quickstart 文档）
>>> /set parameter num_ctx 8192      # 当次会话设置上下文长度（FAQ “How can I specify the context window size?”）
>>> /bye                              # 退出会话（Quickstart “Run a model locally”：Type `/bye` to leave.）
# 多行输入：用三引号 """ 包裹（官方 CLI 参考 “Multiline input”）

# 4. 列出已安装模型
ollama ls

# 5. 查看正在内存中运行的模型（PROCESSOR 列显示 100% GPU / 100% CPU / 混合占比）
ollama ps

# 6. 卸载模型、释放显存
ollama stop qwen3:8b

# 7. 删除本地模型
ollama rm qwen3:8b

# 8. 查看模型 Modelfile / 详情
ollama show --modelfile qwen3:8b

参数说明表

HTTP API 与 OpenAI 兼容接口（官方 https://docs.ollama.com/api/introduction）：

端到端示例（输入 → 命令 → 输出）

场景：RTX 3070 8GB 笔记本，离线环境，用 01.4.3 第 C 步导入的 qwen3-8b-local 完成一次对话，并通过 OpenAI 兼容接口调用。

第 1 步：确认模型已导入

$ ollama ls
NAME                ID              SIZE      MODIFIED
qwen3-8b-local:latest   <hash>      5.03 GB    2 minutes ago

第 2 步：命令行提问（输入 → 命令）

$ ollama run qwen3-8b-local "用三句话解释什么是量化（quantization），面向新手。"

输出（官方 API 字段结构示意，实际文本由模型生成）：

量化就是把模型里原本高精度的数字（如 16 位浮点数）压缩成更低位数（如 4 位整数）来存储和计算。
这样模型文件更小、更省显存，普通电脑也能跑起来；代价是回答质量可能有轻微下降，需要在体积和效果之间权衡。
常见档位有 Q4_K_M、Q5_K_M、Q6_K、Q8_0 等，数字越小体积越小、速度越快。

第 3 步：原生 REST API 调用（官方 README “REST API” 示例，模型名替换为本地模型）：

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3-8b-local",
  "messages": [{"role": "user", "content": "用三句话解释什么是量化（quantization），面向新手。"}],
  "stream": false,
  "options": {"num_ctx": 8192}
}'

返回（结构字段来自官方 /api/chat 文档；message.content 为模型回答）：

{
  "model": "qwen3-8b-local",
  "message": {
    "role": "assistant",
    "content": "量化就是把模型里原本高精度的数字……（同上模型输出）"
  },
  "done": true,
  "prompt_eval_count": 18,
  "eval_count": 96
}

第 4 步：OpenAI 兼容接口调用（Base URL http://localhost:11434/v1，官方 https://docs.ollama.com/api/openai-compatibility）：

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-8b-local",
    "messages": [{"role": "user", "content": "你好，介绍一下你自己。"}]
  }'

常见坑（现象 + 原因 + 解决）

1. 现象：WSL2 内安装 Ollama 或 ollama pull 模型时网络极慢、经常中断。 - 原因：官方 FAQ “Why is networking slow in WSL2 on Windows 10?” 指出，Windows 10 上 vEthernet (WSL) 适配器的 Large Send Offload (LSOv2) 会影响安装与模型下载。 - 解决：控制面板 → 网络和 Internet → 查看网络状态和任务 → 更改适配器设置 → vEthernet (WSL) 属性 → 配置 → 高级，将 Large Send Offload Version 2 (IPv4) 与 Large Send Offload Version 2 (IPv6) 均禁用后重启 WSL。

2. 现象：模型只跑在 CPU 上，ollama ps 显示 100% CPU 或很大比例 CPU/GPU 混合。 - 原因：NVIDIA 驱动过旧或 GPU 发现失败（官方 Troubleshooting “NVIDIA GPU Discovery” 给出错误码含义：3 未初始化、46 设备不可用、100 无设备、999 未知）；WSL2 下 nvidia-smi 看不到显卡时 Ollama 同样无法使用 GPU。 - 解决：先在 Windows 侧升级 NVIDIA 驱动到 ≥550；WSL2 内执行 nvidia-smi 验证直通；Linux 容器场景可执行 sudo nvidia-modprobe -u、重载 nvidia_uvm 驱动（sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm）或重启；查看日志 journalctl -e -u ollama，必要时 OLLAMA_DEBUG=1 获取 GPU 发现细节。

3. 现象：修改了 OLLAMA_HOST、OLLAMA_MODELS 等变量后不生效。 - 原因：Windows 桌面版需先从托盘退出再重启才会继承新的用户环境变量；Linux systemd 服务需 daemon-reload 并重启；变量写错位置（如只在当前 shell export 但服务由 systemd 拉起）不生效。 - 解决：按 01.4.4 官方方式设置：Windows 退出托盘后重启；Linux 用 sudo systemctl edit ollama.service 写 Environment= 后 systemctl daemon-reload && systemctl restart ollama。

4. 现象：模型下载到一半磁盘报错 / 空间不足。 - 原因：默认模型目录在系统盘（Windows C:\Users\%username%\.ollama\models；Linux /usr/share/ollama/.ollama/models），大模型（如 Q8_0、32B 级）体积可达数十 GB。 - 解决：设置 OLLAMA_MODELS 指向大容量目录；Linux 标准安装下需把目录授权给 ollama 用户：sudo chown -R ollama:ollama <目录>（官方 FAQ “Where are models stored?”）。

5. 现象：局域网其他设备 / 前端访问不到 Ollama。 - 原因：服务默认仅绑定 127.0.0.1:11434；浏览器跨域还受 OLLAMA_ORIGINS 限制。 - 解决：设置 OLLAMA_HOST=0.0.0.0:11434 后重启；跨域前端按需在 OLLAMA_ORIGINS 中放行来源（官方 FAQ “How can I expose Ollama on my network?” “How can I allow additional web origins?”）。

6. 现象：/tmp 所在分区挂载了 noexec，Ollama 启动失败或无法解压临时运行库。 - 原因：官方 Troubleshooting “Linux tmp noexec”：临时可执行文件目录不可执行。 - 解决：设置 OLLAMA_TMPDIR 到 ollama 用户可写且带执行权限的目录，例如 OLLAMA_TMPDIR=/usr/share/ollama/。

7. 现象：代理环境下模型拉取失败，或本地客户端连不上服务。 - 原因：FAQ 明确：模型拉取只走 HTTPS，应配置 HTTPS_PROXY；设置 HTTP_PROXY 会打断本地客户端与服务端连接。 - 解决：仅设置 HTTPS_PROXY 并安装代理根证书为系统证书；Docker 场景用 -e HTTPS_PROXY=https://proxy.example.com 传入容器。

本节来源清单

验证方式说明：web_fetch = 通过文档抓取工具实际打开；curl 200 = 命令行 HTTP 状态码核验；general_search = 搜索索引佐证。核验日期 2026-10-25。