Blame for README.md

---
language:
  - zh
  - en
tags:
  - rust
  - llm
  - streaming
  - latency
  - inference
  - tokio
  - framework
license: mit
pretty_name: perch-ultrafast — Hybrid Streaming + Ultrafast Inference
---

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

# ⚡ perch-ultrafast

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

> 你写了个漂亮的 AI 应用，用户点发送，然后……
> **盯着空屏幕等 1 秒**。
>
> 抱歉，你的模型没错。是你的架构错了。

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

> **两条流同时开**——本机小模型先出草稿（用户立刻有字读），
> 云端大模型第一个字一到，立刻接棒替换（质量升级）。
>
> 用户看到的首字 = **本机延迟（80ms）**
> 最终答案的质量 = **云端质量**
>
> **两头都占，一个子儿都不多花。**

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

---

## 📊 这不是理论，是实测

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

```text
⏱  开始（0ms）

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

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

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

---

## 🚀 三行接入

```rust
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** 就能接入任何后端：

```rust
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，零业务耦合**，直接嵌进你的项目。

## 🔬 验证

```bash
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 —— 随便用，注明出处即可。

---

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