极简快速部署：Ollama 本地大模型一键部署与全场景调用

系列：本地大模型部署系列 · 第3篇（共12篇）
面向：AI应用工程师、后端开发、大模型落地从业者
关键词：Ollama / Modelfile / HTTP API / Python SDK / GGUF / 一键部署

一、前言

本篇解决什么问题

你是否经历过这样的场景——想快速跑起一个本地大模型验证想法，结果被环境配置、模型下载、依赖冲突折腾了半天还没跑通？Ollama 就是为此而生的：一条命令拉模型，一条命令开始对话，一条命令起API服务。

本篇解决的核心问题：从零到一，用最短路径在本地跑通大模型，并通过命令行、HTTP API、Python SDK 三种方式完成全场景调用。

适用场景

首次接触本地大模型，想用最快方式跑通第一个模型
需要本地大模型提供 API 服务，对接自己的应用
快速原型验证、个人 AI 助手搭建、学习测试
已有 GPU 但不想折腾复杂的环境配置

读完本篇你将获得

Ollama 的架构认知与”一键部署”原理
三大平台（Windows / Linux / macOS）完整安装流程
从模型拉取到多场景调用的完整实操经验
Modelfile 自定义模型与参数持久化配置能力
一份可复用的踩坑解决方案速查手册
Ollama 适用与不适用场景的工程判断力

二、核心原理极简讲解

2.1 Ollama 的架构设计：C/S 模式

Ollama 本质是一个 Client/Server 架构 的本地模型管理与服务系统：

┌─────────────────────────────────────────────────┐
│                   Ollama Server                   │
│  (后台常驻进程，监听 11434 端口)                    │
│                                                   │
│  ┌───────────┐  ┌───────────┐  ┌──────────────┐ │
│  │ 模型管理器  │  │ 推理引擎   │  │ REST API 服务 │ │
│  │(pull/list)│  │(llama.cpp)│  │(HTTP 11434)  │ │
│  └───────────┘  └───────────┘  └──────────────┘ │
└───────────────────┬─────────────────────────────┘
                    │
        ┌───────────┼───────────┐
        │           │           │
   ┌────┴────┐ ┌───┴────┐ ┌───┴────┐
   │ CLI客户端│ │ HTTP   │ │ Python │
   │(ollama)  │ │ (curl) │ │  SDK   │
   └─────────┘ └────────┘ └────────┘

关键设计：

组件	职责	说明
ollama serve	后台服务	管理 GPU/CPU 资源、模型加载/卸载、推理调度
ollama (CLI)	命令行客户端	发送指令给 serve 进程，如 `ollama run`、`ollama pull`
REST API	HTTP 接口	端口 11434，提供 generate / chat / embeddings 等接口
模型管理器	模型存储与版本管理	类 Docker 体验，模型存放在本地仓库

2.2 底层基于 llama.cpp

Ollama 的推理引擎底层就是 llama.cpp——目前社区最成熟的 GGUF 格式推理引擎。Ollama 做的事情是：

封装 llama.cpp：隐藏编译、参数配置等复杂性
自动选择推理后端：有 GPU 用 GPU（CUDA / Metal / ROCm），没有就 CPU
管理模型生命周期：拉取、存储、加载、卸载、删除，一条命令搞定
暴露标准 API：REST 接口开箱即用，不需要自己写服务端代码

2.3 为什么能做到”一键”

对比手动部署 llama.cpp 的流程：

手动部署 llama.cpp：
  编译 → 下载GGUF → 手动指定参数启动服务 → 自己写API封装

Ollama：
  ollama run qwen2.5:7b   ← 一条命令，完成所有事情

“一键”的本质是 预打包 + 自动配置：

每个模型标签（tag）对应一个预配置好的 GGUF 文件 + 参数集
服务端自动检测硬件，选择最优推理后端和 GPU 层数
模型文件从 Ollama 官方仓库拉取，无需手动找下载链接

工程决策视角：Ollama 的设计哲学是”约定优于配置”——用合理的默认值让 80% 的场景零配置可用，同时通过 Modelfile 和环境变量为 20% 的高级场景提供定制能力。

三、环境 & 前置依赖

3.1 系统要求

项目	最低要求	推荐配置
操作系统	Windows 10 21H2 / Ubuntu 20.04 / macOS 12	Windows 11 / Ubuntu 22.04 / macOS 14+
GPU	无独显可用（CPU推理）	NVIDIA RTX 3060 12GB+
系统内存	8GB（跑7B量化模型）	16GB+
硬盘空间	10GB 可用	50GB+ SSD
NVIDIA Driver	≥ 450.x（GPU推理）	≥ 525.x（CUDA 12.x）

3.2 硬件与模型对应速查

