【大模型基础｜推理篇00】—— Ollama部署本地大模型-二趣网

Ollama 部署本地大模型：安装、模型管理、Modelfile 与 API 调用

想在自己机器上跑个大模型，第一反应通常是去装 CUDA、配 PyTorch、下载权重、写加载脚本——光是把环境跑通就够折腾半天。Ollama 的思路完全不同：把这些全包起来，让你用一条命令就能把模型跑起来。

这篇文章解决一件事：从零把 Ollama 用起来。覆盖它适合什么场景、安装、模型拉取与对话、Modelfile 参数固化、API 两种调用方式，以及国内网络和常见故障的处理。

一、先厘清：Ollama 是什么，适合谁

Ollama 是一个本地大模型运行与管理工具。它底层基于 llama.cpp，负责把模型权重、推理参数、服务端口都封装成开箱可用的形态。

一句话概括它的定位：它不是新模型，也不是训练框架，而是「把下载好的开源模型在本地跑起来」的那一层。

适合的场景

场景	说明
本地开发调试	需要频繁调 Prompt、试模型，不想被 API 额度和网络限制
数据隐私敏感	数据不出本机，适合内部文档、代码等敏感内容
个人知识库 / RAG	作为 RAG 的本地推理后端
低成本原型验证	没有 GPU 集群，先用消费级硬件验证想法

不适合的场景

⚠️ 注意：Ollama 不是高并发生产推理引擎。它的优势在易用性，不在吞吐。如果你要支撑一个高 QPS 的在线服务，应该考虑 vLLM 这类专为吞吐优化的引擎。两者定位不同，不冲突。

二、环境说明与前置条件

项	要求	说明
操作系统	macOS / Linux / Windows	三端均有官方安装包
内存	建议 16GB 起	运行 7B 级模型较流畅；4~8GB 只能选小模型
GPU	可选	NVIDIA / AMD 可加速；macOS 走 Metal
磁盘	视模型而定	7B 量化模型通常几 GB，70B 级可达数十 GB
网络	需可访问模型仓库	国内环境可能需配置代理

硬件加速的边界：

macOS：走 Metal，Apple Silicon 表现最好。
Linux / Windows：NVIDIA 需装好驱动；Windows 下 WSL2 也可用。
macOS 上的 Docker 不支持 GPU 加速（缺少 GPU 直通），官方文档明确说明——想在 Mac 上用 Docker 跑 GPU 推理是行不通的。

三、安装

3.1 Linux 一键安装

curl-fsSLhttps://ollama.com/install.sh|sh

安装脚本会创建 systemd 服务并自动启动。

# 查看服务状态systemctl status ollama

3.2 macOS / Windows

从官网 https://ollama.com/download 下载安装包，安装后应用会常驻后台。

# 验证安装ollama--version

✅ 成功标志：ollama --version能输出版本号。

3.3 Docker

dockerpull ollama/ollamadockerrun-p11434:11434 ollama/ollama

⚠️ 注意：macOS 上 Docker 无法使用 GPU 加速，只适合做接口联调，不适合跑大模型。

四、跑起来：拉模型与对话

4.1 拉取模型

# 拉取模型ollama pull qwen3# 查看本地已有模型ollama list# 查看正在运行的模型及其资源占用ollamaps

🔴 重点：模型名和 tag 请以 https://ollama.com/library 为准。模型库更新很快，各家的模型代际和命名一直在变，照抄一年前的命令很可能拉不到东西。ollama pull <name>:<tag>里的 tag 省略时通常是默认档位。

ollama ps的输出里有一个PROCESSOR列，能直接告诉你模型跑在哪里：

NAME ID SIZE PROCESSOR UNTIL llama3:70b bcfb190ca3a7 42 GB 100% GPU 4 minutes from now

100% GPU：完全跑在显存里
100% CPU：完全跑在内存里（慢）
48%/52% CPU/GPU：部分卸载到 GPU

看到100% CPU就说明没吃到 GPU，这是排查性能问题的第一个观察点。

4.2 交互式对话

ollama run qwen3

进入交互界面后，可以直接对话。几个常用控制命令：

/bye # 退出（也可按 Ctrl+D） /set parameter num_ctx 8192 # 临时调整上下文窗口

4.3 一次性问答

ollama run qwen3"用一句话解释什么是 LoRA"

适合脚本里调用。

