---
language:
  - zh
  - en
tags:
  - gpu
  - ollama
  - metal
  - local-inference
  - llm
  - rust
license: mit
pretty_name: perch-gpu — Local GPU Acceleration Toolkit
---

> ⭐ **这是栖木 Perch 的开源组件之一。**
> 核心应用（macOS 本地优先 AI 工作台 · 0.08s 首字）在这里 →
> [**🪵 栖木 Perch**](https://huggingface.co/datasets/hongcoding/perch)

# 🖥️ perch-gpu

### 让本机大模型真的用上 GPU——而且用得对。

> 你装了个 7B 模型，满心期待地点发送。
> 然后**等了 5 秒**才出第一个字。
>
> 你查了半天，以为是模型太大、显卡太弱。
> 其实——**是 Ollama 把它从显存里卸载了**。

**perch-gpu** 是一个 Rust 工具箱，解决本机大模型 GPU 加速的三个坑。

从 [栖木 Perch](https://huggingface.co/datasets/hongcoding/perch) 生产环境提取 · MIT · `cargo test` 全绿

---

## 🕳️ 三个坑（大多数人都踩了）

### 坑 1 · 强行指定 GPU 层数

```json
{ "num_gpu": 40 }   // ❌ 错
```

很多人以为这样能"控制 GPU 加速"。实际后果：
**Ollama 触发 runner 重载 → 反而更慢。**

**正确做法**：让 Ollama 自己按模型结构和显存选择后端与层数。
你只需要**如实报告**它分配了多少——这就是本库的 `status` 模块。

### 坑 2 · 模型被悄悄卸载

Ollama 默认在空闲后释放显存。下次请求**冷加载 3~5 秒**——
比云端还慢，你的"本机秒回"名存实亡。

**正确做法**：预热一次 + `keep_alive` 保活。
本库的 `warmup` 模块，首 token 从 3s 降到 **0.04~0.18s**。

### 坑 3 · 本机并发抢显存

同时跑两个模型？一块 GPU 会互相拖慢，甚至 OOM。

**正确做法**：本机并发压到 1（排队比抢显存快），云端可控并发。
本库的 `scheduler` 模块。

---

## 🚀 快速开始

```toml
[dependencies]
perch-gpu = { git = "https://huggingface.co/hongcoding/perch-gpu" }
```

```rust
use perch_gpu::{status, warmup, scheduler};

// 1) 预热 + 保活 30 分钟（首 token 从 3s 降到 0.08s）
warmup::warmup_model("qwen3-06b:latest", "30m", None).await?;

// 2) 查真实 GPU 驻留（读 Ollama /api/ps，不是猜）
let st = status::query_status(None).await?;
for m in &st.models {
    println!("{} → GPU 驻留 {}%", m.name, m.gpu_residency_percent);
}

// 3) 本机推理排队（并发 1，防止抢显存）
let _permit = scheduler::acquire(false).await?;
// ... 跑推理 ...
```

跑 demo 看效果：

```bash
cargo run --example gpu_status
```

真实输出：

```
🔍 查询本机 GPU 状态（http://127.0.0.1:11434）…

  📦 qwen3-06b:latest
     GPU 驻留: 100%（0.37GB / 0.37GB）
     上下文: 4096
     过期: 2026-11-05T22:30:00+08:00

✅ GPU 加速正在生效（Ollama 已自动选择 Metal/CUDA 后端）
```

---

## 🧩 三个模块

| 模块 | 作用 | 关键点 |
|---|---|---|
| **`status`** | 读 Ollama `/api/ps` 真实 VRAM 分配 | 驻留百分比来自真实字节，不是估算 |
| **`warmup`** | 预热 + `keep_alive` 保活 | **绝不传 `num_gpu`**（会触发重载）|
| **`scheduler`** | 本机/云端资源调度 + 元数据缓存 | 只控并发度，不改语义 |

## 📊 实测效果（栖木 Perch，Apple Silicon + Metal）

| 状态 | 首 token 延迟 |
|---|---|
| 冷加载（模型被卸载） | **3 ~ 5 秒** |
| 热驻留（预热 + 保活） | **0.04 ~ 0.18 秒** |

**快 20~70 倍**，代价只是让 0.6B 模型占着 ~0.4GB 显存。

---

## 🛡️ 设计红线

| 红线 | 原因 |
|---|---|
| **绝不传 `num_gpu`** | 让 Ollama 自己选，强行指定会重载 |
| **诊断不猜** | 驻留百分比 = 真实 `/api/ps` 字节数 |
| **调度不改语义** | 只控并发，不碰模型/prompt/思考档/回复长度 |
| **预热不出本机** | 预热提示只发 loopback，不进对话历史 |

## 🔬 验证

```bash
cargo test   # 7 个单元测试 + 1 个文档测试
```

覆盖：真实驻留计算 / CPU 回退 / 无模型 / 预热体不含 num_gpu / 并发序列化 / 缓存失效。

---

## 🔗 相关项目

| 项目 | 说明 | 链接 |
|---|---|---|
| **栖木 Perch**（应用） | macOS 本地优先 AI 工作台 | https://huggingface.co/datasets/hongcoding/perch |
| **perch-ultrafast**（框架） | 混合流 + Ultrafast 推理框架：首字 1s → 80ms | https://huggingface.co/hongcoding/perch-ultrafast |
| **perch-gpu**（本库） | 本机 GPU 加速工具箱 | https://huggingface.co/hongcoding/perch-gpu |
| **HF Collection** | 全部归在一起 | https://huggingface.co/collections/hongcoding/perch-ai-workbench-and-ultrafast-framework |

## 📜 许可

MIT —— 随便用，注明出处即可。

---

**🖥️ 别让你的 GPU 闲着。也别让 Ollama 偷偷把它卸载。**