力 力达云
教程聚合APItoken成本国产模型资讯工具关于内测申请
← 返回资讯

Ollama 本地快速跑模型：安装、拉取与 API 接入指南

2026-07-08

Ollama 让”在本地跑大模型”这件事变得像安装一个普通应用一样简单——一行命令拉取模型、一行命令启动服务，并且自动暴露兼容 OpenAI 协议的 HTTP API。对于开发者快速验证提示词、调试 RAG 流程、或构建不依赖外部 API 的私有原型，Ollama 是目前最低门槛的选择。

我见过不少团队第一次接触本地大模型，是被一个具体场景逼的：demo 要给客户演示，但客户网络环境访问不了外部 API，或者数据合规要求提示词不能出内网。这种时候没人有空去折腾 CUDA 版本匹配、pip 装 torch 装到报错，Ollama 基本是唯一能”当场跑起来”的方案。它牺牲了一部分性能上限，换来的是从零到能对话只要几分钟。

Ollama 能解决什么问题

在 Ollama 出现之前，本地跑开源模型需要手动处理 Python 环境、CUDA 驱动、权重格式转换、推理框架配置等一系列门槛。Ollama 把这些全部打包：

需求Ollama 的解法
模型获取ollama pull 自动从仓库下载 GGUF 格式权重
推理引擎内置 llama.cpp，自动匹配 CPU/GPU
服务接口默认在 localhost:11434 提供 REST API
多平台支持macOS（Apple Silicon/Intel）、Linux、Windows 原生支持
显存不足自动降级到 CPU 推理（速度慢但能跑）

这张表背后其实是两层封装，理解了这两层，后面排查问题会顺很多。第一层是 GGUF 格式：它把模型权重、分词器、量化参数打包成单个文件，llama.cpp 读取这一个文件就能跑起来，不需要再额外配 tokenizer.json、config.json 一堆散碎文件——这也是为什么 Ollama 下模型是”一个模型一个包”，而不是 Hugging Face 那种一堆小文件。第二层是 llama.cpp 推理引擎：它是用纯 C/C++ 写的，不依赖 Python 和 PyTorch，所以没有 CUDA 版本对不上、torch 编译失败这类环境问题，也因此能在 Mac 的 Metal、Windows 的 CPU 上直接跑，代价是不支持 vLLM 那种批处理并发优化，单卡吞吐天花板低很多。

安装与基本使用

macOS / Linux：

curl -fsSL https://ollama.com/install.sh | sh

Windows： 从 ollama.com 下载安装包，双击安装即可。

拉取并运行模型：

ollama pull qwen2.5:7b          # 拉取 Qwen2.5-7B
ollama run qwen2.5:7b           # 交互式对话
ollama serve                    # 仅启动后台服务（不进入对话）

查看已下载模型：

ollama list

装完这几条命令之后，有几个点容易被忽略，提前说清楚能少踩坑。第一，ollama serve 和后台自启动是两回事——macOS/Windows 装完安装包会自动装一个常驻的托盘程序，ollama run 直接就能用；但如果你是在 Linux 服务器上用 curl 脚本装的，systemd 服务默认已经帮你注册好了，用 systemctl status ollama 能看到它常驻监听 11434 端口，不需要每次手动 ollama serve。第二，第一次 ollama pull 一个模型时进度条卡住不动很正常，大模型权重动辄几个 GB，取决于你的网络到 Ollama 仓库节点的速度，国内网络有时会明显慢一截，耐心等或者换个网络环境，别以为是命令卡死了就去 Ctrl+C。

模型选择：Ollama 仓库常用模型

模型命令显存需求（Q4）适合场景
qwen2.5:7bollama pull qwen2.5:7b~5 GB中文对话、代码
qwen2.5:14bollama pull qwen2.5:14b~9 GB中文更强，需多一些显存
llama3.2:3bollama pull llama3.2:3b~2 GB极低资源场景
deepseek-r1:7bollama pull deepseek-r1:7b~5 GB推理/数学
nomic-embed-textollama pull nomic-embed-text<1 GB本地 Embedding

