简介：面向希望把大语言模型运行在自有硬件上的开发者、研究者与NLP爱好者，这份PDF围绕云端服务带来的数据隐私、安全与响应速度问题，系统梳理开源工具Ollama的定位、安装与使用路径，适合需要保障敏感信息安全、提升响应时效的读者。正文从一键安装和简单命令运行模型讲起，说明模型权重、配置与数据如何打包管理，覆盖Llama 2、Code Llama、Mistral、Gemma等模型支持，并展开Modelfile自定义、Windows/macOS/Linux跨平台运行、与LangChain集成等关键能力，同时对比vLLM、Hugging Face在本地部署场景下的差异。应用部分结合聊天机器人、文本生成、智能问答等案例，帮助读者理解从环境准备到服务搭建的整体流程。资源包共1个PDF文件，大小约735KB，篇幅紧凑，便于集中阅读和选型参考。已有485人学习，可作为快速了解Ollama特性、适用边界与落地思路的入门材料。

1. 版本与服务端口：先弄清 Ollama 装的到底是什么

有个开发者找我，说他照着教程敲了一行ollama run llama2，机器是 8G 内存的轻薄本，没有独显。回车之后终端开始滚下载进度，滚到一半风扇狂转，桌面直接卡死，最后只能长按电源。他以为是 Ollama 有问题，其实是没人告诉他run会先自动pull，也没人告诉他llama2这个标签默认落下来的是什么量化级别的权重。Ollama 干的事不复杂：把大模型权重、配置和对话模板打包成一份 Modelfile，在本机拉起一个常驻推理服务，让本地化运行大模型这件事变成一条命令。但恰恰是「一条命令」这四个字，最容易让人放下戒心，跳过装之前该盘的那些东西——磁盘够不够、显存有没有、11434 端口通不通、模型默认往哪个目录躺。这篇按我自己的装机顺序走一遍，从环境盘点、三平台安装、参数配置，一路写到装完怎么验证，中间穿插几个真踩过的坑。

2. 装前盘环境：磁盘、显存、端口各留多少

装 Ollama 本身只要几分钟，真正决定这套环境能不能长期跑下去的，是装之前的三个数：可用磁盘、可用内存或显存、以及 11434 端口有没有被别人占。我见过太多人卡在「装完了但跑不起来」，回头一查，全是这三件事没提前看。这一章把对照表和两个必改变量先摆出来，后面安装的时候就不用返工。

2.1 系统版本与硬件底线对照

不同平台对 Ollama 的支持程度差别挺大，尤其是加速这块。Apple Silicon 的 Mac 走 Metal，开箱就有 GPU 加速；Intel 芯片的 Mac 只能纯 CPU 推理，同一个 7B 模型速度差好几倍。Linux 上 NVIDIA 显卡要靠驱动加 CUDA 运行时，安装脚本会尝试帮你装依赖，但驱动版本太老它也没辙。Windows 目前还是预览版，能跑，但别指望和 Linux 一样稳定。

内存这块按经验给个粗略对照，4bit 量化之后大致是这么个体量，实际会随模型结构和上下文长度浮动：

注意：显卡显存不够的时候，Ollama 会把一部分层放到内存里跑，看起来「能用」，但速度掉得厉害。8G 显存跑 13B，大概率是这个下场。

2.2 端口和模型目录：两个最该提前改的变量

Ollama 默认监听127.0.0.1:11434，模型默认落在当前用户主目录下的.ollama/models。前者意味着只有本机能调 API，后者意味着模型全堆在系统盘。装完再改当然也行，但模型已经下了一半再挪，多多少少会出问题，常见做法是装之前就把这两个环境变量定好。

# 模型目录挪到大盘，别让系统盘被几十 G 权重撑爆 export OLLAMA_MODELS=/data/ollama/models # 监听地址，127.0.0.1 只允许本机访问 # 想给局域网其他机器调，改成 0.0.0.0:11434 export OLLAMA_HOST=127.0.0.1:11434

OLLAMA_MODELS的路径必须提前创建好，并且确保运行服务的用户对这个目录有读写权限，否则服务起来之后拉模型会直接报权限错误。OLLAMA_HOST的值格式是主机:端口，只写:11434在部分版本里也能识别，但为了可读性还是写全。把监听地址改成0.0.0.0之前先想清楚，Ollama 默认没有任何鉴权，等于谁连上谁就能用你的机器跑推理。

提示：export只在当前 shell 会话里有效，关掉终端就没了。要让它长期生效，要么写进~/.bashrc，要么写进 systemd 的 Environment，后者更靠谱，第 3 章会讲。

