Ollama — 一键运行本地大模型

GitHub: ollama/ollama
Stars: 174,000+ | Language: Go (66.0%) | License: MIT
官网: ollama.com

目录

1. 项目速览
2. 功能概述
3. 适用场景
4. 快速上手
5. 源码架构
6. 实操 Demo
7. 同类对比
8. 参考资源

项目速览

Ollama 是一个为本地运行大语言模型而生的开源工具，目标是让任何人都能在自己的计算机上”一键运行大模型”。项目由 Jeffrey Morgan（前 Docker 员工）发起，后端推理引擎基于 Georgi Gerganov 的 llama.cpp，使用 Go 语言封装了完整的模型下载、量化、加载和服务功能。截至 2026 年 6 月，项目在 GitHub 上已获得 174,000+ Star，成为 AI 开发者本地工具链的事实标准之一。

Ollama 的设计哲学是”零配置”：用户不需要关心 CUDA 版本、Python 环境、模型格式转换等繁琐细节，一条 ollama run 命令即可下载模型并启动交互式对话。它自动检测 CPU 特性集（AVX/AVX2 等）、GPU 型号和显存大小，智能选择最优推理参数。同时提供了完整的 REST API（监听 localhost:11434），让其他应用可以程序化调用本地模型。

Ollama 官方维护了一个模型库（ollama.com/library），收录了 Llama、Mistral、Qwen、Gemma、Phi、DeepSeek 等数百个主流模型，涵盖 1B 到 405B 参数规模，一键即可拉取使用。

功能概述

一键运行模型

Ollama 的核心体验就是简单。安装完成后的第一个命令即可运行模型：

ollama run llama3.2

Ollama 会自动从模型库下载 GGUF 格式的量化模型（通常 4-8GB），加载到内存/显存后进入交互式对话。系统会自动检测 GPU 可用性：NVIDIA GPU 走 CUDA 后端，Apple Silicon 走 Metal 后端，纯 CPU 走 AVX2 优化路径。用户无需感知这些底层细节。

REST API 服务

Ollama 启动后自动在 localhost:11434 提供 HTTP 服务，暴露 /api/generate（文本生成）和 /api/chat（多轮对话）等端点。任何能发 HTTP 请求的语言都能调用：

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "Why is the sky blue?"}],
  "stream": false
}'

官方还提供了 Python 和 JavaScript SDK：

from ollama import chat

response = chat(model='llama3.2', messages=[
  {'role': 'user', 'content': 'Why is the sky blue?'},
])
print(response.message.content)

import ollama from "ollama";

const response = await ollama.chat({
  model: "llama3.2",
  messages: [{ role: "user", content: "Why is the sky blue?" }],
});
console.log(response.message.content);

Modelfile — 自定义模型配方

Ollama 提供 Modelfile（类似 Dockerfile）用于自定义模型配置。你可以指定基础模型、调整温度参数、注入 System Prompt，甚至挂载 GGUF 文件：

FROM llama3.2

# 设置系统提示
SYSTEM "你是一个精通中国古诗词的助手，回答问题时尽量引用古诗词。"

# 设置生成参数
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 4096

# 自定义停止词
PARAMETER stop "用户:"
PARAMETER stop "助手:"

创建并运行自定义模型：

ollama create shici-assistant -f Modelfile
ollama run shici-assistant

自动量化和显存管理

Ollama 使用 llama.cpp 的量化引擎，对下载的原始模型自动进行 INT4（Q4_0 或 Q4_K_M）量化。对于消费级硬件（如 8GB 显存），Ollama 可以将 7B 模型压缩至约 4GB，在 RTX 3060/4060 级别显卡上流畅运行。通过 ollama ps 可以查看当前加载的模型和显存占用。

Ollama 支持模型”热插拔”：当新模型加载时，自动释放上一个模型占用的内存。通过环境变量 OLLAMA_KEEP_ALIVE 可以设置模型在空闲时的保留时间。

