这两年只要一聊到本地大模型，Ollama 基本是绕不开的关键词。我一开始也不太理解，明明写 Python 也能加载模型，为什么还要多套一层工具？真正上手后才发现，Ollama 干的不是“又多一个框架”这种事，而是把模型下载、管理、推理、服务化打包成了一套很顺手的命令行体验。这篇笔记记录了我从安装到接入业务脚本的完整过程，包含环境变量、参数调优和若干次翻车实录。如果你手头有一台普通电脑，哪怕是显存不大甚至只有纯 CPU 的机器，也想把开源模型真正跑起来，那这份安装配置教程可以直接照着抄。
1. 快速认识 Ollama：它到底解决了什么实际问题
1.1 为什么选择本地部署而不是直接调 API
本地部署最大的理由其实就三个：隐私、成本、可控性。把数据发给云端接口，虽然在大多数场景下没啥问题，但你自己项目的内部文档、客户数据、甚至早期探索性的 Prompt 内容，一旦出了机器就很难追溯。而 Ollama 启动的模型完全跑在本地，没有上传过程，适合离线网络环境，也适合对数据敏感的开发场景。
成本上也可以算一笔账。高频调用云端接口，每个月账单会稳定增长；而本地模型是一次性硬件投入，只要机器不换，跑多少次都是同样的电费。网络波动、接口限流、版本更新导致的返回格式变化，这些外部依赖在本地部署里都不存在。我用一个家常类比来理解：调云端 API 像每次用水都从自来水公司买水，本地跑模型就像自己院子里打了一口井，前期挖井费工夫，但之后用水不花钱、不限量、不受停水影响。
1.2 Ollama 的核心机制：一个工具集合体
Ollama 最吸引人的地方，是它把四件事打包在了一起：
- 模型下载与管理：
ollama pull能直接从模型仓库拉取，不需要自己找权重文件解压； - 推理运行时：内置了推理引擎，不用手动装 PyTorch、CUDA 环境，开箱即跑；
- 命令行交互：
ollama run直接进聊天界面； - HTTP 服务：默认在 11434 端口起一个接口，支持
/api/chat、/api/generate等路径，也兼容许多常见接口格式。
模型文件的底层格式是 GGUF 量化文件。不需要深入理解它，只需要记住一个结论：同样是 7B 参数的模型，发布方原始权重可能是 16GB，量化成 Q4_K_M 之后通常只有 4GB 到 5GB。量化本质上就是把浮点数参数的精度降低来换取体积和显存占用，代价是推理质量有微小损失，但对日常问答、摘要、代码生成来说基本感觉不到。所以 Ollama 模型名字里的7b和实际占用硬盘大小千万别直接画等号，得看具体标签。
2. 安装部署：从零把服务跑起来
2.1 Windows 和 macOS：图形化安装后验证
Windows 和 macOS 的安装方式最省事：到 Ollama 官网下载对应安装包，双击安装。macOS 是标准的 .dmg 拖拽安装，Windows 是 .exe 安装向导，一路下一步就行。装完以后最重要的一步是验证环境变量是否生效，建议重新开一个终端窗口再执行：
ollama -v看到版本号就说明安装成功。如果提示“不是内部或外部命令”，先检查系统环境变量里有没有把安装目录加进 PATH，没加上就手动加一下，或者干脆重新登录系统再试。
验证完版本，直接跑第一个模型：
ollama run qwen2.5:7bOllama 会自动拉取模型，拉取完成进入会话后输入“你好”之类的内容测试。这一步能通过，说明安装和基础推理链路都没问题。Windows 上安装完以后 Ollama 服务默认是后台运行的，托盘区会出现一个小图标，不需要每次手动启动。
2.2 Linux 服务器：命令行安装与服务管理
Linux 上用脚本安装最方便：
curl -fsSL https://ollama.com/install.sh | sh脚本会自动下载二进制、创建ollama用户、配置 systemd 服务。装完以后：
systemctl status ollama看到active (running)就说明服务起来了。如果没自动启动，手动执行sudo systemctl start ollama，开机自启用sudo systemctl enable ollama。这一步很多教程不提，但服务器重启后发现 Ollama 连不上，多半就是 enable 这步漏了。
Linux 安装前还有一件小事值得做：检查显卡驱动。用nvidia-smi看一眼，能显示出显卡信息说明驱动正常。Ollama 只认驱动层，不认你之前装没装过深度学习框架，所以驱动是硬门槛。如果驱动没装好，后文会提到，一切运行都会变成 CPU 龟速模式。
某些精简系统或 ARM 设备上，脚本安装可能会失败。这时候可以下载官方编译好的二进制手动部署，解压到/usr/local/bin之类目录，再用 systemd 管理。手动部署的目录权限要注意，别让服务以 root 身份运行。
2.3 Docker 部署：适合隔离环境
如果不想在宿主机上装一堆东西，Docker 是另一个干净方案：
docker run -d --name ollama \ -v /opt/ollama:/root/.ollama \ -p 11434:11434 \ ollama/ollama-v把模型目录映射到宿主机的/opt/ollama，这样容器重建后模型还在，不用二次下载。映射端口是关键，只映射不指定 host 端口也行，但建议显式写出来。想用 GPU 时加一行--gpus all，然后给容器安装对应显卡运行时组件。这套组合在隔离网络、需要随时重置环境的场景下特别好用。
原生安装和 Docker 部署怎么选，我给个判断逻辑：个人开发机、长期使用、想图形化管理，用原生安装；临时体验、多环境切换、害怕依赖污染系统，用 Docker。我自己的主力机器用 Docker 跑服务端，但 CLI 工具还是用原生的，两者互不冲突。
2.4 安装后的环境检查清单
跑模型之前先花两分钟做环境自检，省得后面排查半天。我会依次确认这四件事：
- 磁盘空间是不是够：一个 7B 模型普遍要 4GB 以上，32B 模型可能要 20GB 以上；
- 显存有没有被其他程序占了：浏览器开了几十个标签页、后台跑着训练任务，显存就没剩多少了；
- Ollama 服务是否在监听：浏览器打开
http://localhost:11434，能看到 “Ollama is running” 类似的提示； - 终端里执行
ollama ps能否正常显示为空列表。
前三项都过了，基本不会遇到安装层面的幺蛾子。
3. 模型选择与模型管理：别只会跑一个默认模型
3.1 主流模型怎么选，尺寸怎么定
Ollama 虽然是“一条命令拉模型”，但模型仓库里各种名字很多，随手乱拉既占硬盘又占显存。我平时主要看几类：
- qwen2.5 系列：中英文混合表现稳定，7B 和 14B 都适合入门；
- llama3.1 系列：英文生态、推理、代码能力均衡，8B 是经典入门选择；
- gemma2 系列：轻量风格，9B 在消费级显卡上比较友好；
- mistral 系列：响应速度快，适合搭对话机器人；
- phi3 系列：小参数，纯 CPU 机器也能扛一下。
选择时不要只盯着参数看，量化版本更重要。拿 7B 模型举例，完整精度可能占十几个 GB，Q4 量化后只要 4GB 到 5GB 显存。显存 8GB 的机器，跑 7B 量化版比较舒服；显存 16GB 可以尝试 14B 甚至 32B，但如果还要同时处理长文本，容量会变得紧张。
我用一句经验总结：显存里能放得下模型，才有流畅体验；放不下就会有一部分层跑在 CPU 和内存上，生成速度会明显掉一截。所以入门阶段别贪大，Q4 量化模型的体验足够日常使用。
3.2 拉取、运行、查看、删除模型
这四个命令是天天都在用的：
# 拉取模型，等同于 run 时自动下载 ollama pull qwen2.5:7b # 进入交互对话 ollama run qwen2.5:7b # 查看本地已有模型 ollama list # 查看当前加载在内存/显存里的模型 ollama ps # 删除不需要的模型 ollama rm qwen2.5:7bollama ps很容易被忽略，但它对排查性能问题特别有用。它显示每个模型占用的 processor 类型是 GPU 还是 CPU，以及保持加载的时间。我发现模型响应变慢时，第一件事就是执行ollama ps，看模型是不是已经被换出到 CPU。
交互模式下输入/bye退出，不会结束服务。如果想一次性传问题，用ollama run qwen2.5:7b "请写一段排序代码"这种非交互方式也是可以的。对于脚本，直接调 API 更合理，后面专门讲。
3.3 模型存储路径与自定义 Modelfile
Ollama 默认把模型存放在用户主目录下的.ollama/models。Linux 就是~/.ollama/models，Windows 是%USERPROFILE%\.ollama\models。如果系统盘不够大，这个目录一定要挪走，挪法很简单：设置环境变量OLLAMA_MODELS指向新路径，然后重启 Ollama 服务。提醒一下：已经下载好的模型不会自动搬家，要手动移动旧目录内容，或者干脆重新拉一遍。
Ollama 允许用 Modelfile 定制模型行为。Modelfile 类似 Dockerfile，是一个纯文本配置。我给了个简单示例：
FROM qwen2.5:7b PARAMETER temperature 0.7 PARAMETER num_ctx 4096 SYSTEM 你是一个严谨的中文技术助手，回答要简洁、有条理。保存为Modelfile后，执行ollama create my-assistant -f Modelfile就能生成一个新模型。这一步最大的价值是团队可以共用同一个系统提示词和参数集合，不用每次对话都在 API 请求里重复传。
4. 性能与配置优化：把硬件潜力尽量挖出来
4.1 环境变量是调优的主入口
Ollama 的默认参数对很多机器是偏保守的，不一定吃满硬件。想调优，先认识几个核心环境变量：
| 环境变量 | 作用 | 我的常用值 |
|---|---|---|
OLLAMA_HOST | 监听地址和端口 | 0.0.0.0:11434允许局域网访问 |
OLLAMA_MODELS | 模型存放路径 | 指向大容量磁盘 |
OLLAMA_NUM_PARALLEL | 并行处理请求的数量 | 小显存 1，大显存 2 或 4 |
OLLAMA_MAX_LOADED_MODELS | 同时保持加载的模型数量 | 内存紧张时设 1 |
OLLAMA_KEEP_ALIVE | 模型保持加载的时间 | 5m 或 -1 |
OLLAMA_CONTEXT_LENGTH | 默认上下文长度 | 默认 2048，按需调大 |
Windows 配置环境变量的标准路径是：右键“此电脑”→“属性”→“高级系统设置”→“环境变量”，新建一个系统变量。Linux 原生安装时，如果用了 systemd，推荐通过 override 文件配置：
sudo mkdir -p /etc/systemd/system/ollama.service.d sudo tee /etc/systemd/system/ollama.service.d/override.conf << 'EOF' [Service] Environment="OLLAMA_HOST=0.0.0.0:11434" Environment="OLLAMA_MAX_LOADED_MODELS=1" Environment="OLLAMA_KEEP_ALIVE=-1" EOF sudo systemctl daemon-reload sudo systemctl restart ollama改完配置文件必须重启服务才生效，这是一个非常容易踩的坑。用docker run时则通过-e参数传进来，比如-e OLLAMA_KEEP_ALIVE=-1。
4.2 显存、内存与上下文长度怎么换算
上下文长度是很多人忽视的显存大户。模型文件本身占一块显存，推理时的 KV Cache（可以理解为模型在回答过程中临时保存的“工作笔记”）也会随上下文长度增长。上下文越长，这个“工作笔记”越大。
一个粗略的估算：7B 量化的模型文件约 4GB 到 5GB，上下文 2048 时 KV Cache 额外占用大约 1GB 左右；上下文拉到 8192，KV Cache 可能到 2GB 以上。所以 8GB 显存的机器，跑 7B 模型时把上下文从默认的 2048 拉到 4096 还可以接受，再往上就容易出现显存不足，Ollama 会把部分层切到 CPU，生成速度瞬间变慢。
还有个容易翻车的点是多个模型同时加载。默认情况下 Ollama 允许同时保持加载多个模型，这会导致显存和内存迅速吃紧。我自己吃过这个亏：先后跑了 7B 和 14B 两个模型，机器开始疯狂换页，UI 都卡成了幻灯片。后来把OLLAMA_MAX_LOADED_MODELS设为 1，一个模型用完自动卸载，世界清净多了。
4.3 四套可直接抄的配置模板
不同硬件环境，我推荐下面四种配置模版。不需要照抄全部，按需挑选即可。
先看 8GB 显存日常使用版：
OLLAMA_NUM_PARALLEL=1 OLLAMA_MAX_LOADED_MODELS=1 OLLAMA_KEEP_ALIVE=5m OLLAMA_CONTEXT_LENGTH=4096模型选 qwen2.5 或 llama3.1 的 7B/8B 量化版。并行度拉满没有意义，一次干好一件事更重要。
16GB 显存进阶版：
OLLAMA_NUM_PARALLEL=2 OLLAMA_MAX_LOADED_MODELS=2 OLLAMA_KEEP_ALIVE=10m OLLAMA_CONTEXT_LENGTH=8192可以尝试 14B 模型。并行 2 适合同时处理多个请求，但注意单线程的生成速度不会因为并行而变快，只是吞吐量提升。
纯 CPU 小内存版：
OLLAMA_NUM_PARALLEL=1 OLLAMA_MAX_LOADED_MODELS=1 OLLAMA_CONTEXT_LENGTH=2048模型选 3B 到 4B 的小尺寸量化版。纯 CPU 推理速度慢是客观事实，小模型是保证体验的唯一出路。
内网服务版：
OLLAMA_HOST=0.0.0.0:11434 OLLAMA_KEEP_ALIVE=-1局域网内多台设备访问一台机器时，KEEP_ALIVE=-1能让模型常驻，避免每次请求都经历重新加载的等待。内网部署时建议加一层防火墙或接口鉴权，毕竟模型服务没有自带的用户体系。
5. 把模型接到业务脚本与网页上
5.1 用 Python 请求快速调通接口
Ollama 默认的/api/chat接口很适合快速集成。我会先用requests做一个最小验证：
import requests url = "http://localhost:11434/api/chat" payload = { "model": "qwen2.5:7b", "messages": [ {"role": "user", "content": "用一句话解释什么是本地大模型"} ], "stream": False } resp = requests.post(url, json=payload) data = resp.json() print(data["message"]["content"])这个请求不会阻塞太久，因为模型已经加载过了。如果需要流式输出，把"stream": False改成True，然后一行行读取返回内容。流式响应在我的经验里对 Web 应用的体验提升巨大，用户不用干等全部生成完。需要注意：接口返回结构里，正文内容是message.content，不是包在最外层的response字段。我用/api/generate时偶尔会混，两个接口的返回结构不一样。
5.2 兼容接口和 Web 界面
Ollama 还提供了/v1/chat/completions这类常见兼容路径，很多现成的客户端库可以直接指向它。对大多数开源生态来说，这意味着不用写太多胶水代码，把 base_url 改成http://localhost:11434/v1就能用上。
想要图形界面，我试过几个方案，最顺手的是 Open WebUI。Docker 部署命令大概是：
docker run -d --name open-webui \ -p 3000:8080 \ -v /opt/open-webui:/app/backend/data \ --add-host=host.docker.internal:host-gateway \ ghcr.io/open-webui/open-webui:main启动后浏览器访问http://localhost:3000，在设置里把 Ollama 服务地址填成http://host.docker.internal:11434，就能在页面上选择模型对话。注册账号之后注意默认不需要给每个用户授权，如果团队使用，建议在设置里打开用户审核，避免所有人都能在模型上下载和删除东西。
5.3 接进常见编排框架
如果项目本身依赖 Agent 编排框架，Ollama 也有现成集成。拿 Python 生态举例，用官方 SDK 是最省心的：
import ollama response = ollama.chat( model="qwen2.5:7b", messages=[{"role": "user", "content": "总结这段日志里的异常"}] ) print(response["message"]["content"])SDK 会把 HTTP 细节封装掉。用其他框架时，一般只要关心两件事：设置正确的 base_url，以及确认模型名称已经 pull 到本地。我经常踩的坑是框架配置写成了云端模型名，本地根本没有对应模型，然后会收到 model not found，这个问题下一节专门说。
6. 高频问题排查实录：我踩过的坑都在这里
6.1 模型下载慢、中断、校验失败怎么办
现象大多是ollama pull长时间卡在下载百分比不动，或者跑到一半进度跳红。最直接的原因是网络波动，模型文件动辄几个 GB，连接稍微不稳就会中断。
我的处理建议是这样的：
- 先确认磁盘空间充足，针对大模型尤其重要；
- 中断后重新执行
ollama pull，通常可以基于已有部分继续，尽量不要手动删除下载目录，否则就是彻底从头开始； - 换一个网络环境再试，或者避开联网高峰；
- 如果下载到一半失败，可以看看模型下载目录有没有临时文件残留，有的话先确认不是完整权重再清理。
另外我把OLLAMA_MODELS指到了机械硬盘上，结果模型加载速度也变慢了。后来才发现闪存文件和权重都在同一个盘，读写瓶颈会影响冷启动。建议把 Ollama 放固态盘上，尤其是要跑 14B 以上的模型的时候。
6.2 GPU 不识别、显存不够、被迫 CPU 跑
明明有显卡，跑起来却慢得离谱，这是最常见的困惑。打开任务管理器发现 GPU 使用率只有个位数而 CPU 飙满，基本可以判断模型没跑在 GPU 上。
排查顺序比较固定：
- 显卡驱动是否正常：执行
nvidia-smi，能显示驱动和显存信息才行； - Ollama 服务是否是在驱动安装后重启的：先改驱动后起服务这种顺序经常踩坑；
- Docker 环境是否真的启用了 GPU runtime：容器里执行
nvidia-smi验证； - 模型是否太大，无法完全放入显存：Ollama 会自动把放不下的层切到 CPU，日志里会提示部分层使用 CPU。
如果模型勉强超出显存容量，复现时频繁出现“Error: model requires more memory”提示，我的优化顺序是：换更小的模型→换 Q4 量化版→调低上下文长度→关掉其他占显存软件。如果还不行，就接受 CPU 推理，反正本地模型胜在离线可用，速度慢一点也能忍。
6.3 API 报错、端口占用、服务崩了怎么办
API 调用报错原因很集中，我整理过一份速查表：
| 报错现象 | 可能原因 | 处理办法 |
|---|---|---|
| 404 Not Found | API 路径写错了 | 确认是/api/chat还是/v1/chat/completions |
| model "xxx" not found | 本地没有该模型 | 先ollama pull xxx或ollama run xxx |
| Connection refused | Ollama 服务没启动 | 启动服务，执行ollama serve或 systemctl 启动 |
| Port already in use | 11434 被其他进程占用 | 换端口OLLAMA_HOST=0.0.0.0:11435，重启服务 |
| 响应空白或卡住 | 模型正在加载冷启动 | 查看ollama ps，看是否已经有模型在加载 |
端口占用时我一般用lsof -i :11434看谁占了端口，确认后换到 11435。还有个比较隐蔽的问题：改了OLLAMA_HOST后忘记重启服务，表面上配置变了，实际上监听地址没变，所有局域网请求全打不进来。配置环境变量之后，无一例外重启一次。
服务崩溃时用日志定位最省时间。原生部署直接看journalctl -u ollama -f --no-pager，容器环境用docker logs ollama。日志里如果出现显存分配失败的记录，十有八九是模型太大或上下文太长。
写在最后的几点实战体会
真正常踩完这些坑之后，我最大的感受是：本地大模型的价值不在于跑出一个漂亮的参数，而在于能稳稳地把模型接入自己的工具链。显存紧张的时候，我宁可选择更小量化的模型，也不要硬上一个把内存打满的大家伙，因为推理速度掉下来之后，体验是灾难级的。
先把环境变量一次配到位，再把 Web 界面或者脚本调通，最后根据实际使用再决定升不升级更大的模型。这个路径对大多数需求都成立。如果你后续想扩展，还可以考虑多模型分工、按场景切换、引入 RAG 给模型外挂知识库，但这都是跑通基础之后的事了。Ollama 真正的门槛不在安装那一瞬间，而在每天使用它时，你是否清楚自己的硬件边界在哪里。
