Ollama 源码拆解:为什么它能把本地大模型做得这么顺手?

开源拆解 · 项目：Ollama源码路径：/Users/chiyi/Desktop/youth/ai/source-code/ollama主语言：Go核心定位：本地大模型运行时、模型分发系统、OpenAI 兼容 API 服务

如果你在本地跑过大模型，大概率遇到过这些问题：

模型文件去哪下？下完怎么放？不同模型的 prompt 模板怎么写？GPU 能不能自动用上？换一个模型会不会爆显存？如果我想让 Open WebUI、Dify、Cherry Studio 或自己的应用调用它，接口又该怎么接？

Ollama 让这些问题变得很简单：

ollama run llama3.2

或者：

curl http://localhost:11434/api/chat -d '{  "model": "llama3.2",  "messages": [    {"role": "user", "content": "用一句话解释什么是量化"}  ],  "stream": false}'

你看到的是一个命令行工具，背后其实是一套完整的本地 AI 运行时。

一句话概括：Ollama 把“下载模型、保存模型、加载模型、调度显存、启动推理后端、暴露 HTTP API”这些脏活累活封装成了一个本地服务。

它不是一个大模型，也不是单纯的 llama.cpp 图形壳。更准确地说，它像本地大模型世界的 Docker：模型像镜像一样被拉取、创建、命名、复用；推理后端像容器运行时一样被按需启动；上层应用只需要通过稳定 API 使用它。

Ollama 到底做了什么？

从用户角度看，Ollama 主要做三件事。

第一，管理模型。

你可以 ollama pull 下载模型，ollama list 查看模型，ollama rm 删除模型，ollama create 基于 Modelfile 创建自定义模型。模型不只是一个 .gguf 文件，还包括模板、参数、系统提示词、license、LoRA adapter、多模态 projector 等元信息。

第二，运行模型。

当你请求 llama3.2 时，Ollama 会找到模型文件，判断模型能力，合并默认参数和请求参数，探测 CPU/GPU 环境，决定怎么加载模型。如果模型还没有加载，它会启动一个 runner；如果已经加载，就复用已有 runner。

第三，提供接口。

Ollama 对外暴露两类接口：

接口类型	示例	作用
Ollama 原生 API	`/api/chat` 、`/api/generate`、`/api/embed`	本地模型调用和管理
OpenAI 兼容 API	`/v1/chat/completions` 、`/v1/embeddings`、`/v1/models`	让现有 OpenAI 生态工具低成本接入

所以很多工具只需要把 base URL 改成 http://localhost:11434/v1，就能把模型切到本地。

从源码看总体架构

Ollama 的主程序入口非常薄：

funcmain() {    cobra.CheckErr(cmd.NewCLI().ExecuteContext(context.Background()))}

真正的逻辑被拆进几个核心目录：

目录	作用
`cmd/`	命令行入口，负责 `run`、`pull`、`create`、`serve` 等命令
`server/`	HTTP 服务、路由、模型管理、推理请求处理
`server/sched.go`	Scheduler 调度器，负责模型加载、复用、驱逐和并发
`llm/`	管理 `llama-server` 子进程，把 Go 请求转成后端 HTTP 请求
`manifest/`	模型 manifest 和 blob 路径管理
`api/`	API 请求/响应结构体
`fs/ggml/`	GGUF 元信息解析
`discover/` 、`ml/`	GPU/系统信息探测、显存估算
`x/imagegen` 、`x/mlxrunner`	图片生成、MLX runner 等扩展能力

可以把它理解成四层：

用户 / 应用  ↓CLI 或 HTTP API  ↓Ollama Server：路由、模型解析、参数合并、模板渲染  ↓Scheduler：决定用哪个 runner，是否加载、复用、驱逐  ↓Runner：llama-server / MLX / imagegen  ↓CPU / GPU 执行真正推理

这也是 Ollama 代码最值得学习的地方：它没有把所有东西揉成一个巨大的“推理函数”，而是把模型管理、请求协议、资源调度、推理后端拆开了。

