Ollama 欢迎(Welcome)
Ollama 官方文档的首页只有三句话:用开源模型武装你的桌面应用和编码代理,或者把它们构建进你自己的应用里。这三句话信息密度很高——它同时划定了 Ollama 的两种使用形态(本地推理 / 云端推理)和两条落地路径(接入现成工具 / 自己写代码调用)。
这一页是整部教程的入口。我先把它压缩的那三句话展开,再给你一张 13 章的阅读地图,让你知道自己现在该往哪一章走。
版本基线 v0.40.12;模型名、安装脚本地址与定价随版本变动,以官方
ollama.com与 GitHub release 为准。
一、Ollama 是什么
一句话:Ollama 是一个把开源大模型跑起来的运行时——负责下载权重、加载模型、暴露本地服务、管理模型生命周期。它自己不训练模型,也不绑定某个厂商;llama、qwen、deepseek、gemma、kimi 这些开源权重都能挂在它下面跑。
装好之后你得到的是一个常驻后台的本地服务,默认监听 127.0.0.1:11434。这个端口同时提供两种用法:
## 用法一:命令行交互,适合立刻试一下模型能力
ollama run gemma4:e2b
## 用法二:HTTP 调用,适合写进你自己的程序
curl http://localhost:11434/api/chat \
-d '{"model":"gemma4:e2b","messages":[{"role":"user","content":"你好"}]}'
两种形态的关键差别只有一条:模型权重存在哪、算力用谁的。
| 维度 | 本地形态(默认) | 云端形态(Ollama Cloud) |
|---|---|---|
| Base URL | http://localhost:11434/api |
https://ollama.com/api |
| 认证 | 免密钥 | 需 Authorization: Bearer $OLLAMA_API_KEY |
| 首次使用成本 | 下载权重(几 GB,只联网这一次) | 无需下载,注册即用 |
| 数据流向 | 不出本机 | 请求出网到 ollama.com |
| 模型上限 | 受本机显存/内存限制 | 可用本机跑不动的大模型 |
| 断网 | 正常可用 | 必然失败 |
隐私敏感的场景选本地,本机跑不动的大模型选云端——就是这么一条判断线。云端细节见 2.1 Ollama Cloud 概览。
二、先选模型:跑在本机,还是调用云端
官方首页把「Explore models」放在第一位,不是随手排的——模型选错,后面所有配置都是白费。它的建议是按用途挑:编码、视觉、嵌入向量、推理,四类模型的选型逻辑完全不同。
到模型库 ollama.com/search 浏览时,注意两个筛选维度:
- 按能力筛:
c=vision(看图)、c=embedding(做检索/向量化)、c=tools(能调工具)、c=thinking(先思考再回答)。 - 按算力筛:模型名后面的
e2b/31b/70b是参数量量级。粗算经验是 4-bit 量化下每 10 亿参数约需 0.7 GB 显存,再留 2 GB 给上下文和运行时——e2b(约 2B)在 8 GB 机器上能跑,31b基本要 24 GB 以上。
## 拉模型但不运行,适合先把权重下好、后面再调
ollama pull gemma4:e2b
## 看看本机已经有哪些模型、各占多少空间
ollama ls
三、官方文档的三条主干
官方把文档切成三块,这个切法对应三种不同的读者,不必全读:
第一条:Integrations(集成)——把 Ollama 接到现成的应用、编辑器或代理里。Claude Desktop、ChatGPT Desktop、VS Code、JetBrains、Cline、Zed、Xcode、n8n 都在这个分组下。你不想写代码、只想让手边的工具用上本地模型,就只看这一条。 入口是 12.0 Ollama 集成 概述。
第二条:API reference(接口参考)——用 Ollama 自己的 REST API,或者用 OpenAI / Anthropic 兼容客户端。你要把模型能力写进自己的程序,就走这一条。 入口是 13.1 Ollama API 总览。兼容层的价值在于:你原有的 OpenAI SDK 代码,只改 base_url 和 api_key 两个字段就能指向 Ollama,业务逻辑一行不用动。
第三条:客户端库(Python / JavaScript)——官方维护了 ollama-python 与 ollama-js 两个仓库。注意这一步在官网上是跳转到 GitHub 的外链,不属于 docs.ollama.com 的页面范围,所以本教程不逐页翻译,而是在 API 章节里给出等价的 curl 与 SDK 写法对照。想看官方库源码直接去 github.com/ollama/ollama-python。
四、五分钟跑通第一条链路
如果你现在只想确认「这东西到底能不能用」,按下面三步走,别展开任何细节:
## 第 1 步:确认服务在跑(装完一般已自启)
ollama --version # 输出形如 ollama version 0.40.12
ollama ps # 空表也正常,说明服务可达
## 第 2 步:拉一个小模型并对话(约 7 GB,只需联网这一次)
ollama run gemma4:e2b
## 第 3 步:让它以非交互方式回答一次,验证可脚本化
ollama run gemma4:e2b "用一句话解释什么是向量数据库"
三步都过了,说明安装、下载、推理、输出四个环节全部打通,后面只需要按需深入。任一步失败,先跳 11.1 故障排查,不要在一个报错上反复重装。
五、本教程 13 章阅读路线(点击直达)
官方文档是「全量参考手册」,按功能罗列;本教程在保持与官网逐页对应的前提下,重排了一条由浅入深的主线。你不必按章节顺序读——下面两张表都是可点击的导航,按你的目标点进去即可。
5.1 按目标选路线
| 你的目标 | 建议路线(点击直达) |
|---|---|
| 只想在本机跑个模型聊天 | 1.1 安装 → 1.2 首跑 → 到此为止 |
| 想接入手边的编辑器 / 桌面应用 | 1.1 安装 → 1.4 桌面应用 或 1.5 编码代理 → 12 章集成生态 |
| 想写代码调用(自己的程序) | 1.1 安装 → 1.3 用 API 构建应用 → 13 章 API → 3 章能力按需补 |
| 想跑大模型但本机显存不够 | 2.1 Cloud 概览 → 13.2 认证 → 13.9 Chat 端点 |
| 想把自己的微调模型塞进来 | 1.1 安装 → 8 章导入模型 → 5 章 Modelfile |
| 想用 Docker 部署给团队用 | 1.1 安装 → 7.4 Docker 部署 → 10 章硬件支持 |
| 程序跑不通 / 报错 | 11 章故障排查 → 9 章常见问题 |
5.2 完整章节目录(13 章 77 篇)
| 章 | 章节(点击进入该章目录) | 篇数 | 讲什么 |
|---|---|---|---|
| 第 1 章 | Ollama 快速入门 | 7 | 安装、首跑、第一次 API 调用、接入桌面应用 / 编码代理 / 个人助手 |
| 第 2 章 | Ollama Cloud | 1 | 云端形态的密钥、模型、计费与数据边界 |
| 第 3 章 | Ollama 模型能力 | 9 | 流式输出、思考、结构化输出、决策、视觉、嵌入向量、语音、工具调用、网络搜索 |
| 第 4 章 | Ollama CLI 命令行参考 | 1 | ollama 全部子命令与参数表 |
| 第 5 章 | Ollama Modelfile 参考 | 1 | 自定义系统提示、模板、参数与量化 |
| 第 6 章 | Ollama 上下文长度 | 1 | num_ctx 与显存占用的换算关系 |
| 第 7 章 | Ollama 安装与部署 | 4 | Linux / macOS / Windows 三平台 + Docker |
| 第 8 章 | Ollama 导入自定义模型 | 1 | GGUF 与 Safetensors 两条导入路径 |
| 第 9 章 | Ollama 常见问题 | 1 | 官方 FAQ 的本土化整理 |
| 第 10 章 | Ollama 硬件支持 | 1 | GPU 型号矩阵与加速后端 |
| 第 11 章 | Ollama 故障排查 | 1 | 按症状组织的排查树 |
| 第 12 章 | Ollama 集成生态 | 27 | 26 个集成的逐个配置说明 + 总览 |
| 第 13 章 | Ollama API 参考 | 22 | 22 个端点与 OpenAI / Anthropic 兼容层 |
每章目录页列出该章全部小节,可直接跳转。第 1 章从 欢迎页 开始,一路读到 1.6 运行个人助手;第 13 章从 API 总览 开始,到 余额查询 结束。
六、失败处理
ollama: command not found:安装后没重开终端(PATH 未刷新),或安装未完成。重开终端再试,仍失败看 1.1 安装 Ollama。Error: could not connect to ollama server:后台服务没起。先ollama serve前台跑一次看真实报错,端口被占用见第 11 章。- 模型下载卡住或极慢:国内网络直连
ollama.com常受限,可中断后重试(已下载的分片会续传),或换更小的标签先跑通链路。 model requires more system memory:模型超出本机内存/显存。换更小的参数档,或改走云端(第 2 章)。- 能跑但回答极慢:很可能在 CPU 上跑。
ollama ps的PROCESSOR列会显示100% CPU,此时看第 10 章确认你的显卡是否被支持。
七、动手试
- 运行
ollama --version与ollama ps,确认服务可达。 ollama run gemma4:e2b进入交互界面,问一句中文并观察输出速度;/bye退出。- 用
ollama run gemma4:e2b "用一句话解释什么是向量数据库"验证非交互模式。 - 打开
ollama.com/search,把c=vision、c=embedding两个筛选各点一次,记住一个你感兴趣的模型名——第 3 章会用到。 - 按上面第五节的路线表,选定你的目标,直接跳到对应章节;不确定就从 1.1 安装 Ollama 开始。