15 KiB
故障排除
当 Speakr 出现问题时，本指南可帮助您快速识别和解决常见问题。大多数问题归为以下几类 — 安装问题、转录失败、性能问题或特定功能异常。同时请参阅 常见问题 了解常见疑问。了解从哪里着手以及需要检查什么可以节省大量排错时间。
安装与设置问题
容器无法启动
当 Docker 容器拒绝启动或立即退出时，问题通常出在配置上。首先检查您的 环境配置文件 — API 密钥中的任何拼写错误或不匹配的引号都可能导致启动失败。查看 安装指南 了解正确的设置方式。运行 docker-compose logs app 查看实际的错误信息。常见原因包括端口冲突（其他服务占用了 8899 端口）、缺少卷挂载或数据目录文件权限不正确。
如果遇到数据库连接错误，请确保数据库文件具有正确的权限。容器以特定用户身份运行，需要对数据目录具有读写权限。在 Linux 系统上，您可能需要使用 chown -R 1000:1000 ./uploads ./instance 调整文件所有者。
无法访问 Web 界面
当 Speakr 成功启动但您无法访问 Web 界面时，通常是网络配置问题。首先使用 docker ps 验证容器是否实际在运行。检查端口 8899 是否正确映射 — docker-compose 文件的 ports 部分应显示 "8899:8899"。
防火墙规则经常阻止访问，尤其是在云服务器上。确保防火墙、安全组（AWS）或网络策略中已开放 8899 端口。如果从其他机器访问，请注意 localhost 无效 — 需要使用服务器的实际 IP 地址或主机名。
管理员登录失败
如果无法使用 管理员凭据 登录，首先验证您使用的是环境配置文件中完全相同的用户名和密码。有关用户管理问题，请参阅 管理员指南。这些值区分大小写，必须完全匹配。检查 Docker 日志中的管理员用户创建消息 — 首次启动时应看到 "Admin user created successfully"。
有时如果密码不符合要求，管理员用户创建会静默失败。确保管理员密码至少为 8 个字符。如果管理员用户未创建，您可能需要删除数据库文件并重启容器以重新触发初始化。
转录问题
转录从未开始
当录音一直处于 "pending" 状态时，后台处理器可能已停止。检查日志中是否有关于 转录服务 的错误消息。在 向量存储 管理面板中监控处理状态。API 密钥问题是最常见的原因 — 验证您的 OpenAI 或 OpenRouter API 密钥是否有效且具有可用额度。
网络连接问题也可能阻止转录。容器需要能够访问外部 API 端点。如果您在公司代理后面，需要在 Docker 环境中配置代理设置。
转录立即失败
快速失败通常表明 API 身份验证问题。仔细检查环境配置文件中的 API 密钥。请注意 OpenAI 和 OpenRouter 使用不同的密钥格式。OpenAI 密钥以 "sk-" 开头，而 OpenRouter 密钥格式不同。确保您为已配置的服务使用了正确的密钥。
API 速率限制或额度不足也会导致立即失败。登录您的 API 提供商仪表板检查使用情况和限制。某些 API 计划的速率限制较为严格，Speakr 处理大文件时可能超出限制。
ASR 端点返回 405 或 404 错误
如果使用 Whisper ASR webservice 时遇到 "405 Method Not Allowed" 或 "404 Not Found" 错误，请检查您的 ASR_BASE_URL 配置。URL 不应包含尾部注释或描述 — 删除环境配置文件中 # 符号之后的任何内容。对于 Whisper ASR webservice，仅使用基础 URL，如 http://whisper-asr:9000，不要在末尾添加 /asr。
使用 Docker Compose 时，始终使用容器名称而非 IP 地址进行服务通信。不要使用 http://192.168.1.132:9000，而应使用 http://whisper-asr-webservice:9000，其中 whisper-asr-webservice 是您的容器名称。
转录质量不佳
转录准确率高度依赖于音频质量。背景噪音、多个重叠说话人或麦克风摆放位置不当都会降低结果质量。AI 模型在清晰的单人音频或分离良好的多人音频上效果最佳。
语言不匹配也会导致结果不佳。如果您在设置中指定了特定的转录语言，但上传了不同语言的音频，准确率会受到影响。请设置正确的语言或留空以启用自动检测。
对于多人录音，使用 带说话人分离功能的 ASR 端点 可显著提高可用性。了解如何在转录后 识别说话人，即使原始转录准确率相似。
中文转录问题
对于 中文语言转录，模型选择至关重要。有关更多详细信息，请参阅 关于语言支持的常见问题。
重要提示：Distil 模型（如 distil-large-v3）不支持正确的中文转录。即使您将语言设置为 "zh"，这些模型也可能将中文音频识别为英文并产生错误输出。对于中文内容，请始终使用完整版的 large-v3 模型或类似的非蒸馏模型。如果您的中文音频被转录为英文，或输出为拼音而非中文字符，请从 distil 模型切换到 large-v3。
摘要语言与偏好不匹配
如果点击 "Reprocess Summary" 后 摘要 回退到英文，尽管已设置了 语言偏好，这可能是模型限制。配置 自定义提示词 以强制执行语言要求。某些模型（如 Qwen3-30B）不一定能正确遵循语言指令。尝试使用能更好地遵循语言指令的不同模型，或确保您的自定义提示词明确指定了输出语言。
性能问题
转录处理缓慢
大音频文件自然需要更长时间处理，但过度延迟表明存在问题。检查您的 服务器资源 并查看 系统统计信息 获取性能指标 — Speakr 需要足够的 CPU 和 RAM，尤其是在同时处理多个录音时。docker stats 命令可显示当前资源使用情况。
网络速度影响转录时间，因为音频必须上传到 API 服务。慢速互联网连接会造成瓶颈，尤其是对于大文件。如果您经常处理长录音，请考虑分块设置。
转录模型的选择影响速度。Whisper Large 更准确但比 Whisper Base 慢。如果速度比完美准确率更重要，请考虑通过 API 设置使用较小的模型。
超过 25MB 的文件在 OpenAI 上失败
OpenAI 的 Whisper API 有 25MB 文件大小限制。对于更大的文件，请在环境配置中启用 分块。了解 分块策略：
ENABLE_CHUNKING=true
CHUNK_LIMIT=20MB # or use duration: CHUNK_LIMIT=1400s
CHUNK_OVERLAP_SECONDS=3
您可以按文件大小（MB）或时长（秒）指定分块限制。对于有特定时长限制的模型（如 Azure 的 1500 秒上限），请使用基于时长的分块。系统会自动拆分录音并重新组装转录。
长录音 ASR 超时
长录音（超过 30 分钟）在 ASR 处理期间可能超时。在管理设置 > 系统设置 > "ASR Timeout Seconds" 中增加超时时间。对于 2 小时的录音，请至少设置为 7200 秒（2 小时）。非常长的录音（如 3 小时以上）可能需要更长的超时时间，具体取决于您用于转录的 GPU（如果是本地转录）。
Web 界面响应迟缓
浏览器在处理非常大的转录时性能会下降。超过 2 小时的录音可能生成大量文本，某些浏览器可能难以流畅显示。说话人标记转录的气泡视图尤其消耗资源。
如果界面随时间推移逐渐变慢，请清除浏览器缓存。Speakr 会在本地缓存数据以提高性能，但此缓存可能会损坏。在 Chrome 或 Firefox 中，使用 Ctrl+Shift+R 硬刷新以重新加载最新资源。
特定功能问题
说话人识别不起作用
说话人分离 需要 ASR 端点，而非标准 Whisper API。在 系统设置 中配置说话人设置。验证您已在环境配置文件中正确配置 ASR 设置。ASR_BASE_URL 应指向支持说话人分离的有效 ASR 服务。
即使启用了 ASR，您也必须在上传或重新处理录音时明确请求说话人分离。Speakr 默认应执行此操作，但用户设置可能会覆盖此行为。检查说话人数量设置 — 如果将最小和最大说话人数都设置为 1，说话人分离实际上已禁用。对于大多数录音，使用 2-6 个说话人的合理范围。
转录后，说话人显示为通用标签（SPEAKER_01 等）。您必须手动 识别说话人，方法是点击标签并分配名称。在账户设置中管理您的 说话人库。
WhisperX 显示 UNKNOWN_SPEAKER
如果 WhisperX 仅显示 "UNKNOWN_SPEAKER" 而不是编号说话人（SPEAKER_00、SPEAKER_01 等），请检查以下常见问题：
-
错误的 ASR_ENGINE：您必须在 ASR 容器的 Docker 环境中使用
ASR_ENGINE=whisperx。faster_whisper引擎不支持说话人分离，尽管它可以转录音频。 -
缺少或无效的 HF_TOKEN：ASR 容器需要有效的 HuggingFace 令牌来下载说话人分离模型。确保您的 ASR 容器配置中设置了
HF_TOKEN环境变量。 -
未启用 ASR_DIARIZE：虽然当
USE_ASR_ENDPOINT=true时应自动启用，但如果未检测到说话人，请在 Speakr .env 文件中显式设置ASR_DIARIZE=true。 -
Docker 网络问题：如果在同一 docker-compose 中使用 Speakr 和 ASR webservice 容器，容器必须通过服务名称通信（如
http://whisper-asr:9000），而非 localhost 或外部 IP。
检查 ASR 容器日志中的 pyannote/VAD 消息，以确认说话人分离模型已正确加载。
Mac 上的 ASR 服务显示 GPU 错误
如果在 macOS 上运行 ASR webservice 并遇到 GPU 相关错误或 "no matching manifest" 错误：
- 使用 CPU 镜像：将
onerahmet/openai-whisper-asr-webservice:latest-gpu替换为onerahmet/openai-whisper-asr-webservice:latest - 移除 GPU 配置：从 docker-compose.yml 中删除包含 GPU 设备预留的整个
deploy部分 - 预期处理速度较慢：基于 CPU 的转录可以工作，但比 GPU 加速慢得多
这是 macOS 上 Docker 的限制 — GPU 直通不受支持，因为 Docker 运行在 Linux VM 中。请参阅 常见问题 了解完整的 Mac 配置。
分享链接不起作用
分享 功能要求您的 Speakr 实例可通过互联网使用 HTTPS 访问。请参阅 分享要求 和 安全注意事项。本地安装或非 SSL 设置无法生成有效的分享链接。分享按钮将禁用或显示错误，说明相关要求。
如果您的实例满足要求但分享仍然失败，请检查环境配置中配置的 URL 是否与实际情况匹配。URL 不匹配会导致分享链接指向错误位置。URL 必须与外部用户访问您实例时使用的地址完全一致。
询问模式无结果
语义搜索 需要正确安装和初始化嵌入模型。在管理设置中查看 向量存储选项卡，并查看 向量存储故障排除 — 应显示 "Available" 状态。如果不是，sentence-transformers 库可能缺失或加载失败。
所有录音在可搜索之前都需要进行处理。向量存储选项卡显示已处理与待处理的录音数量。如果自动处理停滞，请使用处理按钮手动触发嵌入生成。
查询表述方式非常重要。询问模式 理解上下文和含义，而不仅仅是关键词。在用户指南中了解 有效的搜索策略。提出完整的问题，而不是输入孤立的单词。"我们关于预算做了什么决定？" 比仅输入 "预算 决定" 效果更好。
其他注意事项
录音免责声明（法律合规）
在许多司法管辖区，您必须告知参与者他们正在被录音。在 系统设置 中启用录音免责声明。查看 关于录音合规的常见问题。设置在任何录音开始前显示的自定义文本，例如关于同意要求的法律通知。此功能在具有严格录音法律的地区（如澳大利亚或加利福尼亚州）尤为重要。
离线部署
Speakr 可以完全离线运行，因为所有依赖项都内置在 Docker 镜像中。对于离线部署，使用 Ollama 的本地模型进行 文本生成，并确保您的 ASR 端点在本地托管。正确配置后，系统无需互联网访问即可工作。
非 Docker 安装
虽然 Docker 是唯一官方支持的安装方式，但您可以尝试使用 npm 和 Python 进行手动安装。您需要自行处理依赖项、环境设置和配置。此方式不推荐用于常规使用，您需要独立排查问题。
获取帮助
检查日志
Docker 日志包含宝贵的调试信息。使用 docker-compose logs -f app 查看实时日志。查找与问题发生时间对应的 ERROR 或 WARNING 消息。Python 追溯信息表明可能是代码级问题，可能需要寻求支持。
对于 ASR 问题，同时检查 ASR 容器日志：docker-compose logs -f whisper-asr-webservice
系统信息
请求帮助时，请提供账户设置中 About 选项卡的系统配置信息。包括 Speakr 版本、配置的 AI 模型、转录服务类型以及任何错误消息。这些上下文信息有助于他人了解您的具体设置。
社区支持
GitHub 仓库的 issue 追踪器是报告错误或请求功能的最佳资源。请先搜索现有 issue — 可能有人已经遇到并解决了您的问题。创建新 issue 时，请包含重现问题的具体步骤。
下一步：常见问题 →