317 lines
16 KiB
Markdown
317 lines
16 KiB
Markdown
# 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 数据流（以"发送一条消息"为例）
|
||
|
||
1. UI 提交消息 → Rust 命令 → 存入 SQLite。
|
||
2. Rust 组装请求（系统提示词 + 历史 + 采样参数）→ 调用对应模型的引擎 `/v1/chat/completions`（`stream=true`）。
|
||
3. 引擎逐 token 返回 SSE → Rust 转发为 Tauri 事件 → UI 增量渲染。
|
||
4. 完成/中断 → 更新会话 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. 风险清单
|
||
|
||
1. **CUDA 构建/驱动兼容性**（高）→ 多后端 + 预编译矩阵 + 运行时检测。
|
||
2. **与成熟竞品差距**（中）→ 差异化：中文生态 / 轻量化 / RAG / 插件。
|
||
3. **HF 访问不稳定**（中）→ ModelScope + 镜像 + 本地导入。
|
||
4. **长期跟进 llama.cpp 成本**（中）→ 使用官方 llama-server 降低耦合。
|
||
5. **生成内容合规**（低）→ 本地优先、免责声明、可选内容过滤。
|
||
6. **本地 API 安全**（低）→ 默认回环监听 + API Key。
|
||
|
||
---
|
||
|
||
## 10. 待确认决策点
|
||
|
||
1. **桌面技术栈**：推荐 Tauri 2 + Rust + React；若团队以 JS 为主可改用 Electron。
|
||
2. **推理引擎方案**：推荐 llama.cpp llama-server 子进程；不推荐自研推理内核。
|
||
3. **首发范围**：确认纯 Windows（架构保留跨平台空间）。
|
||
4. **差异化优先级**：中文模型生态 / 内置 RAG / 轻量化 / 插件系统，先做哪个。
|
||
5. **开源 or 闭源 / 商业化**：影响社区运营与分发策略。
|
||
|
||
---
|
||
|
||
## 11. 评审确认与 Phase 0 进展（v0.2）
|
||
|
||
### 11.1 决策确认（2026-08-13）
|
||
|
||
用户已确认：
|
||
|
||
1. 技术栈：**Tauri 2 + Rust + React**。
|
||
2. 推理引擎：**llama.cpp llama-server 子进程**。
|
||
3. 首发：**纯 Windows**，架构保留跨平台扩展空间。
|
||
4. 差异化：中文模型生态 / 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）
|
||
|
||
1. CUDA / Vulkan 后端引擎接入与运行时自动检测。
|
||
2. 模型库浏览/搜索（HF + ModelScope API 列表页）。
|
||
3. 下载页集成模型源（量化版本选择、SHA256 展示）。
|
||
4. 会话持久化增强（标题自动生成、上下文管理）。
|
||
5. 打包分发（NSIS 安装包、自动更新、代码签名）。
|