trymirai/uzu · 上手攻略

• 仓库：trymirai/uzu
• 链接：https://github.com/trymirai/uzu
• 分类：llm-infra
• 作者：Tom
• 更新：2026-07-30

一、是什么

uzu 是 Mirai Labs 用 Rust 从头编写的高性能 AI 推理引擎（v0.5.12 · 2026-06-08），目标是让 AI 模型直接运行在你的应用中——零延迟、完整数据隐私、无推理费用。

它不是又一个 REST API 封装，而是一个真正把模型跑在本地的推理运行时。核心用 Rust 编写保证了性能和安全性，同时提供 Python / TypeScript / Swift / Rust 四种语言绑定，方便不同技术栈直接集成。

二、解决什么问题

在 Apple Silicon 上跑本地 LLM，以往的选择（llama.cpp、Ollama）要么是 C++ 绑定、要么缺乏精细的硬件调度。uzu 的核心差异化在于：

1. 超越 llama.cpp 的性能：官方展示的 benchmark 中，uzu 在几乎所有 Apple Silicon 测试场景下 tok/s 均高于 llama.cpp，尤其在 Prefill 阶段利用 ANE（Apple Neural Engine）加速。
2. GPU + ANE 协同调度：不像纯 GPU 方案那样浪费 ANE 算力，uzu 智能地将 GEMM 类 Prefill 任务调度到 ANE，把 Decode 阶段放在 GPU 上，硬件利用率更高。
3. 开箱即用的推理全流程：模型下载、配置、推理、流式输出，一条链不用自己拼。
4. 多语言绑定：Rust / Python / TypeScript / Swift，从后端到 iOS/macOS 应用均能直接集成。

三、快速安装

Rust（核心）

[dependencies]
uzu = { git = "https://github.com/trymirai/uzu", branch = "main", package = "uzu" }

或从 crates.io（最新稳定版本请以 GitHub Release 为准）：

uzu = "0.5"

Python

pip install uzu
# 或使用 uv
uv add uzu

⚠️ 版本注意：pip 安装的包名是 uzu（非 uzu-sdk），当前最新版本 0.5.14（2026-06）。建议通过 pip show uzu 确认安装的版本。

TypeScript / Node.js

pnpm add @trymirai/uzu
# 或 npm install、yarn add

Swift（iOS / macOS）

在 Package.swift 中添加：

dependencies: [
    .package(url: "https://github.com/trymirai/uzu.git", from: "0.5.14")
]

四、核心用法

4.1 Python：最简 Chat 例子

import asyncio
from uzu import ChatConfig, ChatMessage, ChatReplyConfig, Engine, EngineConfig

async def main():
    engine = await Engine.create(EngineConfig.create())

    # 列出可用模型 / 选模型
    model = await engine.model("Qwen/Qwen3-0.6B")
    if model is None:
        print("Model not found")
        return

    # 下载模型（如本地缓存没有）
    async for update in (await engine.download(model)).iterator():
        print(f"Download progress: {update.progress}")

    # 建立会话
    session = await engine.chat(model, ChatConfig.create())

    messages = [
        ChatMessage.system().with_text("You are a helpful assistant"),
        ChatMessage.user().with_text("Tell me a short, funny story about a robot")
    ]

    replies = await session.reply(messages, ChatReplyConfig.create())
    message = replies[-1].message
    print(f"Reasoning: {message.reasoning}")
    print(f"Text: {message.text}")

asyncio.run(main())

4.2 Python：流式输出

import asyncio
from uzu import (
    ChatConfig, ChatMessage, ChatReplyConfig, ChatSessionStreamChunk,
    Engine, EngineConfig
)

async def main():
    engine = await Engine.create(EngineConfig.create())
    model = await engine.model("Qwen/Qwen3-0.6B")
    if model is None:
        raise RuntimeError("Model not found")

    async for update in (await engine.download(model)).iterator():
        print(f"Progress: {update.progress}")

    session = await engine.chat(model, ChatConfig.create())
    stream = await session.reply_with_stream(
        [ChatMessage.user().with_text("Count to 5")],
        ChatReplyConfig.create()
    )

    async for chunk in stream.iterator():
        if isinstance(chunk, ChatSessionStreamChunk.Replies):
            for reply in chunk.replies:
                print(f"Tokens: {reply.stats.tokens_count_output}")
                print(f"Text: {reply.message.text}")

