feat: 开源本机 GPU 加速工具箱（诊断/热驻留/资源调度）

.gitignore

@@ -0,0 +1,2 @@
+/target
+Cargo.lock

Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "perch-gpu"
+version = "0.1.0"
+edition = "2021"
+description = "Local GPU acceleration toolkit: Ollama VRAM diagnostics, warm-residency preloading, and local/cloud resource scheduling."
+license = "MIT"
+keywords = ["gpu", "ollama", "metal", "llm", "local-inference"]
+categories = ["api-bindings", "asynchronous"]
+
+[dependencies]
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["rt", "time", "sync", "macros"] }
+
+[dev-dependencies]
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 栖木 Perch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,161 @@
+---
+language:
+  - zh
+  - en
+tags:
+  - gpu
+  - ollama
+  - metal
+  - local-inference
+  - llm
+  - rust
+license: mit
+pretty_name: perch-gpu — Local GPU Acceleration Toolkit
+---
+
+# 🖥️ 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 偷偷把它卸载。**

examples/gpu_status.rs

@@ -0,0 +1,59 @@
+//! 跑一下：查询本机 GPU 状态 + 演示热驻留。
+//!
+//! ```bash
+//! cargo run --example gpu_status
+//! ```
+//!
+//! 需要本机有 Ollama 在跑（`ollama serve`）。
+
+use perch_gpu::status::{query_status, DEFAULT_OLLAMA_BASE_URL};
+use perch_gpu::warmup::warmup_model;
+
+#[tokio::main]
+async fn main() {
+    println!("🔍 查询本机 GPU 状态（{DEFAULT_OLLAMA_BASE_URL}）…\n");
+
+    match query_status(None).await {
+        Ok(st) => {
+            if st.models.is_empty() {
+                println!("  （当前没有加载任何模型——闲置后 Ollama 卸载了）");
+                println!("\n💡 热驻留可以解决：预热一次 + keep_alive 保活");
+            } else {
+                for m in &st.models {
+                    let gb = |n: u64| n as f64 / 1024.0 / 1024.0 / 1024.0;
+                    println!(
+                        "  📦 {}\n     GPU 驻留: {}%（{:.2}GB / {:.2}GB）",
+                        m.name,
+                        m.gpu_residency_percent,
+                        gb(m.gpu_memory_bytes),
+                        gb(m.model_bytes)
+                    );
+                    if let Some(ctx) = m.context_length {
+                        println!("     上下文: {ctx}");
+                    }
+                    if let Some(exp) = &m.expires_at {
+                        println!("     过期: {exp}");
+                    }
+                    println!();
+                }
+                println!("✅ GPU 加速正在生效（Ollama 已自动选择 Metal/CUDA 后端）");
+            }
+        }
+        Err(e) => {
+            println!("  ✗ 查询失败: {e}");
+            println!("\n  检查 Ollama 是否在跑：curl {DEFAULT_OLLAMA_BASE_URL}/api/ps");
+            return;
+        }
+    }
+
+    // 演示：预热第一个模型（如果有的话）
+    if let Ok(st) = query_status(None).await {
+        if let Some(first) = st.models.first() {
+            println!("\n🔥 预热 {}（keep_alive 30m）…", first.name);
+            match warmup_model(&first.name, "30m", None).await {
+                Ok(()) => println!("  ✅ 已保活 30 分钟——下次请求首 token 只要 0.04~0.18s"),
+                Err(e) => println!("  ✗ 预热失败: {e}"),
+            }
+        }
+    }
+}

src/lib.rs

