简体中文 | English

[!WARNING] 🧪 Beta 公测版本提示：教程主体已完成，正在优化细节，欢迎大家提 Issue 反馈问题或建议。

🎉官方收录

2025.11.06，本项目被 Ollama 官方仓库收录，且是目前唯一的 Tutorial：https://github.com/ollama/ollama#tutorial

🚀 项目简介

动手学 Ollama 教程，轻松上手实现大模型本地化部署，快速在本地管理以及运行大模型，让 CPU 也可以玩转大模型推理部署！

本教程涵盖从基础入门到进阶使用的全方位内容，并通过实际应用案例深入理解和掌握大模型部署以及应用技术。我们的教程提供清晰的步骤和实用的技巧，无论是刚刚接触大模型部署的小白，还是有一定经验的开发者，都可以从零开始学习 Ollama ，实现本地部署大模型以及相关应用。

本项目主要内容：

1. Ollama 介绍、安装和配置，包括在 macOS、Windows、Linux 和 Docker 下的安装与配置；
2. Ollama 自定义导入模型，包括从 GGUF 导入、从 Pytorch 或 Safetensors 导入、由模型直接导入、自定义 Prompt；
3. Ollama REST API，包括 Ollama API 使用指南、在 Python、Java、JavaScript 和 C++ 等语言中使用 Ollama API；
4. Ollama 在 LangChain 中的使用，包括在 Python 和 JavaScript 中的集成；
5. Ollama 可视化界面部署和应用案例，包括使用 FastAPI 和 WebUI 部署可视化对话界面，以及本地 RAG 应用、Agent 应用等。

热忱欢迎感兴趣的同学或者开发者们 提出 issue 或者 提交 pull request，让我们一起完善这个项目！

我们坚信：每一位对大模型充满热情的学习者，都应该有机会探索和实践。无论你的编程语言背景如何，无论你的计算资源如何，我们都希望能帮助你使用个人 PC 实现大模型部署。 让我们携手打破技术壁垒，共同开启 LLM 探索之旅！

目录结构说明：

  docs ---------------------- Markdown 文档文件
  notebook ------------------ Notebook 源代码文件以及部分 Python、Java 和 JavaScript 源文件 
  images -------------------- 图片

📖 在线阅读：https://datawhalechina.github.io/handy-ollama/

💡 立项理由

随着大模型的飞速发展，市面上出现了越来越多的开源大模型，但是许多模型的部署需要利用 GPU 资源，如何让大模型时代的红利普惠到每一个人，让每一个人都可以部署属于自己的大模型。Ollama 是一个开源的大语言部署服务工具，只需 CPU 即可部署大模型。我们希望通过动手学 Ollama 这一开源教程，帮助学习者快速上手 Ollama ，让每一位大模型爱好者、学习者以及开发者都能在本地部署自己的大模型，进而开发一些大模型应用，让大模型赋能千行百业！

🎯 项目受众

• 希望不受 GPU 资源限制，在本地运行大模型；
• 希望在消费级硬件上进行大模型有效的推理；
• 希望在本地部署大模型，开发大模型应用；
• 希望在本地管理大模型，让本地模型安全可靠。

✨ 项目亮点

本项目旨在使用 CPU 部署本地大模型，虽然目前已经有很多 LLM 相关的教程，但是这些教程中模型基本上都需要 GPU 资源，这对于很多资源受限的学习者不是很友好。因此，本项目通过动手学 Ollama ，帮助学习者快速上手本地 CPU 部署大模型。

📖 内容导航

