Installation zh CN - on22s/Side-Story GitHub Wiki

English · 简体中文 · 日本語

安装

常规桌面安装建议使用 Pinokio。基础安装包含有声书应用和本地 Qwen3-TTS 运行环境。无需原生 Voice Tools（声音工具）附加组件，也能完成 Setup（设置）→ Script（脚本）→ Voices（声音）→ Editor（编辑器）→ Result（结果） 的完整流程。

返回首页 · 下一步：LLM 设置和第一本有声书

安装前的准备

  • 为模型下载和工作文件预留空间。 不同 TTS 模型会在首次使用时下载。每种模型请预留数 GB 空间，此外还要考虑 Python/PyTorch 环境、单独的 LLM 权重、原始书籍、参考音频和渲染音频。大型项目占用的磁盘空间可能远超最终 MP3 文件的大小。
  • 选择标注的运行位置。 自动脚本标注需要一个能够访问的、兼容 OpenAI 的 LLM 服务器。它与 TTS 相互独立。你可以使用外部 LLM 服务器、托管 API，或手动复制粘贴；安装应用不会下载 LLM。
  • 先从一小段文字开始。 为了让音频生成更实用，建议使用本地 GPU 加速，但内存需求取决于模型、声音处理方式、批大小和其他工作负载。没有适用于所有情况的安全批大小，也没有可以保证的渲染速度。
  • 使用你有权处理的素材。 远程标注会将书籍文本和任务上下文发送给所选服务提供方。外部 TTS 可能会将声音参考音频及其转录文本发送到所选服务器。参阅LLM 设置和声音。

Pinokio：推荐方式

  1. 安装 Pinokio。
  2. 选择 Download（下载），粘贴 https://github.com/on22s/Side-Story。
  3. 打开下载的应用，点击 Install（安装）。等待安装程序完成；安装期间，不要对同一份检出的仓库再次运行另一个安装程序。
  4. 点击 Start（启动），然后在启动器显示 Open Web UI（打开网页界面） 时点击它。使用启动器提供的 URL；Pinokio 会选择一个可用端口。
  5. 配置 Setup（设置），点击 Save Configuration（保存配置），并按照第一本有声书完成一次简短测试。

全新安装会使用 CPython 3.10 创建 app/env。安装程序先安装适合当前平台的 PyTorch 组件，记录该组件组合的版本约束，然后安装应用依赖和 qwen-tts==0.1.1。如果环境已经存在，会保留它，而不会自动重建。

如果启动器一直显示 Starting（正在启动），请打开其终端，查看最先出现的错误。不要把 Reset（重置） 当作常规的安装修复手段：它会删除当前工作和配置。参阅故障排查和更新与备份。

硬件：安装路径并不等于兼容性保证

以下内容描述随项目提供的安装代码和设备选择代码。它不代表每一种 GPU、驱动、操作系统版本或模型使用路径都能完整运行。

平台 项目提供的安装路径 重要限制
Windows/Linux 上的 NVIDIA PyTorch 2.7.0，搭配 CUDA 12.8 软件包 需要兼容的 GPU 和驱动。可选的注意力机制 wheel 包也取决于具体的 Python 版本和平台组合。
Linux 上的 AMD PyTorch 2.10.0，搭配 ROCm 7.0；triton-rocm 3.6.0 安装程序注明已测试的目标是 RX 9070 XT / RDNA4。这不表示支持所有 AMD 显卡或 APU。请核实主机驱动/ROCm 与 GPU 的组合。
Windows 上的 AMD 安装程序包含 DirectML 软件包，但应用的设备解析逻辑使用 CUDA/ROCm、MPS 或 CPU 不要期待此安装路径能提供 AMD GPU 加速；请使用 CPU 或其他受支持的运行方案。
Apple Silicon macOS PyTorch 2.7.0；运行时在可用时选择 MPS PyTorch 报告 MPS 可用，并不保证所有操作都能运行或性能可以接受。请用一个短样本验证。
Intel macOS 固定使用较旧的 PyTorch 2.2.2；回退至 CPU 在开始整本书之前，先验证环境并测试一个短样本。
其他仅有 CPU 的系统 回退至 CPU 制作长篇书籍可能不切实际；先用一小段文字测量耗时。

