使用教程

版本：0.3.3 | 更新日期：2026-06-11

目录

1. 简介

Soul Agent Launcher（SAL） 是一个 Windows 桌面应用，用于 启动、管理和监控 llama.cpp 推理服务。它提供图形化界面替代命令行操作，支持多种 GPU 后端自动检测、模型下载、流式对话、会话管理等功能。

核心特性

特性 说明
GPU 自动检测自动识别 NVIDIA（CUDA）、AMD/Intel（Vulkan）、CPU 后端
一键启动服务无需手动敲命令，点按钮运行 llama-server
多模型管理同时运行多个模型，每个独立端口
流式对话内置聊天界面（SA Lite），支持深度思考显示
会话管理保存/加载聊天历史，自动总结长对话
自动更新启动时自动检查新版本，管理员后台发布
多语言中文/英文自动切换
完全离线可用全后端捆绑 MSI 安装包，无网络也能用

技术栈

  • 前端框架：Tauri v2（Rust + WebView）
  • 推理引擎：llama.cpp（CUDA / Vulkan / CPU）
  • 本地存储：JSON 文件（会话、配置、模型列表）
  • 更新服务：独立 Flask 服务器（可选部署）

2. 安装与卸载

系统要求

  • 操作系统：Windows 10 / 11（64 位）
  • CPU：x86_64 处理器（支持 AVX2 及以上）
  • 内存：建议 16GB 以上
  • GPU（可选）：
    • NVIDIA：驱动 ≥ 525，推荐 ≥ 570（CUDA 13）
    • AMD / Intel：Vulkan 驱动
  • 磁盘：
    • 离线完整版：约 460MB
    • 在线版：约 15MB

安装步骤

  1. 下载 MSI 安装包（.msi 文件）
  2. 双击运行，按向导完成安装
  3. 安装完成后桌面或开始菜单出现 Soul Agent Launcher 图标
提示：安装目录可在安装向导中自定义，默认为 C:\Program Files\Soul Agent Launcher\

卸载

  • 通过 Windows 设置 → 应用 → 找到 "Soul Agent Launcher" → 卸载
  • 或使用 MSI 自带的卸载程序
注意：卸载不会删除用户数据。配置文件位于 %APPDATA%\Soul-Agent-Launcher\（留空删除可清理）。

安装包类型

类型 大小 说明
离线完整版 MSI~460MB内置全部 GPU 后端，无网络也能用
在线轻量版 MSI~15MB需从网上下载或预置 llama.cpp 包
NSIS 安装包同上替代 MSI 的安装方式

3. 首次启动与自动配置

启动流程

首次启动后，SAL 会自动完成以下步骤：

启动 → 检测硬件 → 匹配后端包 → 解压 → 生成配置 → 就绪

硬件自动检测

SAL 依次检测以下 GPU 后端：

  1. NVIDIA CUDA — 执行 nvidia-smi 获取驱动版本
    • 驱动 ≥ 570 → CUDA 13.3（RTX 40xx Super / 50xx）
    • 驱动 ≥ 525 → CUDA 12.4（RTX 20xx / 30xx / 40xx）
  2. Vulkan — 执行 vulkaninfo 检查
    • AMD Radeon / Intel Arc 等
  3. CPU 兜底 — 无 GPU 加速时自动选用 CPU 后端

内置后端（离线完整版）

包名 大小 适用硬件
cuda-13.3151MBNVIDIA RTX 40xx Super / 50xx
cuda-12.4254MBNVIDIA GTX/RTX（较老型号）
vulkan-x6433MBAMD / Intel 独显
cpu-x6416MB任何 x86 处理器（无 GPU）

启动后状态

配置完成后，打开首页将显示：

[运行中]   ← 服务状态指示灯
0 个模型   ← 当前加载的模型数
端口 20000 ← 默认服务端口

4. 界面概览

整体布局