模型	参数量	量化大小	最低显存/内存	推荐显卡
qwen2.5:1.5b	1.5B	~1.1GB	2GB	集成显卡可用
qwen2.5:7b	7B	~4.7GB	8GB	RTX 3060 12G / RTX 4060 8G
llama3.1:8b	8B	~4.9GB	8GB	RTX 3060 12G / RTX 4060 8G
deepseek-r1:7b	7B	~4.7GB	8GB	RTX 3060 12G / RTX 4060 8G
mistral:7b	7B	~4.1GB	8GB	RTX 3060 12G / RTX 4060 8G
qwen2.5:14b	14B	~9.0GB	12GB	RTX 3060 12G / RTX 4070 12G
llama3.1:70b	70B	~40GB	48GB	A100 / 多卡

注意：Ollama 默认拉取的是 Q4_K_M 量化版本（4-bit量化），这是显存与精度的最佳平衡点。如果你显存充足，可以拉取更高精度版本（如 qwen2.5:7b-q5_K_M）。

3.3 Ollama 不需要的依赖

与 llama.cpp 手动编译不同，Ollama 不需要：

❌ Python 环境
❌ CUDA Toolkit 手动安装（Ollama 自带 CUDA 运行时）
❌ 手动编译任何代码
❌ 手动下载 GGUF 文件

唯一需要的：NVIDIA 显卡驱动（GPU 推理时）。CPU 推理甚至驱动都不需要。

四、Step-by-step 实操流程

4.1 安装 Ollama

Windows

# 方法1：官网下载安装包（推荐）
# 访问 https://ollama.com/download 下载 OllamaSetup.exe
# 双击安装，一路 Next 即可

# 方法2：命令行安装（winget）
winget install Ollama.Ollama

# 验证安装
ollama --version
# 输出示例：ollama version is 0.5.x

安装完成后，Ollama 会自动注册为系统服务并后台运行。任务管理器中可以看到 ollama app.exe 进程。

Linux

# 官方一键安装脚本
curl -fsSL https://ollama.com/install.sh | sh

# 验证
ollama --version

# 手动安装（如果脚本安装失败）
# 1. 下载二进制文件
sudo curl -L https://ollama.com/download/ollama-linux-amd64 -o /usr/bin/ollama
sudo chmod +x /usr/bin/ollama

# 2. 创建 systemd 服务
sudo tee /etc/systemd/system/ollama.service << 'EOF'
[Unit]
Description=Ollama Service
After=network.target

[Service]
Type=simple
User=ollama
Group=ollama
ExecStart=/usr/bin/ollama serve
Restart=always
RestartSec=3
Environment=OLLAMA_HOST=0.0.0.0:11434

[Install]
WantedBy=multi-user.target
EOF

# 3. 启动服务
sudo useradd -r -s /bin/false ollama
sudo systemctl daemon-reload
sudo systemctl enable ollama
sudo systemctl start ollama

# 检查服务状态
sudo systemctl status ollama

macOS

# 方法1：官网下载（推荐，原生支持 Apple Silicon 的 Metal 加速）
# 访问 https://ollama.com/download 下载 Ollama-darwin.zip
# 解压后拖入 Applications 文件夹

# 方法2：Homebrew 安装
brew install ollama

# 验证
ollama --version

# 启动服务（如果未自动启动）
open -a Ollama

Apple Silicon 用户注意：Ollama 对 M1/M2/M3/M4 芯片有原生 Metal 加速支持，7B 模型推理可达 30+ tokens/s，体验非常流畅。

4.2 拉取和运行第一个模型

以 Qwen2.5-7B 为例，从拉取到对话的完整流程：

# 步骤1：拉取模型（自动下载 Q4_K_M 量化版本）
ollama pull qwen2.5:7b

# 输出示例：
# pulling manifest...
# pulling 8c6ec9dd... 100% ▕██████████▏ 4.7 GB/4.7 GB
# pulling ...              100% ▕██████████▏  11 KB/ 11 KB
# verifying sha256 digest
# writing manifest
# success

# 步骤2：运行模型，进入对话模式
ollama run qwen2.5:7b

# 输出示例：
# >>> 你好，请介绍一下你自己
# 你好！我是Qwen，由阿里云开发的大型语言模型...

# 步骤3：退出对话
# 输入 /bye 或按 Ctrl+D 退出

对话模式中的常用命令：

命令	作用
`/bye`	退出对话
`/clear`	清除对话历史
`/show info`	显示模型信息
`/show license`	显示模型许可证
`/show modelfile`	显示当前模型的 Modelfile
`/set parameter <key> <value>`	临时修改推理参数
`/set system <prompt>`	临时修改系统提示词
`"""`	多行输入（三引号包裹）

首次拉取模型较慢？ 模型文件约 4-5GB，国内直连 Ollama 官方仓库速度不稳定。解决方案见第7节踩坑记录。

4.2.1 确认 Ollama 是否使用 GPU 推理

模型跑起来后，第一件事不是急着对话，而是确认 GPU 是否真正参与了推理。很多人装完 Ollama 就开始用，跑了一天发现全程 CPU 推理，速度慢了一大截还不知道原因。

方法1：verbose 模式查看加载详情（最直接）

1 2	# 启动对话时加 --verbose 参数 ollama run qwen2.5:7b --verbose