2.3 裸装还是容器：Docker 方式的取舍

如果机器上本来就有一堆容器在跑，用 Docker 方式装 Ollama 更省心，至少不用管二进制放哪、服务怎么注册。GPU 直通需要先装好nvidia-container-toolkit，否则容器里看不到显卡，只能 CPU 硬扛。

docker run -d --gpus=all \ -v /data/ollama:/root/.ollama \ -p 11434:11434 \ --name ollama \ ollama/ollama

--gpus=all是 GPU 直通开关，没有 NVIDIA 显卡就整行删掉。-v那行是模型目录的卷映射，这一步千万别省，否则容器一删，几十 G 权重跟着一起没。-p决定端口映射，如果宿主机 11434 已被占用，改成-p 11435:11434，那外面调用时就得用 11435。

裸装和容器的差别，实际用起来主要在这几点：裸装的 systemd 服务开机自启、日志好查、GPU 直通不需要额外配置；容器适合已经在用 compose 管服务、想统一升级回滚流程的场景。个人机器我一般裸装，多人共用的开发机我倾向容器，好隔离。

3. 三平台安装：从安装包到 ollama --version

安装这一步其实短，但每个平台都有它自己的怪脾气。Linux 的一键脚本会替你做一堆决定，搞清楚它改了什么，后面出问题才知道从哪查；macOS 两条安装路径混着装会互相抢服务；Windows 预览版的 PATH 问题几乎人人遇到一次。这章按平台分开写，每段都落到能直接执行的命令上。

3.1 Linux：一键脚本到底动了哪些东西

最省事的方式是官方给出的一键脚本，一条命令下去，下载、安装、注册服务、拉起进程全干完了。

# 下载并执行官方安装脚本，自动装依赖、建 ollama 用户、注册 systemd 服务 curl -fsSL https://ollama.com/install.sh | sh

这条命令背后做的事比看上去多：按 CPU 架构选对应二进制包、解压到/usr/local/bin、创建ollama系统用户和用户组、写/etc/systemd/system/ollama.service、检测 NVIDIA 显卡并尝试安装 CUDA 相关依赖、最后把服务启起来。所以跑完之后systemctl status ollama应该是 active 状态，不需要你再手动启动。

生产机上我不太建议直接把远程脚本管道给 sh，先落盘看一眼内容更稳妥：

# 先下载脚本，人工过一遍再执行 curl -fsSL https://ollama.com/install.sh -o install.sh less install.sh sh install.sh

如果是完全离线的机器，就没法用脚本了，得手动下二进制包。包解压出来是一个bin/ollama加一组库文件，解压到/usr下面之后，ollama命令就在 PATH 里了：

# 解压手动下载的二进制包，-C 指定根目录，直接把 bin 和 lib 放到位 sudo tar -C /usr -xzf ollama-linux-amd64.tgz # 验证命令是否可用 which ollama && ollama --version

手动装完不会自动有 systemd 服务，得自己写一个，下一节给完整的 unit 文件。

3.2 手写 systemd 服务：把启动参数固定下来

一键脚本生成的 service 文件里环境变量是空的，模型目录和监听地址都走默认值。想改，可以直接编辑那个文件，也可以用一个更规范的做法——放一个 override 配置覆盖掉，升级的时候不会被冲掉。下面这份是我自己常用的完整 unit，适合手动装的场景：

[Unit] Description=Ollama Service After=network-online.target [Service] Type=simple User=ollama Group=ollama # 这三个环境变量决定了模型存哪、服务听哪个地址、模型加载后驻留多久 Environment="OLLAMA_MODELS=/data/ollama/models" Environment="OLLAMA_HOST=127.0.0.1:11434" Environment="OLLAMA_KEEP_ALIVE=30m" ExecStart=/usr/local/bin/ollama serve Restart=always RestartSec=3 [Install] WantedBy=multi-user.target

OLLAMA_KEEP_ALIVE这个参数容易被忽略，它控制模型加载进显存后驻留多久，默认只有 5 分钟，超时就卸载。频繁调 API 的场景下每次都要重新加载模型，第一次响应会慢好几秒，调到30m或者-1（永不卸载）能明显改善体验，代价是显存一直被占着。

写完文件之后要让 systemd 重新读一遍配置，再设成开机自启：

# 重新加载 unit 配置，启用并立即启动服务 sudo systemctl daemon-reload sudo systemctl enable --now ollama # 看服务状态和实时日志 systemctl status ollama journalctl -u ollama -f