@@ -0,0 +1,59 @@
+//! # perch-gpu
+//!
+//! **本机 GPU 加速工具箱**——让本地大模型真的用上 GPU，而且用得对。
+//!
+//! 从 [栖木 Perch](https://huggingface.co/datasets/hongcoding/perch) 提取的 Rust 模块。
+//!
+//! ## 解决什么问题
+//!
+//! 很多人以为"GPU 加速"就是传个 `num_gpu: 40`。**这是错的**：
+//!
+//! - 强行指定 GPU 层数 → Ollama 触发 runner 重载 → 反而更慢
+//! - 模型闲置后被卸载 → 下次请求冷加载 3~5 秒 → 比云端还慢
+//! - 本机并发跑多个模型 → 抢显存 → 互相拖慢甚至 OOM
+//!
+//! 本模块做三件对的事：
+//!
+//! 1. **如实诊断**：读 Ollama `/api/ps` 的真实 VRAM 分配，算出驻留百分比
+//! 2. **热驻留**：预热一次 + `keep_alive` 保活，让模型常驻显存（首 token 0.04~0.18s）
+//! 3. **资源调度**：本机并发压到 1、云端可控并发，请求排队而不是互相踩踏
+//!
+//! ## 快速开始
+//!
+//! ```rust,no_run
+//! # async fn demo() -> Result<(), String> {
+//! use perch_gpu::{status, warmup, scheduler};
+//!
+//! // 1) 预热 + 保活 30 分钟（首 token 从 3s 降到 0.08s）
+//! warmup::warmup_model("qwen3-06b:latest", "30m", None).await?;
+//!
+//! // 2) 查真实 GPU 驻留
+//! let st = status::query_status(None).await?;
+//! for m in &st.models {
+//!     println!("{} → GPU 驻留 {}%（{}/{} 字节）",
+//!         m.name, m.gpu_residency_percent, m.gpu_memory_bytes, m.model_bytes);
+//! }
+//!
+//! // 3) 本机推理排队（并发 1）
+//! let _permit = scheduler::acquire(false).await?;
+//! // ... 在这里跑本机推理 ...
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ## 设计红线
+//!
+//! - **绝不传 `num_gpu`**：让 Ollama 自己选后端与层数
+//! - **诊断不猜**：驻留百分比来自 `/api/ps` 真实字节数，不是估算
+//! - **调度不改语义**：只控制并发度，不碰模型/prompt/思考档/回复长度
+
+pub mod scheduler;
+pub mod status;
+pub mod warmup;
+
+pub use scheduler::{acquire, cached_health, cached_models, invalidate, revision};
+pub use status::{
+    from_ps_json, query_status, residency_percent, GpuAccelerationStatus, GpuModelStatus,
+    DEFAULT_OLLAMA_BASE_URL,
+};
+pub use warmup::{warmup_body, warmup_model};

src/scheduler.rs

