Ollama 中文教程
Ollama 是一个把开源大模型跑起来的运行时:它负责下载权重、加载模型、暴露本地推理服务、管理模型生命周期。装好之后你得到一个常驻本地服务,默认监听 127.0.0.1:11434,既能用命令行直接对话,也能用 HTTP 接口写进自己的程序。它本身不训练模型,也不绑定厂商——llama、qwen、deepseek、gemma、kimi 等开源权重都能挂在它下面运行。
本教程是 Ollama 官方文档(docs.ollama.com)的中文本土化版本,按官方导航逐页对应改写,共 13 章 77 篇。所有代码示例补充了详细中文注释,命令按 Windows / macOS / Linux 分别给出,并针对国内网络环境补充了下载慢、镜像源、显存不足等实际问题的处理办法。教程不替代英文原文,版本漂移以官方 GitHub release 交叉核对。
适合谁读
- 想在本地电脑运行开源大模型、且不希望数据出网的开发者;
- 需要把本地或私有模型接入自己的应用、编辑器、编码代理的工程师;
- 熟悉 Docker 与基础环境变量配置、准备做推理部署的运维人员;
- 正在评估「本地推理 vs 云端 API」成本与隐私边界的技术负责人。
前置要求
- 一台可联网(用于首次下载模型权重)的电脑,建议 8 GB 以上可用内存或显存;
- 基础命令行操作能力,部分章节需要 Python 或 Node.js 环境;
- 调用云端 Ollama 时需要一个合法的 API Key 与可用额度,本地调用不需要。
三条学习路径
- 只想在本机跑个模型聊天:1.1 安装 Ollama → 1.2 运行你的第一个模型,到这里就够用了。
- 想接入手边的编辑器或桌面应用:1.4 连接桌面应用 或 1.5 使用编码代理,再查 第 12 章 集成生态 里你实际在用的那个工具。
- 想在自己的程序里调用:1.3 用 API 构建应用 → 第 13 章 API 参考 → 按需回 第 3 章 模型能力 补流式输出、结构化输出、工具调用等具体能力。
手册结构(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 个集成的逐个配置说明:Claude Desktop、ChatGPT Desktop、VS Code、JetBrains、Zed、Xcode、Cline、n8n 等 |
| 第 13 章 | Ollama API 参考 | 22 | 22 个端点,含 OpenAI / Anthropic 兼容层、错误码与用量查询 |
两个必须分清的概念
本地推理:Base URL 是 http://localhost:11434/api,免密钥,模型权重下载到本机,数据不出网,受本机显存限制。
云端推理:Base URL 是 https://ollama.com/api,需要 Authorization: Bearer 认证,模型无需下载,可调用本机跑不动的大模型,代价是请求会出网。隐私敏感场景选本地,本机跑不动的大模型选云端。
如果你的原有代码用的是 OpenAI SDK,只需把 base_url 指向 Ollama 并随便填一个 api_key,业务逻辑一行都不用改,详见 13.6 OpenAI 兼容。
版本与更新
- 内容基线:官方 docs.ollama.com,核对于 2026-10-29,对应 Ollama v0.40.12;
- 模型名、安装脚本地址、云端定价随版本变化较快,涉及处已在正文标注来源与日期,以官网为准;
- 官方文档若新增页面,本教程会按同样结构补章,不改变既有短地址。
来源与声明
本教程内容基于 Ollama 官方英文文档(docs.ollama.com)翻译并本土化改写,版权归原作者所有;中文表述、代码注释、国内环境适配与排障经验为本教程新增。教程以学习交流为目的,不代表 Ollama 官方立场。如发现与官方文档不一致之处,以官方英文原文为准。
遇到问题先看 第 11 章 故障排查,那里按症状组织了排查树;仍无法解决可在教程下方留言。