进入对话后随便输入一句话，回复结束后会打印类似以下的性能统计：

>>> 你好
你好！我是Qwen，由阿里云开发的大型语言模型...

>>> 评价:  total duration: 1.234s | load duration: 567ms | 
    prompt eval count: 12 token(s) | prompt eval duration: 89ms | 
    prompt eval rate: 134.83 tokens/s | 
    eval count: 45 token(s) | eval duration: 1.045s | 
    eval rate: 43.06 tokens/s

关键看两个指标：

指标	GPU 推理（正常）	CPU 推理（异常）
`eval rate`	7B模型 ≥ 30 tokens/s	7B模型 < 10 tokens/s
`load duration`	通常 < 1s	通常 > 2s（CPU加载更慢）

方法2：nvidia-smi 实时监控（最直观）

在另一个终端窗口中执行：

1 2	# 持续监控 GPU 状态（每1秒刷新） nvidia-smi -l 1

观察以下字段：

+-----------------------------------------------------------------------------+
|  GPU  Name        |  Memory-Usage  |  Volatile Uncorr. ECC  |  GPU-Util      |
|  0  GeForce RTX   |   4821MiB / 12288MiB  |         0%       |      85%      |
+-----------------------------------------------------------------------------+

Memory-Usage：运行 7B Q4_K_M 模型时，显存占用应在 4-6GB 左右。如果这个数字几乎没变化，说明模型没有加载到 GPU。
GPU-Util：对话生成时应在 60%-100% 之间跳动。如果一直是 0%，说明 GPU 没有参与推理。

方法3：查看 Ollama 服务日志（最准确）

# Windows：日志文件路径
# %LOCALAPPDATA%\Ollama\log\server.log
# 或者直接打开资源管理器地址栏输入 %LOCALAPPDATA%\Ollama\log

# Linux
journalctl -u ollama --no-pager -n 50 | grep -i "gpu\|cuda\|llm"

# macOS：Ollama 应用菜单 → View Log

在日志中搜索关键词，正常情况应看到类似：

# ✅ GPU 推理（正常）
msg="inference compute" id=cuda:0 library=cuda compute=8.6 driver=12.4 name="NVIDIA GeForce RTX 3060" total="11.9 GiB" available="11.2 GiB"
msg="offload to cuda" layers=32 total=32  # 表示全部32层都加载到了GPU
msg="memory" layer=cuda:0 size="4.2 GiB"  # 显存占用

# ❌ CPU 回退（异常）
msg="fallback to CPU" reason="not enough VRAM"  # 显存不足，回退到CPU
msg="inference compute" id=cpu library=cpu       # 使用CPU推理

快速判断口诀：eval rate 大于 30 是 GPU，小于 10 是 CPU；nvidia-smi 显存没变化就是没加载上；日志里搜 cuda 看层数，搜 fallback 看是否回退。

4.3 常用模型一览与推荐

模型	Ollama标签	参数量	量化大小	最低显存/内存	推荐场景
Qwen2.5	`qwen2.5:7b`	7B	~4.7GB	8GB	中文对话首选，指令跟随强
Llama3.1	`llama3.1:8b`	8B	~4.9GB	8GB	英文强，多语言通用
DeepSeek-R1	`deepseek-r1:7b`	7B	~4.7GB	8GB	推理能力突出，数学/代码
Mistral	`mistral:7b`	7B	~4.1GB	8GB	轻量高效，英文优秀
Gemma2	`gemma2:9b`	9B	~5.4GB	8GB	Google出品，多语言均衡
Phi-3.5	`phi3.5:3.8b`	3.8B	~2.4GB	4GB	极致轻量，低配首选
Qwen2.5-Coder	`qwen2.5-coder:7b`	7B	~4.7GB	8GB	代码生成专用
Llama3.2-Vision	`llama3.2-vision:11b`	11B	~7.9GB	12GB	多模态（图文）

按场景推荐：

中文对话/办公助手  → qwen2.5:7b（中文能力最强）
代码辅助/编程助手  → qwen2.5-coder:7b 或 deepseek-r1:7b
英文写作/通用任务  → llama3.1:8b 或 mistral:7b
低配机器/快速测试  → phi3.5:3.8b 或 qwen2.5:1.5b
数学推理/逻辑分析  → deepseek-r1:7b

4.4 命令行核心操作速查

# ===== 模型管理 =====
ollama list                    # 列出本地所有模型
ollama pull qwen2.5:7b         # 拉取模型（不运行）
ollama run qwen2.5:7b          # 拉取并运行模型（进入对话）
ollama rm qwen2.5:7b           # 删除本地模型
ollama cp qwen2.5:7b my-qwen   # 复制模型（用于自定义修改）

# ===== 模型信息 =====
ollama show qwen2.5:7b         # 显示模型详情
ollama show qwen2.5:7b --modelfile  # 显示模型 Modelfile

# ===== 模型运行 =====
ollama run qwen2.5:7b "你好"   # 单次提问（非交互模式）
ollama run qwen2.5:7b --nowordwrap  # 禁用自动换行