一次 `ollama run` 背后发生了什么？

很多人以为 ollama run llama3.2 就是直接启动模型。源码里其实是两段式。

cmd.NewCLI() 注册命令时，会注册 run、serve、pull、create 等子命令。执行 ollama run 时，CLI 会先检查本地服务是否已经运行。如果服务没起来，它会在后台启动：

ollama run llama3.2  ↓检查 localhost:11434 是否有 Ollama server  ↓没有就启动 ollama serve  ↓CLI 通过 HTTP 调用本地 server  ↓server 负责真正加载模型和推理

也就是说，ollama run 本身更像一个客户端。真正常驻的是 ollama serve。

这个设计有一个好处：命令行、Python SDK、JavaScript SDK、Open WebUI、curl 请求，最后都走同一个本地服务。模型只需要加载一次，多种客户端都能复用。

HTTP API 层：所有能力的门面

服务启动时，server.Serve() 会创建 Server，初始化模型缓存和 Scheduler，然后注册路由。

核心路由在 server/routes.go 的 GenerateRoutes()：

GET  /api/versionGET  /api/tagsPOST /api/showPOST /api/pullPOST /api/createPOST /api/chatPOST /api/generatePOST /api/embedGET  /api/psPOST /v1/chat/completionsPOST /v1/completionsPOST /v1/embeddingsGET  /v1/modelsPOST /v1/messages

这里有一个很关键的设计：OpenAI、Anthropic 兼容接口不是另起一套推理系统，而是通过 middleware 把请求转换成 Ollama 内部的 ChatRequest 或 GenerateRequest，最后仍然进入 ChatHandler / GenerateHandler。

这意味着 Ollama 维护的是一条核心推理链路，而不是为每种协议写一套后端。

模型是怎么存的？

Ollama 的模型存储方式很像 OCI 镜像。

它把模型拆成两类东西：

manifests/  记录一个模型由哪些层组成blobs/  保存真正的内容，文件名基于 sha256 digest

源码里的 manifest.BlobsPath() 会校验 digest，只接受形如 sha256:xxxx 或 sha256-xxxx 的内容寻址路径。manifest.WriteManifest() 则把模型的 config 和 layers 写成 manifest。

一个模型可能包含：

层	说明
model layer	真正的 GGUF 权重文件
config layer	模型架构、能力、格式等配置
template layer	prompt 模板
params layer	temperature、num_ctx、stop 等默认参数
system layer	系统提示词
adapter layer	LoRA adapter
projector layer	多模态 projector
license layer	许可证信息

当你调用 GetModel() 时，Ollama 会先解析模型名，再读取 manifest，然后逐层把这些内容还原成一个 Model 对象。

这解释了为什么 ollama show --modelfile llama3.2 能还原出一个 Modelfile，也解释了为什么 ollama create 可以基于一个基础模型叠加模板、参数和系统提示词。

从工程角度看，这套设计有三个好处：

复用：多个模型可以共享相同的权重 blob。
校验：内容由 sha256 标识，便于完整性校验。
组合：模型权重、模板、参数、adapter 可以独立管理。

推理请求是怎么流转的？

以 /api/chat 为例，一次请求大致会经历这些步骤：

POST /api/chat  ↓ChatHandler 解析 JSON  ↓解析 model name，找到本地 manifest  ↓GetModel 读取模型配置、模板、参数、权重路径  ↓modelOptions 合并模型默认参数和请求参数  ↓scheduleRunner 向 Scheduler 申请 runner  ↓Scheduler 复用已加载模型，或者启动新 runner  ↓ChatHandler 渲染 prompt / 处理 tools / thinking / structured output  ↓llm.LlamaServer 调用 llama-server  ↓token 流式返回给客户端

这里有两个容易被忽略的点。

第一，模型能力会被检查。

如果你拿 embedding 模型去聊天，或者拿普通文本模型去做图片能力，Ollama 会根据模型的 capability 拦住请求。

第二，请求参数不是直接透传。

