giveen/ninfer-studio

源码: https://github.com/giveen/ninfer-studio

NInfer Studio

一个从零构建的、原生的 Linux 与 Windows 桌面应用程序（基于 Tauri 2 —— Linux 上使用 WebKitGTK，Windows 上使用 WebView2），专为 NInfer (https://github.com/Neroued/ninfer) 本地 LLM 推理引擎打造——将一个原始的 ninfer-serve 二进制文件转化为一款完整的产品。

NInfer Studio 是 桌面外壳程序：提供带有每 GPU 预设的引擎配置、
支持 Hugging Face 下载的模型管理、支持视觉功能的流式聊天、一个智能体
编码环境，以及实时的 token/吞吐量/VRAM 指标——控制平面在进程内运行。
推理引擎本身 (ninfer-serve) 是一个独立项目，你需要在 Studio 中为其指定路径。

截图

功能特性

• 引擎配置 —— 每个 ninfer-serve 选项都被转化为带有标签和文档说明的控件：上下文/KV 容量与数据类型（bf16 / int8 / fp8 / nvfp4 / k8v4）、并发度、推测解码（MTP / DFlash / DFlash2）、视觉与媒体预算、上下文缓存层级、采样默认值、日志记录——外加一个实时生成的启动命令和一键预设，包括五个根据引擎自身在所有五个注册构件上测量的 KV 密度校准的 RTX 5090 预设（320k k8v4, 128k bf16, C=4 nvfp4 serving, 96k 低延迟, 128k MoE, 实验性 480k NVFP4 KV）。
• VRAM 安全下限 —— 加载后，Studio 追踪引擎的 capacity 日志行（其自身的运行时/空闲 VRAM 统计），并在空闲 VRAM 低于 1.8 GiB 安全下限时发出警告，以防 OOM 在生成过程中终止运行。对已接入的引擎同样有效。
• 模型管理 —— 扫描模型目录以查找已下载的 .ninfer 构件，显示带有本地/下载状态的已注册目录，并通过 hf CLI 从 Hugging Face 下载构件。可选的 Hugging Face 令牌（在 UI 中隐藏显示，通过 HF_TOKEN 环境变量传递——绝不通过命令行参数）可解锁更快、无速率限制的下载。
• 聊天 —— 通过引擎的 OpenAI 兼容 API 进行流式聊天：推理过程显示在可折叠的思考块中，每条消息的引擎指标（TTFT、提示/解码 tok/s、缓存的 token、MTP 草案接受率），每次对话的采样/思考参数覆盖，图片/视频附件在转录中内联渲染（视觉引擎），模型发出的 Markdown 图片，实时上下文使用量仪表盘（直接从引擎读取上下文窗口，无需手动 --max-context 记账），停止按钮，以及持久化的对话历史。输入 /compact 可要求引擎将整个对话浓缩为一个结构化的检查点摘要，该摘要将替换当前线程并成为其起始上下文（在接近上下文限制警告时非常有用）。
• 编码器模式 —— 基于同一引擎的智能体编码环境：包含文件读/写/编辑、grep/glob、带会话和后台作业的 shell 执行、git 集成的计划/执行循环、侦查 / 验证 / 评审环境通行证（可选加入、带标签、可折叠）、带深度和步骤预算的工作器/子代理委托、可恢复的对话检查点、人工审批（HITL）关卡、沙盒化与实时执行模式，以及每个工作区的记忆库——外加实时的预填充/解码指示器，让模型的思考过程永不隐身。
• 引擎监管 —— 从 UI 启动/停止 ninfer-serve，接入已运行的引擎（绝不重复启动），追踪引擎日志，通过 nvidia-smi 报告 GPU 状态，并在重建前停止运行中的引擎，以便全新二进制文件能干净链接。
• 上下文限制感知 —— 聊天视图显示实时的“最大上下文百分比”使用量，并在引擎即将截断前发出警告（接近 >75%，接近满额 >90%）。
• 桌面优化 —— 系统托盘图标 + 关闭时隐藏（关闭窗口会将其隐藏到托盘并保持已启动的引擎运行，而不是终止它）、单实例启动（第二次启动会聚焦现有窗口），以及用于引擎就绪/停止、下载完成和构建完成的原生操作系统通知。在 AppImage、Windows exe 和系统托盘中使用自定义应用图标。
• 强化的本地主机 API —— CORS 使用显式允许列表（Tauri webview + 开发 Vite），并拒绝外部 Host 请求头，从而堵住了针对回环控制平面的 DNS 重绑定攻击向量。
• 按用户持久化 —— 应用设置、引擎配置文件、保存的命名配置文件以及聊天对话都会持久化到按用户的配置目录（Linux 上为 ~/.config/ninfier-studio，Windows 上为 AppData/Roaming/ninfier-studio），使其在重启后得以保留，并随用户主目录漫游。可通过 NINFIER_STUDIO_DATA 覆盖该位置。

架构

desktop/
  Rust 控制平面 + Tauri 2 桌面外壳
control/
  ninfier-control: 引擎监管、模型扫描、hf 下载、编码器端点、VRAM 统计、nvidia-smi 状态、SSE 安全的引擎 API 代理、静态托管
app/
  ninfier-studio: Tauri 2 窗口，承载控制平面
apps/web
  React 19 + Vite + Tailwind 4 前端（聊天 / 编码器 / 引擎 / 模型 / 设置）
apps/sidecar
  零依赖的 Node 22 开发模式服务器，实现相同的控制平面 API
start-stack.sh
  开发便捷脚本：启动 sidecar，从环境变量填充配置，启动/接入引擎
~/.config/ninfier-studio/
  按用户运行时状态 (CONFIG_HOME)；Windows 上为 AppData/Roaming/ninfier-studio —— config.json, profile.json, chats.json, last-start.json, engine-.log。可通过 NINFIER_STUDIO_DATA 覆盖位置。

控制平面（desktop/control，或在浏览器开发模式下的 apps/sidecar）是唯一与引擎交互的进程。在桌面应用中，它运行在 Tauri 核心内，因此引擎的父进程就是应用本身——由单一进程监管引擎。

所有状态更改端点仅接受回环 Host/Origin 值（浏览器跨域调用被限制在允许的 Tauri/Vite 源）——详见安全。

前置条件

• 一个构建好的 NInfer 引擎（ninfer-serve）以及（用于 GPU 统计）NVIDIA 驱动 + nvidia-smi。在设置中为其指定路径（ninferPath, modelsDir）。
• Rust 工具链（稳定版）和 Node ≥ 22 + pnpm（仅需用于构建 web 包）。
• Linux 上的 Tauri 2 系统依赖 (Debian/Ubuntu)：

  sudo apt-get install -y \
    libwebkit2gtk-4.1-dev libgtk-3-dev libjavascriptcoregtk-4.1-dev \
    libsoup-3.0-dev librsvg2-dev libayatana-appindicator3-dev
  

  在一些滚动发布/衍生发行版上，WebKit/GLib 运行时和 -dev 包可能
  不同步（-dev 包要求更旧的运行时）。如果 apt 因版本不匹配错误
  而拒绝安装，请允许运行时降级：
  sudo apt-get install -y --allow-downgrades libwebkit2gtk-4.1-dev ...。

• 可选：用于应用内模型下载的 hf CLI，以及用于编码器仓库地图的 rg (ripgrep)。

构建与运行

git clone && cd ninfier-ui
pnpm install && pnpm build  # 构建 web 包 → apps/web/dist

桌面应用（调试）：

pnpm desktop:run  # 在 :8787 上启动原生 WebKitGTK 窗口（调试）

桌面应用（发布版二进制）：

pnpm desktop:build  # cargo build --release（无托盘功能）
# 或带系统托盘图标：
pnpm desktop:build:tray  # 添加 --features tray（需要 libayatana-appindicator3-dev）
desktop/target/release/ninfier-studio

打包安装程序 / 便携镜像：

pnpm desktop:bundle  # pnpm tauri build --features tray --bundles deb appimage

在 desktop/target/release/bundle/ 中生成 .deb + .AppImage。

开发模式：

pnpm dev           # Web 开发：Vite :5173（HMR）+ Node sidecar :8787（浏览器 UI）
pnpm control:run   # 无头模式：仅 Rust 控制平面，无窗口
pnpm desktop:run   # 原生窗口 + Rust 控制平面（使用 apps/web/dist 中的分发文件）

NINFIER_STUDIO_DATA 覆盖按用户配置目录（Linux 上默认为 ~/.config/ninfier-studio，Windows 上为 AppData/Roaming/ninfier-studio），NINFIER_STUDIO_DIST（默认为 apps/web/dist）覆盖分发位置。

start-stack.sh（开发用）启动 sidecar 并可选地填充配置 + 启动引擎，所有路径来自环境变量——NINFER_DIR、MODELS_DIR、CODER_WORKSPACE、ARTIFACT、ENGINE_PORT；设置在首次运行后持久化于 config.json。

打包与持续集成

发布版 .github/workflows/release.yml 在 ubuntu-24.04（.deb + .AppImage）和 windows-latest（.exe/nsis）上构建并发布——会创建一个草稿 GitHub Release，并将每个平台的构件上传其中。通过推送版本标签触发发布：

git tag v0.2.6 && git push origin v0.2.6

（或在 Actions 标签页手动运行工作流）。Windows 构件目前未签名——在集成代码签名前，预计会出现 SmartScreen 警告。

配置

设置、引擎配置文件、已保存的配置文件和对话都位于按用户配置目录中（Linux 上默认为 ~/.config/ninfier-studio，Windows 上为 AppData/Roaming/ninfier-studio；可通过 NINFIER_STUDIO_DATA 覆盖），在首次保存时创建。关键文件：

config.json 关键字段（使用应用中的 camelCase 写法）：

安全性

控制平面绑定到回环地址，并验证每个请求的 Host 和 Origin 是否来自回环名称和允许的 Tauri/Vite 源——恶意网站既不能跨域调用 API，也不能通过将其 DNS 重绑定到 127.0.0.1 来访问它。密钥（HF 令牌）绝不会通过 API 返回：客户端只能看到 ******** 掩码，并且掩码的写入会保留存储的值。编码器文件操作被限制在配置的工作区内。有关漏洞报告策略和当前依赖项/审计状态，请参阅 SECURITY.md。

延伸阅读

• RESEARCH.md —— 技术栈与参考项目研究。
• DESIGN.md —— 完整架构、屏幕规格、选项→控件映射以及验证日志。