Ollama 默认下载的是 GGUF Q4_K_M 量化版本，在大多数本地硬件上是效果与显存的最佳平衡点。

为什么默认是 Q4_K_M，不是更省显存的 Q2 或者更精确的 Q8？ 这里有个粗算的经验公式：一个 N（单位十亿）参数的模型，用 FP16 原始精度跑，大约需要 2N GB 显存；量化到 Q8 大约是 1N GB；量化到 Q4 大约是 0.5-0.6N GB。以 7B 模型为例，FP16 要 14GB，Q8 要 7GB 左右，Q4_K_M 只要 4-5GB——这就是表里”~5 GB”的来源。Q4_K_M 相比更激进的 Q2/Q3，在困惑度（perplexity，衡量模型对文本的预测能力，数值越低越好）上损失通常控制在个位数百分比以内，但显存直接砍半，所以成了默认选择。如果你的显卡显存宽裕（比如 24GB 以上），拉模型时可以显式指定标签换成 Q8，比如 ollama pull qwen2.5:7b-instruct-q8_0，效果更接近原始精度，代价是显存翻倍、速度略降。

拉模型之前想知道自己的显卡够不够，与其等下载完才发现跑不动，不如先算一笔账：显存需求 ≈ 量化后模型体积 + 上下文缓存（KV Cache）。KV Cache 跟你设置的 num_ctx（上下文长度）成正比，默认 2048 tokens 时占用不大，但如果你把上下文拉到 32K 甚至更长做长文档问答，KV Cache 本身就可能吃掉好几个 GB，这也是为什么同一个模型，短对话跑得很流畅、长文档一喂进去就报显存不足的常见原因。

接入 OpenAI SDK

Ollama 的 API 完全兼容 OpenAI 协议，只需修改 base_url：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",   # 随意填，Ollama 不验证
)

resp = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "用 Python 写一个快速排序"}],
)
print(resp.choices[0].message.content)

LangChain、LlamaIndex、Vercel AI SDK 等框架同样可以通过修改 base_url 接入 Ollama 本地服务。

这段代码里 api_key="ollama" 那行经常让人一头雾水——既然本地服务不验证密钥，为什么还要传一个值？因为 OpenAI SDK 在客户端初始化的时候会校验 api_key 字段非空，传空字符串或者不传都会在实例化阶段直接报错，随便填个字符串只是为了绕过这层校验，Ollama 服务端根本不会读取这个值，你填 “abc” 效果一样。

真正用起来，单条请求等待完整结果往往不是你想要的体验，尤其是回答长的时候。想要打字机效果的流式输出，把 stream=True 加上，然后逐块读取：

stream = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "写一篇 300 字的产品介绍"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

如果你要在同一台机器上跑批量任务，比如给 100 条客服记录打标签，别用 for 循环挨个调用——Ollama 默认只加载一份模型权重到显存，串行请求之间几乎没有并行收益，反而更容易暴露超时问题。更实际的做法是用异步客户端配合有限并发，既能提速，也不会一次性把请求全砸过去打满显存：

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
semaphore = asyncio.Semaphore(4)  # 按显存和模型大小调整并发数

async def ask(prompt: str):
    async with semaphore:
        resp = await client.chat.completions.create(
            model="qwen2.5:7b",
            messages=[{"role": "user", "content": prompt}],
        )
        return resp.choices[0].message.content

async def main(prompts: list[str]):
    return await asyncio.gather(*(ask(p) for p in prompts))

并发数怎么定？没有万能值，经验做法是从 2 开始逐步往上加，边加边看 nvidia-smi（有 GPU 的话）或者任务管理器里的显存/内存占用曲线，一旦逼近上限或者响应时间明显变长就往回退一档。Ollama 本身没有 vLLM 那种连续批处理（continuous batching）机制，并发请求是靠请求队列排队处理的，所以并发数调太高换来的往往只是排队变长，而不是真正的吞吐提升。

Ollama vs vLLM：该选哪个