Ollama 会合并三个来源的参数：

api.DefaultOptions()  + Modelfile 里的 PARAMETER  + 当前请求里的 options

所以一个模型可以自带默认行为，而一次请求又可以临时覆盖它。

Scheduler：Ollama 最核心的“调度室”

如果只看 API 层，Ollama 似乎只是一个 HTTP 包装器。但真正让它好用的是 server/sched.go 里的 Scheduler。

本地大模型最麻烦的资源不是 CPU，而是内存和显存。

一个 7B 模型可能占几 GB，一个 70B 模型可能占几十 GB。用户连续请求不同模型时，如果来一个就加载一个，很快就会爆显存；如果每次请求完都卸载，体验又会非常慢。

Scheduler 要解决的就是这个矛盾。

它内部维护了几类 channel 和状态：

字段	作用
`pendingReqCh`	等待加载或分配 runner 的请求队列
`finishedReqCh`	请求结束通知
`expiredCh`	runner 空闲超时，需要卸载
`loaded`	当前已加载的模型 runner
`activeLoading`	当前正在加载的模型，避免多个模型同时抢资源

调度逻辑可以简化成：

请求来了  ↓这个模型已经加载了吗？  ├─ 是：refCount +1，直接复用  └─ 否：进入 pending 队列       ↓       探测 GPU 和系统内存       ↓       估算模型加载需要的显存       ↓       能放下：启动 runner       放不下：找一个空闲 runner 卸载       ↓       请求结束后 refCount -1       ↓       空闲超过 keep_alive 后卸载

这就是为什么你第一次请求一个模型会慢，第二次会快很多：第一次在加载权重，第二次只是复用已经常驻的 runner。

这也是 keep_alive 参数的意义。它不是“让请求持续多久”，而是“请求结束后模型继续留在内存里多久”。

runner：真正推理的是谁？

Ollama 本身不直接在 Go 里做矩阵乘法。对于 GGUF 模型，它会启动一个 llama-server 子进程。

llm/llama_server.go 文件开头就写得很清楚：这个文件负责把 llama-server 二进制包装成子进程，并通过 HTTP 和它通信。

启动时，Ollama 会：

找到 llama-server 二进制；
分配一个本地端口；
拼出启动参数；
设置 GPU 相关环境变量；
启动子进程；
轮询 /health 等它加载完成。

启动参数里有几个重要选项：

--model <模型路径>--port <本地端口>--host 127.0.0.1--no-webui--offline-c <上下文长度 * 并发数>-np <并发数>

如果用户指定了 num_gpu，会加上 -ngl 控制 GPU offload 层数；如果没有指定，就让 llama-server 自动判断。线程数、flash attention、KV cache 类型、LoRA、projector 等也会在这里组装。

这层封装很关键：Ollama 负责产品和工程体验，llama.cpp/llama-server 负责高性能推理。两者边界清晰。

token 是怎么流式返回的？

当 runner 准备好后，Ollama 会向 llama-server 发请求。

对于 Go 侧渲染 prompt 的模型，会调用：

POST http://127.0.0.1:<runner-port>/completion

对于可以使用 GGUF 内置 chat template 的模型，会调用：

POST http://127.0.0.1:<runner-port>/v1/chat/completions

llama-server 返回的是 SSE 风格的流。Ollama 用 scanner 一行行读取 data:，反序列化成 token 响应，再转换成自己的 api.ChatResponse 或 api.GenerateResponse。

所以完整链路其实是两段流：

llama-server → Ollama server → 客户端

客户端看到的流式输出，不是模型直接吐给你的，而是 Ollama 在中间做了一层协议转换、错误处理、指标统计和格式整理。

最终响应里常见的这些字段：

{"eval_count": 128,"eval_duration": 1234567890,"prompt_eval_count": 32,"load_duration": 456789000}

就是在这条链路里累计出来的。它们可以用来判断模型加载时间、prompt 处理时间、生成速度。

Modelfile：Ollama 的模型“配方”

Ollama 最实用的设计之一是 Modelfile。