# ===== 服务管理 =====
ollama serve                   # 启动服务（前台运行）
# Windows/macOS：Ollama 作为后台服务自动运行

# ===== 自定义模型 =====
ollama create my-model -f Modelfile   # 从 Modelfile 创建模型
ollama update qwen2.5:7b             # 更新模型到最新版

4.5 HTTP API 调用

Ollama 默认在 http://localhost:11434 提供 REST API，这是对接应用的核心入口。

4.5.1 检查服务状态

1 2	curl http://localhost:11434/api/tags # 返回本地所有模型列表

4.5.2 Generate 接口（单轮补全）

curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "请用三句话介绍Python语言的特点",
  "stream": false
}'

流式输出：

curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "请用三句话介绍Python语言的特点",
  "stream": true
}'

流式模式下，每个 token 会以 JSON 行（JSONL）格式逐行返回，最后一行包含 "done": true。

4.5.3 Chat 接口（多轮对话）

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [
    {
      "role": "system",
      "content": "你是一个专业的Python编程助手，回答要简洁准确。"
    },
    {
      "role": "user",
      "content": "Python的GIL是什么？"
    }
  ],
  "stream": false
}'

4.5.4 Embeddings 接口（文本向量化）

curl http://localhost:11434/api/embed -d '{
  "model": "qwen2.5:7b",
  "input": "这是一段需要向量化的文本"
}'

注意：Embeddings 接口建议使用专门的 Embedding 模型（如 nomic-embed-text），效果更好且更快：

# 拉取专用 Embedding 模型
ollama pull nomic-embed-text

# 调用
curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": "这是需要向量化的文本"
}'

4.6 Python 调用

4.6.1 官方 ollama 库（推荐）

1	pip install ollama

import ollama

# ===== 单轮对话 =====
response = ollama.chat(
    model="qwen2.5:7b",
    messages=[
        {
            "role": "system",
            "content": "你是一个专业的技术顾问，回答简洁准确。"
        },
        {
            "role": "user",
            "content": "什么是向量数据库？用两句话解释。"
        }
    ]
)
print(response["message"]["content"])


# ===== 流式输出 =====
stream = ollama.chat(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "写一首关于编程的短诗"}],
    stream=True
)
for chunk in stream:
    print(chunk["message"]["content"], end="", flush=True)
print()  # 换行


# ===== Generate（单轮补全） =====
response = ollama.generate(
    model="qwen2.5:7b",
    prompt="请用三个关键词概括大语言模型的核心能力："
)
print(response["response"])


# ===== Embeddings（文本向量化） =====
response = ollama.embed(
    model="nomic-embed-text",
    input=["这是第一段文本", "这是第二段文本"]
)
print(f"向量维度: {len(response['embeddings'][0])}")
print(f"第一段文本向量前5维: {response['embeddings'][0][:5]}")

4.6.2 requests 库调用（更灵活的控制）

import json
import requests

OLLAMA_BASE = "http://localhost:11434"


def chat_completion(
    model: str,
    messages: list[dict],
    stream: bool = False,
    **kwargs
) -> str | None:
    """调用 Ollama Chat API，支持流式和非流式"""
    url = f"{OLLAMA_BASE}/api/chat"
    payload = {
        "model": model,
        "messages": messages,
        "stream": stream,
        **kwargs
    }

    try:
        if stream:
            # 流式：逐行读取 JSON
            with requests.post(url, json=payload, stream=True, timeout=120) as resp:
                resp.raise_for_status()
                full_content = []
                for line in resp.iter_lines(decode_unicode=True):
                    if line:
                        chunk = json.loads(line)
                        content = chunk.get("message", {}).get("content", "")
                        if content:
                            print(content, end="", flush=True)
                            full_content.append(content)
                    if chunk.get("done", False):
                        break
                print()  # 换行
                return "".join(full_content)
        else:
            # 非流式：一次返回完整结果
            resp = requests.post(url, json=payload, timeout=120)
            resp.raise_for_status()
            result = resp.json()
            return result.get("message", {}).get("content")

    except requests.exceptions.ConnectionError:
        print("❌ 连接失败：请确认 Ollama 服务已启动（ollama serve）")
    except requests.exceptions.Timeout:
        print("❌ 请求超时：模型推理时间过长，尝试减小上下文或换更小模型")
    except Exception as e:
        print(f"❌ 请求异常: {e}")

    return None


# 使用示例
if __name__ == "__main__":
    messages = [
        {"role": "system", "content": "你是一个Python专家，用代码示例回答问题。"},
        {"role": "user", "content": "如何读取CSV文件？给出两种方法。"}
    ]

    # 非流式调用
    result = chat_completion("qwen2.5:7b", messages, stream=False)
    if result:
        print("--- 非流式输出 ---")
        print(result)

    # 流式调用
    print("--- 流式输出 ---")
    chat_completion("qwen2.5:7b", messages, stream=True)

4.6.3 兼容 OpenAI 格式调用

