16 KiB
16 KiB
LM Studio 类 Windows 桌面软件 —— 产品与技术方案
版本：v0.1（评审稿）
日期：2026-08-13
状态：待确认决策点后进入 Phase 0
0. 摘要
本项目目标是在 Windows 上打造一款对标 LM Studio 的本地大模型桌面应用：用户可以浏览与下载开源模型（GGUF 格式），在本机 CPU/GPU 上运行推理，获得流畅的聊天体验，并通过本地 OpenAI 兼容 API 将模型能力开放给其他工具。
本方案的核心推荐：
- 桌面框架：Tauri 2 + Rust + React（轻量、内存占用低、Rust 与推理引擎集成自然）
- 推理引擎：llama.cpp 官方 llama-server 子进程（GGUF 事实标准，CPU/CUDA/Vulkan 全覆盖，省去自研推理内核）
- 数据存储：SQLite + sqlite-vec（应用元数据 + 向量检索）
- 模型源：Hugging Face + ModelScope 双源，支持国内镜像与本地导入
- 首发范围：纯 Windows，架构保留跨平台空间
1. 产品定位
1.1 一句话定位
一个 Windows 上的"本地大模型工作站"：管模型、跑模型、用模型（聊天 + API + 知识库）。
1.2 目标用户
- AI 开发者/工程师：快速尝试不同开源模型、调试提示词、把本地模型接入自己的工具链（通过 OpenAI 兼容 API）。
- 数据敏感/科研用户：数据不出本机，有隐私与合规诉求。
- AI 爱好者：低门槛体验本地模型，不需要命令行。
1.3 对标与差异化
| 维度 | LM Studio | 本产品（建议） |
|---|---|---|
| 模型源 | Hugging Face | HF + ModelScope + 国内镜像 |
| 资源占用 | Electron，内存 300MB+ | Tauri，目标内存 < 200MB，安装包 < 150MB |
| 中文体验 | 一般 | 中文界面/文档/热门模型推荐 |
| RAG | 基础 | 内置本地文档知识库 |
| 扩展性 | 有限 | 预留插件机制（P2） |
2. 功能规划
2.1 P0 —— MVP（必须）
| 模块 | 说明 |
|---|---|
| 模型库 | 浏览/搜索/筛选 HF 与 ModelScope 的 GGUF 模型；量化版本列表；一键安装/更新/删除 |
| 下载管理 | 多分片断点续传、进度/速度展示、暂停恢复、SHA256 校验、磁盘空间预检 |
| 聊天 | 多会话、流式输出、Markdown/代码高亮、停止/重新生成、系统提示词、采样参数 |
| 推理引擎 | llama.cpp；CPU / CUDA / Vulkan 后端自动检测；GPU 层数、上下文长度可调 |
| 设置 | 模型目录、后端选择、显存/内存展示、主题、语言 |
| 本地模型导入 | 选择本地 GGUF 文件直接导入 |
2.2 P1（第二阶段）
- OpenAI 兼容 API 服务（
/v1/models、/v1/chat/completions、/v1/embeddings，SSE 流式） - 提示词/角色模板库
- 会话导出与导入（JSON / Markdown）
- 结构化输出（JSON Schema / grammar）
- 多模型并发（双模型槽位）
2.3 P2（第三阶段）
- RAG 知识库：文档导入（PDF/Word/Markdown/TXT）、分块、本地嵌入模型、向量检索、带引用的回答
- 视觉模型支持（多模态输入）
- 本地语音（whisper.cpp）
- LoRA / 适配器加载
- 插件系统
2.4 非目标（当前阶段不做）
- 云端模型托管/训练
- 移动端
- 模型微调训练（仅支持加载现成适配器）
3. 总体架构
3.1 架构总览
┌──────────────────────────────────────────────────────────────┐
│ UI 层（WebView2） │
│ React 18 + TypeScript + Tailwind + shadcn/ui │
│ 模型库 / 聊天 / 下载 / API 服务 / 设置 │
└───────────────▲──────────────────────────────────────────────┘
│ Tauri IPC（invoke / events）
┌───────────────┴──────────────────────────────────────────────┐
│ 应用核心层（Rust） │
│ ├ 命令路由与状态管理 │
│ ├ 模型注册表（SQLite） │
│ ├ 下载管理器（tokio + reqwest，分片断点续传） │
│ ├ 会话 / 提示词管理 │
│ ├ 本地 API 服务（axum，OpenAI 兼容） │
│ └ 引擎生命周期管理（spawn / monitor / restart） │
└───────────────▲──────────────────────────────────────────────┘
│ HTTP（127.0.0.1 随机端口，仅本机）
┌───────────────┴──────────────────────────────────────────────┐
│ 推理引擎（llama.cpp llama-server 子进程） │
│ 每模型一个进程；CPU / CUDA / Vulkan 后端 │
│ 流式输出 / 采样 / grammar / embeddings │
└──────────────────────────────────────────────────────────────┘
3.2 进程模型（关键设计决策）
- 推理引擎独立子进程：llama.cpp 偶发崩溃不会拖垮 UI；支持多模型并发；可随时重启引擎而不重启应用。
- 引擎只监听
127.0.0.1随机端口，默认不对外暴露。 - 主进程做监管：健康检查、异常自动重启、退出时优雅关闭。
3.3 数据流（以"发送一条消息"为例）
- UI 提交消息 → Rust 命令 → 存入 SQLite。
- Rust 组装请求（系统提示词 + 历史 + 采样参数）→ 调用对应模型的引擎
/v1/chat/completions（stream=true）。 - 引擎逐 token 返回 SSE → Rust 转发为 Tauri 事件 → UI 增量渲染。
- 完成/中断 → 更新会话 token 统计 → UI 刷新。
4. 技术选型
4.1 桌面框架对比
| 方案 | 优势 | 劣势 | 结论 |
|---|---|---|---|
| Tauri 2（推荐） | 安装包小、内存低、Rust 后端与引擎集成天然 | 依赖 WebView2（Win10/11 自带）、Rust 团队门槛 | ✅ 首选 |
| Electron | 生态最成熟、招人容易（LM Studio 同款） | 内存 300MB+、安装包 100MB+ | 备选 |
| WPF / WinUI 3 | 原生 Windows 体验 | 迭代慢、跨平台难 | 不推荐 |
| Qt / QML | 性能好、跨平台 | 许可与 UI 生态成本 | 不推荐 |
4.2 推理引擎
| 方案 | 优势 | 劣势 | 结论 |
|---|---|---|---|
| llama.cpp（推荐） | GGUF 事实标准；CUDA/Vulkan/ROCm/CPU 全覆盖；社区最活跃 | 需要持续跟进上游版本 | ✅ 选用 |
| ONNX Runtime + DirectML | Windows 原生 | LLM 聊天与量化生态弱 | 仅辅助 |
| MLC LLM | 编译优化好 | 工具链复杂、生态小众 | 不选 |
| vLLM | 高吞吐服务端 | Windows 部署重、不适合桌面 | 不选 |
具体集成方式：直接复用 llama.cpp 官方 llama-server，由 Rust 核心层作为子进程拉起。它已内置 OpenAI 兼容 API、grammar / JSON Schema、embeddings、健康检查与 metrics，能省去自研推理 IPC 的大量工作，并持续跟随上游修复。每个模型实例一个进程。
4.3 推荐技术栈清单
| 层次 | 选型 |
|---|---|
| 桌面壳 | Tauri 2（Rust 1.8x） |
| 前端 | React 18 + TypeScript + Vite + Tailwind CSS + shadcn/ui + Zustand |
| Markdown 渲染 | react-markdown + remark-gfm + shiki 代码高亮 |
| 应用后端 | Rust：tokio、axum、reqwest、rusqlite、serde、tracing |
| 推理引擎 | llama.cpp（llama-server），构建矩阵：CPU + CUDA 12 + Vulkan |
| 数据库 | SQLite（元数据）+ sqlite-vec（向量检索，P2） |
| 下载 | reqwest 多分片 Range 下载 + SHA256 校验 |
| 模型源 | Hugging Face Hub API + ModelScope API；支持镜像切换 |
| 自动更新 | Tauri Updater（NSIS/MSI + 代码签名） |
| 测试 | Rust 单测 + 集成测试（小 GGUF）+ Playwright E2E |
5. 核心模块设计
5.1 模型注册表（SQLite）
models表：repo_id、source（hf/modelscope）、文件路径、量化等级、大小、SHA256、状态、元数据（参数量/上下文/License）、安装时间。- 元数据展示：参数量、量化等级、上下文长度、显存/内存估算、License。
- 操作：安装、升级、删除（先进回收站）、导入本地文件。
5.2 下载管理器
- 流程：解析 repo 文件列表 → 获取直链 → 磁盘空间预检 → 多分片并行下载（每片 4–16MB）→
.part临时文件 → 校验 → 原子改名。 - 断点续传：记录已完成分片，重启应用后自动恢复。
- 镜像切换：HF 失败自动重试 / 手动切换 hf-mirror 或 ModelScope。
- 安全：校验 SHA256，拒绝不匹配文件。
5.3 推理引擎管理
- 启动：读取模型配置 → 选择后端（CUDA > Vulkan > CPU）→ 估算默认 offload 层数 → 拉起 llama-server。
- 运行时监控：tok/s、显存/内存占用、上下文使用率。
- 参数控制：temperature、top_p、top_k、repeat_penalty、max_tokens、context_length。
- 结构化输出：JSON Schema 转 GBNF grammar。
- 多模型：每模型一个进程，默认允许 1–2 个并发，内存不足时给出提示。
5.4 会话与聊天
- 数据表：
conversations/messages（role、content、tokens、耗时）。 - 上下文管理：超过 context_length 时先做滑动截断（P2 升级为自动摘要）。
- 渲染：流式 Markdown、代码高亮、复制按钮、tok/s 与耗时展示。
- 能力：停止生成、重新生成、编辑上一条、多分支会话（P1）。
5.5 本地 API 服务
- axum 实现
/v1/models、/v1/chat/completions、/v1/completions、/v1/embeddings。 - 默认仅监听
127.0.0.1，可配置端口与 API Key；默认关闭 CORS。 - API 请求使用独立上下文，不与 UI 会话互相污染。
- 内置快速测试面板。
5.6 设置与硬件检测
- 启动时枚举：GPU 型号、显存、驱动版本、CUDA/Vulkan 可用性。
- 模型内存估算：模型文件大小 + KV cache 估算，指导用户选择量化与 offload。
5.7 RAG（P2 设计要点）
- 文档解析：PDF（pdfium）、docx、md、txt；分块采用 text-splitter（按结构 300–500 tokens，带重叠）。
- 嵌入：本地 bge-m3 / nomic-embed-text（llama.cpp embeddings）。
- 检索：sqlite-vec 近似最近邻 + BM25 混合召回，重排后拼入提示词。
- 引用：回答附来源文档与页码。
6. 关键技术难点与对策
| 难点 | 对策 |
|---|---|
| Windows 多 GPU 后端 | 预编译 CPU/CUDA/Vulkan 三套引擎；运行时检测驱动；用户可手动指定 |
| AMD / Intel GPU | Vulkan 兜底；保留 ROCm 实验通道 |
| 下载稳定性 / 大文件 | 分片断点续传、SHA256 校验、镜像切换、磁盘预检 |
| llama.cpp 崩溃 | 子进程隔离 + 监管自动重启 + 本地崩溃日志 |
| 流式体验 | SSE 直通 + 前端增量渲染；首 token 延迟埋点 |
| 中国网络环境 | ModelScope 直连 + HF 镜像 + 本地模型导入 |
| 安装分发 | WebView2 引导安装、NSIS/MSI、代码签名、自动更新 |
| 数据安全 | 全部本地存储；API 默认仅本机；遥测默认关闭 |
7. 工程化与质量
7.1 仓库结构（建议 monorepo）
apps/desktop # Tauri 壳
crates/core # 业务核心（模型注册表、会话）
crates/engine # 引擎生命周期管理
crates/download # 下载管理器
crates/api # OpenAI 兼容 API 服务
ui/ # React 前端
scripts/ # llama.cpp 构建脚本、打包脚本
models/ # 测试用迷你模型
7.2 CI/CD 与质量
- GitHub Actions Windows 矩阵：CPU / CUDA / Vulkan 构建缓存；nightly 自动构建；release 签名发布。
- 测试：核心逻辑单测；下载管理器用本地 mock HTTP 测断点续传；引擎集成测试用 0.5B 小模型；GPU 冒烟测试矩阵。
- 日志：Rust tracing 滚动日志，支持一键导出诊断包。
8. 里程碑与排期
| 阶段 | 内容 | 周期 |
|---|---|---|
| Phase 0 技术验证 | Tauri 骨架、llama.cpp 编译、llama-server 集成、单文件下载 | 1–2 周 |
| Phase 1 MVP | 模型库、下载、聊天、引擎管理、设置 | 8–10 周 |
| Phase 2 生态 | API 服务、提示词库、结构化输出、多模型 | 4–6 周 |
| Phase 3 RAG | 文档知识库、嵌入、检索、引用 | 6–8 周 |
| Phase 4 进阶 | 多模态、语音、插件、对比评测 | 持续迭代 |
人员配置建议：Rust 后端/引擎集成 1 人 + 前端 1 人 + ML 顾问 0.5 人 + 设计/测试 0.5 人 → MVP 约 2.5–3 个月；单人全职约 4–5 个月。
9. 风险清单
- CUDA 构建/驱动兼容性（高）→ 多后端 + 预编译矩阵 + 运行时检测。
- 与成熟竞品差距（中）→ 差异化：中文生态 / 轻量化 / RAG / 插件。
- HF 访问不稳定（中）→ ModelScope + 镜像 + 本地导入。
- 长期跟进 llama.cpp 成本（中）→ 使用官方 llama-server 降低耦合。
- 生成内容合规（低）→ 本地优先、免责声明、可选内容过滤。
- 本地 API 安全（低）→ 默认回环监听 + API Key。
10. 待确认决策点
- 桌面技术栈：推荐 Tauri 2 + Rust + React；若团队以 JS 为主可改用 Electron。
- 推理引擎方案：推荐 llama.cpp llama-server 子进程；不推荐自研推理内核。
- 首发范围：确认纯 Windows（架构保留跨平台空间）。
- 差异化优先级：中文模型生态 / 内置 RAG / 轻量化 / 插件系统，先做哪个。
- 开源 or 闭源 / 商业化：影响社区运营与分发策略。
11. 评审确认与 Phase 0 进展（v0.2）
11.1 决策确认（2026-08-13）
用户已确认：
- 技术栈：Tauri 2 + Rust + React。
- 推理引擎：llama.cpp llama-server 子进程。
- 首发：纯 Windows，架构保留跨平台扩展空间。
- 差异化：中文模型生态 / RAG / 轻量化 / 插件系统全部纳入规划，后续高级功能逐步迭代。
11.2 Phase 0 完成情况
- Monorepo 骨架：
apps/desktop（Tauri 壳）+crates/core|engine|download|api+ui/（React）+scripts/。 - 工具链：Rust 1.97.1、VS Build Tools 17.14（MSVC + Windows SDK）、Node 22 就绪。
- 编译验证：4 个 crate 与桌面应用（debug）全部编译通过；前端 tsc + vite 构建通过。
- 推理链路：llama.cpp b10375 预编译 CPU 引擎 + Qwen2.5-0.5B Q4_K_M 冒烟测试通过（普通请求 + 流式 SSE）。
- 应用启动：桌面应用可正常启动并初始化 SQLite（
%APPDATA%\XianrenStudio）。 - 已有页面：模型库（导入/删除）、聊天（流式、参数调节、会话）、下载（进度事件）、本地 API 服务、设置。
11.3 下一步（Phase 0 收尾 → Phase 1）
- CUDA / Vulkan 后端引擎接入与运行时自动检测。
- 模型库浏览/搜索（HF + ModelScope API 列表页）。
- 下载页集成模型源（量化版本选择、SHA256 展示）。
- 会话持久化增强（标题自动生成、上下文管理）。
- 打包分发（NSIS 安装包、自动更新、代码签名）。