| --- |
| 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 偷偷把它卸载。** |
| |
