Whisper 模型 Windows 部署：使用 WiX 构建安装包

设计决策：将模型文件作为可选组件，允许用户选择安装不同大小的模型（tiny/base/medium/large），减少初始安装体积。

2.2 组件定义与功能集划分

合理的组件划分是安装包设计的核心。以下是针对 Whisper 的推荐配置：

核心组件（Core）：

• Whisper.dll 及其依赖 DLL
• 必要的计算着色器文件
• 运行时环境检测脚本

可选组件（Examples）：

• WhisperDesktop.exe 图形界面
• 命令行工具集
• 示例音频文件

在 WiX 中定义功能集：

<!-- Features/Core.wxs -->
<Feature Title="Whisper Core" Level="1" Absent="disallow">
    <ComponentGroupRef />
    <ComponentGroupRef />
    <ComponentRef />
</Feature>
<Feature Title="Example Applications" Level="100">
    <ComponentGroupRef />
    <ComponentRef />
</Feature>

2.3 安装流程设计与用户体验优化

设计符合直觉的安装流程，包含以下关键步骤：欢迎界面 → 许可协议 → 功能选择 → 安装位置 → 模型选择 → 安装进度 → 完成界面。

特别为 Whisper 添加两个自定义对话框：

• 模型选择对话框：允许用户选择要安装的模型类型
• 安装选项对话框：配置是否添加环境变量、创建桌面快捷方式

三、实施验证：WiX 安装包制作与测试全流程

3.1 开发环境准备与 WiX 工具链安装

准备工作环境需要三个步骤：

准备：确保系统满足以下要求

• Windows 10/11 64 位系统
• .NET Framework 4.8 或更高版本
• 管理员权限

执行：安装 WiX Toolset

# 使用 Chocolatey 安装 WiX（推荐）
choco install wixtoolset -y

# 验证安装
wix --version

验证：检查 WiX 工具是否正确安装

# 查看已安装的 WiX 工具
Get-Command candle, light, heat

注意事项：WiX 4.x 与 3.x 语法有较大差异，本文使用 WiX 4.x 版本，请确保安装正确的版本。

3.2 核心配置文件编写指南

创建 Product.wxs，这是安装包的核心配置文件：

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
    <Product Name="Whisper Speech Recognition" Version="1.0.0" Manufacturer="Whisper Project" UpgradeCode="YOUR-UNIQUE-GUID-HERE">
        <Package InstallerVersion="500" Compressed="yes" InstallScope="perMachine" Platform="x64" />
        <!-- 引入功能集 -->
        <FeatureRef />
        <FeatureRef />
        <!-- 安装界面 -->
        <UI>
            <UIRef />
            <DialogRef />
        </UI>
        <!-- 升级策略 -->
        <MajorUpgrade DowngradeErrorMessage="较新版本的 [ProductName] 已安装。" />
        <!-- 系统要求 -->
        <Condition Message="需要 Windows 10 或更高版本。">
            VersionNT >= 1000000
        </Condition>
    </Product>
</Wix>

创建二进制文件组件定义（Components/Binaries.wxs）：

<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
    <Fragment>
        <ComponentGroup Directory="INSTALLFOLDER">
            <!-- 核心 DLL -->
            <Component Guid="*">
                <File Source="$(var.SourceDir)\Whisper.dll" KeyPath="yes" />
            </Component>
            <!-- .NET 包装器 -->
            <Component Guid="*">
                <File Source="$(var.SourceDir)\WhisperNet.dll" KeyPath="yes" />
            </Component>
            <!-- 桌面应用程序 -->
            <Component Guid="*">
                <File Source="$(var.SourceDir)\WhisperDesktop.exe" KeyPath="yes" />
                <Shortcut Directory="DesktopFolder" Name="Whisper Desktop" Target="[INSTALLFOLDER]WhisperDesktop.exe" />
            </Component>
        </ComponentGroup>
    </Fragment>
</Wix>

3.3 构建脚本与自动化测试

创建 build.cmd 脚本自动化构建过程：

@echo off
setlocal
:: 配置路径
set WIX_PROJECT_DIR=%~dp0
set SOURCE_DIR=..\Whisper
set OUTPUT_DIR=%WIX_PROJECT_DIR%\bin\Release
:: 创建输出目录
mkdir %OUTPUT_DIR% 2>nul
:: 使用 WiX 构建安装包
wix build %WIX_PROJECT_DIR%\src\Product.wxs ^
 -dSourceDir=%SOURCE_DIR% ^
 -out %OUTPUT_DIR%\WhisperSetup.msi
echo 安装包已生成：%OUTPUT_DIR%\WhisperSetup.msi
endlocal

测试矩阵：为确保安装包质量，建议进行以下测试：

四、扩展优化：高级功能与部署流程改进

4.1 模型文件动态下载功能实现

对于大型模型文件（通常 1GB 以上），建议在安装时动态下载而不是包含在 MSI 中：