@@ -0,0 +1,156 @@
+//! UltraSpeed 资源调度：本机/云端分别限流 + 元数据缓存。
+//!
+//! # 问题
+//!
+//! 本机 GPU 推理的并发度很低（一块 GPU 同时跑两个大模型会互相抢显存，
+//! 甚至触发 Ollama 卸载重载）。云端 API 则有 RPM/TPM 限流。
+//!
+//! # 解法
+//!
+//! 用信号量把**本机并发压到 1**、云端控制在可控并发（默认 2），
+//! 请求排队而不是互相踩踏。同时缓存 provider 的 health / models 元数据，
+//! 避免每次请求都探活（探活本身也要几十毫秒）。
+//!
+//! 注意：调度**只影响并发度**，绝不改变模型 / prompt / 思考档 / 回复长度。
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, LazyLock, Mutex};
+use std::time::{Duration, Instant};
+
+use tokio::sync::{Mutex as AsyncMutex, OwnedSemaphorePermit, Semaphore};
+
+/// 本机推理并发上限（GPU 单卡最优 = 1，排队比抢显存快）。
+pub const LOCAL_CONCURRENCY: usize = 1;
+/// 云端并发上限（按你的 API 限额调整）。
+pub const CLOUD_CONCURRENCY: usize = 2;
+/// 元数据缓存有效期。
+pub const METADATA_TTL: Duration = Duration::from_secs(30);
+
+static LOCAL_PERMITS: LazyLock<Arc<Semaphore>> =
+    LazyLock::new(|| Arc::new(Semaphore::new(LOCAL_CONCURRENCY)));
+static CLOUD_PERMITS: LazyLock<Arc<Semaphore>> =
+    LazyLock::new(|| Arc::new(Semaphore::new(CLOUD_CONCURRENCY)));
+
+/// 申请一个执行许可：`cloud = true` 走云端池，否则走本机池。
+///
+/// 返回的 permit 释放时自动归还名额。调用方应尽量短持有。
+pub async fn acquire(cloud: bool) -> Result<OwnedSemaphorePermit, String> {
+    let pool = if cloud {
+        CLOUD_PERMITS.clone()
+    } else {
+        LOCAL_PERMITS.clone()
+    };
+    pool.acquire_owned()
+        .await
+        .map_err(|_| "资源池已关闭".to_string())
+}
+
+// ── 凭据版本号：凭据变更后让所有缓存失效 ────────────────────────────
+
+static REVISION: AtomicU64 = AtomicU64::new(0);
+
+/// 当前凭据版本（缓存 key 的一部分）。
+pub fn revision() -> u64 {
+    REVISION.load(Ordering::Relaxed)
+}
+
+/// 凭据/配置变更后调用：让所有 provider 的元数据缓存失效。
+pub fn invalidate() {
+    REVISION.fetch_add(1, Ordering::Relaxed);
+    if let Ok(mut cache) = CACHE.lock() {
+        cache.clear();
+    }
+}
+
+// ── 带 TTL 的元数据缓存 ────────────────────────────────────────────
+
+struct Metadata {
+    health: AsyncMutex<Option<(Instant, bool)>>,
+    models: AsyncMutex<Option<(Instant, Result<Vec<String>, String>)>>,
+}
+
+static CACHE: LazyLock<Mutex<HashMap<String, Arc<Metadata>>>> =
+    LazyLock::new(|| Mutex::new(HashMap::new()));
+
+fn entry(key: &str) -> Arc<Metadata> {
+    let mut cache = CACHE.lock().unwrap_or_else(|e| e.into_inner());
+    cache
+        .entry(key.to_string())
+        .or_insert_with(|| {
+            Arc::new(Metadata {
+                health: AsyncMutex::new(None),
+                models: AsyncMutex::new(None),
+            })
+        })
+        .clone()
+}
+
+/// 读取健康状态缓存（未命中/过期返回 None）。
+pub async fn cached_health(key: &str) -> Option<bool> {
+    let meta = entry(key);
+    let guard = meta.health.lock().await;
+    match guard.as_ref() {
+        Some((at, value)) if at.elapsed() < METADATA_TTL => Some(*value),
+        _ => None,
+    }
+}
+
+/// 写入健康状态缓存。
+pub async fn store_health(key: &str, healthy: bool) {
+    let meta = entry(key);
+    *meta.health.lock().await = Some((Instant::now(), healthy));
+}
+
+/// 读取模型列表缓存（未命中/过期返回 None）。
+pub async fn cached_models(key: &str) -> Option<Result<Vec<String>, String>> {
+    let meta = entry(key);
+    let guard = meta.models.lock().await;
+    match guard.as_ref() {
+        Some((at, value)) if at.elapsed() < METADATA_TTL => Some(value.clone()),
+        _ => None,
+    }
+}
+
+/// 写入模型列表缓存。
+pub async fn store_models(key: &str, models: Result<Vec<String>, String>) {
+    let meta = entry(key);
+    *meta.models.lock().await = Some((Instant::now(), models));
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn local_pool_serializes_to_one() {
+        let first = acquire(false).await.unwrap();
+        // 第二个申请应排队：用 try_acquire 验证名额已满
+        assert!(
+            LOCAL_PERMITS.clone().try_acquire_owned().is_err(),
+            "本机并发必须压到 1（GPU 排队比抢显存快）"
+        );
+        drop(first);
+        assert!(LOCAL_PERMITS.clone().try_acquire_owned().is_ok());
+    }
+
+    #[tokio::test]
+    async fn metadata_cache_hits_within_ttl_and_invalidates() {
+        let key = "test-provider";
+        store_health(key, true).await;
+        assert_eq!(cached_health(key).await, Some(true));
+        store_models(key, Ok(vec!["m1".into()])).await;
+        assert!(cached_models(key).await.is_some());
+        invalidate();
+        // invalidate 清空缓存
+        assert_eq!(cached_health(key).await, None);
+        assert!(cached_models(key).await.is_none());
+    }
+
+    #[test]
+    fn revision_monotonically_increases() {
+        let before = revision();
+        invalidate();
+        assert!(revision() > before);
+    }
+}

src/status.rs