┌─────────────────────────────────────────────────────┐
│  窗口标题栏（自定义无边框）      [─] [□] [×]      │
├──────────┬──────────────────────────────────────────┤
│ 侧边导航  │          主内容区                       │
│           │                                          │
│  首页    │  （根据所选页面显示不同内容）            │
│  模型    │                                          │
│  启动    │                                          │
│  会话    │                                          │
│  对话    │                                          │
│  设置    │                                          │
│           │                                          │
│  Soul     │                                          │
│  Agent    │                                          │
├──────────┴──────────────────────────────────────────┤
│                状态栏（版本号）                      │
└─────────────────────────────────────────────────────┘

导航栏说明

页面 功能
首页服务状态总览、启停控制
模型模型列表管理、下载新模型
启动页高级参数配置、手动编译
会话聊天历史管理
对话SA Lite 极简聊天界面
设置全局配置、语言、卸载选项

托盘图标

SAL 最小化后会在系统托盘显示图标：

  • 双击 → 显示窗口
  • 右键菜单 → 显示窗口 / 退出
  • 提示文字 → "Soul Agent Launcher"

5. 首页 —— 服务总控

服务状态卡片

首页顶部显示 llama-server 的运行状态：

状态 指示灯 说明
运行中绿色服务正常，有模型加载
加载中橙色脉冲模型正在加载进显存
未启动灰色服务未运行

启停控制

按钮 作用
启动服务启动 llama-server（默认端口 20000）
停止服务停止所有正在运行的模型
管理服务进入启动页查看详情

多模型显示

当有多个模型同时运行时，首页会列出：

2 个模型 · qwen2.5-7b, llama-3.1-8b
显存 12.5GB

每个模型有独立的代理端口，API 地址格式：

原生 /chat → http://localhost:20001/chat
OpenAI    → http://localhost:20001/v1/chat/completions

状态轮询

SAL 每 5 秒自动刷新服务状态。当模型处于加载阶段（503 响应），状态栏会显示 "模型正在加载中~马上就好~"。

6. 模型管理

查看已安装模型

切换到「模型」页面，可看到已放置在 models 目录下的所有 GGUF 模型文件。

模型格式要求

SAL 支持所有 GGUF 格式 的模型文件。常见来源：

下载模型

前提：需要 Python + pip 环境，已安装 modelscope SDK。
  1. 在「模型」页点击「下载模型」
  2. 搜索或从预置列表中选择
  3. 点击下载，进度条显示实时进度
  4. 下载完成后自动出现在模型列表

加载与卸载模型

  1. 在模型列表点击模型名称
  2. 设置上下文长度（默认 4096）
  3. 点击「加载」启动
  4. 加载完成后模型进入运行状态
  5. 点击「卸载」停止模型
提示：多个模型可以同时运行，每个模型占用独立的端口。

模型文件管理

  • 模型目录：%APPDATA%\Soul-Agent-Launcher\models\
  • 刷新：点击「刷新模型列表」扫描目录
  • 删除：选中模型点击删除确认

7. 启动页 —— 高级控制

服务参数

参数 说明 默认值
端口主服务端口20000
上下文推理上下文长度4096
连接数最大并发连接8
额外参数传递给 llama-server 的其他参数（可选）

待机模式

「待机」按钮将服务切换到低功耗状态，模型仍驻留显存但释放计算资源：

待机中 → 发送请求 → 自动唤醒（1-3 秒延迟）
唤醒后 → 正常响应 → 无活动一段时间 → 自动待机

手动编译（高级）

对于需要自定义编译参数的用户：

  1. 在启动页找到「手动编译」区域
  2. 选择构建脚本路径（预置 build-minimal.ps1）
  3. 点击「开始编译」
  4. 等待编译完成（可能需要 10-30 分钟）
要求：需要安装 CMake、Visual Studio Build Tools 或 MSVC。

8. SA Lite —— 极简对话

界面说明

