第 9 章 · 03 Web/Desktop/Docker 与全书回顾

第 9 章 · 03 Web/Desktop/Docker 与全书回顾

本节摘要:本节是全书最后一节,做两件事。第一,完成全栈交付层的最后一块——web/(纯 OpenAI-API 客户端浏览器 UI,React/Vite,实时指标 / 硬件面板 / 专家层级)、desktop/(Tauri v2 桌面壳,Rust 包 web UI)、docker/(CPU 推理镜像 Dockerfile / Dockerfile.slim)。第二,把第 1-9 章的机制深潜旅程整体回顾,提炼 Colibrì 的核心哲学四点,并给读者下一步的具体建议。本节末尾不做过渡,直接收尾全书。

内容来源:原项目源码 web/、desktop/、docker/、全书前八章

⚠️ 注意:本节配图 images/colibri-dashboard.png 是 dashboard 实际截图。Web UI 是"纯客户端"——它不内嵌推理引擎,只连一个 OpenAI 兼容端点(可以是 coli serve、也可以是任何远端服务)。

学习目标

1. 认识 web/ 浏览器 UI 的三大面板(实时指标 / 硬件面板 / 专家层级)及其数据来源。
2. 理解 desktop/ 是 Tauri v2 壳,不重写前端,共享 web/ 的 React 代码。
3. 区分 Dockerfile(完整带构建工具)与 Dockerfile.slim(多阶段精简运行时)。
4. 复述全书九章机制深潜的主线,把每个机制放回 per-token 五步路径。
5. 内化 Colibrì 的核心哲学四点:权重 JIT、三级存储、诚实研究、纯 C 零依赖。

一、web/:纯 OpenAI-API 客户端浏览器 UI

web/ 是一个标准 React + Vite + TypeScript 工程,目录结构:

web/
├── src/
│   ├── App.tsx          # 根组件
│   ├── Brain.tsx        # 推理可视化(配合 colibri-brain.png 风格)
│   ├── Profiling.tsx    # per-turn PROF 曲线(数据来自 /profile)
│   ├── components/      # 复用组件
│   ├── lib/             # API 客户端、工具函数
│   └── i18n/            # 多语言
├── index.html
├── package.json
└── vite.config.ts
​

它是一个纯 OpenAI-API 客户端——所有数据都通过 HTTP 从某个 OpenAI 兼容端点拉取(coli serve 启动的服务或任何远端)。三大面板:

• 实时指标(live metrics):tok/s、首 token 延迟、当前 turn 进度,从 /profile 拉滚动 120 turn 的 PROF 快照;
• 硬件面板(hardware panel):RAM/VRAM 占用、CPU/GPU 利用率、磁盘读吞吐,数据来自 /health + /experts;
• 专家层级(expert tiers):专家热图(配合第 6 章 route_trace),按访问频次分层展示——高频专家、中频、冷专家。

这套 UI 的关键设计:它对引擎一无所知——只要对方说 OpenAI 协议,任何后端都能接。这让 dashboard 可以同时作为本地 coli serve 的监控面板,以及远端集群服务的可视化客户端。

二、desktop/:Tauri v2 桌面壳

desktop/ 是 Tauri v2 工程,不重写前端,直接包 web/:

desktop/
├── README.md
└── src-tauri/
    ├── Cargo.toml         # Rust 依赖
    ├── src/               # Rust 主程序
    ├── tauri.conf.json    # Tauri 配置
    └── icons/
​

tauri.conf.json 关键字段:

{
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "colibrì",
  "build": {
    "beforeDevCommand": "npm --prefix ../web run dev",
    "devUrl": "http://localhost:5173",
    "beforeBuildCommand": "npm --prefix ../web run build",
    "frontendDist": "../../web/dist"
  }
}
​

要点:

• 开发模式 Tauri 启动 web/ 的 Vite dev server(localhost:5173),Rust 侧只做壳;
• 发布构建打包 web/dist 进桌面 app,跨平台(Windows/macOS/Linux);
• 不内嵌推理引擎——desktop/README.md 明说"模型几百 GB,必须作为外部、用户选择的资源,而不是 opaque 应用 sidecar"。

后果:桌面 app 只是一个"漂亮的 OpenAI 客户端",引擎可以是用户本机的 coli serve,也可以是远端服务。这与 web UI 的设计哲学完全一致。

三、docker/:CPU 推理容器镜像

docker/ 提供两份 Dockerfile:

• Dockerfile:完整版,基于 debian:stable-slim,装 git/build-essential/python3,git clone 仓库后 ./setup.sh && ./coli build 编译引擎。适合在镜像里现编现用。
• Dockerfile.slim:多阶段构建——Stage 1 编译引擎,Stage 2 只拷贝二进制 + Python 启动器到精简运行时。最终镜像不含编译工具,体积小。

Dockerfile.slim 顶部注释把"什么进镜像、什么不进"讲得极清:

# This image ships ONLY the inference path (chat/serve/run/info/plan/doctor) —
# the ~372 GB model is mounted, never baked in, and the converter (which needs
# torch) is deliberately out of scope; convert from a source checkout instead.
​

三条规则:

