选择启用 Windows ROCm¶

当您显式设置 OMNIVOICE_TORCH_VARIANT=rocm 时，VoiceStudio 可以安装 AMD 匹配的原生 Windows 技术栈。源码设置和 Electron 使用相同的已检入配方和安装程序。Windows 默认设置仍为 NVIDIA 上的 CUDA，否则为 CPU；因此在您在此处选择启用之前，Radeon（包括 RX 9070 / 9070 XT 和 RX 9060、gfx1201/gfx1200）会在 CPU 上运行 PyTorch 引擎；设置界面的 GPU 检查和设置 → 性能 → GPU 加速会指出这一点，并标明此选择启用选项。此选项不会启用 Ryzen AI NPU、安装显卡驱动程序或下载模型。

前提条件与确切范围¶

• Windows 11 x64 以及 AMD 的 7.2.1 Radeon 矩阵或 Ryzen 矩阵中列出的 GPU。仅凭匹配的 gfx 架构并不能确立对未列出产品的支持。
• 由您按照 AMD 安装指南自行安装 AMD 所需的 26.2.2 显卡驱动。
• Microsoft Visual C++ 2015–2022 x64 Redistributable。源码设置会在本地检查此先决条件，缺失时会停止运行并给出手动安装指引。源码用户和已安装 Electron 的用户必须在启动 ROCm 运行时设置之前，自行安装或核验官方 Microsoft x64 Redistributable。
• 为 SDK、Python 环境和临时包下载准备空间；可选的引擎环境和模型权重需要额外空间。

该配方选择 x64 Python 3.12、ROCm 7.2.1、Torch/audio 2.9.1+rocm7.2.1、vision 0.24.1+rocm7.2.1，以及精确的 HIP CTranslate2 4.8.2 归档/wheel/DLL 哈希值。Windows ARM64、Windows 10 以及未列出的 GPU（包括 RX 6700 XT）均不在该配方支持的范围内。请勿使用 Linux ROCm wheel 索引或 HSA_OVERRIDE_GFX_VERSION 重映射来声称支持那些系统。仅靠 PATH 上的独立 HIP SDK 是不够的。

设置程序下载什么，以及如何校验¶

设置程序仅从 AMD 的 repo.radeon.com（SDK 和 PyTorch wheel）以及 OpenNMT/CTranslate2 的 GitHub 发布页（HIP CTranslate2 归档）下载。每个文件在配方中都有 SHA-256 校验值，设置程序会拒绝任何字节不符的文件。其余所有包都保持您的环境已有的版本，因此该覆盖层绝不会悄悄升级依赖项。

在此版本之前，OMNIVOICE_TORCH_VARIANT=rocm 在 Windows 上会被忽略。现在它会选择此技术栈。如果一台机器上已设置该变量且拥有可用的 CUDA 或 CPU 运行时，应用会显示设置界面，而不会自行切换；在您于那里启动设置之前不会下载任何内容。

源码设置¶

在仓库根目录下，完成常规的 Windows 源码先决条件后：

$env:OMNIVOICE_TORCH_VARIANT = 'rocm'
bun run setup:api
bun run dev

设置命令会选择 cp312，在同步其他依赖项之前排除锁定的 Torch/CTranslate2/CUDA 包，然后安装并验证匹配的 Windows 覆盖层。直接运行 scripts/setup.py 在选择启用时也会调用该共享安装程序，但它必须已在 Windows x64 Python 3.12 下运行；请使用 bun run setup:api 自动选择解释器。

已安装的 Electron 应用¶

完全退出 VoiceStudio，包括其托盘进程。打开 PowerShell，设置该变量，然后启动已安装的可执行文件；请将示例路径替换为 VoiceStudio 快捷方式显示的可执行文件位置：

$env:OMNIVOICE_TORCH_VARIANT = 'rocm'
& 'C:\path\to\VoiceStudio.exe'

在应用中开始或继续运行时设置。只要您希望选择 ROCm，就请继续使用此启动方法：这些命令仅影响当前 shell 及其子进程。它们不会更改系统环境。现有的模型、语音和项目都会保留。更改配方或 Python ABI 会使运行时就绪标记失效，并需要验证/修复。

此功能必须存在于已安装的构建版本中；旧版本不会通过环境变量获得此功能。请参阅 Releases 页面了解可用的构建版本。

