English · 简体中文 · 日本語

可选声音工具

制作基础有声书并不需要原生 Voice Tools。请先阅读第一本有声书和声音。当你需要原生 Preparer/Voice Lab 阶段，或 Pinokio 附带的本地 LLM 启动器时，再安装此附加组件。

返回首页 · 前置条件：安装 · 相关内容：LLM 设置

常规安装包含什么？

核心安装提供有声书应用、Qwen3-TTS、Designer、Dataset Builder，以及 Training 选项卡所需的应用依赖。出现这些选项卡，并不意味着所有高级原生工具或模型都已安装。

• **Designer（设计器）：**根据描述创建声音并保存参考音频。
• **Dataset（数据集）：**利用生成的样本构建数据集，支持预览和编辑。
• **Training（训练）：**使用应用的解释器，从准备好的数据集训练 LoRA。
• **Preparer（预处理器）：**将现有音频及可选的原文转换为数据集 ZIP；它需要单独准备的原生环境。
• **Voice Lab（声音实验室）：**使用已配置的解释器及所需的分析模型，运行从数据集到适配器的多阶段流程。

训练和本地声音设计仍然需要合适的硬件、磁盘空间、模型权重及兼容依赖。它们都是可选流程，并非使用 Custom 或 Clone 声音的前提。

在 Pinokio 中安装原生工具

1. 保存当前工作并停止应用。请先完成或取消正在运行的生成/训练任务。
2. 在 Pinokio 中选择 Install Voice Tools (Optional)（安装声音工具，可选）。
3. 等待所有原生编译和下载完成。如果某一步失败，请检查安装终端。
4. 重新启动应用，并配置计划使用的工具所需的路径。

安装程序会：

• 根据检测到的 CUDA、HIP、Metal 或 CPU 路径，在 app/env 中构建 llama-cpp-python[server]。
• 如果 preparer_env 不存在，则创建一个隔离的 CPython 3.10 环境，安装平台对应的 PyTorch，并限制后续依赖安装，使其与该软件栈保持一致。
• 安装 Preparer 的依赖及其单独的 llama-cpp-python 构建。
• 获取固定版本的 whisper.cpp 源码和固定版本的模型，检查资源，然后构建选定的后端。
• 仅在 Linux AMD 平台安装可选的 pyannote 说话人分离依赖，因为该平台当前固定的 PyTorch 版本符合 pyannote 4 的要求。

原生编译需要 CMake 和可用的 C/C++ 工具链；GPU 构建还需要匹配的 CUDA/ROCm SDK。这会增加下载量、编译时间和磁盘占用。基础 Docker 镜像不会运行此安装程序，也不包含准备好的 preparer_env；不要仅因为网页能加载，就认为高级原生阶段已经就绪。

检查环境

在检出的项目根目录中，使用可用的 Python 解释器运行：

python env_doctor.py
python env_doctor.py --voice-tools

第一条命令检查 app/env；第二条还会检查已配置的 Voice Lab 解释器和 Preparer 环境。添加 --json 可获得机器可读报告。依赖检查并不等于完整的音频生成、训练或 GPU 兼容性测试。

这三个环境各有用途：

环境	用途
app/env	Web 应用、常规本地 TTS/Training、附带的 llama_cpp.server 启动器
preparer_env	原生音频预处理；受支持时，说话人分离依赖应安装在这里
Voice Lab 的 ROCm Python	Voice Lab 各阶段；默认可使用应用解释器，也可配置一个单独准备好的解释器

ROCm Python 是当前界面中的标签；它表示解释器路径，并不证明已安装 ROCm，也不表示每一种阶段都需要 ROCm。请选择具备对应阶段依赖的解释器。不要将它指向空环境，也不要假定 preparer_env 包含完整的 TTS 训练软件栈。

准备音频数据集

请使用自己的录音，或已取得许可且许可范围涵盖预期处理方式和声音用途的音频。由他人声音制作的数据集，并不自动赋予你再次分发或用于冒充的权利。