Ollama 从 0.1.x 版本开始支持 OpenAI 兼容接口，已有 OpenAI 项目可以零改造切换：

from openai import OpenAI

# 指向本地 Ollama 服务
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # Ollama 不验证key，随便填
)

# 调用方式和 OpenAI 官方 SDK 完全一致
response = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "用一句话解释什么是量化"}
    ],
    temperature=0.7
)

print(response.choices[0].message.content)

工程决策：如果你的项目已经在用 OpenAI SDK，切换到本地 Ollama 只需改 base_url 和 model 两个参数，零代码改动。这使得本地测试和线上 API 之间的切换变得极其简单。

4.7 自定义模型：Modelfile 编写

Modelfile 是 Ollama 的核心定制能力，类似于 Dockerfile——通过声明式配置创建自定义模型。

4.7.1 Modelfile 基础结构

# Modelfile 基础语法
FROM qwen2.5:7b

# 设置系统提示词
SYSTEM """
你是一个资深的Python全栈工程师，擅长：
- 代码审查与重构
- 系统架构设计
- 技术方案评估
回答要求：
1. 先给结论，再展开分析
2. 代码示例必须完整可运行
3. 涉及性能问题时给出具体数据
"""

# 设置推理参数
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER top_k 40
PARAMETER num_ctx 4096
PARAMETER repeat_penalty 1.1

# 设置模板（控制对话格式）
TEMPLATE """{{- if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{- end }}
<|im_start|>user
{{ .Prompt }}<|im_end|>
<|im_start|>assistant
{{ .Response }}<|im_end|>"""

4.7.2 创建和运行自定义模型

# 从 Modelfile 创建模型
ollama create my-python-assistant -f Modelfile

# 运行自定义模型
ollama run my-python-assistant

# 查看自定义模型的 Modelfile
ollama show my-python-assistant --modelfile

创建完成后，执行 ollama list 查看本地模型列表，你会看到两个模型：

1
2
3

NAME                        ID              SIZE      MODIFIED
my-python-assistant:latest  a1b2c3d4e5f6    4.7 GB    10 seconds ago
qwen2.5:7b                  f8a9b0c1d2e3    4.7 GB    2 hours ago

⚠️ 重要说明：自定义模型与原始模型的关系

共用底层权重：my-python-assistant:latest 与 qwen2.5:7b 共用同一套底层模型权重文件，自定义模型并不会重复下载权重，也不会额外占用大量硬盘空间。

本质是别名打包：Ollama 的自定义模型本质上是复用本地已存在的基础模型权重，仅把你配置的系统提示词、推理参数、对话格式打包，生成一个全新的模型别名。

删除原始模型需谨慎：由于两个模型共用权重，如果你执行 ollama rm qwen2.5:7b 删除了原始模型，自定义模型 my-python-assistant 也将无法正常运行。如果确实需要删除原始模型，请确保没有其他自定义模型依赖它。

4.7.3 从本地 GGUF 文件导入模型

如果你已经下载了 GGUF 文件（比如从 HuggingFace 下载的），可以直接导入 Ollama：

# 创建 Modelfile，指向本地 GGUF 文件
FROM ./models/Qwen2.5-7B-Instruct-Q4_K_M.gguf

PARAMETER temperature 0.7
PARAMETER num_ctx 4096

TEMPLATE """{{- if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{- end }}
<|im_start|>user
{{ .Prompt }}<|im_end|>
<|im_start|>assistant
{{ .Response }}<|im_end|>"""

# 创建模型
ollama create my-local-qwen -f Modelfile

# 运行
ollama run my-local-qwen

注意：FROM 指令支持两种格式——FROM model:tag（从 Ollama 仓库拉取）和 FROM ./path/to/file.gguf（从本地文件导入）。本地文件路径支持相对路径和绝对路径。

4.7.4 实战：创建一个领域专属助手

# 金融分析助手 Modelfile
FROM deepseek-r1:7b

SYSTEM """
你是一位专业的金融分析师，具备以下能力：
- 财报解读与关键指标分析
- 行业趋势判断与投资逻辑梳理
- 风险评估与提示

回答规范：
1. 数据引用必须注明来源和时效
2. 给出明确结论和支撑逻辑
3. 风险提示不可遗漏
4. 不构成投资建议的声明
"""

PARAMETER temperature 0.3
PARAMETER top_p 0.85
PARAMETER num_ctx 8192
PARAMETER repeat_penalty 1.15

1 2	ollama create finance-analyst -f Modelfile ollama run finance-analyst

4.8 持久化配置

4.8.1 环境变量一览

环境变量	默认值	说明
`OLLAMA_HOST`	`127.0.0.1:11434`	服务监听地址
`OLLAMA_MODELS`	`~/.ollama/models`	模型存储路径
`OLLAMA_NUM_GPU`	自动检测	GPU 层数（-1=全部，0=仅CPU）
`OLLAMA_KEEP_ALIVE`	`5m`	模型卸载前的保活时间
`OLLAMA_DEBUG`	`false`	调试日志
`OLLAMA_FLASH_ATTENTION`	`false`	启用 Flash Attention