多模态支持

Ollama 支持视觉语言模型（VLM），可以理解图像输入：

ollama run llava:13b

进入对话后，在提示中包含图片路径即可：

>>> 请描述这张图片的内容 /path/to/image.jpg

支持的视觉模型包括 LLaVA、llama3.2-vision、gemma3-vision、minicpm-v 等。

多平台与编程集成

Ollama 覆盖 macOS、Linux 和 Windows 三大平台。除直接安装外，还可以通过 Docker 运行：

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

Ollama 还深度集成到开发者常用工具中：可作为 Claude Code、GitHub Copilot CLI、Continue（VS Code 插件）等编码工具的本地模型后端，也可配合 Open WebUI 搭建私有 ChatGPT 风格的 Web 界面。

适用场景

本地 AI 助手

开发者日常工作中需要快速问答、代码解释、文本润色等任务。Ollama 提供零配置的本地 AI 体验，无需网络、无 API 费用、数据隐私完全可控。适合对数据安全和隐私敏感的企业或个人。

离线环境部署

军事、金融、医疗等无法连接外网的场景，Ollama 可以将模型文件离线拷贝后运行。先在有网络的机器上 ollama pull，然后将 ~/.ollama 目录复制到离线机器即可。

IDE/编辑器集成

将 Ollama 作为 Continue（VS Code）、Cursor 或 Neovim 插件的本地推理后端，实现代码补全、错误解释、重构建议等功能，延迟极低且无 API 成本。

原型开发和测试

在开发 LLM 应用时，使用 Ollama 提供的本地 API 替代昂贵的云端 API 进行快速原型迭代。待应用逻辑稳定后，再切换到生产级推理引擎。

个人知识库 RAG

配合 Open WebUI 或自建 RAG 管线，Ollama 可以作为私有知识库的推理后端。将公司文档、个人笔记导入向量数据库，Ollama 提供问答能力，所有数据保存在本地，确保信息安全。

快速上手

安装

macOS / Linux:

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

Windows:

irm https://ollama.com/install.ps1 | iex

其他方式:

# macOS Homebrew
brew install ollama

# Arch Linux
pacman -S ollama

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

拉取和运行模型

# 拉取模型（默认下载 4-bit 量化版）
ollama pull llama3.2          # 3B 参数，约 2GB
ollama pull qwen2.5:7b        # 7B 参数，约 4.4GB
ollama pull deepseek-r1:8b    # 8B 推理模型，约 4.9GB

# 列出已下载的模型
ollama list

# 运行交互对话
ollama run llama3.2

# 运行后常用命令
# /bye      退出
# /show info  查看模型信息
# /load <model>  切换模型
# /save <name>  保存对话

REST API 基础调用

# Chat 格式（推荐）
curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "用中文解释什么是REST API"}
  ],
  "stream": false
}'

# Generate 格式（单轮）
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "写一首关于秋天的五言绝句",
  "stream": false
}'

源码架构

Ollama 使用 Go 语言构建，核心架构清晰，层次分明：

ollama/
├── api/              # API 类型定义（请求/响应结构体）
├── cmd/              # CLI 入口（ollama 命令行）
│   └── cmd.go        # 命令注册：run/pull/list/create/serve/ps/rm
├── server/           # HTTP 服务端
│   ├── routes.go     # REST API 路由注册
│   └── auth.go       # API 认证逻辑
├── llama/            # llama.cpp CGO 绑定
│   └── llama.go      # Go 调用 llama.cpp 的 C 接口
├── model/            # 模型管理
│   ├── models.go     # 模型下载、缓存、列表管理
│   └── modelfile.go  # Modelfile 解析器
├── runner/           # 模型运行器
│   └── ollamarunner/ # 实际推理循环（调用 llama.cpp）
├── format/           # 各模型家族的 prompt 模板（Llama/Mistral/Command R等）
├── template/         # Go template 聊天模板渲染
├── openai/           # OpenAI 兼容 API（/v1/chat/completions）
├── convert/          # 模型格式转换（Safetensors -> GGUF）
├── discover/         # GPU 自动发现（CUDA/Metal/CPU 特性检测）
├── kvcache/          # KV Cache 管理
├── tokenizer/        # 分词器加载
├── parser/           # 命令行输出解析
├── progress/         # 下载进度条
├── ml/               # 机器学习工具层
├── fs/               # 文件系统抽象
├── types/            # 共享类型定义
├── version/          # 版本注入
├── scripts/          # 构建和发布脚本
├── docs/             # 文档
└── main.go           # 主入口