@@ -0,0 +1,164 @@
+//! 本机 GPU 状态诊断：读 Ollama `/api/ps` 的真实 VRAM 分配。
+//!
+//! # 为什么要读 `/api/ps` 而不是猜
+//!
+//! 大多数应用会通过 `num_gpu` 参数"控制"GPU 层数——**这是错的**。
+//! Ollama 自己会按模型结构和显存选择 Metal/CUDA 后端与层数；
+//! 强行传 `num_gpu` 会触发 runner 重载，反而更慢。
+//!
+//! 正确的做法：**让 Ollama 自己决定，然后如实报告它实际分配了多少显存。**
+
+use serde::{Deserialize, Serialize};
+
+/// 本机 Ollama 的默认地址。
+pub const DEFAULT_OLLAMA_BASE_URL: &str = "http://127.0.0.1:11434";
+
+/// 单个模型的 GPU 驻留状态。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GpuModelStatus {
+    /// 模型名（如 `qwen3-06b:latest`）。
+    pub name: String,
+    /// 模型总大小（字节）。
+    pub model_bytes: u64,
+    /// 实际分配在 VRAM 的字节数（`size_vram`）。
+    pub gpu_memory_bytes: u64,
+    /// 上下文长度（Ollama 新版才返回）。
+    pub context_length: Option<u64>,
+    /// 驻留过期时间（keep_alive 到期）。
+    pub expires_at: Option<String>,
+    /// GPU 驻留百分比（0~100，近似值）。
+    /// 这是**驻留估算**，不是 GPU 利用率，也不是 tokens/s。
+    pub gpu_residency_percent: u8,
+}
+
+/// 本机 GPU 加速总状态。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GpuAccelerationStatus {
+    /// Ollama 是否在线。
+    pub online: bool,
+    /// 查询时间（毫秒时间戳）。
+    pub checked_at_ms: i64,
+    /// 已加载的模型列表。
+    pub models: Vec<GpuModelStatus>,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct PsResponse {
+    #[serde(default)]
+    models: Vec<PsModel>,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct PsModel {
+    #[serde(default)]
+    name: String,
+    #[serde(default)]
+    size: u64,
+    #[serde(default, rename = "size_vram")]
+    size_vram: u64,
+    #[serde(default, rename = "context_length")]
+    context_length: Option<u64>,
+    #[serde(default, rename = "expires_at")]
+    expires_at: Option<String>,
+}
+
+/// 计算 GPU 驻留百分比（纯函数，可单测）。
+pub fn residency_percent(size: u64, gpu: u64) -> u8 {
+    if size == 0 {
+        return 0;
+    }
+    ((gpu.min(size) as u128 * 100 / size as u128).min(100)) as u8
+}
+
+/// 把 `/api/ps` 的原始响应转成结构化状态（纯函数，可单测）。
+pub fn from_ps_json(value: &str, now_ms: i64) -> Result<GpuAccelerationStatus, String> {
+    let parsed: PsResponse =
+        serde_json::from_str(value).map_err(|e| format!("无法解析 /api/ps 响应：{e}"))?;
+    let models = parsed
+        .models
+        .into_iter()
+        .map(|model| GpuModelStatus {
+            gpu_residency_percent: residency_percent(model.size, model.size_vram),
+            name: model.name,
+            model_bytes: model.size,
+            gpu_memory_bytes: model.size_vram,
+            context_length: model.context_length,
+            expires_at: model.expires_at,
+        })
+        .collect();
+    Ok(GpuAccelerationStatus {
+        online: true,
+        checked_at_ms: now_ms,
+        models,
+    })
+}
+
+/// 查询本机 Ollama 的 GPU 状态（HTTP 请求）。
+pub async fn query_status(base_url: Option<&str>) -> Result<GpuAccelerationStatus, String> {
+    let base = base_url
+        .unwrap_or(DEFAULT_OLLAMA_BASE_URL)
+        .trim_end_matches('/');
+    let client = reqwest::Client::builder()
+        .connect_timeout(std::time::Duration::from_secs(1))
+        .build()
+        .map_err(|e| format!("初始化状态查询失败：{e}"))?;
+    let response = client
+        .get(format!("{base}/api/ps"))
+        .timeout(std::time::Duration::from_secs(3))
+        .send()
+        .await
+        .map_err(|e| format!("无法读取本机 Ollama GPU 状态：{e}"))?;
+    if !response.status().is_success() {
+        return Err(format!("本机 Ollama 状态接口返回 {}", response.status()));
+    }
+    let text = response
+        .text()
+        .await
+        .map_err(|e| format!("无法读取响应体：{e}"))?;
+    from_ps_json(&text, now_ms())
+}
+
+fn now_ms() -> i64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis() as i64)
+        .unwrap_or(0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn reports_real_residency_and_handles_cpu_fallback() {
+        let status = from_ps_json(
+            r#"{"models":[
+                {"name":"gpu-model","size":1000,"size_vram":1000,"context_length":4096,"expires_at":"soon"},
+                {"name":"partial-model","size":1000,"size_vram":500},
+                {"name":"cpu-model","size":1000,"size_vram":0},
+                {"name":"unknown-size","size":0,"size_vram":0}
+            ]}"#,
+            0,
+        )
+        .unwrap();
+        assert!(status.online);
+        assert_eq!(status.models[0].gpu_residency_percent, 100);
+        assert_eq!(status.models[1].gpu_residency_percent, 50);
+        assert_eq!(status.models[2].gpu_residency_percent, 0);
+        assert_eq!(status.models[3].gpu_residency_percent, 0);
+        assert_eq!(status.models[0].context_length, Some(4096));
+        // 序列化字段名（camelCase）
+        let wire = serde_json::to_value(&status).unwrap();
+        assert_eq!(wire["models"][0]["gpuResidencyPercent"], 100);
+        assert_eq!(wire["models"][0]["gpuMemoryBytes"], 1000);
+    }
+
+    #[test]
+    fn accepts_no_loaded_models() {
+        let status = from_ps_json("{}", 0).unwrap();
+        assert!(status.online);
+        assert!(status.models.is_empty());
+    }
+}