4.8.2 修改模型存储路径

默认模型下载到 ~/.ollama/models，如果你的 C 盘/系统盘空间不足：

Windows：

# 方法1：系统环境变量设置
[System.Environment]::SetEnvironmentVariable("OLLAMA_MODELS", "D:\ollama_models", "User")
# 重启 Ollama 服务生效

# 方法2：修改快捷方式启动参数
# 右键 Ollama 快捷方式 → 属性 → 目标
# 修改为："C:\Users\你的用户名\AppData\Local\Programs\Ollama\ollama app.exe"
# 在启动前设置环境变量

Linux：

# 方法1：systemd 服务配置
sudo systemctl edit ollama.service

# 添加：
[Service]
Environment="OLLAMA_MODELS=/data/ollama_models"

# 重启服务
sudo systemctl daemon-reload
sudo systemctl restart ollama

macOS：

# 方法1：launchctl 设置
launchctl setenv OLLAMA_MODELS /Users/你的用户名/ollama_models

# 重启 Ollama 应用

4.8.3 GPU 层数控制

Ollama 默认将所有模型层加载到 GPU。显存不足时可以控制 GPU 卸载层数：

# 方式1：环境变量（全局生效）
export OLLAMA_NUM_GPU=20      # 只把前20层放到GPU，其余走CPU

# Windows PowerShell
$env:OLLAMA_NUM_GPU = "20"

# 方式2：在 Modelfile 中指定
# PARAMETER num_gpu 20

工程决策：OLLAMA_NUM_GPU 是显存不足时的降级利器。比如 7B Q4_K_M 模型约 4.7GB，如果你的显存只有 6GB，把 GPU 层数从全部（约32层）减到 20 层，KV Cache 有更多空间，可以支持更长的上下文。

4.8.4 允许局域网访问

默认 Ollama 只监听本机。如果需要局域网其他设备访问：

# Linux（systemd 服务方式）
sudo systemctl edit ollama.service
# 添加：
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

# 重启
sudo systemctl daemon-reload
sudo systemctl restart ollama

# Windows（环境变量设置）
[System.Environment]::SetEnvironmentVariable("OLLAMA_HOST", "0.0.0.0:11434", "User")
# 重启 Ollama 服务

# macOS
launchctl setenv OLLAMA_HOST "0.0.0.0:11434"
# 重启 Ollama 应用

五、关键参数详解

5.1 推理参数一览

参数	默认值	作用	调优建议
`temperature`	0.8	控制随机性。0=确定性输出，越高越随机	事实性任务用 0.1-0.3；创意写作用 0.7-1.0
`top_p`	0.9	核采样：从概率累积前 top_p 的 token 中采样	0.9 适用于大多数场景；追求精确可降到 0.5
`top_k`	40	从概率最高的 top_k 个 token 中采样	40 是通用值；增大至 100 更多样，减小至 10 更精确
`num_ctx`	2048	上下文窗口大小（token数）	越大显存占用越高；短对话 2048 足够，长文档用 4096-8192
`num_gpu`	自动	卸载到 GPU 的层数	-1=全部GPU；0=纯CPU；显存不足时减小此值
`repeat_penalty`	1.1	重复惩罚系数	模型容易重复时调高（1.2-1.5）；正常保持 1.1
`num_predict`	128	最大生成 token 数	增大可生成更长回复（如 512、1024）；-1 为无限生成
`stop`	无	停止词列表	指定遇到哪些 token 停止生成，常用于格式化输出
`seed`	随机	随机种子	设定固定值可复现输出，用于调试和测试

5.2 参数调优实战场景

# 场景1：精确问答（RAG、知识提取）
PARAMETER temperature 0.1
PARAMETER top_p 0.5
PARAMETER num_predict 256

# 场景2：创意写作（文案、故事）
PARAMETER temperature 0.9
PARAMETER top_p 0.95
PARAMETER num_predict 1024

# 场景3：代码生成（编程助手）
PARAMETER temperature 0.2
PARAMETER top_p 0.85
PARAMETER repeat_penalty 1.2
PARAMETER num_predict 512

# 场景4：长文档总结
PARAMETER num_ctx 8192
PARAMETER temperature 0.3
PARAMETER num_predict 512

核心认知：temperature 是最关键的参数——它直接控制模型的”创造力”。所有其他参数都是在 temperature 基础上的微调。新手建议先调 temperature，不够再动 top_p 和 top_k。

六、踩坑记录 & 问题解决

6.1 模型下载慢/中断

症状：ollama pull 速度极慢或下载中途卡住。

解决方案：

# 方案1：设置代理（如果有）
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
ollama pull qwen2.5:7b

# Windows PowerShell
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
ollama pull qwen2.5:7b

# 方案2：使用国内镜像站
# 设置 OLLAMA_ORIGINS 允许从镜像拉取
export OLLAMA_ORIGINS="https://registry.ollama.ai"
# 如果有社区镜像，也可以尝试

