docs: 顶部加「核心应用」标记

383dad4 verified 1 day ago

5.82 kB

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

---

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

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

	---

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