1. 打开 Preparer（预处理器），选择一个 WAV/MP3 音频文件。
2. 打开 Advanced (source alignment & LLM enrichment)（高级：原文对齐与 LLM 信息补充）。在 **Primary GGUF Model (optional, default from Setup)（主要 GGUF 模型，可选，默认取自 Setup）**中提供实际的本地 GGUF 路径。
   • 尽管该字段当前的标签写着可选，常规预处理命令仍然要求主要模型路径。不要指望 API 模型名称或 Setup 中的 URL 能代替本地 GGUF。
   • **Fallback GGUF Model (optional)（备用 GGUF 模型，可选）**也应填写另一个本地文件路径。
3. 可附加匹配的 Source Text (EPUB/TXT, optional)（原文，EPUB/TXT，可选）。原文引导的对齐可以依据书籍纠正转录拼写。请确保文本与录音采用的版本一致。
4. 选择 Output Filename（输出文件名）、**Language（语言）**和质量阈值。进行原文对齐时，**Source Threshold（原文匹配阈值）**控制所需的匹配程度。提高置信度、信噪比或匹配阈值会拒绝更多素材；放宽阈值并不能修复质量问题。
5. 除非具备下文的额外前置条件，否则请保持 Speaker Diarization: Off（说话人分离：关闭）。在基础预处理成功之前，也请先关闭信息补充功能。
6. 点击 Start Preparation（开始预处理），并查看 Execution Logs（执行日志）。完成后，通过 **Completed Datasets（已完成的数据集）**下载生成的 ZIP。训练前请检查样本音频和转录文本。

**Batch Mode（批量模式）**接受多个音频文件，并分别生成数据集 ZIP。它与命令行中明确配对音频和原书的工作流程不同。

说话人分离与信息补充

说话人分离是在现有音频中区分不同说话人。它不同于核心“书籍转脚本”流程中的说话人标注。

• **Auto-detect multiple speakers（自动检测多位说话人）**和 **Always diarize（始终进行说话人分离）**要求运行 Preparer 的解释器安装 pyannote 依赖，并且能够访问 Community-1 模型。
• 请在 Hugging Face 上接受该模型的条款，并提供具有必要访问权限的令牌。Preparer 界面中的 Hugging Face Token仅用于本次运行，界面不会保存它。也支持启动环境中的 HF_TOKEN。
• 随附的可选安装程序仅在 Linux AMD 平台配置这些依赖。不要为了绕过缺失模块而把 pyannote 安装到 app/env：它要求的 PyTorch 版本可能与其他平台固定的版本冲突。
• **LLM enrichment（LLM 信息补充）**要求填写 Enrichment LLM Model Path（信息补充 LLM 模型路径），并至少选择一项任务，例如 Speaker attribution（说话人归属）、**Narration style（叙述风格）**或 Emotional tone（情绪语气）。此处需要单独的本地 GGUF 路径，而不是你的 OpenAI 兼容服务器地址。

高级安装中，可通过 ALEXANDRIA_PREPARER_PYTHON 选择 Preparer 解释器。ALEXANDRIA_WHISPER_CPP_BIN 和 ALEXANDRIA_WHISPER_CPP_MODEL 可覆盖 whisper.cpp 的可执行文件和模型路径。请只在准备并验证好这些文件后使用。

谨慎使用 Voice Lab

Voice Lab 可以运行 Quality → Dedup → Train → Evaluate → Profile → Name（质量检查 → 去重 → 训练 → 评估 → 分析描述 → 命名）。打开 Pipeline settings & environment（流水线设置与环境），设置实际路径，然后点击 Save settings（保存设置）：

• **ROCm Python：**具备所需阶段依赖的解释器
• **Profiler model (GGUF, optional)（分析模型，GGUF，可选）：**使用 **Profile（分析描述）**阶段时所需的本地分析模型；默认设置期望项目根目录中存在特定的 GGUF，并不会自动下载模型
• **Default input folder（默认输入文件夹）：**你的朗读者数据集文件夹
• **EPUB search folders (optional)（EPUB 搜索文件夹，可选）：**每行一个文件夹，用于为声音描述提供书籍上下文