核心模块说明：

• cmd/cmd.go：定义了 ollama 命令行的所有子命令（run、pull、list、create、serve、ps、rm、push、show），每个命令对应一个执行函数。
• server：基于 Go 标准库 net/http 构建的 HTTP 服务器，提供 /api/generate、/api/chat、/api/embeddings 等 REST 端点，同时实现了 /v1/chat/completions 的 OpenAI 兼容端点。
• **llama/**：Go 与 C 之间的桥梁。通过 CGO 调用 llama.cpp 的动态链接库，将 Go 层的请求参数传递给 C++ 推理引擎，并将生成结果返回。
• **runner/**：模型的推理运行器，负责创建 llama.cpp 的推理上下文、管理 token 生成循环、控制停止条件、处理流式输出等。每个模型加载时创建独立的 runner 实例。
• model/models.go：负责从 Ollama 模型库（registry.ollama.ai）拉取 GGUF 文件，计算 SHA256 校验，管理本地模型注册表（~/.ollama/models/ 下的 manifest 文件）。
• **format/**：包含每个模型家族的 prompt template（ChatML、Llama3、Mistral、Command R 等），用于将结构化的 messages 列表渲染为模型理解的原始文本。

实操 Demo

完整示例：搭建私有中文技术助手

1. 安装 Ollama 并拉取模型

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

# 拉取中文能力较好的模型
ollama pull qwen2.5:7b
ollama pull nomic-embed-text    # Embedding 模型，用于 RAG

2. 创建自定义 Modelfile

cat > Modelfile << 'EOF'
FROM qwen2.5:7b

SYSTEM """你是一个专业的中文技术写作助手。你的职责包括：
1. 将复杂的技术概念用通俗易懂的中文解释清楚
2. 为代码片段写清晰的中文注释
3. 帮助润色和校对中文技术文档
4. 回答问题时尽量给出代码示例

请始终保持专业、严谨、友善的态度。"""

PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER top_k 40
PARAMETER num_ctx 8192
EOF

ollama create tech-writer -f Modelfile

3. 启动 REST API 服务（如未运行）

# 启动服务（默认监听 11434 端口）
ollama serve

4. Python 客户端：批量处理文本

import json
import ollama

# 测试自定义模型
questions = [
    "请用通俗易懂的语言解释什么是 Docker。",
    "Python 中的 GIL 是什么？为什么它很重要？",
    "什么是 CI/CD？请给出一个实际工作流程的例子。",
]

for i, q in enumerate(questions):
    response = ollama.chat(
        model="tech-writer",
        messages=[{"role": "user", "content": q}],
    )
    print(f"=== 问题 {i+1} ===")
    print(f"Q: {q}")
    print(f"A: {response.message.content[:200]}...")
    print(f"Token 数: {response.eval_count}")
    print()

# 使用流式输出
print("=== 流式输出示例 ===")
stream = ollama.chat(
    model="tech-writer",
    messages=[{"role": "user", "content": "写一个 Python 快速排序的代码实现，要带中文注释。"}],
    stream=True,
)
for chunk in stream:
    print(chunk.message.content, end="", flush=True)
print("\n")

5. 使用 curl 测试各种 API 端点

# Chat API（流式）
curl -N http://localhost:11434/api/chat -d '{
  "model": "tech-writer",
  "messages": [{"role": "user", "content": "什么是微服务架构？优点和缺点是什么？"}],
  "stream": true
}'

# Generate API（非流式）
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "写一个 Python 函数，将列表中的重复元素去重，保持原始顺序。",
  "stream": false,
  "options": {
    "temperature": 0.2,
    "num_predict": 256
  }
}' | jq -r '.response'

# Embeddings API
curl http://localhost:11434/api/embeddings -d '{
  "model": "nomic-embed-text",
  "input": "人工智能正在改变软件开发的范式"
}' | jq '.embedding[:5]'

# 查看已加载模型
curl http://localhost:11434/api/ps | jq

# 列出本地模型
ollama list

6. 用 Python SDK 构建带 System Prompt 的问答循环

import ollama

SYSTEM_PROMPT = """你是一个精通 Git 的助手。当用户问到 Git 相关问题时：
1. 先解释概念
2. 给出具体的命令示例
3. 指出常见陷阱和最佳实践
"""

messages = [{"role": "system", "content": SYSTEM_PROMPT}]

while True:
    user_input = input("\n用户: ")
    if user_input.lower() in ("exit", "quit", "q"):
        print("再见！")
        break

    messages.append({"role": "user", "content": user_input})
    response = ollama.chat(
        model="tech-writer",
        messages=messages,
        stream=True,
    )

    full_response = ""
    print("助手: ", end="", flush=True)
    for chunk in response:
        content = chunk.message.content
        print(content, end="", flush=True)
        full_response += content
    print()

    messages.append({"role": "assistant", "content": full_response})

7. 清理和管理

# 查看模型显存占用
ollama ps

# 停止某个模型（释放显存）
ollama stop tech-writer

# 删除模型
ollama rm tech-writer

# 清理未使用的模型缓存
ollama list
# 手动删除 ~/.ollama/models/blobs/ 下的文件

同类对比

特性	Ollama	llama.cpp	vLLM	LM Studio
安装	一条命令	git clone && make	pip install	下载安装包
配置	零配置	需要指定参数	需要配置	GUI 配置
推理引擎	llama.cpp	原生的 C++	Python + CUDA	llama.cpp
模型来源	官方模型库 + HF	HF GGUF	HF Hub	HF + 本地
自动量化	内置	手动	配置项	自动
API	REST (非标准)	OpenAI 兼容 (llama-server)	OpenAI 兼容	REST (非标准)
多 GPU	不支持	有限支持	完整支持	不支持
吞吐量	中等	中等	极高	中等
显存管理	自动	手动	自动分页	自动
UX	CLI + API	CLI + API	CLI + API	GUI
平台	Mac/Win/Linux	全平台	Linux 为主	Mac/Win/Linux
Star	174k	117k	82.9k	28k
适合人群	开发者/个人	开发者/嵌入端	企业/生产环境	非技术用户

选型建议：

• Ollama 是本地快速体验模型的最佳选择，零配置、一条命令运行。适合日常开发辅助、原型验证、离线使用，但生产环境吞吐量有限。
• llama.cpp 是 Ollama 的底层引擎，适合需要精细控制推理参数、部署到边缘设备或追求极致性能的开发场景。
• vLLM 是生产级 API 服务的标准选择，适合需要高并发、多用户的服务端场景，但需要 GPU 和一定的配置工作。
• LM Studio 提供图形界面，适合不想接触命令行的非技术用户，但灵活性和自动化能力有限。

参考资源

• 官方网站: https://ollama.com
• GitHub 仓库: https://github.com/ollama/ollama
• 模型库: https://ollama.com/library
• 文档: https://docs.ollama.com
• Modelfile 参考: https://docs.ollama.com/modelfile
• llama.cpp 项目: https://github.com/ggerganov/llama.cpp