环境配置
Tip
AI攥写，待完善
本页介绍 Windows x64 桌面端的运行环境：需要安装哪些组件、如何选择计算后端、怎样检查安装结果，以及失败时如何处理。安装包已经内置 Python 3.12 基础环境；普通使用者应通过软件管理推理组件，不需要先安装 Anaconda 或在系统 Python 中执行安装命令。
如果只修改代码，请改读开发环境配置。这里的“安装环境”面向软件使用者，与开发者创建 .venv 的流程不同。
一、先确定运行方案
1. 区分程序、组件与模型
首次启动时能看到界面，说明桌面程序已经运行，但不代表识别模型已准备好。一个本地识别或翻译任务通常还需要以下条件：
| 层次 | 作用 | 从哪里准备 |
|---|---|---|
| Python 基础环境 | 启动音频和推理引擎 | Windows 安装包内置 |
| PyTorch／llama.cpp | 提供对应模型的计算后端 | “设置 → 计算设备” |
| 模型权重 | 提供模型学习得到的参数 | “模型管理” |
| 计算设备与模型配置 | 指定如何运行、支持什么语言 | 设置及模型配置窗口 |
安装 PyTorch 不会自动下载识别模型；下载 GGUF 文件也不会自动提供 llama.cpp 程序。看到模型“已安装”后，仍需确认其配置和所选运行组件一致。
2. 根据本地任务安装组件
| 识别方式 | 翻译方式 | 一般需要的本地推理组件 |
|---|---|---|
| SenseVoiceSmall／Qwen3-ASR | 不翻译或远程翻译 | PyTorch |
| SenseVoiceSmall／Qwen3-ASR | Hy-MT2／Index-Translate GGUF | PyTorch 和 llama.cpp |
| SenseVoiceSmall／Qwen3-ASR | M2M100 等 PyTorch 翻译模型 | PyTorch |
| 阿里云／MiniMax | 本地 GGUF 翻译 | llama.cpp |
| 阿里云／MiniMax | 远程翻译 | 不需要为远程推理安装这两类组件 |
本表对应项目内置的常见模型。自定义模型需要按实际引擎和能力配置判断，不能只根据模型名称猜测后端。
全部使用远程服务时，可以直接配置云端模型，无需为消除未使用组件的“未安装”状态而下载大型环境。
二、检查硬件与磁盘
1. CPU 与 GPU
CPU 方案不要求独立显卡，适合先检查采集和配置是否完整。是否能跟上目标音频的处理速度，需要用实际模型和短会话验证；软件不为所有处理器提供统一的速度保证。
GPU 加速需要同时满足三个条件：系统可以识别硬件、所选组件包含兼容后端、模型可以在该设备运行。任务管理器里能看到显卡，只能证明第一个条件。
在 Windows 设备管理器或“任务管理器 → 性能”中确认显卡型号，再在软件的“检测到的系统显卡”“可用计算设备”中对照。笔记本可能同时有集成显卡和独立显卡，两项推理任务也可能选择不同设备，应分别检查。
2. 后端怎样选择
| 后端方向 | 选择依据 | 不能据此推出的结论 |
|---|---|---|
| CPU | 不使用 GPU，或先建立可运行基线 | 不保证大模型适合实时字幕 |
| CUDA | NVIDIA 硬件、驱动与组件所需版本兼容 | 不是版本号越大越适合所有显卡 |
| Vulkan | 所选 llama.cpp 包和显卡驱动提供支持 | 不代表 PyTorch 也使用同一后端 |
| OpenVINO／SYCL | 对应硬件及运行包支持 | 不代表任意 Intel 设备都经过验证 |
| ROCm | 清单内组件及目标硬件兼容 | 不代表所有 AMD 显卡都可运行 |
软件提供的组合以随发布附带的清单为准。PyTorch 组合与 llama.cpp 安装包分别选择，不应把一个后端选项理解为整个应用的统一 GPU 开关。
驱动来自显卡或设备厂商官方渠道。不要通过复制网络上的单个 DLL、修改系统目录或安装不明“运行库合集”来绕过组件检查。
3. 内存与显存
模型参数规模、权重格式、精度、量化、上下文、音频长度以及识别和翻译同时驻留都会影响占用。磁盘上的文件大小不是加载后显存占用，下载能完成也不等于模型能运行。
首次使用时先用较小的识别模型和翻译权重，确认能完成短会话，再尝试更大的配置。发生显存不足时，应先检查是否两项任务共用同一 GPU，以及是否有游戏、浏览器或其他模型占用资源。
4. 磁盘空间
除安装包和最终模型文件外，还需要为组件解压、依赖安装、未完成下载分块和录音预留空间。模型管理中的大小用于理解权重下载量，不能当作整个运行方案的总容量。
在“设置 → 存储”确认保存位置，避免把组件安装到即将断开的移动磁盘。需要迁移时使用软件入口，按提示重启后检查，不能在模型加载期间手动移动目录。
三、安装 PyTorch
1. 找到安装面板
结束同传、悬浮字幕和浏览器字幕会话。打开“设置 → 计算设备”，向下滚动到“运行组件”和“安装 PyTorch”。会话或组件任务占用资源时，部分安装按钮会禁用，应先结束占用，而不是重复点击。
本页截图来自真实 React 页面，硬件及安装状态为内存演示数据。
2. 选择组合并安装
- 展开“安装 PyTorch”，查看“当前安装”。尚未找到可用组件时，先不要更换模型文件。
- 在“选择版本”中选择适合 CPU 或目标显卡的组合。下拉框显示的是本次发布支持的组合，不是任意 pip 版本。
- 首次安装保持“强制重新安装”关闭，点击安装按钮。
- 等待下载、校验、解压、准备依赖和检查安装结果完成。准备依赖阶段可能没有连续的下载百分比，应结合阶段和已用时间判断。
- 完成后点击“重新检查”，确认组件状态可以使用，再回到上方选择“语音识别设备”。
“已安装”按钮不可点击通常表示当前选择与已有组件相同，不代表操作失败。强制重装只针对软件有安装记录、能够管理的组件，不用于覆盖任意外部 Python 环境。
3. 已有环境与修复
软件会检查可复用的本地组件。发现环境不等于该环境已通过 Python ABI、依赖导入和 DLL 检查，最终以组件检查结果为准。软件不会因为系统里存在 python.exe 就自动把它当作兼容引擎。
由软件管理的安装出现损坏时，页面可显示修复区域，按需勾选 PyTorch 后执行修复。没有相应管理记录的外部环境，不应通过本应用强制修复；应由其原安装方式处理，或安装一个独立的受管理组合。
四、安装 llama.cpp
llama.cpp 用于项目支持的 GGUF 推理。使用 Hy-MT2 或 Index-Translate GGUF 翻译时，需要与权重分别准备它。
- 在同一“计算设备”页展开“安装 llama.cpp”。
- 根据 CPU、CUDA、Vulkan 等实际兼容条件选择安装包，不直接沿用 PyTorch 的版本名称。
- 点击安装，等待包与配套依赖下载、校验及检查完成。
- 重新检查后，确认“llama.cpp”行显示可用组件。
- 在上方“本地翻译设备”中选择设备，或保留“由引擎决定”。
截图中的具体版本只是示例状态。不要将其当作每台电脑都应照选的版本；可选项与实际兼容性应由当前发布和设备检查确定。
五、配置计算设备与性能
1. 自动分配和指定设备
“由引擎决定”让引擎按模型、后端和资源选择设备。需要固定设备时，分别设置“语音识别设备”和“本地翻译设备”。同一显卡承担两项任务时，预算应按总占用考虑。
“GPU 失败时回退 CPU”用于设备失效或显存不足等允许回退的情形，不会让模型获得原本没有的语言能力，也不能修复无效的云端密钥。启动后在“当前运行分配”查看实际设备，不要只看之前保存的选择。
2. 精度、量化和显存
“性能与显存”中的 PyTorch 精度和运行时量化只对支持它们的模型有效。GGUF 的量化等级由下载的文件决定，不能通过将运行时量化下拉框改成 NF4 来修改 GGUF。
增加本地翻译上下文会增加缓存占用；提高 GPU 卸载层数也可能增加显存使用。首次配置建议保留默认值，建立可运行结果后一次调整一项。详细字段说明见系统设定。
六、下载慢或无法连接
先确认失败资源属于哪一类，再调整“设置 → 常规 → 网络设置”。三类下载并不共用一个镜像开关。
| 失败资源 | 优先检查的设置 | 说明 |
|---|---|---|
| Python 依赖包 | PyPI 镜像节点、Pip 代理 | 镜像主要改变依赖获取来源 |
| Hugging Face 权重 | 模型下载源、Hugging Face 镜像、模型下载代理 | 每个模型支持的来源可能不同 |
| GitHub 分发的运行包 | GitHub 加速、组件下载代理 | 只覆盖相关分发请求 |
代理地址必须指向已经存在的服务。http://127.0.0.1:7890 只是格式示例，端口不存在时照填会使请求失败。填入地址后还要检查相应应用开关；留空时表示不使用该代理。
阿里云 PyPI 节点可对清单中的 PyTorch wheel 尝试相应镜像，缺失资源才回到固定官方地址；依赖包缺少分发时也有对应回退。不要为了加速而手工删掉哈希校验或随意混用不同索引。
七、验证环境是否可用
环境验证分三步完成：
- 组件检查：运行组件状态通过，设备检测完成。它说明基础加载条件满足。
- 音频测试：在“音频与识别”听到正确的两秒回放。它说明输入链路可用，不加载模型。
- 短会话：选择已安装模型开始同传，检查原文和译文，并在当前运行分配中确认设备。它才验证本次具体推理组合。
三步结果不能互相代替。测试音频成功而模型加载失败时，继续排查组件、权重或资源，不要先反复改音源。
八、常见故障
组件一直显示不可用
记录选中的组合、失败阶段和错误原因。先重新检查，再核对驱动、后端和 Python 兼容性。软件拥有安装记录时可使用修复；外部环境不要直接覆盖。
GPU 没有出现在可选设备中
对照“检测到的系统显卡”和“可用计算设备”。前者存在、后者没有时，重点检查运行组件支持。可以先使用 CPU 完成小模型测试，确认是否仅 GPU 路径异常。
安装被取消或下载中断
等待取消操作完成，再重试。模型下载的已完成分块可以保留，但运行组件安装暂存与模型断点缓存不是同一机制。不要承诺所有组件安装都能按原进度续传。
检查通过，但一启动就显存不足
结束会话后缩小模型、减少上下文或调整分配，再重新启动。结束会话后模型可能为下次使用保留在内存中；需要释放或切换时按软件流程操作，不要手动删除被占用的文件。
无法定位时，按如何反馈提供本次启动日志和支持码。环境说明的组织参考 SD Note 起步配置及环境维护，具体操作与边界按本项目实现编写。
九、离线准备与安装
在联网电脑准备
两台电脑安装相同版本的 Nola Translator。在联网的 Windows x64 电脑打开运行组件设置，选择“准备离线包”。
- 选择识别、翻译模型，保留“包含所需运行组件及全部依赖”。也可以不选模型，只准备运行组件。
- 选择目标电脑。给另一台电脑准备时，按目标电脑的设备选择后端；不清楚设备情况时可先选择 CPU。
- 核对模型和组件清单，选择保存文件夹并开始准备。
准备过程下载完整依赖，并将只有源码分发的依赖构建为 wheel，不会将该环境安装到联网电脑。若某项依赖构建失败，应检查启动日志中的具体原因；离线安装端不会临时补下载或编译。
成功后打开输出文件夹，将整个 Nola-offline-… 文件夹复制到移动硬盘。不要只复制 manifest.json：模型和组件目录同样必需。名称以 .partial 结尾的文件夹是尚未完成的准备任务，不能作为离线包导入。大文件需要目标存储设备支持相应单文件大小，当前格式不提供分卷。
在离线电脑安装
打开运行组件设置，选择“导入离线包”，在复制来的文件夹中选择 manifest.json。软件检查应用版本、文件完整性、依赖和可用空间；核对清单后开始安装。来源文件夹保持不变，安装完成后可移除移动硬盘。
离线包中的摘要用于检查文件完整性，不证明包的发布者身份。使用自己准备或来源可信的包。包不包含账号密钥、同传记录或显卡驱动；GPU 运行还取决于目标电脑的驱动与硬件。
安装完成后选择相应的本地模型、关闭不需要的云端或备用翻译，再完成一次音频测试和短会话。组件安装通过只说明组件可加载，不能代替实际模型、语言与设备组合的验证。