然后选择 **Input folder (narrator subfolders)（输入文件夹，包含朗读者子文件夹）**并点击 Inspect（检查）。只选择你打算运行的 Stages to run（运行阶段），检查界面显示的预检查结果，再使用 Run Pipeline（运行流水线）。输入变化后需要重新预检查。

请仔细阅读各阶段的说明：

• **Quality（质量检查）**只进行健康状况/重复项审计并发出警告。
• **Dedup（去重）**可在处理流程中合并已确认的匹配项，并删除完全重复的片段。请备份原件。
• **Train（训练）**会消耗大量资源并创建适配器；通过预检查并不保证后续所有工作负载都能在现有资源内运行。
• **Evaluate（评估）**会报告基于探测的相似度、静音和削波证据。也请进行试听。
• **Profile（分析描述）**需要原生 LLM 依赖和模型。
• **Name stage: actually rename（命名阶段：实际重命名）**默认勾选。取消勾选可只预览命名，不实际修改。重命名会真正更改适配器文件。

需要支持时，可使用 **Copy diagnostics（复制诊断信息）**或 Download diagnostics（下载诊断信息）；即使输出已经脱敏，分享前也请检查。

数据集与训练基础

手动准备训练数据集时，请使用包含 WAV 片段和 metadata.jsonl 记录的 ZIP，每条记录包含 audio_filepath 和 text。文档指定的目标音频格式为 24 kHz 单声道。引用路径必须指向数据集内部文件，转录文本应准确匹配录音中的文字。如果希望在应用内创建样本，可使用 Build New Dataset（构建新数据集）。

在 **Training（训练）**中：

1. 上传 ZIP，或选择已有的 Dataset（数据集）。
2. 输入 Adapter Name（适配器名称）。
3. 检查 Epochs（训练轮数）、Learning Rate（学习率）、Batch Size（批大小）、LoRA Rank（LoRA 秩）、LoRA Alpha（LoRA 缩放参数）、**Grad Accum Steps（梯度累积步数）**和 Language（语言）。
4. 使用 Start Training（开始训练），并查看进度和日志。
5. 将结果适配器用于全书之前，先用未参与训练的台词测试，并与使用干净参考音频制作的 Clone voice 比较。

将当前界面默认值作为起点，不要把它们视为质量保证。更多片段、更高的秩、更多训练轮数，或更低的训练损失，都不能单独证明声音更好。录音一致性、转录准确度、语言、表现力和评估都很重要。在运行大型库任务前，先做规模小、便于检查的实验。

不要把 Voice Lab 资源预检查的最低门槛当成推荐系统配置。允许任务运行的检查，并不测量你的数据集在端到端流程中的内存占用或性能。

命令行入口

安装原生工具后，从检出的项目根目录运行以下命令。在 Windows 上，将 preparer_env/bin/python 替换为 preparer_env\Scripts\python.exe。

preparer_env/bin/python alexandria_batch_processor.py --help
preparer_env/bin/python alexandria_compare.py --help

批处理器支持有声书文件夹及对应的原文文件夹，并要求明确指定 GGUF 模型。比较工具支持将提取的数据集与其原文对照检查。正式运行前请阅读帮助，并备份原始音频和数据集。

download_model.py 下载的是独立的旧版 Whisper-base Transformers 包。它不会获取 GGUF LLM，也不能替代当前的 whisper.cpp 配置。同样，Linux 辅助脚本 start_llama_server.sh / ensure_llama_server.sh 要求已单独安装原生 llama-server，并明确配置模型路径；它们不会安装这两项中的任何一项。

若要使用适配器，请继续阅读声音；若要渲染，请参阅渲染与导出；若依赖或路径检查失败，请参阅故障排查。

来源

已对照发布的 main 提交 8c7a33cb310ab9264594a09ca27e48271585094f 核验：可选安装程序、高级功能界面、Preparer 路由、Preparer 命令行、Voice Lab 路由、Training 路由、环境诊断工具。