五、Modelfile：把配置固化成模型

.set parameter的改动是临时的，退出就没了。要让配置持久化，用Modelfile。

5.1 基本写法

FROM qwen3 # 上下文窗口设为 8192 PARAMETER num_ctx 8192 # 温度调低，回答更稳定 PARAMETER temperature 0.7 # 设定系统提示词 SYSTEM 你是一个严谨的技术助手，回答简洁准确。

创建并运行：

ollama create my-qwen-f./Modelfile ollama run my-qwen

5.2 查看已有模型的 Modelfile

ollama show--modelfileqwen3

这是个实用技巧：想知道某个模型的默认模板和参数长什么样，直接导出来看。

5.3 常用 PARAMETER

参数	作用	官方标注默认值
`num_ctx`	上下文窗口大小	见下方说明
`temperature`	随机性，越高越有创意	`0.8`
`top_p`	采样范围	`0.9`
`top_k`	候选词数量	`40`
`repeat_penalty`	重复惩罚	`1.0`（即关闭）
`repeat_last_n`	回看多少 token 来抑制重复	`64`
`num_predict`	最大生成 token 数	`-1`（不限）
`seed`	随机种子，固定后输出可复现	`0`
`stop`	停止序列	——

⚠️ 注意：num_ctx的默认值在官方文档里存在不一致——Modelfile 参数表标注为2048，而 FAQ 页面写明「Ollama 默认使用 4096 tokens 的上下文窗口」。这种文档内部打架的情况，最稳妥的做法是显式设置num_ctx，不依赖默认值。

num_ctx是本地部署最值得调的一个参数：调大能容纳更长的对话和文档，但显存/内存占用会随之上升。8GB 显存的机器把它设得太大会直接跑不动。

5.4 用环境变量改全局默认

不想每建一个模型都写num_ctx，可以用环境变量设置全局默认：

OLLAMA_CONTEXT_LENGTH=8192ollama serve

5.5 从本地权重构建

Modelfile 的FROM也支持直接指向本地模型：

# 从 safetensors 目录构建 FROM /path/to/model_directory # 从 GGUF 文件构建 FROM ./my-model.gguf

这对加载自己微调导出的模型很有用。

六、API 调用

Ollama 服务默认监听http://localhost:11434，提供两套接口。

6.1 原生 API

原生接口路径前缀是/api。

curlhttp://localhost:11434/api/generate-d'{ "model": "qwen3", "prompt": "为什么天空是蓝色的？" }'

指定推理参数用options字段：

curlhttp://localhost:11434/api/generate-d'{ "model": "qwen3", "prompt": "为什么天空是蓝色的？", "options": { "num_ctx": 4096, "temperature": 0.7 } }'

6.2 OpenAI 兼容 API

这是更推荐的接入方式。Ollama 在同一端口上暴露了一套 OpenAI 兼容接口，路径是/v1/...，已有的 OpenAI SDK 代码基本只需改base_url。

支持的端点：

端点	对应 OpenAI 能力
`/v1/chat/completions`	对话补全（多轮）
`/v1/completions`	文本补全（单轮）
`/v1/embeddings`	文本向量化
`/v1/models`	模型列表

Python 调用示例：