// 自定义 WiX 动作：模型下载器
[CustomAction]
public static async Task<ActionResult> DownloadModelAsync(Session session)
{
    var modelType = session["MODEL_TYPE"];
    var installDir = session["INSTALLFOLDER"];
    var modelUrls = new Dictionary<string, string>
    {
        {"tiny", "https://example.com/models/ggml-tiny.bin"},
        {"base", "https://example.com/models/ggml-base.bin"},
        {"medium", "https://example.com/models/ggml-medium.bin"}
    };
    try
    {
        using (var client = new HttpClient())
        {
            var modelPath = Path.Combine(installDir, "models", modelUrls[modelType].Split('/').Last());
            session.Log($"开始下载模型：{modelUrls[modelType]}");
            using (var stream = await client.GetStreamAsync(modelUrls[modelType]))
            using (var fileStream = File.Create(modelPath))
            {
                await stream.CopyToAsync(fileStream);
            }
            session.Log($"模型下载完成：{modelPath}");
        }
        return ActionResult.Success;
    }
    catch (Exception ex)
    {
        session.Log($"模型下载失败：{ex.Message}");
        return ActionResult.Failure;
    }
}

在 WiX 中注册自定义动作：

<Binary SourceFile="$(var.CustomActionsDir)\Whisper.Installer.Actions.dll" />
<CustomAction BinaryKey="CustomActions" Method="DownloadModelAsync" Execute="deferred" Return="check" />
<InstallExecuteSequence>
    <Custom Action="DownloadModel" After="InstallFiles">INSTALL_MODEL=1</Custom>
</InstallExecuteSequence>

4.2 多语言支持与本地化配置

为安装包添加多语言支持，特别是中文界面：

1. 准备本地化资源：创建 zh-CN.wxl 文件

<?xml version="1.0" encoding="utf-8"?>
<WixLocalization Culture="zh-CN" xmlns="http://wixtoolset.org/schemas/v4/wxl">
    <String>Whisper 语音识别</String>
    <String>核心组件</String>
    <String>示例应用程序</String>
    <String>选择安装位置</String>
    <!-- 其他本地化字符串 -->
</WixLocalization>

2. 在构建命令中指定语言：

wix build Product.wxs -loc zh-CN.wxl -out WhisperSetup_zh-CN.msi

3. 检测系统语言并自动选择界面语言：

<Property Value="1033" /> <!-- 默认英语 -->
<SetProperty Value="2052" After="CostInitialize">LanguageID = 2052</SetProperty>

4.3 CI/CD 集成与自动化部署

将安装包构建集成到 GitHub Actions 工作流：

name: 构建 Whisper 安装包
on:
  push:
    branches: [ main ]
    tags: [ 'v*' ]
  pull_request:
    branches: [ main ]
jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
        with:
          repository: https://gitcode.com/gh_mirrors/wh/Whisper
      - name: 安装 WiX Toolset
        uses: wixtoolset/setup-wix@v1
        with:
          wix-version: 4.0.1
      - name: 构建 Whisper 项目
        run: |
          nuget restore WhisperCpp.sln
          msbuild WhisperCpp.sln /p:Configuration=Release /p:Platform=x64
      - name: 构建安装包
        run: |
          cd Installer
          build.cmd
      - name: 上传安装包
        uses: actions/upload-artifact@v3
        with:
          name: whisper-setup
          path: Installer/bin/Release/WhisperSetup.msi

五、替代工具对比与资源附录

5.1 安装包制作工具对比

除了 WiX，还有其他工具可用于制作 Windows 安装包：

5.2 故障排查决策树

遇到安装问题时，可按以下流程排查：

1. 安装程序无法启动
   • → 检查 Windows 版本是否符合要求
   • → 检查是否有足够的磁盘空间
   • → 尝试以管理员身份运行
2. 安装过程中报错
   • → 查看%TEMP%目录下的安装日志
   • → 检查是否有其他版本 Whisper 正在运行
   • → 验证安装包文件完整性
3. 安装完成后应用无法启动
   • → 检查事件查看器中的应用程序错误
   • → 使用 Dependency Walker 检查缺失 DLL
   • → 尝试重新注册 VC 运行时：vc_redist.x64.exe /repair

5.3 实用资源与参考资料

• WiX 官方文档：详细的 WiX 语法和最佳实践指南
• Windows Installer 开发指南：深入理解 MSI 安装包结构
• Whisper 安装包示例项目：包含本文所有示例代码和配置文件
• WiX 社区论坛：解决特定问题的最佳资源

通过本文介绍的方法，你已经掌握了使用 WiX Toolset 为 Whisper 构建专业安装包的全过程。从问题诊断到方案设计，再到实施验证和扩展优化，这套方法论不仅适用于 Whisper，也可应用于其他 Windows 应用程序的部署需求。随着项目的发展，你还可以进一步探索数字签名、模块化安装和硬件加速检测等高级特性，为用户提供更加完善的部署体验。