如果说 GGUF 是权重，Modelfile 就是模型的使用说明和默认配置。

一个简单例子：

FROM llama3.2PARAMETER temperature 0.7PARAMETER num_ctx 4096SYSTEM """你是一个严谨的中文技术助手，回答要有结构、有例子。"""

然后执行：

ollama create my-assistant -f Modelfileollama run my-assistant

源码里 parser.ParseFile() 会解析 Modelfile，CreateHandler 会把它转换成模型创建请求。最终，模板、参数、系统提示词等内容会作为不同 layer 写入 manifest/blob 存储。

这让 Ollama 的模型不只是“一个权重文件”，而是一个可分发、可复现的运行配置。

在团队内部，这个能力非常实用。你可以把某个业务助手封装成一个模型名：

customer-support:latestsql-reviewer:latestdoc-writer:latest

每个模型背后使用同一个基础权重，但拥有不同的 system prompt、参数、模板和上下文策略。

实用方式一：作为本地 OpenAI 替代服务

很多应用支持 OpenAI API，只要能配置 base URL，就可以直接接 Ollama。

常见配置是：

Base URL: http://localhost:11434/v1API Key: ollamaModel: llama3.2

API Key 通常只是为了兼容客户端校验，本地 Ollama 默认不依赖真实 OpenAI key。

Python 示例：

from openai import OpenAIclient = OpenAI(    base_url="http://localhost:11434/v1",    api_key="ollama",)resp = client.chat.completions.create(    model="llama3.2",    messages=[        {"role": "user", "content": "解释一下 Ollama 的作用"}    ],)print(resp.choices[0].message.content)

这种方式适合：

本地开发调试；
内网环境不能访问外部模型；
对隐私有要求的数据分析；
给 Agent、编辑器插件、知识库工具提供本地模型。

实用方式二：用 `keep_alive` 控制体验和资源

如果你发现第一次调用慢，后面变快，这是正常现象。第一次加载模型，后续复用 runner。

如果你希望模型请求结束后马上释放资源：

curl http://localhost:11434/api/generate -d '{  "model": "llama3.2",  "prompt": "hello",  "keep_alive": 0}'

如果你希望模型在内存里多留一会儿：

curl http://localhost:11434/api/chat -d '{  "model": "llama3.2",  "messages": [{"role": "user", "content": "继续"}],  "keep_alive": "10m"}'

背后对应的就是 Scheduler 的 sessionDuration 和空闲过期机制。

生产使用时，可以按场景调整：

场景	建议
单人本地聊天	keep_alive 可以长一点，减少重复加载
多模型频繁切换	keep_alive 短一点，避免资源被占住
内存较小机器	限制并发，减少常驻模型
固定服务模型	预热模型，保持常驻

实用方式三：理解几个关键参数

Ollama 的参数很多，但刚开始最该理解这几个。

num_ctx：上下文窗口大小。它决定模型最多能看多少 token。越大越能装长文本，但内存和显存压力也越大。

temperature：采样温度。越高越发散，越低越稳定。写作可以高一点，代码和事实问答可以低一点。

num_predict：最多生成多少 token。设太小会截断，设太大可能拖慢响应。

top_k / top_p / min_p：控制采样范围。通常不用一上来就调，先调 temperature。

num_gpu：控制 GPU offload。默认情况下 Ollama 会让后端自动判断；只有你明确知道硬件和模型适配时才建议手动改。

num_thread：CPU 线程数。同样不建议盲目拉满，因为线程过多可能带来调度开销。

一个实用原则是：先让 Ollama 自动调度，遇到具体瓶颈后再调参数。

实用方式四：用 API 观测模型状态

Ollama 不只是能生成文本，还能告诉你当前运行状态。

查看本地模型：

curl http://localhost:11434/api/tags

查看模型详情：

curl http://localhost:11434/api/show -d '{"model": "llama3.2"}'

查看正在运行的模型：

curl http://localhost:11434/api/ps