fromopenaiimportOpenAI client=OpenAI(base_url="http://localhost:11434/v1",api_key="ollama",# Ollama 不校验，但字段必填，随便填)resp=client.chat.completions.create(model="qwen3",messages=[{"role":"system","content":"你是一个简洁的助手"},{"role":"user","content":"用一句话解释 LoRA"},],)print(resp.choices[0].message.content)

✅ 成功标志：返回结构是标准的choices[].message.content，流式输出也正常。

⚠️ 注意：官方文档说明Ollama 的 API 不做严格版本管理，但保持向后兼容。这意味着接口不会频繁破坏，但也别指望有明确的版本号可以锁。升级 Ollama 后建议跑一遍回归。

6.3 官方 SDK

官方提供了 Python 和 JavaScript 库：

Python：https://github.com/ollama/ollama-python
JavaScript：https://github.com/ollama/ollama-js

七、国内网络与加速

7.1 用代理拉模型

Ollama 官方并没有提供「镜像站点」这类环境变量——网上流传的OLLAMA_MIRROR并不是 Ollama 支持的变量，设了不会有任何效果。

官方文档支持的方式是通过HTTPS 代理：

# 临时设置（当前 shell 生效）exportHTTPS_PROXY=http://你的代理地址:端口 ollama pull qwen3

Linux 下要让 systemd 服务也走代理，需要改服务配置：

sudosystemctl edit ollama

在打开的编辑器中加入：

[Service] Environment="HTTPS_PROXY=http://你的代理地址:端口"

保存后重载：

sudosystemctl daemon-reloadsudosystemctl restart ollama

⚠️ 注意：不要设置HTTP_PROXY。官方文档明确说明 Ollama 拉模型只走 HTTPS，设置HTTP_PROXY可能反而中断客户端与服务端的连接。

7.2 变更模型存储位置

默认模型目录：

系统	路径
macOS	`~/.ollama/models`
Linux	`/usr/share/ollama/.ollama/models`
Windows	`C:\Users\%username%\.ollama\models`

换到大容量磁盘：

exportOLLAMA_MODELS=/path/to/your/models

Linux 下用标准安装方式时，还要确保ollama用户对该目录有读写权限：

sudochown-Rollama:ollama /path/to/your/models

7.3 降低资源占用

模型跑不动时，按这个顺序处理：

换更小的模型或量化档位——收益最直接；
调小num_ctx——上下文窗口直接决定 KV 缓存占用；
确认是否真的用上了 GPU——ollama ps看 PROCESSOR 列；
关掉其他吃内存的程序。

八、常见问题排查

8.1 连接不上 11434 端口

原因：服务没启动。

解决：

systemctl status ollamasudosystemctl start ollama

验证：curl http://localhost:11434/api/tags能返回模型列表。

8.2 想让局域网内其他机器访问

原因：默认只监听127.0.0.1。
解决：设OLLAMA_HOST=0.0.0.0:11434后重启服务。
⚠️ 注意：暴露到公网前务必评估安全风险，Ollama 默认没有认证机制。

8.3 模型拉取中断

原因：网络不稳定。
解决：重跑ollama pull <模型名>即可，支持断点续传，不用从头下；长期不稳就配代理。

8.4 推理速度慢

排查：ollama ps看 PROCESSOR 列。
解决：如果是100% CPU，说明没吃到 GPU，检查驱动；如果是 GPU 但依然慢，说明模型超出了显存，考虑换小模型或加量化。

8.5 macOS 上 Docker 里跑不动 GPU

原因：Docker Desktop 在 macOS 上不支持 GPU 直通。
解决：macOS 直接用原生安装包，别用 Docker。

8.6 查看日志

# Linux（systemd）journalctl-uollama-f# macOScat~/.ollama/logs/server.log

九、总结：你真正需要记住的 N 件事

Ollama 是本地模型运行与管理工具，优势是易用，不是高并发吞吐——生产高 QPS 场景请用 vLLM。
服务默认在http://localhost:11434，原生接口在/api/*，OpenAI 兼容接口在/v1/*。
接入已有 OpenAI SDK 代码只需改base_url，api_key随便填但要写上。
num_ctx是本地部署最该调的参数，官方文档对它的默认值说法不一致（2048 vs 4096），建议显式设置。
ollama ps的 PROCESSOR 列是判断有没有用上 GPU 的第一手依据。
没有OLLAMA_MIRROR这个变量，加速要走HTTPS_PROXY；且不要设HTTP_PROXY。
模型名与 tag 以官方模型库为准，模型代际更新很快，旧命令可能失效。

验证清单

ollama --version正常输出版本
ollama list能看到已拉取的模型
ollama run <模型>能正常对话
ollama ps的 PROCESSOR 列显示 GPU 参与（如有 GPU）
curl http://localhost:11434/api/tags返回模型列表
/v1/chat/completions用 OpenAI SDK 调用成功
已显式设置num_ctx，不依赖默认值
需要跨机访问时已配置OLLAMA_HOST并评估过安全风险

参考资源

Ollama 官方文档：https://docs.ollama.com/
Ollama API 文档：https://docs.ollama.com/api
Ollama OpenAI 兼容说明：https://docs.ollama.com/api/openai-compatibility
Modelfile 参考：https://docs.ollama.com/modelfile
常见问题（FAQ）：https://docs.ollama.com/faq
模型库：https://ollama.com/library
Python SDK：https://github.com/ollama/ollama-python

企业官网建设流程全解析