xianren_studio/docs/LMStudio类Windows桌面软件_产品技术方案.md

# 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 安装包、自动更新、代码签名）。