⭐ 这是栖木 Perch 的开源组件之一。 核心应用（macOS 本地优先 AI 工作台 · 0.08s 首字）在这里 → 🪵 栖木 Perch

⚡ perch-ultrafast

LLM 首字延迟 1 秒 → 80 毫秒。不换模型，不掉质量。

你写了个漂亮的 AI 应用，用户点发送，然后…… 盯着空屏幕等 1 秒。

抱歉，你的模型没错。是你的架构错了。

perch-ultrafast 是一个 600 行的 Rust 框架，解决这一个问题：

两条流同时开——本机小模型先出草稿（用户立刻有字读）， 云端大模型第一个字一到，立刻接棒替换（质量升级）。

用户看到的首字 = 本机延迟（80ms） 最终答案的质量 = 云端质量

两头都占，一个子儿都不多花。

从 栖木 Perch 生产环境提取 · MIT · cargo test 全绿

---

📊 这不是理论，是实测

真实运行 cargo run --example hybrid_demo 的输出：

⏱  开始（0ms）

[82ms]   首字可见 → 我是一个本机小模型，这是我的草稿答案。
[902ms]  ⚡ 云端模型已接棒（清空草稿）
         这是云端大模型的正式答案，质量更高、信息更全。
[1130ms] ✅ 完成

首字延迟: 82ms（纯云端需要 900ms）—— 快 11 倍

场景	首字延迟	用户感受
纯云端	0.88 ~ 1.39s	😐 盯着空屏幕
纯本机	0.04 ~ 0.18s	😀 快，但质量有限
本框架	< 0.2s 首字 + 云端质量	🤩 立刻有字，随后升级

---

🚀 三行接入

use perch_ultrafast::{hybrid::{run_hybrid, HybridConfig}, types::*};

run_hybrid(
    local_provider,   // 你的本机小模型（预热过）
    cloud_provider,   // 你的云端大模型
    fast_request,     // 本机用：关思考 + 小 max_tokens
    slow_request,     // 云端用：原样
    cancel_token,
    HybridConfig::default(),
    |chunk| match chunk {
        StreamChunk::Delta { text } => print!("{text}"),
        StreamChunk::Replaced { .. } => println!("\n[云端接棒]"),
        _ => {}
    },
).await;

只需实现一个 trait 就能接入任何后端：

pub trait Provider: Send + Sync {
    fn chat_stream(&self, request: ChatRequest, cancel: CancellationToken)
        -> BoxFuture<Result<ProviderStream, String>>;
}

Ollama / OpenAI 兼容 / 自建推理服务 —— 各几十行适配。

---

🧠 附带：Ultrafast 推理框架（三条加速法则）

混合流解决首字，Ultrafast 解决整体。

法则 1 · 关思考

推理模型的 thinking 链会拉高首 token 延迟。加速模式下发时强制 think: Off。 只改本次请求，不动用户存档。

法则 2 · 连接池复用

reqwest::Client 做成进程级单例。省掉每条请求的 TCP + TLS 握手。 再开 gzip/brotli —— 下行字节更少，正文更早到。

法则 3 · 回复预算

兜底 max_tokens（默认 2048），不让模型啰嗦。 用户显式设定优先，绝不覆盖。

法则 4 · 模型锁 🔒

加速开关无权更换模型。

速度不能靠"偷偷换成更快的模型"——那会改变答案质量，是欺骗。 用户选了 MiMo 就只用 MiMo。

---

🛡️ 四条设计红线（都有测试钉死）

红线	原因
加速不换模型	偷偷换模型 = 欺骗用户
只改下发值	不动持久化档位，关掉即恢复
云端失败保留草稿	不把用户答案变成错误页
本机失败静默降级	行为等同没用混合流，不打扰用户

🧩 生产环境的降级矩阵

情况	行为
本机预热完成	草稿 0.08s 出字，云端 ~0.9s 接棒
本机冷启动	超时 50ms → 纯云端（用户无感）
本机不可用	门控跳过 → 纯云端
云端建流失败	本机草稿继续跑完（不丢答案）
云端中途出错	保留草稿按完成收尾
用户取消	两条流同时取消

---

🏗️ 架构（就这么点）

src/
├── types.rs       Provider trait / StreamChunk / ChatRequest
├── hybrid.rs      混合流 mux（本机草稿 → 云端接棒 + 双向降级）
├── ultrafast.rs   加速规则（关思考 / 预算 / 简洁提示 / 模型锁）
└── pool.rs        连接池单例
examples/
└── hybrid_demo.rs 可运行 demo（真实时序）

600 行 Rust，零业务耦合，直接嵌进你的项目。

🔬 验证

cargo test                        # 5 个单元测试 + 1 个文档测试
cargo run --example hybrid_demo   # 看真实时序

---

🔗 相关项目

项目	说明	链接
栖木 Perch（应用）	macOS 本地优先 AI 工作台：0.08s 首字、真智能体、隐私优先	https://huggingface.co/datasets/hongcoding/perch
perch-ultrafast（开源框架）	就是你正在看的这个	https://huggingface.co/hongcoding/perch-ultrafast
HF Collection	上面两个项目归在一起	https://huggingface.co/collections/hongcoding/perch-ai-workbench-and-ultrafast-framework

📖 来源

栖木 Perch v5.2.1 的 commands.rs + providers/cloud.rs 中混合流/加速逻辑的独立提取版， 去掉了 Tauri/数据库/UI 业务耦合，保留可复用的核心。

📜 许可

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

---

⚡ 别让用户等云端。让本机先开口。