先使用 Device: auto（设备：自动）。运行时依次优先选择 CUDA/ROCm、MPS、CPU。PyTorch 对 ROCm 也使用 cuda 设备命名空间，因此仅凭 CUDA 风格的设备名称，不能判断 AMD 机器使用了错误的后端。

为验证本 Wiki，并未实际运行应用、GPU 任务、模型下载或音频生成。上述硬件说明来自源代码，并单独保留了安装程序自身声明的测试范围。

Docker：随项目提供的 NVIDIA 配置

随项目提供的 Compose 文件面向 NVIDIA GPU。它需要 Docker 和 NVIDIA Container Toolkit。这不是 AMD 部署方案。

在终端中运行：

git clone https://github.com/on22s/Side-Story.git
cd Side-Story
docker compose up --build

在 Docker 主机上打开 http://localhost:4200。项目提供的镜像使用 PyTorch 2.8.0/CUDA 12.8 运行时基础镜像，与 Pinokio 固定使用的 PyTorch 版本不同。它会安装有声书核心运行环境；不会构建可选的原生 Voice Tools，也不会创建 preparer_env。

持久保存 Docker 数据

项目提供的挂载会保留：

  • data/runtime：当前状态、报告、导出文件和其他运行时产物
  • data/uploads、data/scripts、data/designed_voices、data/clone_voices、data/lora_models、data/lora_datasets 和 data/dataset_builder：各自对应的库和输入文件
  • data/output：生成的语音片段
  • data/config：应用配置
  • 名为 hf_cache 的 Docker 卷：下载的 Hugging Face 模型

自定义 Compose 时请保留这些挂载。如果使用 docker run，请自行持久保存 /alexandria/runtime 和 /alexandria/config。重建容器并不等于备份。升级前请参阅更新与备份。

在容器内部，localhost 指的是容器自身。如果 LLM 在主机或另一台机器上运行，请使用容器能够访问的地址；主机的回环 URL 不会自动通向该服务。

将网络访问限制在私有范围

默认 Compose 端口映射为 127.0.0.1:4200:4200。应用在容器内绑定 0.0.0.0，以便 Docker 转发流量，但发布到主机的端口仍仅能通过回环地址访问。

身份验证默认关闭。在将端口发布到其他网络接口、创建隧道或添加反向代理之前：

  1. 在应用/容器的环境中设置 ALEXANDRIA_AUTH_PASSWORD。Basic Auth（基本身份验证）的默认用户名是 alexandria；如有需要，可通过 ALEXANDRIA_AUTH_USERNAME 覆盖。
  2. 从受信任的本地网络之外访问时，使用 HTTPS。
  3. 使用域名时，将 ALEXANDRIA_ALLOWED_HOSTS 设置为预期的主机名。如果另一个浏览器来源需要访问 API，请通过 ALEXANDRIA_ALLOWED_ORIGINS 配置该准确来源；浏览器的 CORS 响应权限也可能需要设置 CORS_ORIGINS。
  4. 不要将密码放进镜像、仓库、共享的 Compose 文件或公开的诊断信息中。

主机/来源检查是有用的保护措施，但不能代替身份验证或传输加密。

其他开始方式

  • 仓库包含一个 Colab 笔记本。请遵循它自己的设置和持久保存步骤；GPU 可用性和会话限制取决于 Colab。
  • 对于已经安装好的本地环境，在 app/ 中运行 python app.py，默认使用端口 4200，除非设置了 ALEXANDRIA_PORT。请使用应用环境的解释器，而不是无关的系统 Python。
  • 仅在需要原生 Preparer（预处理器）/Voice Lab（声音实验室）处理阶段，或随项目提供的 Start LLM（启动 LLM） 启动器时，才安装可选声音工具。

参考来源

已对照项目主分支（main）提交 8c7a33cb310ab9264594a09ca27e48271585094f 核实：README、核心安装程序、PyTorch 安装程序、设备解析逻辑、Dockerfile、Compose、应用安全配置。