注意：User=ollama意味着进程以 ollama 用户身份跑，/data/ollama/models这层目录的属主必须改成它，否则拉模型时写文件会失败。

# 递归改属主，让 ollama 用户能写模型目录 sudo chown -R ollama:ollama /data/ollama

3.3 macOS：dmg 和 brew 别混着装

Mac 上有两条路。一条是官网下载 dmg，拖进 Applications，装完菜单栏会多一个羊驼图标，服务已经在后台跑着了；另一条是brew install ollama，装完是个命令行工具，得自己ollama serve。

# Homebrew 方式安装 brew install ollama # 前台启动服务，调试阶段用这个能看到完整日志 ollama serve

这两条路不能同时走。我见过有人 dmg 装了一份，后来又 brew 装了一份，结果 11434 端口被先起的那个占着，后起的报address already in use，而他又不知道是谁占的。查起来就一条命令：

# 看谁占着 11434 lsof -i :11434

dmg 版适合只想要个能用的大模型的人，双击装完直接用。brew 版适合本来就用 Homebrew 管软件、想统一升级的人。两者选一个就行，别贪。macOS 的日志位置和 Linux 不一样，不在 journalctl 里，dmg 版一般在~/.ollama/logs/server.log，遇到启动失败先去这里翻。

3.4 Windows 预览版：PATH 和服务状态两个坎

Windows 版目前还是预览状态，官网下载 exe 安装程序，双击下一步到底，装完托盘区会出现图标，服务在后台已经起来了。验证就是打开 PowerShell 敲一条：

# 查版本，能出版本号说明命令可用了 ollama --version

两个坎几乎每个 Windows 用户都遇到。第一个是装完当前终端里敲ollama提示「不是内部或外部命令」，因为安装程序改的是系统 PATH，已经开着的终端不会自动刷新，关掉重开一个就好。第二个是从 Linux 教程照抄命令——PowerShell 里curl是Invoke-WebRequest的别名，参数格式完全不一样，直接粘贴curl -fsSL ...大概率报错。

注意：Windows 的模型目录在%USERPROFILE%\.ollama\models，也就是 C 盘用户目录下。C 盘剩余空间不到 20G 的话，装完先改OLLAMA_MODELS环境变量再拉模型，别等撑爆了再挪。

3.5 装完先看的三个地方

不管哪个平台，装完别急着run，先把这三件事确认一遍，能省掉后面一堆莫名其妙的问题：

# 1. 版本号能出来，说明二进制和 PATH 没问题 ollama --version # 2. 服务状态是 active，说明守护进程正常 systemctl status ollama # 3. 端口在监听，说明 API 能通 ss -lntp | grep 11434

三条都对上了，说明这套环境的基础装好了。哪条不对，就顺着那一层往下查，别跳步。

4. 拉模型与写 Modelfile：参数怎么填才不炸内存

装完只是有了个空壳子，真正的重头在模型和配置。这一段是最容易「看起来成功了其实埋了雷」的地方：模型标签不带清楚，拉下来一个几十 G 的大家伙；num_ctx无脑调大，推理直接 OOM 被系统 kill。这章把标签、Modelfile 三个关键参数、自定义模型创建讲透，每一步都给出能直接抄的写法和调参依据。

4.1 pull 和 run 的关系：先弄懂标签

ollama run是一个复合动作：本地没有这个模型就先pull，有了就加载进内存进交互界面。所以第一回run会看到下载进度条，这属于正常流程，不是卡住了。标签（tag）决定拉哪个变体，不写就是latest。

# 明确指定版本和参数规模，别让它自己猜 ollama pull llama2:7b # 看本地已经有哪些模型、各占多大 ollama list # 清理不用的，释放磁盘 ollama rm llama2:13b

ollama list输出的 SIZE 列能帮你判断拉下来的到底是什么量化级别，同一个 7B 模型，Q4 量化和全精度能差出十倍体积。下载到一个 G 左右的 7B，那基本可以确定是量化版；下到十几 G，说明你拉的是全量权重，8G 内存的机器根本跑不动。ollama rm删模型是把磁盘上的文件一起删掉，删之前确认一下，没那么好恢复。

提示：下载中途断了不用从头来，重新执行同一条pull命令，Ollama 会断点续传，已经下好的层不会重复拉。

4.2 Modelfile 里最该改的三个参数

