# 把模型搬回电脑：用 Ollama 跑通本地对话与 API

> 前三集里，工具虽然装在电脑上，真正负责回答的模型却一直在云端。今天只升级一件事：把模型下载到自己的电脑，让它不调用云端模型也能回复。

![本集主线：安装 Ollama、让轻量模型开口、再用本地 API 调用它](images/01-episode-guide.png)<!-- display-width:520 -->

**这一集，只做一件事**

让一个轻量模型在 Ollama 应用、终端和本地 API 中都回复我们。

- **预计用时**：约 20～30 分钟，模型下载时间另算。
- **你要准备**：Windows 10 22H2 或更新版本、稳定网络，以及至少约 5 GB 可用磁盘空间。
- **通关标志**：聊天窗口、终端和 API 都收到本地模型的回复。
- **电脑配置有限也没关系**：主线只下载一个约 398 MB 的轻量模型。

先让这个小家伙开口，其他复杂玩法全部放到通关以后。

**完全新手先看这里：** 主线只使用 Ollama 应用和 Windows 自带的 PowerShell，不需要 VS Code、Python、Claude Code 或 WorkBuddy。后面看到这些名字时都属于选做，可以放心跳过。

- Ollama：负责下载和运行本地模型。
- PowerShell：Windows 自带的命令窗口，本篇也把它叫作“终端”。
- 浏览器：只用于打开官方下载页，Windows 自带的 Edge 就够用。