# 方案3：手动下载 GGUF 后导入（最稳定）
# 从 HuggingFace 下载 GGUF 文件（使用 hf-mirror.com 加速）
# 然后用 Modelfile FROM ./path/to/model.gguf 导入

# 方案4：断点续传
# Ollama pull 支持断点续传，直接重新执行相同命令即可
ollama pull qwen2.5:7b  # 如果之前中断了，重新执行会继续下载

6.2 GPU 未被识别/未启用

症状：模型推理速度极慢（<5 tokens/s），nvidia-smi 显示 GPU 空闲。

排查步骤：

# 步骤1：确认 GPU 驱动正常
nvidia-smi
# 如果报错，说明驱动有问题

# 步骤2：查看 Ollama 日志
# Windows：打开 %LOCALAPPDATA%\Ollama\log 目录查看日志
# Linux：journalctl -u ollama --no-pager -n 50
# macOS：打开 Ollama 应用菜单 → View Log

# 步骤3：确认 Ollama 检测到 GPU
# 在日志中搜索 "GPU" 或 "CUDA" 关键词
# 正常情况应该看到类似：
# "using CUDA GPU 0: NVIDIA GeForce RTX 3060"

# 步骤4：如果日志显示 "fallback to CPU"
# 检查 NVIDIA Driver 版本是否 >= 450
# 检查是否误设了 OLLAMA_NUM_GPU=0

常见原因与解决：

原因	解决方案
NVIDIA 驱动过旧	更新驱动至 ≥ 525.x
`OLLAMA_NUM_GPU=0`	移除此环境变量或设为 -1
Linux 下未安装 NVIDIA CUDA 库	安装 `nvidia-cuda-toolkit` 或确保 `libcuda.so` 可访问
WSL2 下 GPU 直通未配置	参考 NVIDIA 官方 WSL2 配置指南
AMD 显卡（Linux）	安装 ROCm 驱动，Ollama 支持 AMD GPU（仅 Linux）

6.3 显存不足时的降级策略

症状：运行模型时报 CUDA out of memory 或系统内存占用飙升（CPU fallback）。

按优先级依次尝试：

# 1. 减小上下文长度
# 在 Modelfile 中：
PARAMETER num_ctx 2048    # 从默认降到 2048 或 1024

# 2. 减少 GPU 卸载层数
export OLLAMA_NUM_GPU=20  # 部分层走 CPU

# 3. 换用更小的量化版本
ollama pull qwen2.5:7b-q3_K_M   # 更激进的量化

# 4. 换用更小参数量的模型
ollama run qwen2.5:1.5b          # 从 7B 降到 1.5B

# 5. 使用 Flash Attention 减少显存占用
export OLLAMA_FLASH_ATTENTION=true

经验值：7B Q4_K_M 模型在 8GB 显存上，num_ctx=2048 可以稳定运行。如果 num_ctx=4096，需要约 10GB 显存。KV Cache 随上下文长度线性增长，是显存占用的”隐形杀手”。

6.4 Windows 下的常见权限问题

症状1：安装后 ollama 命令无法识别。

# 检查 PATH 环境变量
$env:PATH -split ";" | Select-String "Ollama"
# 如果没有，手动添加
$env:PATH += ";C:\Users\$env:USERNAME\AppData\Local\Programs\Ollama"
# 持久化：
[System.Environment]::SetEnvironmentVariable(
    "PATH",
    [System.Environment]::GetEnvironmentVariable("PATH", "User") +
    ";C:\Users\$env:USERNAME\AppData\Local\Programs\Ollama",
    "User"
)

症状2：模型文件存放在 C 盘，空间不够。

# 修改模型存储路径（见4.8.2节）
[System.Environment]::SetEnvironmentVariable("OLLAMA_MODELS", "D:\ollama_models", "User")
# 重启 Ollama 后生效
# 之前已下载的模型需要手动迁移或重新拉取

症状3：Windows 防火墙阻止局域网访问。

1 2	# 添加防火墙入站规则 New-NetFirewallRule -DisplayName "Ollama" -Direction Inbound -Protocol TCP -LocalPort 11434 -Action Allow

6.5 多模型切换时的内存管理

问题：运行多个模型时，显存/内存不够用。

关键机制：Ollama 有模型保活机制——模型加载后不会立即卸载，而是保持 OLLAMA_KEEP_ALIVE（默认5分钟）后再释放。

# 调整保活时间
# 设置较短保活，快速释放显存
export OLLAMA_KEEP_ALIVE=2m    # 2分钟后卸载

# 或设为 0，用完立即卸载（牺牲下次启动速度）
export OLLAMA_KEEP_ALIVE=0

# 手动卸载所有模型（停止 Ollama 服务）
# Windows：右键托盘图标 → Quit Ollama
# Linux：sudo systemctl restart ollama
# macOS：关闭 Ollama 应用

# 查看当前内存占用
# Linux
nvidia-smi  # 查看GPU显存
free -h     # 查看系统内存