章节	关键内容	状态
第一章 Ollama 介绍
1.1 Ollama 介绍	基础概念、核心特性	✅
第二章 Ollama 安装与配置		✅
2.1 macOS 安装与配置	macOS 安装、配置	✅
2.2 Windows 安装与配置	Windows 安装、配置	✅
2.3 Linux 安装与配置	Linux 安装、配置	✅
2.4 Docker 安装与配置	Docker 安装、配置	✅
第三章 自定义使用 Ollama	个性化使用	✅
3.1 自定义导入模型	外部模型导入	✅
3.2 自定义模型存储位置	存储路径更改	✅
3.3 自定义在 GPU 中运行	GPU 加速配置	✅
第四章 Ollama REST API
4.1 Ollama API 使用指南	调用规则、参数说明	✅
4.2 Python 中使用 Ollama API	Python 调用	✅
4.3 Java 中使用 Ollama API	Java 调用	✅
4.4 JavaScript 中使用 Ollama API	JavaScript 调用	✅
4.5 C++ 中使用 Ollama API	C++ 调用	✅
4.6 Golang 中使用 Ollama API	Golang 调用	✅
C# 中使用 Ollama API	C# 调用（待更）	🚧
Rust 中使用 Ollama API	Rust 调用（待更）	🚧
Ruby 中使用 Ollama API	Ruby 调用（待更）	🚧
R 中使用 Ollama API	R 调用（待更）	🚧
第五章 Ollama 在 LangChain 中的使用
5.1 Python 中的集成	Python + LangChain 集成	✅
5.2 JavaScript 中的集成	JavaScript + LangChain 集成	✅
第六章 Ollama 可视化界面部署
6.1 FastAPI 部署可视化界面	FastAPI 部署	✅
6.2 WebUI 部署可视化界面	WebUI 部署	✅
第七章 应用案例
7.1 搭建本地 AI Copilot 编程助手	本地编程助手	✅
7.2 Dify 接入本地模型	Dify 集成本地模型	✅
7.3 LangChain 搭建本地 RAG 应用	LangChain + 本地 RAG	✅
7.4 LlamaIndex 搭建本地 RAG 应用	LlamaIndex + 本地 RAG	✅
7.5 LangChain 实现本地 Agent	LangChain + 本地 Agent	✅
7.6 LlamaIndex 实现本地 Agent	LlamaIndex + 本地 Agent	✅
7.7 DeepSeek R1 + Ollama 本地 RAG	DeepSeek R1 + 本地 RAG	✅
...	...	...

注：所有标记（待更新）的内容，以及其他相关的内容，热忱欢迎感兴趣的开发者们 提出 issue 或者 提交 pull request，让我们一起完善这个项目！

想要深度参与的同学可以联系我们，我们会将你加入到项目的维护者中。

🙏 致谢

核心贡献者

• 张友东（Datawhale成员）
• 林通（Datawhale成员）
• 柴春阳（内容创作者）
• 王莹莹（Datawhale成员）
• 曾鑫民（内容创作者）
• 娄天奥（Datawhale成员）
• 杨卓（内容创作者）
• 姜舒凡（Datawhale成员）
• 曹越（内容创作者）
• 王晓亮（Datawhale成员）

特别感谢

• Ollama 官方仓库：https://github.com/ollama/ollama
• 感谢 @Sm1les 对本项目的帮助与支持
• 感谢所有为本项目做出贡献的开发者们 ❤️

Star History

LICENSE

本作品采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。

handy-ollama 快速上手指南

📋 环境准备

系统要求：

• 操作系统：macOS、Windows 10/11、Linux (Ubuntu/Debian/CentOS 等) 或 Docker 环境
• 硬件配置：仅需 CPU 即可运行（支持 GPU 加速可选），推荐内存 8GB 以上
• 网络环境：需能访问 Hugging Face 或 ModelScope（魔搭社区）下载模型

前置依赖：

• 无需复杂的 Python 环境或 CUDA 驱动（基础运行）
• 若使用 Docker，请预先安装 Docker Desktop 或 Docker Engine

---

🚀 安装步骤

根据你的操作系统选择以下一种安装方式：

方案一：macOS / Windows / Linux 原生安装

访问官网或 GitHub Release 页面下载对应系统的安装包：

• macOS: 下载 .dmg 文件并拖拽安装
• Windows: 下载 .exe 安装包一键安装
• Linux: 执行官方一键安装脚本

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

💡 国内加速建议：若下载速度慢，可尝试配置代理或使用国内镜像源拉取模型。

方案二：Docker 部署（推荐跨平台用户）

拉取镜像并启动容器：

docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

验证安装是否成功：

docker exec -it ollama ollama -v

---

🛠️ 基本使用

1. 拉取并运行模型

以最流行的 Llama 3 模型为例，在终端执行以下命令即可自动下载并运行：

ollama run llama3

注：首次运行会自动下载模型文件，后续启动将秒开。

2. 交互式对话

命令执行后进入交互模式，直接输入问题即可：

>>> 你好，请介绍一下你自己
>>> 如何用 Python 实现快速排序？
>>> /bye  (退出对话)

3. 常用管理命令

在另一个终端窗口中，你可以管理本地模型：

# 查看已下载的模型列表
ollama list

# 删除指定模型
ollama rm llama3

# 查看正在运行的模型服务状态
ollama ps

4. 通过 API 调用（开发者必备）

Ollama 默认在 http://localhost:11434 启动服务。使用 curl 测试 API：

curl http://localhost:11434/api/generate -d '{
  "model": "llama3",
  "prompt":"Hello!",
  "stream": false
}'

现在你已经成功在本地 CPU 上部署并运行了大模型！接下来可以探索自定义导入模型、LangChain 集成或搭建 RAG 应用等进阶功能。