Modelfile 是 Ollama 的配置载体，语法不复杂，FROM指定基础模型，PARAMETER调推理参数，SYSTEM写系统提示词。真正影响能不能跑起来的是num_ctx，影响输出风格的是temperature和num_predict。

# 基础模型，可以直接引用本地已有的模型名 FROM llama2:7b # 温度：0 最确定、最保守；0.7 左右比较自然；1 以上开始发散 PARAMETER temperature 0.7 # 上下文窗口，单位是 token。这是内存杀手，别乱调 PARAMETER num_ctx 4096 # 单次最多生成多少 token，防止它一直说不完 PARAMETER num_predict 512 # 系统提示词，三引号支持多行 SYSTEM """你是一个本地知识助手，回答简短直接，不确定的地方就说不确定，不要编。"""

temperature的取舍很直白：做代码补全、信息抽取这类要求稳定的任务，往下调到 0.2 甚至 0；写文案、头脑风暴往上调到 0.9。num_ctx是最需要克制的参数，它决定模型一次能「看到」多少上下文，从 2048 提到 8192，KV cache 的占用差不多涨 4 倍，显存吃紧的机器直接 OOM。我一般先按 2048 或 4096 起步，真需要长文档再往上加，加完立刻观察一次推理的内存峰值。num_predict是输出上限，设太小会话说一半被截断，设太大则可能长时间占着资源不放。

4.3 create 一个自定义模型：把参数固化下来

参数写在命令行里每次都要重敲，写成 Modelfile 再create成新模型，后面直接run这个模型名就行。

# 用 Modelfile 创建一个叫 my-assistant 的新模型 ollama create my-assistant -f ./my_model.Modelfile # 跑起来看看效果 ollama run my-assistant

-f后面跟 Modelfile 的路径，my-assistant是你自己起的名字，不要和官方模型重名，否则容易搞混。创建过程很快，因为它只是把基础模型的层引用和新参数组合起来打个标记，不涉及重新训练。

改完参数想确认到底生效没有，别靠猜：

# 看这份自定义模型的完整配置 ollama show my-assistant --modelfile # 只看参数部分 ollama show my-assistant --parameters

这两条命令能直接看到当时写进去的temperature、num_ctx值，参数是不是生效一眼就清楚。

4.4 常见参数取值对照

调参这件事没必要纯靠试，下面这张表是我自己常用的一组起点，按任务类型选，再微调：

显存或内存不够的时候，优先砍num_ctx，再砍num_predict，最后才考虑换更小的模型。反过来，先换模型再用参数补救，很多时候是白折腾。

5. 避坑与排查：装完最容易翻车的五处

前面按顺利路径走了一遍，这一章写的是翻车现场。这几条几乎每条我都在不同机器上亲眼见过，按「现象 → 原因 → 解决」的次序摆出来，对着排查就行。

5.1 模型下到一半系统盘满了

现象：ollama pull进度条走到某个百分比突然不动，df -h一看根分区 100%。原因：模型默认落在~/.ollama/models，也就是系统盘的用户目录，几十 G 直接吃掉全部分区空间。解决：先删掉拉了一半的模型ollama rm <模型名>，设好OLLAMA_MODELS指向大盘目录，重启服务后再重新拉。

# 改完环境变量后必须重启服务，进程读的是启动时的值 sudo systemctl restart ollama systemctl show ollama | grep OLLAMA_MODELS

5.2 报 could not connect to ollama app

现象：一执行ollama run就提示连不上服务，或者 API 调用返回 connection refused。原因：服务根本没起来，或者端口被别的进程占了。解决：先看服务状态和端口占用，再决定是启动服务还是换端口。

# 服务状态、端口占用，两条一起看 systemctl status ollama ss -lntp | grep 11434

macOS 上还有一种情况：dmg 版和 brew 版同时装了，谁先起谁占端口，后起的那个永远起不来，把多余那份卸掉就行。

5.3 GPU 明明在，推理却慢得像 CPU

现象：nvidia-smi显示显卡正常，但推理速度慢得出奇，显存占用一直是 0。原因：驱动版本太低，或者装的是不带 CUDA 支持的包，Ollama 悄悄退回 CPU 跑了。解决：看服务启动日志里关于计算设备的输出，那里会写明用的是 GPU 还是 CPU。

# 看启动阶段的设备探测信息 journalctl -u ollama | grep -i -E "gpu|cuda|inference compute" # 确认显卡驱动版本，驱动太老要先升级 nvidia-smi

日志里如果出现类似inference compute但后端写的是 CPU，那就是没识别到 GPU，回去升级驱动是最有效的办法。

