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":"你好"}]}'

两种形态的关键差别只有一条：模型权重存在哪、算力用谁的。

隐私敏感的场景选本地，本机跑不动的大模型选云端——就是这么一条判断线。云端细节见 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 章阅读路线

官方文档是「全量参考手册」，按功能罗列；本教程在保持与官网逐页对应的前提下，重排了一条由浅入深的主线。你不必按章节顺序读，按你的目标选路线：

各章定位速查：

• 第 1 章 快速入门：安装、首跑、第一次 API 调用、接入桌面应用 / 编码代理 / 个人助手。所有人的起点。
• 第 2 章 Ollama Cloud：云端形态的密钥、模型、计费与数据边界。
• 第 3 章 模型能力：流式输出、思考、结构化输出、决策、视觉、嵌入向量、语音、工具调用、网络搜索——9 个能力项，按需查，不要通读。
• 第 4 章 CLI 参考：ollama 全部子命令的参数表。
• 第 5 章 Modelfile 参考：自定义系统提示、模板、参数、量化。
• 第 6 章 上下文长度：num_ctx 与显存占用的换算关系。
• 第 7 章 安装与部署：Linux / macOS / Windows 三平台 + Docker。
• 第 8 章 导入自定义模型：GGUF 与 Safetensors 两条导入路径。
• 第 9 章 常见问题：官方 FAQ 的本土化整理。
• 第 10 章 硬件支持：GPU 型号矩阵与加速后端。
• 第 11 章 故障排查：按症状组织的排查树。
• 第 12 章 集成生态：27 个集成的逐个配置说明。
• 第 13 章 API 参考：22 个端点与兼容层，含错误码与用量查询。

六、失败处理

• 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 章确认你的显卡是否被支持。

七、动手试

1. 运行 ollama --version 与 ollama ps，确认服务可达。
2. ollama run gemma4:e2b 进入交互界面，问一句中文并观察输出速度；/bye 退出。
3. 用 ollama run gemma4:e2b "用一句话解释什么是向量数据库" 验证非交互模式。
4. 打开 ollama.com/search，把 c=vision、c=embedding 两个筛选各点一次，记住一个你感兴趣的模型名——第 3 章会用到。
5. 按上面第五节的路线表，选定你的目标，直接跳到对应章节；不确定就从 1.1 安装 Ollama 开始。