简介面向希望把大语言模型运行在自有硬件上的开发者、研究者与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 一样稳定。平台系统要求加速方式装前必须确认macOSmacOS 11 以上Apple Silicon 优先MetalM 系列芯片芯片型号、统一内存大小Linux主流 x86_64 发行版内核 5.x 以上NVIDIA CUDA / AMD ROCm显卡驱动版本、磁盘剩余空间WindowsWindows 10 以上预览版NVIDIA CUDA是否最新驱动、是否有管理员权限内存这块按经验给个粗略对照4bit 量化之后大致是这么个体量实际会随模型结构和上下文长度浮动模型规模4bit 量化后大致占用建议内存/显存常见标签写法2B3B23 GB8 GBgemma:2b7B8B46 GB16 GBllama2:7b13B810 GB24 GBllama2:13b70B40 GB 以上64 GB 以上llama2:70b注意显卡显存不够的时候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_HOST127.0.0.1:11434OLLAMA_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 --gpusall \ -v /data/ollama:/root/.ollama \ -p 11434:11434 \ --name ollama \ ollama/ollama--gpusall是 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] DescriptionOllama Service Afternetwork-online.target [Service] Typesimple Userollama Groupollama # 这三个环境变量决定了模型存哪、服务听哪个地址、模型加载后驻留多久 EnvironmentOLLAMA_MODELS/data/ollama/models EnvironmentOLLAMA_HOST127.0.0.1:11434 EnvironmentOLLAMA_KEEP_ALIVE30m ExecStart/usr/local/bin/ollama serve Restartalways RestartSec3 [Install] WantedBymulti-user.targetOLLAMA_KEEP_ALIVE这个参数容易被忽略它控制模型加载进显存后驻留多久默认只有 5 分钟超时就卸载。频繁调 API 的场景下每次都要重新加载模型第一次响应会慢好几秒调到30m或者-1永不卸载能明显改善体验代价是显存一直被占着。写完文件之后要让 systemd 重新读一遍配置再设成开机自启# 重新加载 unit 配置启用并立即启动服务 sudo systemctl daemon-reload sudo systemctl enable --now ollama # 看服务状态和实时日志 systemctl status ollama journalctl -u ollama -f注意Userollama意味着进程以 ollama 用户身份跑/data/ollama/models这层目录的属主必须改成它否则拉模型时写文件会失败。# 递归改属主让 ollama 用户能写模型目录 sudo chown -R ollama:ollama /data/ollama3.3 macOSdmg 和 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 :11434dmg 版适合只想要个能用的大模型的人双击装完直接用。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:13bollama 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 提到 8192KV 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 常见参数取值对照调参这件事没必要纯靠试下面这张表是我自己常用的一组起点按任务类型选再微调任务类型temperaturenum_ctxnum_predict说明代码补全 / 结构化抽取00.320484096256512要确定性别让它自由发挥日常问答 / 客服0.50.74096512平衡准确和自然文案 / 创意写作0.81.0409681921024上下文要够输出要长长文档摘要0.20.48192 以上512先确保显存放得下显存或内存不够的时候优先砍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_MODELS5.2 报 could not connect to ollama app现象一执行ollama run就提示连不上服务或者 API 调用返回 connection refused。原因服务根本没起来或者端口被别的进程占了。解决先看服务状态和端口占用再决定是启动服务还是换端口。# 服务状态、端口占用两条一起看 systemctl status ollama ss -lntp | grep 11434macOS 上还有一种情况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, jsonpayload, timeout120) 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 --version输出版本号服务在跑systemctl status ollamaactive (running)端口在听ss -lntp | grep 11434有进程监听模型已落盘ollama list能看到模型名和体积命令行推理ollama run 模型能正常对话/bye退出HTTP 接口curl 打/api/generate返回带response字段的 JSON多轮对话Python 调/api/chat返回带message.content的 JSON七项里最后两项是我最看重的前面五项都过了、接口调不通的情况太常见了八成是模型名写错或者服务只监听了回环地址。有一次我在开发机上折腾到半夜ollama list明明有模型、命令行也能聊Python 脚本死活连不上最后发现是OLLAMA_HOST被我改成了127.0.0.1而脚本跑在另一个容器里压根不在同一个网络命名空间。从那以后我每次装完 Ollama不管多急七项验证都强制走一遍尤其是接口那两项——命令行能聊不等于服务能用这个差别吃过一次亏就忘不掉。希望这套流程能帮你少走几段弯路。本文还有配套的精品资源点击获取