维度OllamavLLM
上手难度极低，一行命令中等，需 CUDA 环境
并发性能弱，无批处理优化强，PagedAttention 高吞吐
模型格式GGUF（llama.cpp）原始权重 + HF 格式
CPU 推理支持基本不支持
适合场景本地开发测试生产级服务
推荐 GPU消费卡或 CPU 均可专业卡，显存越大越好

结论：开发测试用 Ollama，上生产用 vLLM。判断依据其实很简单，问自己两个问题：会不会有多个用户同时发请求？响应速度要不要卡在几百毫秒级别？只要有一个答案是”是”，就该往 vLLM 方向走；如果就是你自己写代码调试、跑离线批处理任务、或者给几个人内部试用，Ollama 完全够用，没必要为了性能上限去折腾 vLLM 的部署门槛。如果你打算部署面向用户的服务，请看 vLLM 部署高并发推理。

避坑实录：几个真实会遇到的报错

Error: pull model manifest: file does not exist —— 这个报错通常不是网络问题，而是模型名字或标签打错了。Ollama 仓库里的模型名区分大小写、标签要精确匹配，比如你想要 Qwen2.5 的 14B 版本，写成 qwen2.5-14b 而不是 qwen2.5:14b（用短横线代替了冒号）就会直接报这个错。去 ollama.com 的模型页面把命令原样复制，别自己拼写。

请求半天没反应，最后报 httpx.ReadTimeout 或者客户端直接卡死 —— 十有八九是模型体积超出了你机器的处理能力，正在用 CPU 硬跑，第一次加载权重到内存/显存本身就要花时间，之后每个 token 生成也慢。先用 ollama run <model> 在终端里手动测一下这个模型能不能正常对话、大概多快出字，如果终端里都很慢，说明不是 API 调用的问题，是该换更小的模型或者升级硬件了。如果终端里正常但 API 调用超时，检查你客户端设置的 timeout 参数是不是给得太短，本地推理没有云端 API 那么稳定的响应时间，超时建议设到 60 秒以上再说。

返回内容是乱码或者 <0xEF><0xBF><0xBD> 这类字符 —— 多半出现在流式输出场景，因为多字节的中文字符（UTF-8 编码下一个汉字占 3 个字节）可能被截断在两个 chunk 的边界上，你如果自己手写了字节层面的流式解析逻辑就容易踩这个坑。用官方 SDK 的流式接口（如上面 stream=True 的写法）一般不会有这个问题，因为 SDK 内部已经做了缓冲区拼接处理；如果是自己拿 requests 直连 API 做流式解析，记得按 SSE 的 data: 行边界处理，不要按固定字节数切割。

长文档喂进去直接报错或者回答明显”失忆”、前面说的内容不认账 —— 这是上下文长度超限。Ollama 默认 num_ctx 只有 2048 tokens，中文场景大约对应 1000-1500 个汉字，超出的部分会被悄悄截断而不是报错，所以你感觉”模型是不是记性不好”，其实是历史对话已经被挤出窗口了。解决办法是在请求里显式传 options: {"num_ctx": 8192} 这样的参数调大窗口，但要注意前面提过的 KV Cache 占用会跟着涨，显存不够时调大窗口反而会引发真正的显存不足报错，两者需要权衡。

常见问题

Ollama 没有 GPU 也能用吗？
可以。Ollama 会自动检测 GPU，没有 GPU 时降级到 CPU 推理。CPU 跑 7B 模型大约每秒 3–8 个 token，用于个人测试基本够用，不适合有响应速度要求的场景。

如何让 Ollama 在局域网内可访问？
设置环境变量 OLLAMA_HOST=0.0.0.0 后重启服务，Ollama 会监听所有网卡，团队内网共享一台本地机器跑模型时非常实用。

Ollama 支持多模态模型吗？
支持，例如 ollama pull llava 可以运行图文理解模型。发送图片时在 API 的 messages 中按 base64 格式附带图片内容。

模型文件存在哪里？可以换路径吗？
macOS/Linux 默认在 ~/.ollama/models，Windows 在 %USERPROFILE%\.ollama\models。可以通过 OLLAMA_MODELS 环境变量修改存储路径。

延伸阅读：