175 lines
15 KiB
Markdown
175 lines
15 KiB
Markdown
# 故障排除
|
||
|
||
当 Speakr 出现问题时，本指南可帮助您快速识别和解决常见问题。大多数问题归为以下几类 — [安装问题](getting-started/installation.md)、转录失败、性能问题或特定功能异常。同时请参阅 [常见问题](faq.md) 了解常见疑问。了解从哪里着手以及需要检查什么可以节省大量排错时间。
|
||
|
||
## 安装与设置问题
|
||
|
||
### 容器无法启动
|
||
|
||
当 Docker 容器拒绝启动或立即退出时，问题通常出在配置上。首先检查您的 [环境配置文件](getting-started.md#step-3-configure-your-transcription-service) — API 密钥中的任何拼写错误或不匹配的引号都可能导致启动失败。查看 [安装指南](getting-started/installation.md) 了解正确的设置方式。运行 `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 地址或主机名。
|
||
|
||
### 管理员登录失败
|
||
|
||
如果无法使用 [管理员凭据](getting-started.md#step-4-configure-admin-account) 登录，首先验证您使用的是环境配置文件中完全相同的用户名和密码。有关用户管理问题，请参阅 [管理员指南](admin-guide/user-management.md)。这些值区分大小写，必须完全匹配。检查 Docker 日志中的管理员用户创建消息 — 首次启动时应看到 "Admin user created successfully"。
|
||
|
||
有时如果密码不符合要求，管理员用户创建会静默失败。确保管理员密码至少为 8 个字符。如果管理员用户未创建，您可能需要删除数据库文件并重启容器以重新触发初始化。
|
||
|
||
## 转录问题
|
||
|
||
### 转录从未开始
|
||
|
||
当录音一直处于 "pending" 状态时，后台处理器可能已停止。检查日志中是否有关于 [转录服务](features.md#multi-engine-support) 的错误消息。在 [向量存储](admin-guide/vector-store.md) 管理面板中监控处理状态。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 端点](features.md#speaker-diarization) 可显著提高可用性。了解如何在转录后 [识别说话人](user-guide/transcripts.md#speaker-identification)，即使原始转录准确率相似。
|
||
|
||
### 中文转录问题
|
||
|
||
对于 [中文语言转录](features.md#language-support)，模型选择至关重要。有关更多详细信息，请参阅 [关于语言支持的常见问题](faq.md#can-speakr-transcribe-languages-other-than-english)。
|
||
|
||
**重要提示**：Distil 模型（如 distil-large-v3）不支持正确的中文转录。即使您将语言设置为 "zh"，这些模型也可能将中文音频识别为英文并产生错误输出。对于中文内容，请始终使用完整版的 large-v3 模型或类似的非蒸馏模型。如果您的中文音频被转录为英文，或输出为拼音而非中文字符，请从 distil 模型切换到 large-v3。
|
||
|
||
### 摘要语言与偏好不匹配
|
||
|
||
如果点击 "Reprocess Summary" 后 [摘要](features.md#automatic-summarization) 回退到英文，尽管已设置了 [语言偏好](user-guide/settings.md#language-preferences)，这可能是模型限制。配置 [自定义提示词](admin-guide/prompts.md) 以强制执行语言要求。某些模型（如 Qwen3-30B）不一定能正确遵循语言指令。尝试使用能更好地遵循语言指令的不同模型，或确保您的自定义提示词明确指定了输出语言。
|
||
|
||
## 性能问题
|
||
|
||
### 转录处理缓慢
|
||
|
||
大音频文件自然需要更长时间处理，但过度延迟表明存在问题。检查您的 [服务器资源](getting-started.md#prerequisites) 并查看 [系统统计信息](admin-guide/statistics.md) 获取性能指标 — Speakr 需要足够的 CPU 和 RAM，尤其是在同时处理多个录音时。`docker stats` 命令可显示当前资源使用情况。
|
||
|
||
网络速度影响转录时间，因为音频必须上传到 API 服务。慢速互联网连接会造成瓶颈，尤其是对于大文件。如果您经常处理长录音，请考虑分块设置。
|
||
|
||
转录模型的选择影响速度。Whisper Large 更准确但比 Whisper Base 慢。如果速度比完美准确率更重要，请考虑通过 API 设置使用较小的模型。
|
||
|
||
### 超过 25MB 的文件在 OpenAI 上失败
|
||
|
||
OpenAI 的 Whisper API 有 25MB 文件大小限制。对于更大的文件，请在环境配置中启用 [分块](features.md#audio-chunking)。了解 [分块策略](faq.md#whats-the-difference-between-chunking-by-size-vs-duration)：
|
||
```
|
||
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 硬刷新以重新加载最新资源。
|
||
|
||
## 特定功能问题
|
||
|
||
### 说话人识别不起作用
|
||
|
||
[说话人分离](features.md#speaker-diarization) 需要 [ASR 端点](getting-started.md#option-b-custom-asr-endpoint-configuration)，而非标准 Whisper API。在 [系统设置](admin-guide/system-settings.md) 中配置说话人设置。验证您已在环境配置文件中正确配置 ASR 设置。ASR_BASE_URL 应指向支持说话人分离的有效 ASR 服务。
|
||
|
||
即使启用了 ASR，您也必须在上传或重新处理录音时明确请求说话人分离。Speakr 默认应执行此操作，但用户设置可能会覆盖此行为。检查说话人数量设置 — 如果将最小和最大说话人数都设置为 1，说话人分离实际上已禁用。对于大多数录音，使用 2-6 个说话人的合理范围。
|
||
|
||
转录后，说话人显示为通用标签（SPEAKER_01 等）。您必须手动 [识别说话人](user-guide/transcripts.md#speaker-identification)，方法是点击标签并分配名称。在账户设置中管理您的 [说话人库](user-guide/settings.md#speakers-management-tab)。
|
||
|
||
### WhisperX 显示 UNKNOWN_SPEAKER
|
||
|
||
如果 WhisperX 仅显示 "UNKNOWN_SPEAKER" 而不是编号说话人（SPEAKER_00、SPEAKER_01 等），请检查以下常见问题：
|
||
|
||
1. **错误的 ASR_ENGINE**：您必须在 ASR 容器的 Docker 环境中使用 `ASR_ENGINE=whisperx`。`faster_whisper` 引擎不支持说话人分离，尽管它可以转录音频。
|
||
|
||
2. **缺少或无效的 HF_TOKEN**：ASR 容器需要有效的 HuggingFace 令牌来下载说话人分离模型。确保您的 ASR 容器配置中设置了 `HF_TOKEN` 环境变量。
|
||
|
||
3. **未启用 ASR_DIARIZE**：虽然当 `USE_ASR_ENDPOINT=true` 时应自动启用，但如果未检测到说话人，请在 Speakr .env 文件中显式设置 `ASR_DIARIZE=true`。
|
||
|
||
4. **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 中。请参阅 [常见问题](faq.md#can-i-use-the-asr-webservice-for-speaker-diarization-on-mac) 了解完整的 Mac 配置。
|
||
|
||
### 分享链接不起作用
|
||
|
||
[分享](user-guide/sharing.md) 功能要求您的 Speakr 实例可通过互联网使用 HTTPS 访问。请参阅 [分享要求](user-guide/sharing.md#requirements-for-sharing) 和 [安全注意事项](user-guide/sharing.md#security-and-privacy-considerations)。本地安装或非 SSL 设置无法生成有效的分享链接。分享按钮将禁用或显示错误，说明相关要求。
|
||
|
||
如果您的实例满足要求但分享仍然失败，请检查环境配置中配置的 URL 是否与实际情况匹配。URL 不匹配会导致分享链接指向错误位置。URL 必须与外部用户访问您实例时使用的地址完全一致。
|
||
|
||
### 询问模式无结果
|
||
|
||
[语义搜索](user-guide/inquire-mode.md) 需要正确安装和初始化嵌入模型。在管理设置中查看 [向量存储选项卡](admin-guide/vector-store.md)，并查看 [向量存储故障排除](admin-guide/vector-store.md#troubleshooting-common-issues) — 应显示 "Available" 状态。如果不是，sentence-transformers 库可能缺失或加载失败。
|
||
|
||
所有录音在可搜索之前都需要进行处理。向量存储选项卡显示已处理与待处理的录音数量。如果自动处理停滞，请使用处理按钮手动触发嵌入生成。
|
||
|
||
查询表述方式非常重要。[询问模式](user-guide/inquire-mode.md) 理解上下文和含义，而不仅仅是关键词。在用户指南中了解 [有效的搜索策略](user-guide/inquire-mode.md#asking-effective-questions)。提出完整的问题，而不是输入孤立的单词。"我们关于预算做了什么决定？" 比仅输入 "预算 决定" 效果更好。
|
||
|
||
## 其他注意事项
|
||
|
||
### 录音免责声明（法律合规）
|
||
|
||
在许多司法管辖区，您必须告知参与者他们正在被录音。在 [系统设置](admin-guide/system-settings.md#recording-disclaimer) 中启用录音免责声明。查看 [关于录音合规的常见问题](faq.md#do-i-need-to-inform-people-theyre-being-recorded)。设置在任何录音开始前显示的自定义文本，例如关于同意要求的法律通知。此功能在具有严格录音法律的地区（如澳大利亚或加利福尼亚州）尤为重要。
|
||
|
||
### 离线部署
|
||
|
||
Speakr 可以完全离线运行，因为所有依赖项都内置在 Docker 镜像中。对于离线部署，使用 Ollama 的本地模型进行 [文本生成](features.md#automatic-summarization)，并确保您的 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 时，请包含重现问题的具体步骤。
|
||
|
||
---
|
||
|
||
下一步：[常见问题](faq.md) →
|