colibrì Web面向 OpenAI 兼容推理服务器的 React/Vite 前端实战指南【免费下载链接】colibriRun frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 项目地址: https://gitcode.com/GitHub_Trending/colibri3/colibricolibrì 仓库自带一个名为colibrì web代码中标记为colibri-web的浏览器端界面它是一套 React 18 Vite 构建的单页应用专门面向本仓库 C 引擎提供的 OpenAI 兼容服务器。本文基于 web/README.md 展开结合 web/src 源码与测试完整讲解它的安装启动、端点探测、三大视图Chat / Brain / Profiling、底层 API 客户端、运行时能力协商以及存储安全策略。读完你既能把这套界面跑起来接上任意兼容后端也能理解其「浏览器尽量轻、逻辑收敛到纯函数」的设计取舍。一、colibrì web 是什么web/目录是一套前端界面 轻量 API 客户端通过 OpenAI 兼容协议与引擎通信。核心事实技术栈React 18 TypeScript Vite Tailwind CSS 4测试用 Vitest见 web/package.json默认端点http://127.0.0.1:8000/v1对应引擎启动的 OpenAI 兼容服务见 docs/api.md三个视图Chat对话、BrainMoE 专家热力图、Profiling逐轮耗时画像界面既可在本地开发服务器中运行也可由引擎自身托管此时前端与 API 同源。界面左侧边栏承担全部「连接 运行监控」职责端点输入、API Key、Probe 按钮、运行时硬件信息、调度器指标、推理参数与 KV 会话切换右侧主区随 Tab 切换视图。二、快速开始安装、开发、构建与验证原文档给出了最核心的四条命令这里结合package.json中的 scripts 补充说明。npm install npm run devnpm run dev由 Vite 启动开发服务器端口固定为5173strictPort: true见 web/vite.config.ts并配置了 Tailwind 4 的 Vite 插件与路径别名指向./src若在 Tauri 桌面环境TAURI_DEV_HOST存在中开发HMR 会改用ws协议监听1421端口并忽略src-tauri目录的监听。默认端点即http://127.0.0.1:8000/v1。先启动 API 服务器本仓库 C 引擎或任何兼容后端再点击侧边栏的Probe server拉取模型列表。本地验证两条命令npm test # vitest run —— 全部测试 npm run build # tsc -b vite build —— 先类型检查再打包npm run preview可对构建产物做本地预览。测试套件刻意保持「浏览器轻量」API 请求统一 mockfetch运行时能力与存储行为通过纯函数覆盖无需启动真实浏览器。三、端点连接、Probe server 与自动连接3.1 默认端点与同源部署web/src/App.tsx 中有一个值得注意的判定逻辑const servedByEngine typeof window ! undefined window.location.port ! 5173 window.location.protocol.startsWith(http) const defaultBase servedByEngine ? ${window.location.origin}/v1 : http://127.0.0.1:8000/v1当页面由引擎直接托管非5173开发端口时默认端点自动取当前页面源 /v1实现同源访问否则回退到本地开发默认值http://127.0.0.1:8000/v1连接后若当前选中模型不在服务器模型列表中会自动切换到第一个可用模型。3.2 Probe server 流程点击 Probe 后connect函数App.tsx调用listModels拉取/v1/models得到data[].id列表再调用getHealth拉取健康与调度器信息用于填充侧边栏 Runtime 面板成功后状态变为connected进入每 5 秒一次的/health轮询页面隐藏时暂停见 EFFECT #4。在引擎托管场景下应用还会自动连接一次通过useEffect在挂载后触发connect()避免每次刷新都要手动点 Probe见 App.tsx。四、三个视图解析4.1 Chat流式对话、推理过程与多模态Chat 视图是主界面具备SSE 流式输出通过streamChat实时消费/v1/chat/completions的data:帧思考过程分离reasoning_content增量单独渲染为可折叠的 reasoning 块且不会随历史回传给服务器见 web/src/lib/api.ts 中ChatMessage.reasoning的设计注释图片附件支持粘贴、拖拽或按钮上传图片以data:URI 保存在attachments中发送时若有图messages会转成 OpenAI 的 parts 形式[{type:text},{type:image_url,image_url:{url}}]见 api.ts实时指标徽章token 计数、tok/s、TTFT首 token 延迟以 reasoning 或正文首个 token 为准、用量prompt→completion、截断告警finish_reason length、队列等待时间等全部展示在顶栏见 App.tsx。4.2 BrainMoE 专家热力图Brain 视图可视化模型各层专家驻留情况数据来自两个端点见 web/src/Brain.tsxGET /experts引擎持续发布的EMAP/HITS状态返回{rows, cols, map, hits, seq}每 1.5 秒轮询一次GET /experts.json同源、同认证可选发布的专家主题图谱experts对应 c/tools/expert_atlas 生成的内容提供主题亲和度、熵与专家类型标注。每个专家格子按字节编码解析高 2 位是驻留 tierdisk/ram/vram低 6 位是热度被路由选中的次数命中过的专家会触发白色脉冲并随时间衰减p * 0.94。悬停可查看真实层号含 MTP 层换算、tier、热度与主题亲和 Top-3。4.3 Profiling逐轮耗时画像原文档特别强调的 Profiling 面板其数据源是服务器的GET /profile端点——一个滚动窗口的逐轮PROF快照由引擎在每轮结束点发出。前端 web/src/Profiling.tsx 每 2 秒轮询一次并做如下拆解阶段分解expert_wait_sI/O 等待、expert_matmul_s专家矩阵乘、attention_s注意力、lm_head_sLM 头剩余时间归入other_sShareBar按 wall time 占比绘制单轮与全部轮次的堆叠色条蓝IO、绿matmul、橙attention、深绿lm_head、紫other两张图表吞吐柱状图tok/s与按阶段堆叠的 wall time 柱状图最近 40 轮四个指标卡最近一轮 tok/s、wall 时间、批处理效率completion_tokens / forwards即每次 forward 的平均 token 数、磁盘服务时间expert_disk_s引擎侧与计算重叠的部分明细表按轮列出 prompt→completion tokens、tok/s、各阶段耗时与磁盘服务时间。对应的数据结构定义在 web/src/lib/api.tsProfileTurn含wall_s / prompt_tokens / completion_tokens / expert_disk_s / expert_wait_s / expert_matmul_s / attention_s / lm_head_s / forwardsProfileResponse为{seq, turns[]}。五、API 客户端端点归一化与 SSE 解析web/src/lib/api.ts 是整个前端的通信核心几个关键设计值得展开5.1 端点归一化export function endpoint(baseUrl: string, path: string) { return ${baseUrl.replace(/\/$/, )}/${path.replace(/^\//, )} } export function serverEndpoint(baseUrl: string, path: string) { return endpoint(baseUrl.replace(/\/v1\/?$/, ), path) }OpenAI 协议路径models、chat/completions走endpoint挂在/v1之下运行时端点/health、/profile走serverEndpoint剥掉/v1前缀后解析到同级路径——这正是原文档强调的「/health与/profile解析在 OpenAI/v1前缀旁边、而非其下方」。测试 web/src/lib/api.test.ts 对三种 base 形态带/v1、带尾部斜杠/v1/、不带/v1验证了这一归一化行为。5.2 SSE 流式解析extractSSE按空行切帧、只取data:行并保留未完成的残帧等下一个网络块补齐{data, rest}结构同时兼容\n\n与\r\n\r\n、单帧多data:行。流结束后从响应头读取两个 colibrì 专属字段x-colibri-queue-wait-ms调度器队列等待毫秒数无法解析或非有限数时为nullx-request-id本轮请求 ID。5.3 请求体的兼容性设计streamChat组装请求体时api.tsenable_thinking: options.enableThinking, ...(options.cacheSlot undefined ? {} : { cache_slot: options.cacheSlot }), stream: true, stream_options: { include_usage: true },enable_thinking控制推理模型是否输出思考过程cache_slot仅在调用方显式传入时才出现在请求体且是否传值由运行时协商决定见下节保证对通用 OpenAI 后端完全透明stream_options.include_usage让末帧携带usage用于顶栏 token 统计。六、运行时能力协商/health、scheduler.active 与 KV 会话前端通过/health返回内容动态调整自身行为核心在 web/src/lib/runtime.tsexport function activeRequests(health: HealthResponse | null): number { return Number(health?.scheduler?.active || 0) } export function supportsCacheSlots(health: HealthResponse | null): boolean { return typeof health?.kv_slots number health.kv_slots 0 }scheduler.active双形态归一化兼容布尔true/false与数字两种响应Number()统一成 0/1/N缺省视为空闲。测试 web/src/lib/runtime.test.ts 覆盖true→1、false→0、3→3、0→0四种情形KV 会话协商仅当health.kv_slots是正数时侧边栏才出现「KV Session」下拉会话按 slot 编号对话历史按 slot 隔离存放见 App.tsx且请求体才携带cache_slot。测试 api.test.ts 明确断言通用后端不携带cache_slotcolibrì 广告了 KV slots 后才发送cache_slot: 0调度器面板/health.scheduler中的active/queued/max_queue/admitted/completed/rejected/timed_out/cancelled驱动侧边栏「活跃/排队/完成/失败」计数失败数 rejected timed_out cancelledApp.tsx/health.tiers则渲染 VRAM/RAM/Disk 三层驻留分布条/health.hwinfo显示 CPU/GPU/RAM 硬件信息。关于服务器侧实现可参考 docs/api.md 中对GET /health与cache_slot字段的说明/health暴露健康与调度信息请求可用可选整数cache_slot选择 KV 槽位见 docs/api.md。七、持久化与安全API Key 只存内存web/src/lib/storage.ts 实现了明确的存储边界export function persistPublicSettings(storage: StringStorage, baseUrl: string, model: string) { storage.setItem(colibri.baseUrl, baseUrl) storage.setItem(colibri.model, model) // API credentials intentionally remain memory-only. Remove values left by // older web releases whenever public settings are persisted. storage.removeItem(colibri.apiKey) }只持久化公共设置端点与模型选择写入localStorage键为colibri.baseUrl与colibri.modelAPI Key 仅内存apiKey只存在于 React state任何时刻都不写入存储清理旧值每次持久化公共设置时主动删除旧版本遗留的colibri.apiKey防止凭据残留在浏览器中存储降级stored与persistPublicSettings均在try/catch中回退受限存储模式下静默失败并接受可注入的存储接口以便测试。对应测试 web/src/lib/storage.test.ts 验证了「持久化 baseUrl/model 同时移除 legacy apiKey」与「绝不写入 apiKey」两个关键约束。八、测试策略浏览器轻量、纯函数优先测试套件Vitest遵循「API 请求用 mock fetch、逻辑收敛到纯 helper」的原则api.test.tsextractSSE的残帧保持与 CRLF 兼容、serverEndpoint的/v1前缀剥离、/health携带 Bearer 凭据、/profile解析在/v1旁边、cache_slot按能力协商发送/省略runtime.test.tsscheduler.active布尔/数字归一化、缺省指标视为空闲、KV slots 能力判定storage.test.ts存储边界与旧凭据清理。这些测试与引擎侧PROF快照/profile的数据来源及EMAP/HITS/experts的数据来源共同构成前后端协议的一致性保障相关引擎数据结构可从 c/colibri.c 中的专家缓存索引ecache_slot_by_expert与 docs/serve_protocol.md 的/experts端点说明继续追查。九、常见问题与运行前提端口占用Vite 开发端口固定5173且strictPort: true被占用时直接报错而非换端口后端未启动Probe 会显示错误信息连接失败提示连接成功后/health轮询失败只更新 healthError不会断开已建立的连接状态浏览器自动连接仅当页面由引擎托管非 5173 端口时生效KV 会话切换切换 slot 即切换对话历史若当前 slot 超出health.kv_slots范围会自动回落到 slot 0多模态请求图片必须为服务器接受的data:URI 形式前端不做磁盘路径假设。适用前提本前端面向仓库 C 引擎或兼容后端的/v1OpenAI 协议建议先按 docs/api.md 启动并验证GET /health与GET /profile两个非/v1端点可用再接入本界面。十、总结colibrì web 用最轻量的方式把「运行在自有硬件上的 MoE 引擎」搬进浏览器Chat 提供完整流式对话含推理过程与多模态Brain 把 MoE 专家驻留状态变成可交互热力图Profiling 让引擎每一轮的 wall time 去向I/O、专家矩阵乘、注意力、LM 头一目了然。而它的核心竞争力在于协议严谨性——/health、/profile、/experts与 OpenAI/v1前缀的正确解析、scheduler.active双形态归一化、cache_slot按能力协商发送、API Key 绝不落盘这些细节都有对应源码与单测背书也让前端可以安全地对接任何 OpenAI 兼容后端。【免费下载链接】colibriRun frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 项目地址: https://gitcode.com/GitHub_Trending/colibri3/colibri创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考