SA Lite 是一个轻量级聊天界面，模仿 Soul Agent 的对话体验：

┌──────────────────────────────────────┐
│  [SA] Soul Agent Lite                │
│                                      │
│  ┌──────────────────────────────────┐│
│  │ 欢迎使用 Soul Agent Lite        ││
│  │ 输入消息开始对话                 ││
│  └──────────────────────────────────┘│
│                                      │
│  ┌──────────────────────────────────┐│
│  │ 用户消息                         ││
│  └──────────────────────────────────┘│
│  ┌──────────────────────────────────┐│
│  │ 思考过程  ▼                     ││
│  │ ┌──────────────────────────────┐││
│  │ │ 模型的思考内容...            │││
│  │ └──────────────────────────────┘││
│  │                                  ││
│  │ 助手回复内容...                 ││
│  └──────────────────────────────────┘│
│                                      │
│  ┌──────────────────────────────────┐│
│  │ 输入消息，Enter 发送...  [发送] ││
│  └──────────────────────────────────┘│
│  ▓▓▓▓░░░░ 45% 上下文使用率           │
└──────────────────────────────────────┘

基础操作

  • 发送消息：在输入框输入文字，按 Enter 发送
  • 换行：Shift + Enter 换行
  • 停止生成：点击「停止」中断模型输出
  • 新建对话：切换到会话页创建新会话

深度思考

当模型返回思考过程时（如 Qwen3、DeepSeek 等），SA Lite 会显示可折叠的思考块：

思考过程  ▼           ← 点击折叠/展开
┌─────────────────────┐
│ 模型内部推理过程...  │
└─────────────────────┘
  • 思考块默认 60ms 后自动折叠
  • 可点击展开查看完整思考内容
  • 支持选中复制

多模态输入

支持图片理解模型（需模型支持）：

  1. 在设置中开启「多模态」
  2. 发送时模型会处理图片内容
  3. 需要模型以 --mmproj 参数加载视觉编码器

打字动画

发送消息后，SA Lite 显示三点跳动加载动画：

● ● ●    ← 等待第一个 Token

一旦收到模型返回的第一个 Token（思考或正文），动画消失并开始流式输出。

自动总结（长对话保护）

当对话上下文使用率达到 80% 时，自动触发总结：

对话上下文 80% → LLM 生成总结 → 存为系统消息 → 释放上下文空间
  • 80%：静默自动总结，无感
  • 95%：强制总结

总结内容会注入到后续每次请求中作为 system 消息，保持长对话的连续性。

上下文状态指示

聊天框右下角显示进度环：

▓▓▓▓░░░░ 45%  ← 当前上下文使用率
  • 绿色：健康（< 70%）
  • 橙色：接近阈值（70-80%）
  • 红色：超限风险（> 90%）

9. 会话管理

会话列表

在「会话」页面可以查看所有保存的聊天历史：

┌──────────────────────────────────┐
│  会话                            │
│                                  │
│  ┌──────────────────────────────┐│
│  │ 关于项目架构讨论             ││
│  │ 12 条消息 · 14:23:05         ││
│  ├──────────────────────────────┤│
│  │ 新会话                       ││
│  │ 3 条消息 · 14:15:02          ││
│  └──────────────────────────────┘│
│                                  │
│  [新建会话]                       │
└──────────────────────────────────┘

操作

操作 方式
加载会话点击会话条目 → 自动切换到对话页并加载消息
新建会话点击「新建会话」按钮
重命名点击编辑图标 → 输入新名称
删除点击删除图标 → 确认删除

自动重命名

当触发自动总结时，会话标题会根据总结内容自动更新。

数据存储位置

所有会话数据存储在：

%APPDATA%\Soul-Agent-Launcher\sessions\
├── s{id}.json          ← 会话元数据（标题、时间）
├── s{id}.msgs.json     ← 消息历史
└── s{id}.summary       ← 自动总结（可选）

