快速开始

1. 安装依赖

powershell

npm install

VILab 现在已经支持同一仓库下的 Windows 和 Apple Silicon macOS 桌面开发。

2. 启动桌面 App

powershell

npm run dev

在 Apple Silicon macOS 上，也可以直接使用辅助脚本：

bash

bash scripts/dev-mac.sh

如果你在 Windows 上编译本地 Whisper 运行时，可能还需要一个可用的 64-bit libclang.dll。仓库里的 npm run dev、npm run build、npm run cargo:check 会优先自动探测常见安装路径。如果 cargo 仍然在 whisper-rs-sys 阶段失败，再把 LIBCLANG_PATH 指向包含该 DLL 的目录，然后重新执行命令。

同一条启动链路现在也会自动为内置 SenseVoice 准备 ONNX Runtime。通常不需要再手动安装 onnxruntime.dll。

在 macOS 上，第一次完整使用听写流程时，还需要给系统授权：

麦克风权限，用于录音
辅助功能权限，用于全局快捷键和把结果写回当前前台应用

当前 macOS 默认听写快捷键是 Cmd+Shift+Option+D。

这个命令会启动：

Vite 前端
Tauri 桌面壳
由 App 管理的 VILab 内嵌 HTTP 服务

3. 确认服务地址

打开桌面 App 的设置，检查 Server URL。

当前默认值是：

text

http://127.0.0.1:8765

4. 检查健康状态

powershell

curl http://127.0.0.1:8765/health

预期返回：

json

{
  "serviceId": "uuid",
  "version": "0.1.7",
  "publicModel": "vilab-local-stt"
}

publicModel 表示当前对外暴露的 STT 模型别名。它既可能对应当前激活的本地模型，也可能对应当前路由到的云端 STT 别名。

5. 先选择 STT 模式

打开设置，在 Routing and models -> STT mode 中选择：

Local：桌面录音和 /v1/audio/transcriptions 都走当前激活的本地语音运行时
Cloud：桌面录音和 /v1/audio/transcriptions 都走当前选择的云端 Provider 和云端 STT 模型

首页快速开始区域现在会直接显示当前 STT 来源和模型名，例如：

本地路 Whisper Small
本地路 SenseVoice
云端路 whisper-large-v3-turbo

设置现在会在每次调整后自动保存。切换 STT 模式、听写优先级、Provider 或本地模型后，不需要再额外点击保存按钮。

6. 如果使用本地 STT，再安装并激活本地语音模型

在桌面录音或局域网客户端调用 /v1/audio/transcriptions 之前，先在设置的 Local speech models 区域完成以下任一方式：

下载内置模型，例如 Whisper Base、Whisper Small 或 SenseVoice
或者把兼容的 Whisper.cpp .bin 模型放进 models 目录后点击刷新
激活你要给当前宿主使用的模型

桌面 App 和内嵌 HTTP 服务现在共用同一套本地语音转录运行时。

内置 SenseVoice 会以受管目录模型的形式安装。当前阶段，手动放入的自定义本地模型仍然只支持 Whisper.cpp .bin 文件。

本次版本里的内置 SenseVoice 同时支持 Windows 和 Apple Silicon macOS。

如果你切到 Cloud 模式，则在同一个 routing 区域里配置云端 STT provider 和云端 STT model。

7. 选择转录输出模式

打开设置，配置 Transcript mode 和 Scene mode：

Verbatim：尽量保持和原始转录接近
Smart Clean：只用本地规则清理口头语、重复词和明显改口
Polished：在 smart clean 之后调用云端文本变换，并可按 chat、email、notes 场景整理

历史记录现在会为每条 session 保留多个输出变体，因此你可以在 raw、smart clean、polished 之间切换，而不会丢失原始转录。

8. 配置文本变换 Provider

云端 Provider 现在主要负责 polished 听写、清理、改写、翻译等文本后处理能力。

在设置中配置：

Transform provider
API key
API base URL
Rewrite model

9. 打开测试平台

在侧边栏底部文档入口下面点击 测试平台，会在浏览器中打开 Prompt Lab。

测试平台用于内部 prompt / model 对比：

Smart Clean 只跑本地规则，通常会非常快
Polished 才会真正调用所选 Provider、模型、Preset 和可选 Prompt Override
所有实验结果都不会写入正式历史记录

10. 创建 external API key

在 设置 -> External API keys 中：

按项目、脚本、设备或集成分别创建 key
不要把 adminKey 发给普通调用方
新 key 生成后立刻复制，完整值只会显示一次

11. 打包 macOS App

在 Apple Silicon macOS 上：

bash

npm run build:mac
bash scripts/run-mac-app.sh

npm run build:mac 会生成 .app 和 .dmg，run-mac-app.sh 会直接打开最新打好的本地安装包，方便做快速冒烟验证。

快速开始 ​

1. 安装依赖 ​

2. 启动桌面 App ​

3. 确认服务地址 ​

4. 检查健康状态 ​

5. 先选择 STT 模式 ​

6. 如果使用本地 STT，再安装并激活本地语音模型 ​

7. 选择转录输出模式 ​

8. 配置文本变换 Provider ​

9. 打开测试平台 ​

10. 创建 external API key ​

11. 打包 macOS App ​

下一步 ​

快速开始

1. 安装依赖

2. 启动桌面 App

3. 确认服务地址

4. 检查健康状态

5. 先选择 STT 模式

6. 如果使用本地 STT，再安装并激活本地语音模型

7. 选择转录输出模式

8. 配置文本变换 Provider

9. 打开测试平台

10. 创建 external API key

11. 打包 macOS App

下一步