asyncio.run(main())

4.3 Rust：核心示例

use uzu::{
    engine::{Engine, EngineConfig},
    types::session::chat::{ChatConfig, ChatMessage, ChatReplyConfig},
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new(EngineConfig::default()).await?;
    let model = engine.model("Qwen/Qwen3-0.6B".to_string()).await?.ok_or("Model not found")?;

    let downloader = engine.download(&model).await?;
    while let Some(update) = downloader.next().await {
        println!("Progress: {}", update.progress());
    }

    let session = engine.chat(model, ChatConfig::default()).await?;

    let messages = vec![
        ChatMessage::system().with_text("You are a helpful assistant".to_string()),
        ChatMessage::user().with_text("Hello!".to_string()),
    ];

    let replies = session.reply(messages, ChatReplyConfig::default()).await?;
    if let Some(reply) = replies.last() {
        println!("Text: {}", reply.message.text().unwrap_or_default());
    }

    Ok(())
}

4.4 运行官方 Examples

# 查看可用 example
cargo tools example --list

# 运行 Rust chat example
cargo tools example rust chat

# 运行 Python chat example
cargo tools example python chat

# 运行 TypeScript chat example
cargo tools example typescript chat

五、内置功能（自动启用，无需额外配置）

根据官方披露，以下功能已内置并自动应用：

• Speculative Decoding：预测解码，加速推理
• Structured Output：结构化输出支持
• MPS + ANE 协同调度：GPU 处理 Decode，ANE 处理 Prefill GEMM
• 统一内存利用：在 Apple 设备上自动利用统一内存架构

⚠️ 量化方式：当前支持 AWQ 量化，其他量化方法（如 GPTQ、GGUF）在路线图中（截至 2026-07 尚未发布）。

六、典型适用场景

1. Apple 平台本地 AI App：iOS/macOS 应用直接集成 uzu，不需要任何云服务，数据完全留在设备上。
2. 隐私敏感场景：医疗、法律、金融等数据不能出境的场景，uzu 完全本地推理。
3. 降低推理成本：应用内嵌小模型（Qwen3-0.6B 等），无需 GPU 云服务费用。
4. 需要低延迟的边缘场景：设备端实时推理，无网络往返延迟。
5. 跨平台应用：同一套 Rust 核心，Python/TS/Swift 三套绑定，macOS/iOS/Android（Swift upcoming）全覆盖。

七、坑与注意

1. Apple Silicon 独占优势：uzu 的 ANE 调度优势主要体现在 Apple Silicon 上，Linux/Windows 平台支持情况需进一步确认（当前文档以 Apple 平台为主）。
2. 量化格式有限：当前只支持 AWQ，GPTQ 和 GGUF 等常用格式尚未支持，如果你的模型是 GGUF 格式，暂时无法直接使用 uzu。
3. 模型生态锁定：使用模型平台（Qwen/Qwen3-0.6B 格式），需要在 Mirai 官方模型列表注册过的模型。
4. Swift Package 尚未在主分支稳定：Swift 绑定在 bindings/swift，建议持续关注官方 Release 稳定性声明。
5. 文档语言障碍：README 以英文为主，部分 API 示例有 TypeScript 语法格式在 Markdown 中显示异常（如 import 语句被截断），实际使用前建议直接参考 GitHub 源码中的示例。
6. 版本年轻：v0.5.x 属于早期版本，API 可能随次版本变化，生产使用时建议锁定精确版本。

八、与同类对比

九、一句话推荐结论

在 Apple 平台做设备端 AI 集成的团队，uzu 是目前性能最优、绑定最完善的选择；如果你不需要 Apple 平台特性，仍然推荐关注其在多语言 SDK 统一体验上的持续进化。

来源：GitHub README、PyPI（uzu 0.5.14）、npm（@trymirai/uzu）、Hacker News 技术讨论、arXiv:2607.00501（BaseRT 论文对 uzu 的 benchmark 对比）

注意：Rust/Python/TypeScript 代码示例中的 ChatSessionStreamChunk.Replies 类型标注在 Python 中可能需要用字符串或类型检查而非类型注解，实际使用请参考 GitHub 源码。Swift 绑定版本以官方 Package.swift 中声明的 from: "0.5.14" 为准。