ollama 中文使用教程

一、项目速览

入门 · 1 分钟版

Ollama 是一个本地大模型运行引擎，用 Go 语言编写。它的核心能力是让你在自己的电脑上，通过一条命令就能拉起 Gemma、Qwen、DeepSeek 等开源模型，不需要配置 CUDA、Python 虚拟环境或 GPU 驱动——它把整个「模型下载→量化→推理→API 暴露」的流程压缩成了两个单词：ollama run。

一句话判断：如果你需要在本机运行开源 LLM，但不想折腾 llama.cpp 的编译参数或 Hugging Face 的下载流程，Ollama 就是那个「开箱即用」的方案。

截至 2026 年 4 月，Ollama 已支持超过 200 个模型家族（含 Kimi-K2.6、GLM-5.1、MiniMax、DeepSeek 等中国团队模型），Star 数 17.5 万，是目前社区最活跃的本地推理工具之一。它的设计哲学很明确：把「跑一个模型」这件事的门槛降到跟 curl 一样低。

二、核心功能与架构

进阶 · 推荐细读

Ollama 的架构其实非常简洁，不需要理解复杂的推理引擎原理就能上手。它由三个层次组成：

模型仓库层：Ollama 维护了一个中心化的模型索引（ollama.com/library），每个模型以 Modelfile 的形式描述——类似于 Dockerfile，但内容更简单：指定基础模型、参数模板、对话模板、量化精度等。你不需要手动去 Hugging Face 找权重文件，ollama pull gemma4 会自动下载并转换。

运行时层：底层依赖 llama.cpp 进行推理，但 Ollama 把它包装成了 HTTP 服务。启动后，Ollama 在 localhost:11434 监听 REST API，支持 /api/chat、/api/generate、/api/embeddings 等端点。这意味着你可以用任何语言（Python、JS、Go、甚至 curl）调用它。

集成层：这是 Ollama 最近版本的重点。它提供了 ollama launch 子命令，可以直接启动 Claude Code、Codex CLI、Copilot CLI、OpenClaw 等第三方工具的本地版。你不再需要手动配置 API Key 和环境变量——Ollama 帮你完成了模型与工具之间的粘合。

作者视角：如果你是做后端开发的，建议先理解「Ollama = 模型下载器 + 推理服务器 + 工具启动器」这个三层模型。很多人以为 Ollama 是「另一个 ChatGPT」，但它本质上是一个本地推理的 API 网关。你真正的工作流是：Ollama 跑在后台，你的代码或编辑器通过 HTTP 调用它。

三、动手实践

入门

环境准备

安装过程因系统而异。macOS/Linux 一条命令即可：

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

Windows 用户用 PowerShell：

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

安装完成后，验证版本：

ollama --version

最小可运行示例

拉取并运行一个轻量模型（Qwen2.5 0.5B，仅需约 1GB 内存）：

ollama run qwen2.5:0.5b

你应该会看到类似这样的输出：

>>> Send a message (/? for help)

输入一句话测试：

你好，请用一句话解释什么是 REST API。

模型会返回中文回答。按 Ctrl+D 或输入 /bye 退出对话。

如果你想通过代码调用，这是 Python 的最小示例（无需安装 ollama-python 库，直接用 requests）：

import requests

response = requests.post("http://localhost:11434/api/chat", json={
    "model": "qwen2.5:0.5b",
    "messages": [{"role": "user", "content": "用中文说'hello world'"}],
    "stream": False
})

print(response.json()["message"]["content"])

运行前确保 Ollama 服务在后台运行（安装后默认已启动）。如果遇到连接拒绝，手动启动：

ollama serve

常见踩坑

坑 1：模型下载超慢。ollama run 会自动下载模型权重（通常 2-8GB），国内网络可能很慢。解决方案：先 ollama pull qwen2.5:0.5b 看看速度，如果太慢，可以手动从镜像站下载 Modelfile 再 ollama create。

坑 2：显存不够。如果你只有 8GB 显存，不要尝试 ollama run gemma4（需要 24GB+）。用 ollama list 查看已下载模型的大小，优先选 :0.5b、:1.5b 或 :7b 标签。Ollama 默认使用 CPU 推理，加了 --gpu 才用 GPU——但即使 CPU 模式，大模型也会吃满内存。

四、进阶玩法

深入 · 老手可选

自定义 Modelfile

Ollama 真正的威力在于你可以定制模型行为。创建一个 Modelfile：

FROM qwen2.5:7b

# 设置系统提示词
SYSTEM "你是一个只讲冷笑话的助手。每次回答必须包含一个冷笑话。"

# 调整推理参数
PARAMETER temperature 0.9
PARAMETER top_p 0.95
PARAMETER num_ctx 4096

然后构建并运行：

ollama create my-joker --file ./Modelfile
ollama run my-joker

现在这个模型只会讲冷笑话——这在做垂直领域助手（客服、教学、角色扮演）时非常有用。

嵌入向量提取

Ollama 支持 embedding 端点，可用于 RAG 应用：

import requests

response = requests.post("http://localhost:11434/api/embeddings", json={
    "model": "qwen2.5:7b",
    "prompt": "今天天气真好"
})

# 返回 4096 维向量
print(len(response.json()["embedding"]))

作者视角：这个功能我专门测过。很多人以为 embedding 必须用专门的模型（如 text-embedding-ada-002），但 Ollama 上的通用模型也能生成可用的向量——对于原型验证和中小规模 RAG 项目完全够用。如果你要上线，再换成 nomic-embed-text 这类专用模型。

集成到 VS Code

Ollama 官方提供了 VS Code 扩展「AI Toolkit for VS Code」（微软出品）。安装后，在设置中把模型端点指向 http://localhost:11434，即可在编辑器中选中代码后按 Cmd+I 请求解释、重构或生成注释。整个过程不需要网络——你的代码永远不会离开本地。

五、判断与建议