这些接口对应源码里的 ListHandler、ShowHandler、PsHandler。如果你要把 Ollama 接进自己的平台，这几个接口可以用来做模型列表、详情页、运行状态页。

Ollama 的设计取舍

Ollama 好用，是因为它做了几个非常明确的取舍。

第一，Go 负责工程外壳，C/C++ 后端负责推理性能。

Go 适合写 CLI、HTTP 服务、并发调度、文件管理；llama.cpp 适合做高性能推理。Ollama 没有试图在 Go 里重写推理内核，而是通过子进程和 HTTP 把两者连接起来。

第二，本地优先，但协议兼容云生态。

原生 API 保留了 Ollama 自己的模型管理能力，OpenAI 兼容 API 又让大量现成应用可以接入。这是它传播很快的重要原因。

第三，模型不是文件，而是可组合资产。

manifest/blob/Modelfile 让模型具备了版本化、复用和分发的基础。你可以把权重、模板、参数、adapter 组合成一个更高层的“模型产品”。

第四，显存管理交给 Scheduler，而不是交给用户记忆。

用户不需要手动启动/停止每个模型。Scheduler 会根据请求、空闲时间、资源情况去复用或卸载 runner。

如果你要读 Ollama 源码，建议按这个顺序

不要从仓库根目录漫无目的地读。更高效的顺序是：

第一步，看 CLI 入口：

main.gocmd/cmd.go

理解 ollama run、ollama serve、ollama pull 最后都在做什么。

第二步，看路由：

server/routes.go

重点看 GenerateRoutes()、ChatHandler()、GenerateHandler()、scheduleRunner()。

第三步，看模型解析：

server/images.gomanifest/manifest.gomanifest/paths.goparser/parser.go

弄懂 manifest、blob、Modelfile 如何组成一个模型。

第四步，看调度器：

server/sched.go

重点理解 pendingReqCh、loaded、runnerRef、processPending()、processCompleted()。

第五步，看 runner：

llm/server.gollm/llama_server.go

理解 Ollama 如何启动 llama-server，如何等待 /health，如何把 SSE token 流转换回客户端响应。

读完这条线，你基本就能理解 Ollama 的主干。

可以从 Ollama 学到什么？

如果你在做 AI 工程系统，Ollama 给了几个很好的范式。

第一，把复杂能力收敛到稳定接口。

底层可以有 llama.cpp、MLX、imagegen、不同 GPU 后端，但上层仍然是统一的 /api/chat 和 /v1/chat/completions。

第二，把重资源做成可调度对象。

模型加载不是普通函数调用，而是资源占用很大的运行时对象。Ollama 用 Scheduler 管它的生命周期，这是本地 AI 系统最该学的一点。

第三，把配置产品化。

Modelfile 把模板、参数、系统提示词变成可复用资产，降低了团队共享模型行为的成本。

第四，兼容生态比重新发明协议更重要。

OpenAI 兼容接口让 Ollama 直接进入了现有工具链。对基础设施项目来说，这是非常聪明的增长方式。

总结

Ollama 的核心价值，不是“能在本地跑一个模型”这么简单。

它真正解决的是本地大模型工程化的最后一公里：

模型怎么下载、命名、存储和复用；
模板、参数、系统提示词怎么和权重绑定；
多个请求如何复用已加载模型；
显存不足时如何排队、驱逐和重试；
如何把本地模型包装成标准 HTTP 服务；
如何让 OpenAI 生态应用几乎无缝接入。

如果把大模型权重比作发动机，Ollama 做的就是整车系统：钥匙、油路、仪表盘、散热、换挡、保养接口都给你装好了。

对普通用户，它是“本地跑模型最简单的方式”。

对开发者，它是“本地 AI Runtime 的参考实现”。

对想做 AI 基础设施的人，Ollama 最值得学的不是某个接口怎么写，而是它背后的工程判断：把模型当资产管理，把推理当服务暴露，把显存当稀缺资源调度，把生态兼容当产品能力。

这才是它真正跑通本地大模型体验的原因。