• 模型挂载不烤进镜像(-v /nvme/glm52_i4:/model):几百 GB 的模型不适合进镜像层;
• 只装推理路径:chat/serve/run/info/plan/doctor 子命令;
• converter 不在镜像:它依赖 torch,体积大,从源码 checkout 转换更合理。

典型用法:

docker run --rm -p 5000:5000 -v /nvme/glm52_i4:/model colibri \
    serve --host 0.0.0.0 --model-id glm-5.2
​

把容器当作"打包好的 coli serve"——内部跑 openai_server.py + 引擎二进制,对外暴露 OpenAI 兼容端点。

四、全书九章机制深潜回顾

把九章串成一条线,每个机制放回 per-token 五步路径(路由 → 联合 → 放置 → 重叠 → 学习):

把它们放进 per-token 五步:

• 路由(route):第 6 章 route_trace 决定每 token 激活哪些专家;
• 联合(union):第 5 章 uring.h 把多专家的磁盘读联合成批量 IO;
• 放置(place):第 4 章 tier.h 把稠密部分常驻 RAM、专家放磁盘按需流式;第 3 章 expert_store.h 是放置的具体执行(LRU lease 契约);
• 重叠(overlap):第 5 章 O_DIRECT + io_uring 让读 / 写 / 算重叠;第 8 章 CPU/GPU 重叠隐藏传输;
• 学习(learn):第 6 章 route_trace 的学习型缓存;第 3 章 pinned hot-store 的固定热存。

第 1 章是命题(为什么万亿模型能跑),第 2 章是数据格式(safetensors + 量化容器),第 7 章是状态压缩(KV 持久化 + 复用),第 9 章是交付(CLI + 服务 + Web)。九章合起来,就是"一个纯 C 的万亿参数 MoE 推理引擎如何在消费硬件上跑通"的完整答案。

五、Colibrì 的核心哲学四点

把九章的所有具体决策,抽象到四条心法:

1. 权重 JIT,只加载热点专家:MoE 每 token 仅激活约 5.4% 参数,所以模型不需要塞进内存,只需要被智能放置。稠密部分常驻 RAM,19456 个路由专家放磁盘按需流式加载,LRU + 学习型热存 + 一层前瞻预取。这是第 1 / 3 / 6 章的总纲。
2. 三级存储 VRAM-RAM-NVMe,放置只决速度:存储 / 内存 / 显存不再是"能不能装下"的二选一,而是"放在哪层最快"的放置问题。有限的高速内存只改变速度,绝不改变模型语义——这是第 4 / 5 / 8 章的总纲。
3. 诚实研究,每优化都是可证伪假设:每条优化都要 token-exact forward validation 绑定正确性,然后端到端 A/B 测收益。speculative decoding acceptance 不够就关,spin-wait 在 disk-bound 引擎上变慢就不加,GPU offload 在快 CPU + 低驻留下抹平收益就退化到 CPU。这是第 7 / 8 章的方法论。
4. 纯 C 零依赖,一个 .c 一个模型族,共享头文件:不依赖 BLAS / Python 运行时 / GPU 必须;每个模型引擎一个 .c(colibri.c / deepseek_v4.c / inkling.c / kimi_k3.c / olmoe.c),共享一组头文件(st.h / quant.h / expert_store.h / tier.h / route_trace.h / kv_*.h)。这是全书的工程姿态。

六、建议读者下一步

读完这本教程后,推荐的进阶路径:

• 跑通第一个模型:make glm 编译,coli plan 看推荐配置,coli chat 跑通第一轮对话,coli doctor 排查任何环境问题;
• 深入感兴趣的机制:挑一个章节对应的源文件,逐行读 + 改 + 测——比如改 expert_store.h 的 LRU 策略,跑 tests/ 的 token-exact 回归;或调 kv_prefix_reuse 的复用条件观察 DeepSeek V4 第二 turn 的 320s→61s 实测;
• 参与开放假设实验:Colibrì 自述是"一个你今天就能跑的推理引擎,也是一个开放研究平台"。文档里有大量"已知假设待验证"的条目,比如 spin-wait 在 unified memory 上的真实收益、Metal MTLResidencySet 的 E5 实验、Vulkan iGPU 的流式专家 offload 边界;
• 贡献负结果:Colibrì 把负结果(某优化实测变慢)也当成有价值的研究产出——#707/#341/#116 这些 PR 都记录了"为什么不这么做"。如果你测出一个反直觉的负结果,提 issue 或 PR 记录下来,对社区同样重要。

七、全书收尾

九章机制深潜到此为止。从 colibri.c 顶部的命题,到 docker/Dockerfile.slim 的运行时镜像,我们走完了"一个纯 C 的万亿参数 MoE 推理引擎如何在消费硬件上跑通"的完整答案——命题、稀疏性、量化容器、专家缓存、多层级存储、双 SSD 重叠、路由遥测、KV 压缩、CPU/GPU 异构、CLI 服务 Web 全栈。每一步都附了源码、附了边界、附了诚实假设。剩下的工作交给读者:打开 c/,选一个章节对应的文件,开始读、改、测、贡献。蜂鸟虽小,机制完整——这就是 Colibrì。