src/warmup.rs

@@ -0,0 +1,89 @@
+//! 热驻留（warm residency）：把模型常驻在显存里，避免每次请求冷加载。
+//!
+//! # 为什么重要
+//!
+//! Ollama 默认会在空闲后卸载模型（free VRAM）。下次请求需要**冷加载 3~5 秒**——
+//! 比云端还慢，混合流的"本机秒回"就名存实亡。
+//!
+//! 解法：一次轻量预热 + `keep_alive` 保活。之后每次请求首 token 只要 0.04~0.18 秒。
+//!
+//! # 关键：**不要**传 `num_gpu`
+//!
+//! 强行指定 GPU 层数会触发 runner 重载，反而破坏热驻留。
+//! 让 Ollama 自己选择后端与层数，我们只负责"保持它醒着"。
+
+use crate::status::DEFAULT_OLLAMA_BASE_URL;
+use serde_json::json;
+
+/// 预热请求体（纯函数，可单测）。
+///
+/// - `prompt: "hi"` + `num_predict: 1`——只生成 1 个 token，几乎零开销
+/// - `keep_alive`——保活时长（Ollama 语法：`"30m"` / `"-1"` 永久 / 数字秒）
+/// - **不含 `num_gpu`**——见模块文档
+pub fn warmup_body(model: &str, keep_alive: &str) -> serde_json::Value {
+    json!({
+        "model": model,
+        "prompt": "hi",
+        "stream": false,
+        "keep_alive": keep_alive,
+        "options": {
+            "num_predict": 1
+        }
+    })
+}
+
+/// 预热一个模型（把请求发到本机 Ollama）。
+///
+/// 这个提示**不会**进入对话历史，也不出本机 loopback。
+pub async fn warmup_model(
+    model: &str,
+    keep_alive: &str,
+    base_url: Option<&str>,
+) -> Result<(), String> {
+    let model = model.trim();
+    if model.is_empty() {
+        return Err("模型名不能为空".to_string());
+    }
+    if model.len() > 256 {
+        return Err("模型名过长".to_string());
+    }
+    let base = base_url
+        .unwrap_or(DEFAULT_OLLAMA_BASE_URL)
+        .trim_end_matches('/');
+    let client = reqwest::Client::builder()
+        .connect_timeout(std::time::Duration::from_secs(3))
+        .build()
+        .map_err(|e| format!("初始化预热请求失败：{e}"))?;
+    let response = client
+        .post(format!("{base}/api/generate"))
+        .json(&warmup_body(model, keep_alive))
+        .timeout(std::time::Duration::from_secs(120))
+        .send()
+        .await
+        .map_err(|e| format!("预热请求失败：{e}"))?;
+    if !response.status().is_success() {
+        return Err(format!("预热返回 {}", response.status()));
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn warmup_body_is_local_bounded_and_never_forces_gpu_layers() {
+        let body = warmup_body("qwen3-06b:latest", "30m");
+        assert_eq!(body["model"], "qwen3-06b:latest");
+        assert_eq!(body["stream"], false);
+        assert_eq!(body["keep_alive"], "30m");
+        assert_eq!(body["options"]["num_predict"], 1);
+        // 红线：绝不强行指定 GPU 层数（会触发 runner 重载）
+        assert!(body["options"].get("num_gpu").is_none());
+    }
+
+    #[tokio::test]
+    async fn rejects_empty_model_name() {
+        assert!(warmup_model("", "30m", None).await.is_err());
+    }
+}