English · 简体中文 · 日本語

从第一个失败的步骤及其实际错误开始排查。更改依赖项或配置前，请先保存工作；重新运行整本书之前，先用一小段文本验证修复是否有效。Reset（重置）会删除当前项目数据和设置，不应作为常规修复步骤。

返回首页 · 相关页面：更新与备份

• 在 Pinokio 中打开 Terminal（终端）；启动尚未完成时，打开 Starting（正在启动）查看进程输出。
• 对于正在运行的任务，阅读其选项卡中的日志。Reports → Runs（报告 → 运行记录）记录了运行历史，Review Checkpoints（审校检查点）可帮助你找到保留的审校工作。
• 记录操作系统、GPU／驱动程序、安装方式、具体任务、模型，以及第一条完整的错误消息。报告问题时，也请提供检出目录的修订版本。
• 在检出目录的根目录运行 python env_doctor.py；检查高级原生工具环境时加上 --voice-tools，需要结构化输出时加上 --json。
• 对于 Voice Lab（声音实验室），使用 Copy diagnostics（复制诊断信息）或 Download diagnostics（下载诊断信息）。即使输出已脱敏，发布前也要检查。请移除凭据、私密书籍摘录、声音录音以及不必要的个人路径。

环境检查不会渲染音频，也不能证明 GPU 兼容性。本指南已对照代码和界面核查，但未进行应用／GPU 运行时测试。

脚本生成时模型的每一条回复都在 logs/llm_responses.log（审校为 logs/review_responses.log）。旁边的 *.requests.log 用 request= 编号记录了产生每条回复的完整请求，可以原样重放出错的回复。附到问题报告前，请检查其中是否含有不公开的书籍正文。

1. 在启动器终端中查找 ModuleNotFoundError、ImportError、“Address already in use”（地址已被占用），或第一段回溯信息。
2. 确认核心 Install（安装）已完成。应用需要使用它自己的 app/env，而不是 shell 的 PATH 中碰巧找到的某个 python。
3. 如果缺少依赖项，请停止应用，使用 Reinstall（重新安装），然后再次查看终端。不要随意安装新的 PyTorch 包来覆盖针对平台配置的依赖栈。
4. 如果已有环境使用了不同的 Python 版本，请注意：安装程序中的可选 attention wheel 包需要 CPython 3.10。全新安装会使用 3.10，但不会自动重建已有环境。重建任何环境前，请先备份数据。
5. 直接启动时若发生端口冲突，请停止冲突的服务，或使用一个空闲的 ALEXANDRIA_PORT。Pinokio 会选择端口；请使用它当前提供的 Open Web UI（打开 Web 界面）链接，不要使用旧书签。

Docker 用户还应检查容器启动输出、NVIDIA 运行时配置，以及随项目提供的回环地址端口映射。Compose 文件面向 NVIDIA 配置，不是通用的 AMD GPU 配置。请参阅安装。

Test Connection（测试连接）不会保存设置。请点击 Save Configuration（保存配置），并等待保存反馈；更改 LLM Location（LLM 位置）后也需要这样做。

如果 Setup（设置）显示加载警告，请使用 Retry loading configuration（重试加载配置），先解决该错误，再覆盖设置。如果使用了自定义环境变量，请检查实际的 ALEXANDRIA_CONFIG_PATH 和 ALEXANDRIA_DATA_DIR；实际设置文件可能不是默认的 app/config.json。

随项目提供的 Pinokio Start LLM（启动 LLM）启动器会编辑默认的 app/config.json。如果当前使用的配置位于其他位置，请手动检查 Setup（设置）。

请按顺序检查：

1. API 服务器是否正在运行？是否已加载预期模型？
2. Base URL（基础 URL）是否指向其 OpenAI 兼容 API（通常以 /v1 结尾）？Alexandria 所在的主机／容器能否访问它？
3. Model Name（模型名称）是否与服务提供的模型 ID 完全一致？可使用旁边的刷新图标查看模型列表。
4. API Key（API 密钥）对该服务器是否有效？如果使用 env:NAME，运行 Alexandria 的进程中是否存在该变量？
5. Test Connection（测试连接）报告的是哪一步的问题：URL 验证、模型列表，还是补全请求？模型列表探测失败，可以在处理书籍之前帮助识别错误的 API 路由或身份验证问题。
6. 探测成功后，保存配置，并尝试 Test this book with the LLM（用 LLM 测试本书），或进行一次短文本生成。

在 Docker 内部，localhost 指向容器本身。如果服务器运行在宿主机上，就需要使用容器能够访问的地址。经过端口转发的远程服务器可能看起来像本地服务；请根据实际执行计算的位置设置 Runs on this machine's GPU?（是否在本机 GPU 上运行？）。