工程建议：如果你的显卡显存 ≤ 8GB，同一时间只运行一个模型。切换模型时等前一个模型卸载完成再启动新的。多模型并发是大显存（24GB+）的特权。

七、场景适配 & 优劣分析

7.1 Ollama 适合的场景

场景	说明	推荐配置
快速原型验证	一条命令跑起模型，API 开箱即用	7B Q4_K_M
个人 AI 助手	本地对话，隐私安全，零费用	7B Q4_K_M + 自定义 system prompt
轻量 API 服务	内部工具、小团队使用，低并发	Ollama + OpenAI 兼容接口
学习与测试	对比不同模型效果，理解推理参数	多个7B模型
本地 RAG 系统	结合 LangChain/LlamaIndex，本地知识库	7B + nomic-embed-text
开发调试	替代 OpenAI API 做本地开发调试	OpenAI 兼容接口

7.2 Ollama 不适合的场景

场景	原因	替代方案
高并发生产服务	单进程架构，并发能力有限	vLLM（PagedAttention，吞吐量 20x+）
极致推理性能	llama.cpp 封装有额外开销	直接用 llama.cpp 编译优化 / vLLM
自定义推理管线	无法修改推理流程（如自定义采样策略）	HuggingFace Transformers + vLLM
GPTQ/AWQ 格式模型	仅支持 GGUF 格式	vLLM（原生支持 AWQ/GPTQ）
模型微调	Ollama 是推理框架，不支持训练	transformers + peft + CUDA
多卡张量并行	不支持模型切分到多张 GPU	vLLM（tensor_parallel_size）

7.3 与其他框架的定位区分

易用性维度：  Ollama >>> Text Gen WebUI > FastChat > llama.cpp >>> vLLM
性能维度：    vLLM >> llama.cpp > FastChat ≈ Ollama > Text Gen WebUI
灵活性维度：  llama.cpp > vLLM > Text Gen WebUI > FastChat > Ollama
生产可用性：  vLLM > FastChat > Ollama > Text Gen WebUI > llama.cpp

一句话定位：

Ollama = 快速上手，开发调试首选
llama.cpp = 极致控制，低配环境之王
vLLM = 生产部署，高并发性能天花板

工程决策：不要纠结”最好的框架”，而是问”当前场景最合适的框架”。项目初期用 Ollama 快速验证 → 需要性能时切 vLLM → 低配环境用 llama.cpp。三个框架可以共存，按场景切换。

八、本篇小结

核心知识点复盘

Ollama 架构：C/S 模式，ollama serve 后台服务 + CLI/HTTP/Python 多种客户端
底层引擎：基于 llama.cpp，自动选择 GPU/CPU 推理后端
“一键”本质：预打包 GGUF 模型 + 自动硬件检测 + 合理默认参数
三种调用方式：命令行交互、HTTP API（curl）、Python SDK（ollama 库 / requests / OpenAI 兼容）
Modelfile 定制：FROM 基础模型 + SYSTEM 提示词 + PARAMETER 参数 + TEMPLATE 模板
关键参数：temperature 控制创造性、num_ctx 控制上下文长度、num_gpu 控制 GPU 层数
降级策略：减小 num_ctx → 减少 num_gpu → 换更小量化 → 换更小模型

关键命令速查表

# ===== 安装与验证 =====
ollama --version                       # 查看版本
ollama serve                           # 启动服务

# ===== 模型管理 =====
ollama pull qwen2.5:7b                 # 拉取模型
ollama run qwen2.5:7b                  # 运行模型（交互式）
ollama run qwen2.5:7b "你好"           # 单次提问
ollama list                            # 列出本地模型
ollama rm qwen2.5:7b                   # 删除模型
ollama show qwen2.5:7b                 # 查看模型信息
ollama cp qwen2.5:7b my-qwen          # 复制模型

# ===== 自定义模型 =====
ollama create my-model -f Modelfile    # 从 Modelfile 创建
ollama show my-model --modelfile       # 查看 Modelfile

# ===== API 调用 =====
curl http://localhost:11434/api/tags   # 查看模型列表
curl http://localhost:11434/api/chat -d '{...}'   # Chat 接口
curl http://localhost:11434/api/generate -d '{...}'  # Generate 接口
curl http://localhost:11434/api/embed -d '{...}'     # Embed 接口

# ===== 环境变量 =====
OLLAMA_HOST=0.0.0.0:11434              # 监听地址
OLLAMA_MODELS=/data/ollama_models      # 模型存储路径
OLLAMA_NUM_GPU=20                      # GPU 层数控制
OLLAMA_KEEP_ALIVE=5m                   # 模型保活时间
OLLAMA_FLASH_ATTENTION=true            # Flash Attention

Python 调用速查

# 官方 SDK
import ollama
response = ollama.chat(model="qwen2.5:7b", messages=[...])

# OpenAI 兼容
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
response = client.chat.completions.create(model="qwen2.5:7b", messages=[...])

本文为「本地大模型部署系列」第3篇，完整系列持续更新中。