5.4 num_ctx 调大之后进程被 kill

现象：把num_ctx从 4096 改到 32768，跑一次推理服务直接挂，日志里出现 OOM 或 killed。原因：上下文窗口和 KV cache 占用是近似线性关系，翻 8 倍意味着显存也要多好几倍。解决：把num_ctx退回到能稳住的档位，或者换更小的量化模型。

# 看是不是被内核 OOM killer 干掉的 dmesg -T | grep -i "killed process" | tail -5

这条能直接确认是不是内存不足导致的强制终止，确认了就别硬扛，降参数或者换模型。

5.5 API 返回 model not found

现象：/api/generate返回 404，提示模型不存在。原因：请求体里的模型名和本地实际存的完全对不上，少个标签或者多个前缀。解决：先ollama list把名字抄准，标签要不要带看清楚。

# 列出本地模型全名，请求体里照抄 ollama list

名字大小写一般不敏感，但llama2和llama2:7b在某些版本里被当成两个不同条目，请求里写哪个就去 list 里找哪个，别凭记忆。

6. 装完怎么验证：三类接口都跑通才算真装好

ollama --version出个版本号，只能说明二进制装上了，离「这套环境能用」还差得远。我更看重的是三类入口能不能各自跑通：命令行交互、HTTP 接口、编程语言 SDK 调用。三条都过一遍，日常开发和后续接应用才不会在第一步就卡壳。

6.1 第一层：命令行交互先跑通

这是最直观的验证。跑起来问一句话，能看到回复，说明模型加载、推理链路、显存分配都正常。

# 起一个交互会话，第一次会稍慢，模型要加载进显存 ollama run llama2:7b # 进去之后随便问一句，比如：用一句话解释什么是量化 # 想退出输入 /bye

回复如果出来得很快、内容连贯，这一层就算过了。如果第一次响应等了十几秒才出字，多半是模型在加载，属于正常；但如果你问了三次每次都要等十几秒，那说明OLLAMA_KEEP_ALIVE设得太短，模型被反复卸载重载。

6.2 第二层：REST 接口能不能一次返回

Ollama 默认在 11434 端口暴露 HTTP 接口，/api/generate是单轮生成，/api/chat是多轮对话。用 curl 直接打一发，能看到 JSON 返回就说明服务对外可用。

# 单轮生成，stream 设 false 让它一次性返回完整结果 curl http://localhost:11434/api/generate -d '{ "model": "llama2:7b", "prompt": "用三句话说明本地部署大模型的好处", "stream": false }'

model字段必须和ollama list里的名字完全一致，这是最常见的 404 来源。stream设false表示等全部生成完再一次性返回，方便脚本处理；设true则是流式，一个字一个字吐，适合做前端打字机效果。

6.3 第三层：用 Python 调一遍聊天接口

真正要接进应用，得多轮对话这层也通。/api/chat和 generate 的区别在于它接收的是消息数组，带角色区分，模型能记住前文。

import requests url = "http://localhost:11434/api/chat" payload = { "model": "llama2:7b", # messages 是对话历史，role 分 user 和 assistant "messages": [ {"role": "user", "content": "我要在本机跑一个 7B 模型，需要注意什么？"}, {"role": "assistant", "content": "主要看内存和磁盘。"}, {"role": "user", "content": "那具体留多少合适？"} ], "stream": False } resp = requests.post(url, json=payload, timeout=120) if resp.status_code == 200: # 聊天接口的结果在 message.content 里，不是 response 字段 print(resp.json()["message"]["content"]) else: print("请求失败", resp.status_code, resp.text)

这里有个容易混的点：/api/generate的返回结果在response字段，/api/chat在message.content字段，写代码时用错字段会拿到空字符串，还以为是模型没回。timeout给足，本地模型首次加载加生成长文本，超过 60 秒不奇怪。

6.4 验证清单

七项里最后两项是我最看重的，前面五项都过了、接口调不通的情况太常见了，八成是模型名写错或者服务只监听了回环地址。有一次我在开发机上折腾到半夜，ollama list明明有模型、命令行也能聊，Python 脚本死活连不上，最后发现是OLLAMA_HOST被我改成了127.0.0.1，而脚本跑在另一个容器里，压根不在同一个网络命名空间。从那以后我每次装完 Ollama，不管多急，七项验证都强制走一遍，尤其是接口那两项——命令行能聊不等于服务能用，这个差别吃过一次亏就忘不掉。希望这套流程能帮你少走几段弯路。

本文还有配套的精品资源，点击获取