处理流程要求特定的结构化回复，并会检查是否保留了源文本。即使服务器可访问，仍可能返回格式错误的 JSON、不完整的文本、推理过程而非答案，或不正确的标注。

• 使用能够遵循指令的模型，并使用该模型支持的推理／非思考控制选项。不要依赖禁用 <think> 来解决问题。
• 在排查服务提供商错误时，移除不受支持的自定义请求头／请求体参数。
• 检查上下文／输出限制，先使用更短的文本片段或较保守的生成设置。
• 检查错误和保留的检查点，不要直接删除。反复重试相同的无效输出，可能只会消耗时间或 API 额度，而无法修复根本原因。
• 如果希望自行提供每次回复，请使用手动传输模式，并且只粘贴最终答案。

有关源文忠实度、审校、快照和恢复控件，请参阅脚本与审校。连接、费用和隐私详情见 LLM 设置。

手动模式下，请跳过 Test Connection（测试连接）和 Test this book with the LLM（用 LLM 测试本书）。目前的探测不支持正常的手动回复流程；书籍预检可能一直等待回复，但常用面板并未显示相应的回复入口。请使用 Cancel book test（取消书籍测试），上传一小段摘录，然后使用常规的 Generate Annotated Script（生成标注脚本）。通过 Copy prompt（复制提示词）、Model reply（模型回复）和 Submit reply（提交回复），完成其中的 Your turn（轮到你了）提示。

增加重试次数之前，请先检查服务提供商的可用性和限制。Minimum interval (seconds)（最小间隔，秒）可用于拉开请求间隔；Request timeout (seconds)（请求超时，秒）可为运行缓慢但仍在工作的模型留出时间。这两项都无法解决错误的凭据或无效请求。

When retries run out（重试次数用尽时）控制分块是标记为失败，还是让本次运行等待你处理。恢复运行前，请先修复服务端点。自动故障切换可能会切换到远程／计费服务提供商，因此请检查两个配置档案及信息披露设置。

Windows 上无法使用进程级 Pause/Resume（暂停／继续）。对于脚本生成，先使用 Cancel（取消），再使用 Generate Annotated Script（生成标注脚本），可以从保留且兼容的检查点恢复。不要假定所有高级任务都支持这种方式，也不要假定更改输入／设置后仍会复用同一检查点。

首次使用时，可能需要下载 TTS 模型、加载权重或预热内核。在认定进程无响应之前，请先观察终端以及网络／磁盘活动。Compile Codec（编译编解码器）目前不起作用，因此不是首次运行缓慢的原因。

如果日志报告下载失败，请检查网络访问、可用磁盘空间和 Hugging Face 的可用性。模型权重与应用的 Git 检出目录相互独立。如果模型访问权限或速率限制要求令牌，请使用已获授权的 HF_TOKEN；不要将令牌发布到日志或 issue 中。

对于受限网络，请在启动前有意识地配置下载端点或镜像。第三方镜像会改变你对下载文件以及可能涉及的凭据所信任的对象；不要使用不明镜像，也不要将令牌复制到不可信的端点。除非已确认某个资源损坏，否则请保留现有缓存数据。

阅读启动警告，并确认已安装的 PyTorch 构建版本。Device: auto（设备：自动）依次尝试 CUDA／ROCm、MPS，最后是 CPU。系统中确实存在 GPU，但 PyTorch 无法使用它，可能意味着驱动程序、构建版本或环境不匹配。

• 在 AMD／Linux 上，请检查实际的 GPU／驱动程序／ROCm 组合。PyTorch 的 cuda 命名空间也用于 ROCm。
• 在 AMD／Windows 上，应用当前的设备解析逻辑不使用 DirectML 加速；安装了 DirectML 包，并不代表 TTS 已有可用的 GPU 执行路径。
• 在 Apple Silicon 上，PyTorch 必须报告 MPS 可用。仅安装软件包，并不能验证模型能正常运行。
• 如果后续安装的软件包替换了针对 GPU 的 PyTorch，请使用适当的项目安装程序并检查其输出，而不是盲目从通用软件包索引升级 torch。

请参阅安装中根据源码整理的硬件注意事项。不要假定别人的 GPU 性能测试结果也适用于你的系统。

1. 在 Setup（设置）中调低 Parallel Workers（并行工作进程数）和 Max Items/Batch（每批最大条目数）。
2. 关闭其他占用大量 GPU 资源的任务，并检查 LLM 是否与音频任务共用同一块显卡。
3. 准确设置 Runs on this machine's GPU?（是否在本机 GPU 上运行？），以便应用协调 LLM 和音频任务。错误地选择“No”（否）可能使争用资源的任务同时运行。
4. 保持 Compile Codec（编译编解码器）关闭；它目前对速度没有影响。运行 **Auto-configure（自动配置）**为显卡选择批大小。
5. 如果 **Review Script（审校脚本）**提示 GPU 显存已满并立即停止，请释放显存（例如卸载占用显存的模型）后重新开始审校。
6. 在处理整本书之前，先重试少量待处理分块。

