2026-08-13 12:48:50 +08:00
|
|
|
|
# Xianren Studio（仙人工作室）
|
|
|
|
|
|
|
|
|
|
|
|
一款对标 LM Studio 的 Windows 本地大模型桌面应用：浏览/下载/管理 GGUF 模型，本机 CPU/GPU 推理聊天，并提供 OpenAI 兼容的本地 API 服务。
|
|
|
|
|
|
|
2026-08-13 15:37:28 +08:00
|
|
|
|
## 当前功能
|
|
|
|
|
|
|
|
|
|
|
|
- **模型库**：启动时自动扫描模型目录（可手动重新扫描），支持导入本地 GGUF、添加 OpenAI 兼容在线 API 模型（聊天时可直接选用）
|
|
|
|
|
|
- **模型广场**：搜索 Hugging Face / ModelScope 上的 GGUF 模型，按量化版本一键下载（ModelScope 文件自动附带 SHA256 校验），下载进度实时显示
|
|
|
|
|
|
- **聊天**：流式输出、Markdown/代码高亮、采样参数调节、多会话管理；本地模型与在线 API 模型统一入口
|
|
|
|
|
|
- **本地 API 服务**：OpenAI 兼容端点（/v1/models、/v1/chat/completions、/v1/embeddings），仅本机监听，可选 API Key
|
|
|
|
|
|
|
2026-08-13 12:48:50 +08:00
|
|
|
|
## 技术栈
|
|
|
|
|
|
|
|
|
|
|
|
- 桌面壳：Tauri 2（Rust）+ WebView2
|
|
|
|
|
|
- 前端：React 18 + TypeScript + Vite + Tailwind CSS
|
|
|
|
|
|
- 应用核心：Rust（tokio / axum / reqwest / rusqlite）
|
|
|
|
|
|
- 推理引擎：llama.cpp 官方 `llama-server` 子进程（CPU / CUDA / Vulkan）
|
|
|
|
|
|
- 存储：SQLite（元数据、会话、设置）
|
|
|
|
|
|
|
|
|
|
|
|
## 仓库结构
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
apps/desktop Tauri 壳（Rust 命令层 + tauri.conf.json）
|
|
|
|
|
|
crates/core 领域核心：模型注册表、会话、设置（SQLite）
|
|
|
|
|
|
crates/engine llama-server 子进程生命周期与流式聊天
|
|
|
|
|
|
crates/download 分片断点续传下载器
|
|
|
|
|
|
crates/api OpenAI 兼容本地 API 服务（axum）
|
|
|
|
|
|
ui/ React 前端
|
|
|
|
|
|
scripts/ 构建/下载脚本
|
|
|
|
|
|
docs/ 产品与技术方案
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 环境要求（Windows）
|
|
|
|
|
|
|
|
|
|
|
|
- Rust（stable，MSVC 工具链）
|
|
|
|
|
|
- Visual Studio 2022 Build Tools（含 C++ 桌面开发）
|
|
|
|
|
|
- Node.js 18+
|
|
|
|
|
|
- WebView2 Runtime（Win10/11 一般自带）
|
|
|
|
|
|
- 可选：CUDA Toolkit（GPU 推理）/ Vulkan SDK（AMD/Intel GPU）
|
|
|
|
|
|
|
|
|
|
|
|
## 快速开始
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
# 1. 安装前端依赖
|
|
|
|
|
|
npm --prefix ui install
|
|
|
|
|
|
|
|
|
|
|
|
# 2. 获取预编译 llama.cpp 引擎（默认 CPU 版，可加 -Backend cuda/vulkan）
|
|
|
|
|
|
.\scripts\fetch-llama.ps1
|
|
|
|
|
|
|
|
|
|
|
|
# 3. 下载一个测试模型（默认 Qwen2.5-0.5B Q4_K_M，约 400MB）
|
|
|
|
|
|
.\scripts\download-test-model.ps1
|
|
|
|
|
|
|
|
|
|
|
|
# 4. 启动开发模式（自动拉起 Vite + Tauri）
|
|
|
|
|
|
npm --prefix apps/desktop run dev
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-13 15:13:12 +08:00
|
|
|
|
> **重要：调试版（debug）exe 不能直接双击运行。**
|
|
|
|
|
|
> `target\debug\xianren-desktop.exe` 在调试构建下会去连 Vite 开发服务器
|
|
|
|
|
|
> （`http://localhost:5173`），不先启动前端就会显示“拒绝连接”，并会附带一个空终端窗口。
|
|
|
|
|
|
> 开发时请始终使用 `npm --prefix apps/desktop run dev`。
|
|
|
|
|
|
|
|
|
|
|
|
**直接双击运行的正式版**：
|
|
|
|
|
|
|
|
|
|
|
|
```powershell
|
|
|
|
|
|
# 编译正式版（内嵌前端页面，无终端窗口；必须带 custom-protocol 特性）
|
|
|
|
|
|
cargo build --release -p xianren-desktop --features custom-protocol
|
|
|
|
|
|
|
|
|
|
|
|
# 运行
|
|
|
|
|
|
.\target\release\xianren-desktop.exe
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
正式版双击后：设置页确认引擎路径 → 模型库导入 GGUF → 聊天页选择模型即可对话。
|
|
|
|
|
|
如需安装包，可用 `npm --prefix apps/desktop run build`（tauri build 会自动启用该特性并打 NSIS 安装包）。
|
|
|
|
|
|
|
2026-08-13 12:48:50 +08:00
|
|
|
|
## 常用脚本
|
|
|
|
|
|
|
|
|
|
|
|
| 脚本 | 用途 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| `scripts/fetch-llama.ps1` | 从 GitHub Releases 下载预编译 llama.cpp（cpu/cuda/vulkan） |
|
|
|
|
|
|
| `scripts/build-llama.ps1` | 从源码编译 llama.cpp（需要 CMake，可选 CUDA/Vulkan） |
|
|
|
|
|
|
| `scripts/download-test-model.ps1` | 下载迷你 GGUF 测试模型（支持 HF 镜像/ModelScope） |
|
|
|
|
|
|
| `scripts/generate-icons.ps1` | 重新生成应用图标 |
|
|
|
|
|
|
|
|
|
|
|
|
## 引擎与模型目录
|
|
|
|
|
|
|
|
|
|
|
|
运行时数据默认存放在 `%APPDATA%\XianrenStudio`：
|
|
|
|
|
|
|
|
|
|
|
|
- `models/`：下载的模型文件
|
|
|
|
|
|
- `engines/`：llama-server 可执行文件
|
|
|
|
|
|
- `logs/`：引擎日志
|
|
|
|
|
|
- `xianren.db`：SQLite 数据库
|
|
|
|
|
|
|
|
|
|
|
|
可在应用“设置”页修改模型目录与引擎路径。
|