10. 设置

通用设置

设置项 说明
llama.cpp 路径llama-server.exe 所在目录
模型目录GGUF 模型文件存放位置
默认端口服务监听端口（默认 20000）
默认上下文推理上下文窗口大小（默认 4096）

语言

支持中文和英文，三种切换方式：

  1. 自动检测：根据系统语言自动切换
  2. 手动设置：在设置页下拉选择
  3. 持久化：选择后自动保存到 localStorage

主题

  • 亮色模式 / 暗色模式 切换
  • 通过顶栏的主题按钮快速切换

行为

  • 退出时自动卸载模型：关闭窗口后自动清理所有模型进程，释放显存

检查更新

点击「检查更新」按钮手动触发版本检查。详见[自动更新](#update)章节。

11. 自动更新

检查机制

  • 自动检查：启动后 3 秒自动检查
  • 手动检查：设置页点击「检查更新」
  • 检查地址：https://sal.bszx.site/api/check-update

更新提示

当有新版本时，右下角弹出提示卡：

┌──────────────────────────┐
│ SAL 0.3.3 发布！        │
│ 建议更新至最新版！       │
│                          │
│          [更新] [跳过]   │
└──────────────────────────┘
  • 更新：打开浏览器下载最新 MSI
  • 跳过：当前版本不再提示（localStorage 记录）

管理后台

管理员可通过网页发布新版本：

地址 https://sal.bszx.site/admin
用户名Saki
密码已设置

管理功能：

  1. 登录后台
  2. 填写版本号、更新说明
  3. 上传 MSI 安装包
  4. 选择是否强制更新
  5. 点击「发布版本」

12. 多语言支持

当前支持语言

语言 代码 覆盖度
简体中文zh100%
Englishen100%

切换方式

方法一：自动切换

系统语言为中文 → 自动使用中文
系统语言为其他 → 自动使用英文

方法二：手动切换

设置 → 语言 → 下拉选择 → 即时生效

切换范围

切换语言会即时更新：

  • 导航栏文字
  • 服务状态文字
  • 会话列表文字
  • 对话输入框占位符
  • 新建会话欢迎语
  • 设置页文字
  • 自动总结提示

13. 常见问题

Q：启动后一直显示「未启动」

可能原因：

  1. 首次安装需要自动解压：等待几秒钟，SAL 正在解压对应的后端包
  2. 端口被占用：更改默认端口（设置 → 默认端口）
  3. 后端包下载不完整：重新安装完整 MSI

Q：模型加载时报错

常见错误：

  • OOM（显存不足）：降低上下文长度或换用小尺寸模型
  • 模型文件损坏：重新下载模型
  • 格式不兼容：确认模型为 GGUF 格式

Q：503 "Loading model"

这是正常现象，表示模型正在加载进显存。等待 10-30 秒后自动变为"运行中"。

Q：按钮点了没反应

通常是因为 JavaScript 加载失败：

  1. 关闭应用重新打开
  2. 如反复出现，重新安装 MSI
  3. 检查日志：E:\Soul-Agent\SoulLogs\soul_*.json

Q：聊天记录不见了

检查会话目录：

%APPDATA%\Soul-Agent-Launcher\sessions\

如果文件存在，重启应用即可自动加载。如果文件被删除则无法恢复。

Q：如何手动添加模型？

将 GGUF 格式的模型文件放入以下目录即可：

%APPDATA%\Soul-Agent-Launcher\models\

放置后在「模型」页点击刷新即可看到。

Q：更新后配置会丢失吗？

不会。用户数据（配置、会话、模型文件）保存在 %APPDATA%\Soul-Agent-Launcher\，与程序安装目录分离，卸载/更新/重装均不会影响。

Q：日志在哪里？

E:\Soul-Agent\SoulLogs\soul_YYYY-MM-DD.json

每条日志包含时间戳、等级、分类和消息内容。