在支持的情况下，Render Pending（渲染待处理项）会自动使用本地批处理。Voice Design（声音设计）和 Character Ensemble（角色组合）路径按顺序执行，因此增加工作进程数并不是通用的提速方法。CPU 可以作为回退方案，但可能不适合长时间任务。请参阅渲染与导出。

• 使用干净的参考录音，并提供与录音中所说内容完全一致的转写文本。
• 导入的参考文件必须满足应用的时长和音频质量检查；文档规定的时长范围是 3–30 秒。请阅读具体的验证结果。
• 确认文件仍然存在，且运行 Alexandria 的机器能够访问它。笔记本电脑上的路径不会自动在容器或服务器中可用。
• 确认你有权使用该录音和声音。
• 克隆生成不像 Custom（自定义）、LoRA 或 Voice Design（声音设计）那样使用逐行 instruct 指令。修改这些指令并不能修复质量欠佳的克隆参考录音。

渲染整本书之前，请先试听几句有代表性的台词。选择合适的声音类型，请参阅声音；定向重新生成，请参阅渲染与导出。

对于外部 TTS，请确认 TTS Mode: external（TTS 模式：外部）、Gradio 服务器 URL，以及服务是否正在运行。外部路径支持 Custom（自定义）和 Clone（克隆）声音；仅限本地的声音路径需要本地 TTS。如果外部调用较慢，请检查 External call timeout (s)（外部调用超时，秒）。

对于本地 TTS，请从第一条模型加载／渲染错误、内存使用情况，以及受影响说话人的配置开始排查。不要反复合并包含失败或缺失分块的书籍；请先解决就绪状态警告。

MP3 编码需要支持 MP3 的 FFmpeg 构建版本。在带有 POSIX shell 的系统上，可使用以下命令检查：

ffmpeg -encoders 2>/dev/null | grep mp3

在 Windows 上，运行 ffmpeg -encoders，并查找 MP3 编码器，例如 libmp3lame。请检查应用环境实际可用的 FFmpeg 可执行文件，尤其是在系统中存在多个安装版本时。

MP3 编码失败时，单个分块可能会回退为 WAV；但合并 MP3 仍然需要可正常工作的编码器。请修复实际使用的 FFmpeg 安装，不要删除有效的已生成音频。有关 M4B 和章节／Audacity 导出的要求，请参阅渲染与导出。

在应用停止运行时执行 Install Voice Tools (Optional)（安装声音工具，可选），然后通过 python env_doctor.py --voice-tools 检查。

• Preparer（数据准备工具）通常使用 preparer_env；单独配置的 Voice Lab 解释器并不自动成为完整的替代环境。
• 输入真实的本地 GGUF 文件路径。不要依赖 Preparer 中“optional, default from Setup”（可选，默认取自 Setup）的标签：正常的数据准备运行需要主模型文件。
• 说话人分离需要 Preparer 解释器中具备兼容的 pyannote 依赖项、令牌以及 Community-1 模型访问权限。随项目提供的可选安装程序仅在 Linux AMD 上配置该功能。
• Voice Lab 的 Profile（声音画像分析）需要 llama-cpp-python 和用于画像分析的 GGUF；Train（训练）需要所选解释器中的训练依赖项。
• 如果预检提示输入发生变化，请检查当前设置／数据集，并重新运行预检。不要绕过检查。
• 原生编译器／SDK 的构建错误，无法仅靠刷新网页解决。

有关设置与训练边界，请参阅可选声音工具。

确认源文本是有效的 UTF-8，且与预期版本一致。应用可以在内存中修复某些已知编码问题，但仍会报告无法解决的情况。请保留未经修改的源文件副本。

接受合并结果之前，请阅读文本完整性报告。字词被修改、文本片段缺失或说话人错误，都需要审校；API 调用成功并不意味着朗读忠于原文。请使用脚本与审校中针对性的检查和修复方法。

请提供足够的信息，以便复现一个小规模失败案例：修订版本、安装方式、操作系统／GPU、相关设置、具体操作、预期结果、实际结果，以及第一条错误。说明问题是否会在一个短样本中发生，还是只在较大任务中出现。只有实际运行过测试，才可以报告测试通过。

在检查文件内容并确认有权分享之前，不要附上完整配置、受版权保护／私密的书籍，或他人的声音录音。简短、已脱敏的日志通常是更好的起点。

依据已发布的 main 分支版本 8c7a33cb310ab9264594a09ca27e48271585094f 核对：README 故障排查、启动器启动流程、界面控件、设备解析、LLM 连接测试、手动请求与书籍预检、环境诊断。