本地验证¶

在源码根目录下，或 Electron 设置日志中命名的托管运行时目录下，使用该环境的解释器运行以下命令：

& .\.venv\Scripts\python.exe -m backend.core.windows_rocm.install --verify-only
& .\.venv\Scripts\python.exe scripts\smoke_windows_rocm.py

不带语音输入的两个命令都会执行无模型检查：精确的 ABI 和包版本、原生音频/视觉导入、固定的 HIP CT2 DLL、受支持的 GPU 架构、带已校验结果的同步 Torch 算术，以及 CT2 GPU/float16 发现。超时、崩溃或 CPU 回退都会使就绪检查失败。这既不证明语音推理能力，也不证明 WhisperX/MIOpen 兼容性。

要进行单独的本地 CT2 语音检查，请提供一个已安装的本地 CT2 模型文件夹和一个现有的 PCM 语音 WAV：

& .\.venv\Scripts\python.exe scripts\smoke_windows_rocm.py --model 'C:\models\local-ct2' --wav 'C:\audio\speech.wav'

冒烟测试绝不会解析远程模型 ID 或下载资源。它会消耗 GPU/float16 推理资源，并要求语音片段非空且具有有限的时间戳；报告会省略转写文本和用户路径。无模型就绪检查和本地 CT2 推理会作为不同的范围分别报告。

引擎边界¶

IndexTTS 保持其 Python 3.10/3.11 要求；CosyVoice 保持 Torch 2.7；VoxCPM2 保持 Torch 2.11。cp312/Torch 2.9 方案不适用于这些环境。受管理的 Windows sidecar 保留其自身的 CPU 可用性和上游要求。已知的非 HIP IndexTTS 元数据在所有平台上保留 CPU 回退。只有显式的 Windows ROCm 选择加入才会保守地处理未知 sidecar 元数据；默认未知元数据行为在所有平台上保持不变。现有手动安装的 HIP sidecar 仍可检测到；单凭该检测并非推理认证。没有任何引擎仅因为主环境通过就被认证为 GPU 就绪。Native/Vulkan 引擎有其自己的安装和能力检查。

修复与回滚¶

对于源码安装，重复执行已选择加入的 bun run setup:api。对于 Electron，请完全退出并使用相同的选择加入重新启动，然后恢复/重试设置。严格验证可区分中断或不兼容的安装与可用的安装；修复不会将项目锁定的 CUDA 包覆盖到健康的 HIP 环境上。失败的安装仍可重试，并保留用户数据。

要返回受支持的 CPU 路径，请完全退出并显式选择 CPU：

$env:OMNIVOICE_TORCH_VARIANT = 'cpu'
# Source checkout:
bun run setup:api
# Or launch the installed Electron executable and resume runtime setup:
& 'C:\path\to\VoiceStudio.exe'

请根据你的安装类型使用对应命令，而不是同时使用两者。单独使用 OMNIVOICE_DEVICE=cpu 会在现有 HIP 环境中选择 CPU 执行；它不会替换包。在排查原本受支持的 GPU 问题时，请移除手动设置的 HSA 覆盖。不要通过删除语音、项目、模型缓存或可选引擎环境来修复主运行时。

只有显式启动的安装才会下载 AMD 包和固定的 OpenNMT/CTranslate2 GitHub 发布版本，并通过包索引进行正常的依赖解析。验证和本地冒烟测试均为离线进行。此安装工作整合了 #2600 和 #2607 中的定向贡献；它不会吸收其整个草案，也不会混入 #2908 中提出的单独方案。

全新受支持的 AMD 硬件上的推理、打包的 Windows 执行和上游 CI 仍然是各自独立的验证关口；通过模拟测试套件并不是那种证据。

设置修复只处理已确认缺失、不匹配或损坏的包，包括缺少或损坏 wheel 文件的原生音频、视觉和 CTranslate2 导入。仅凭导入异常可能表明缺少外部先决条件（例如 VC 运行时），并不能授权进行包修复。GPU 支持、驱动/内核故障、超时、崩溃和未分类故障会停止验证，而不会下载或重新安装覆盖层。CLI 诊断包含一个有界故障类别；请在重试之前修正所报告的主机问题。成功的包修复仍必须通过完整的无模型 GPU 验证。