[Ollama Windows 文档](https://docs.ollama.com/windows)说明程序安装至少需要约 4 GB，模型文件还会额外占空间；加上本集约 398 MB 的轻量模型，建议先预留至少约 5 GB。

## 1. 安装 Ollama：先请来一位“本地模型管家”

今天要用的工具叫 **Ollama**。可以先把它理解成“本地模型管家”：它负责下载、保存和运行模型，并给程序留一个调用入口。

从 [Ollama 官方网站](https://ollama.com/)进入下载，不要从不明镜像、网盘或第三方软件站获取安装包。

![从 Ollama 官方网站下载 Windows 安装程序](images/02-ollama-download.png)<!-- display-width:600 -->

Windows 用户直接下载安装程序即可。根据 [Ollama Windows 文档](https://docs.ollama.com/windows)，当前要求 Windows 10 22H2 或更新版本；安装程序不要求管理员权限，安装后 Ollama 会在后台运行。

安装完成后，按 Windows 键，搜索 `PowerShell` 并普通打开，不要选择“以管理员身份运行”。如果打开的是 Windows Terminal，只要命令行前面有 `PS` 也可以；可参考 [Microsoft PowerShell 入门](https://learn.microsoft.com/en-us/powershell/scripting/learn/ps101/01-getting-started?view=powershell-7.6)。

第一次只做两条自检：

```powershell
$PSVersionTable.PSVersion
Get-Command Invoke-RestMethod
```

两条都有输出，说明本篇需要的 PowerShell 已经准备好，不用另外安装 PowerShell 7。教程代码框上方的 `powershell` 是语言标签，命令行前面的 `PS C:\...>` 是提示符，都不用复制。

关闭旧终端，再打开一个新的 PowerShell，执行：

```powershell
ollama --version
ollama list
```

**看到这个就算过关：** 第一条命令显示版本号；第二条命令即使没有模型，也能正常返回列表。

**如果提示找不到 `ollama`：** 先重新打开终端，再从开始菜单启动一次 Ollama。

## 2. 选择今天的小模型：先轻装上阵

现在才需要认识模型名：

```text
qwen2.5:0.5b
```

不用背，也不用先理解名字。根据 [Ollama 的 Qwen2.5 模型页](https://ollama.com/library/qwen2.5)，这个版本下载体积约 398 MB，适合先验证链路。

打开 Ollama 应用，在模型选择器中搜索并选择它：

![在模型选择器中搜索并选择 qwen2.5:0.5b](images/03-small-model-select.png)<!-- display-width:560 -->

第一次发送消息时，Ollama 会先下载模型。

![第一次使用时，Ollama 会先把模型下载到本地](images/04-small-model-download.png)<!-- display-width:560 -->

**看到这个就算过关：** 下载进度持续前进，最后进入可输入消息的对话界面。

模型库和下载界面显示的数字可能略有差异，只要下载正常完成，不必追求每个数字完全一致。

## 3. 第一次成功：让电脑自己回一句话

输入一个很短的问题：

```text
写一首关于程序员的短诗。
```

![Ollama 应用已经能完成一轮基础对话](images/05-small-model-chat.png)<!-- display-width:600 -->

只要收到回复，第一个里程碑就完成了：模型文件已经下载到电脑，Ollama 能在本机加载并调用它。

回复和截图不完全一样很正常，大模型不是复读机。这里不评诗，只确认它已经开口。

现在再看名字：`qwen2.5` 是模型家族，`0.5b` 表示它大约有 5 亿参数。这只是帮助你识别轻量版本，不需要记忆。

## 4. 再走一步：在终端里和同一个模型说话

打开 PowerShell，先查看已经下载的模型：

```powershell
ollama list
```

确认列表中出现 `qwen2.5:0.5b`，再执行：

```powershell
ollama run qwen2.5:0.5b
```

输入：

```text
只回复：终端也连接成功
```

![终端列出本地模型并运行 qwen2.5:0.5b](images/06-small-model-cli.png)<!-- display-width:600 -->

**看到这个就算过关：** 终端中出现模型回复。

这说明同一个本地模型不只会在聊天窗口工作，也能被命令行调用。退出对话输入：

```text
/bye
```

今天只需要记住两个命令：

- `ollama run 模型名`：运行模型并进入对话。
- `ollama list`：查看已经下载的模型。
其他命令真正需要时再查，不用现在背命令表。

## 5. 核心通关：让程序调用本地模型

第一集里我们把 API 理解为“程序之间传话的窗口”。Ollama 也在电脑上开了这样一个窗口，默认地址是：

```text
http://localhost:11434
```

`localhost` 就是“这台电脑自己”。先在 PowerShell 检查窗口是否打开：

```powershell
Invoke-RestMethod http://localhost:11434/api/version
Invoke-RestMethod http://localhost:11434/api/tags
```

**看到这个就算过关：** 返回版本信息，并在模型列表中看到 `qwen2.5:0.5b`。

接着复制下面这段请求。第一次不用逐行看懂，先跑通：

```powershell
$body = @{
    model = "qwen2.5:0.5b"
    messages = @(
        @{
            role = "user"
            content = "只回复：Ollama 本地调用成功"
        }
    )
    stream = $false
} | ConvertTo-Json -Depth 5

$result = Invoke-RestMethod `
    -Uri "http://localhost:11434/api/chat" `
    -Method Post `
    -ContentType "application/json; charset=utf-8" `
    -Body $body

$result.message.content
```

本次实验返回：

```text
Ollama 本地调用成功。
```

**看到这个就算通关：** 最后一行打印出模型回复。

[Ollama Chat API 文档](https://docs.ollama.com/api/chat)要求请求里提供模型名和消息数组。这里把 `stream` 设为 `false`，只是为了让 PowerShell 一次拿到完整结果。

**如果访问失败：** 先确认 Ollama 正在运行，再重新执行版本检查命令。不要一上来改防火墙或重装软件。

## 6. 到这里，本集已经完成

现在核对三项：

1. Ollama 应用能让轻量模型回复。
2. `ollama run` 能在终端收到回复。
3. `/api/chat` 能把回复交给 PowerShell。

三项都完成，就可以放心收工。你已经把“云端模型 API”换成了“电脑里的模型 API”。

现在回头看，刚才的链路其实很简单：

![刚才的主链路：程序通过 Ollama 调用电脑里的模型；联网能力是另一条支线](images/07-local-inference-diagram.png)<!-- display-width:520 -->

- **模型文件**：真正负责理解和生成。
- **Ollama**：负责下载、加载模型，并提供调用入口。
- **你的程序**：把问题发给 Ollama，再接住回复。

根据 [Ollama API 认证说明](https://docs.ollama.com/api/authentication)，本机访问 `http://localhost:11434` 不需要 API Key。正因为如此，不要把 11434 端口直接开放到公网。

还要记住一个边界：**“本地模型”描述的是推理发生在哪里，不代表下载模型、更新软件、网页搜索和第三方工具都不需要联网。**

### 6.1 选做一分钟：复用第一集的 Python 代码

只有做过第一集，并且下面的检查打印 `OK`，才继续这一小节；否则直接跳过，不影响本集通关。

```powershell
python -c "from openai import OpenAI; print('OK')"
```

检查通过后，可以把 OpenAI SDK 的地址换成本机：

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",
)

response = client.chat.completions.create(
    model="qwen2.5:0.5b",
    messages=[
        {"role": "user", "content": "只回复：本地模型已连接"}
    ],
)

print(response.choices[0].message.content)
```

Ollama 提供 [OpenAI 兼容接口](https://docs.ollama.com/api/openai-compatibility)。这里的 `api_key="ollama"` 只是满足 SDK 的参数形式，本地 Ollama 会忽略它，它不是真实密钥。

## 7. 选做挑战：把本地模型接进 AI 工具

> 下面已经不是通关必需项。它会多下载约 7.6 GB 的模型，也更吃内存和显存。电脑空间紧张，或只想理解本地 API，可以直接跳到第 11 节看总结。

能聊天，不代表能稳定写文件、调用工具。为了验证这条边界，本次实验又用了一个更强的模型：`gemma4:12b`。

[Gemma 4 模型页](https://ollama.com/library/gemma4)显示，`gemma4:12b` 下载体积约 7.6 GB，并支持工具调用等能力。模型文件 7.6 GB 不等于只需要 7.6 GB 内存；运行时还要给系统、上下文和客户端留空间。

下载并运行：

```powershell
ollama pull gemma4:12b
ollama run gemma4:12b
```

本次实验环境是 Windows 11、Intel i7-10700、32 GB 内存和 RTX 3060 12 GB。这只是实验记录，不是官方最低配置。

### 7.1 先用 Claude Code 做连接测试

Claude Code 是能读取代码、编辑文件和运行命令的终端工具。先执行 `claude --version`：看到版本号再继续；没有版本号时，可以按 [Claude Code 官方安装文档](https://code.claude.com/docs/en/installation)安装，也可以直接跳过 7.1。

在一个新建的空文件夹里打开终端，执行：

```powershell
ollama launch claude --model gemma4:12b
```

[Ollama 的 Claude Code 集成文档](https://docs.ollama.com/integrations/claude-code)把 `ollama launch claude` 作为当前快速启动方式。

![Ollama 的 Launch 菜单给出了 Claude Code 的启动命令](images/08-ollama-launch-menu.png)<!-- display-width:520 -->

素材截图来自早期实验，当时在 home directory 中启动。正式复现请使用空实验目录，避免把过大的文件范围交给工具。

![Claude Code 已通过 Ollama 识别 gemma4:12b 并完成基础对话](images/09-claude-local-result.png)<!-- display-width:600 -->

看到模型名并收到普通回复，只能证明连接层成功：

```text
Claude Code → Ollama → gemma4:12b
```

能回复 `hi`，只能证明它来上班了；会不会干活，还得派一个小任务。

实验继续要求它写文件时，出现了：

```text
Invalid tool parameters
```

![一次工具参数未通过客户端校验；当前证据不足以判断具体根因](images/10-claude-tool-error.png)<!-- display-width:600 -->

这张失败图不能证明“Ollama 失败”或“模型一定不支持工具”。它只能确认：文本连接已经成功，但这一次工具参数没有被成功接受或执行；具体原因还可能涉及模型输出、上下文、兼容层或客户端实现。

### 7.2 再用 WorkBuddy 做最小连接测试

只有 WorkBuddy 已安装、已登录，并且能打开模型设置页时才做这一节；否则直接跳过，不影响 Ollama 主线通关。

进入 WorkBuddy：

```text
系统设置 → 模型 → 添加模型 → Ollama 本地
```

填写或确认：

```text
接口地址：http://localhost:11434/v1/chat/completions
模型名称：gemma4:12b
```

![WorkBuddy 使用 localhost 的 OpenAI 兼容地址接入 gemma4:12b](images/11-workbuddy-ollama-config.png)<!-- display-width:600 -->

模型名必须与 `ollama list` 中显示的完整标签一致。

WorkBuddy 不同版本的地址字段可能要求填写 `localhost` 基础地址，也可能自动补全 `/chat/completions`。以当前界面的字段说明为准，避免把同一段路径重复填写；可同时参考 [WorkBuddy 模型配置说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model)。

保存后，先只输入：

```text
hi
```

![WorkBuddy 已能调用本地 gemma4:12b 完成最小文本回复](images/12-workbuddy-local-response.png)<!-- display-width:600 -->

收到回复，说明最小连接已经打通。本次实验继续叠加 UI 设计师后，没有稳定交付网页文件。因此准确结论是：**WorkBuddy 已经连到本地模型，但复杂工具任务还没有在这台机器和这组配置上稳定跑通。**

如果要继续排查，按这个顺序增加难度：

```text
固定回复 → 两轮对话 → 创建一个只有标题的 HTML → 修改现有文件 → 完整网页
```

一次只加一个变量，才能知道是哪一层开始掉链子。

## 8. 选做观察：网页搜索会让“本地”重新连上云端

直接问本地模型刚发生的新闻，它可能说明自己无法获取实时信息。

![只靠本地模型权重，无法自动知道刚发生的实时新闻](images/13-web-search-unavailable.png)<!-- display-width:600 -->

这是正常现象。模型文件不会自动知道训练之后的新消息。

在 Ollama 应用中启用网页搜索时，界面会要求登录账号。

![Ollama 网页搜索要求登录账号，说明此时已经引入云端能力](images/14-web-search-signin.png)<!-- display-width:600 -->

根据 [Ollama 网页搜索文档](https://docs.ollama.com/capabilities/web-search)，网页搜索访问的是 Ollama 在线 API，程序调用还需要免费账号和 API Key。

所以要分清四件事：

- 调用已经下载的本地模型：推理可以在本机完成。
- 下载或更新模型：需要联网。
- 使用网页搜索：会访问云端搜索服务。
- 使用带 `:cloud` 的模型：推理由云端服务完成。

如果目标是完全离线或内网隔离，就不要启用网页搜索或云端模型，并单独检查客户端自身的登录、更新和遥测行为。

## 9. 选做排查：为什么 Agent 比聊天更吃配置

聊天只需要模型生成文字；Agent 还要读入文件、记住更多上下文，并稳定生成工具参数。

先执行：

```powershell
ollama ps
```

重点看两列：

- `PROCESSOR`：模型主要使用 GPU、CPU，还是两者混合。
- `CONTEXT`：这次实际分配了多少上下文。

[Ollama 上下文说明](https://docs.ollama.com/context-length)指出，低于 24 GiB 显存时默认上下文通常是 4K，而代码和 Agent 类任务建议更长上下文；增加上下文也会增加内存或显存占用。

因此，模型页面写着 256K，不代表当前电脑已经分配了 256K。实际值以 `ollama ps` 为准，不要让 12 GB 显卡盲目照抄 64K 配置。

## 10. 常见问题：先判断卡在哪一层

### 终端找不到 `ollama`

关闭终端后重新打开，并确认 Ollama 已从开始菜单启动。

### 本地 API 无法访问

先执行：

```powershell
Invoke-RestMethod http://localhost:11434/api/version
```

如果仍失败，再看 Ollama 是否正在运行。

### `ollama serve` 提示端口已占用

常见原因之一是桌面版已经在后台启动服务，相当于“已经有人上班了”。如果关闭桌面版后端口仍被占用，再检查是否有其他进程使用 11434。

### 提示找不到模型

```powershell
ollama list
ollama pull qwen2.5:0.5b
```

核对完整标签，尤其是冒号后的版本。

### 回答很慢，电脑也很卡

执行 `ollama ps`。如果主要落在 CPU，先换小模型、缩短任务，并关闭占用内存的其他程序。

### 模型忘记了前面的对话

先检查是否仍在同一个会话，以及客户端是否把历史消息继续发送给模型。Ollama 的 `/api/chat` 需要客户端在 `messages` 数组中提交对话历史，另一个窗口里的聊天不会自动跟过来。

### 能回复 `hi`，却不会创建文件

`hi` 只验证文本调用。创建文件还需要模型稳定生成工具参数、客户端正确执行工具，并且工作区有写入权限。

先把任务缩成“只在当前空目录创建一个只有标题的 `index.html`”，再逐步增加要求。

## 11. 收尾：模型已经住进电脑了

今天的核心成果只有三项：

1. 用 Ollama 下载并运行一个轻量模型。
2. 在应用和终端里收到本地回复。
3. 让 PowerShell 通过本地 API 调用它。

![核心通关：本地模型已经能在聊天窗口、终端和 API 中回复](images/15-episode-summary.png)<!-- display-width:520 -->

选做实验还额外验证了一个很重要的边界：**接入成功不等于复杂 Agent 任务一定稳定。** 文本回复、工具参数、文件操作和联网能力是不同层，排错时要一层层看。

本地部署真正带来的，是把模型文件、推理算力和基础 API 放回自己的控制范围；代价则是磁盘、内存、显存、速度和兼容性工作。

下一集，我们只增加一个变量：

> 模型只会通用知识，怎样让它先查阅我们自己的资料，再根据证据回答？

我们会从一个最小 RAG 实验开始，把“先找资料，再回答”亲手跑一遍。