故障排除

使用 Gladia API 时常见的问题、注意事项及其解决方案。

SDK 优先诊断：首先确认用户是否使用官方 SDK —— 许多问题（轮询、重连、重试）可通过 SDK 自动解决。有关设置和策略，请参阅 [gladia-sdk-integration](../gladia-sdk-integration/SKILL.md)。

适用场景

• 调用 Gladia API 时遇到错误（401、403、429、格式无效、超时）
• 出现异常行为：转录质量差、漏词、语言识别错误
• WebSocket 断开、轮询失败或会话卡死
• 计费困惑（多通道、并发限制、计划限制）
• 在上线生产前验证集成配置是否正确

不适用场景：初始 SDK 设置与配置，请使用 [gladia-sdk-integration](../gladia-sdk-integration/SKILL.md)。如需特定功能指导（参数、选项、响应结构），请参考 [gladia-pre-recorded-transcription](../gladia-pre-recorded-transcription/SKILL.md) 或 [gladia-live-transcription](../gladia-live-transcription/SKILL.md)。

参考资料

根据需要查阅以下资源：

• ../gladia-sdk-integration/SKILL.md — SDK 设置、客户端配置（重试、超时）、SDK 与原生 API 的选择指南
• ../gladia-sdk-integration/references/sdk-versions.md — 当前 SDK 版本（由 CI 自动同步）
• ../gladia-pre-recorded-transcription/SKILL.md — 预录制配置选项与限制
• ../gladia-live-transcription/SKILL.md — 实时会话配置与 WebSocket 事件处理
• ../gladia-audio-intelligence/SKILL.md — 音频智能功能配置及可用性矩阵

认证错误

401 未授权

• 原因：API 密钥无效或缺失
• 修复（SDK）：确认密钥通过 apiKey（JS）或 api_key（Python）构造函数参数传递，或设置 GLADIA_API_KEY 环境变量
• 修复（原生 REST）：确认密钥通过 x-gladia-key 头部传递
• 检查：访问 [app.gladia.io](https://app.gladia.io) → API 密钥 → 确认密钥处于激活状态

403 禁止访问

• 原因：密钥无权访问请求的功能或区域
• 修复：检查当前计划等级；部分功能受计划限制

速率限制与并发控制

429 请求过多

按计划的并发限制：

修复：等待正在进行的任务完成后，再启动新任务，或升级计划。

常见陷阱

1. 启用代码切换但未指定语言列表

问题：启用 code_switching: true 且 languages 数组为空时，系统会在超过 100 种语言间进行评估，导致频繁误识别。

修复：始终提供 3–5 个预期语言：

{
  "language_config": {
    "languages": ["en", "fr", "es"],
    "code_switching": true
  }
}

2. 自定义词汇强度过高

问题：intensity 值超过 0.6 会导致无关词汇被错误替换为词汇表条目。

修复：将强度保持在 0.4–0.6 范围内。若需更好识别，应使用 pronunciations 而非提高强度：

{
  "vocabulary": [
    { "value": "Gladia", "pronunciations": ["gla-dee-ah"], "intensity": 0.5 }
  ]
}

3. 音频超出时长限制而无声失败

问题：预录制文件超过 135 分钟可能失败，且无明确错误提示。

修复：上传前将长音频拆分为约 60 分钟的片段。企业版支持最长 4 小时 15 分钟，如有需求请联系客服。

4. 多通道计费意外

问题：发送双通道（立体声）音频按两倍时长计费。

修复：若无需每通道说话人识别，应合并为单声道。仅在需要区分独立音源时才使用多通道。

5. WebSocket 断开后无法恢复

问题：WebSocket 断开后，创建新会话将丢失上下文。

修复（SDK — 推荐）：SDK 自动处理重连，可配置 wsRetry。使用 SDK 时无需额外操作。

修复（原生 WebSocket）：重新连接至相同的 WebSocket URL以恢复会话。切勿再次调用 /v2/live。

6. 无退避机制的轮询

问题：快速轮询 /v2/pre-recorded/:id 会浪费请求，可能触发速率限制。

修复（SDK — 推荐）：SDK 自动处理轮询。使用 transcribe() 方法（内置退避机制），或直接配置 poll()：

const result = await client.preRecorded().transcribe(audio, options, {
  interval: 5000, // 每次轮询间隔 5 秒
});

result = client.prerecorded().transcribe(
    "audio.mp3",
    options,
    {"interval": 5000},  # 每次轮询间隔 5 秒
)

修复（原生 REST）：实现指数退避（起始 3 秒，最大 30 秒），或改用 Webhook/回调方式。

7. 忘记停止录音

问题：未发送 stop_recording 使 WebSocket 保持打开状态，会话将持续到 3 小时超时。

修复：完成录音后务必显式调用 session.stopRecording()（Python 中为 session.stop_recording()）。在错误处理中也应实现清理逻辑。

8. 部分转录结果未出现

问题：默认情况下，实时结果仅以最终转录形式返回。

修复：在会话配置中启用部分转录：

{
  "messages_config": {
    "receive_partial_transcripts": true
  }
}

9. 期望实时模式下支持说话人分离

问题：说话人分离功能仅适用于预录制转录。

修复：对于实时多说话人场景，建议使用多通道音频，每通道对应一位说话人，并通过通道编号追踪。

10. 实时模式下的 PII 信息脱敏

name: Gladia Troubleshooting

version: 1.0.0

description: 常见问题排查指南，适用于 Gladia 的预录制与实时语音转写功能。

summary: 本指南帮助解决 Gladia 语音转写中常见的音频格式、转写质量、回调接收及配置问题。

问题：pii_redaction: true 在实时转写中被静默忽略

修复方法：PII（个人身份信息）脱敏功能仅适用于预录制音频。如需实时合规处理，请在客户端对转写文本实施本地脱敏。

音频格式问题

“无效音频格式”错误

• 确保 encoding、sample_rate、bit_depth、channels 与实际音频流一致
• 预录制音频：格式由文件自动检测；此错误仅出现在实时场景
• 支持的格式及大小限制，请参考 [gladia-pre-recorded-transcription](../gladia-pre-recorded-transcription/SKILL.md#limits-and-specifications) 和 [gladia-live-transcription](../gladia-live-transcription/SKILL.md#limits)

转写质量问题

准确率低

1. 检查音频质量：背景噪音、音量过低或严重压缩会降低识别效果
2. 启用音频增强：设置 pre_processing.audio_enhancer: true（仅限实时）
3. 明确指定语言：始终提供预期语言列表，避免依赖自动检测
4. 使用自定义词汇表：针对医疗、法律、技术等专业术语
5. 检查采样率：16kHz 及以上采样率比 8kHz 效果更好

语言识别错误

1. 明确提供 languages 列表
2. 若为多语言内容，启用 code_switching 并指定 3–5 个预期语言
3. 若为单语言内容，仅指定一个语言并禁用 code_switching

丢失词语或出现空白段落

1. 检查是否存在静音或极低音量区域
2. 确认音频未损坏（尝试回放测试）
3. 实时场景下：确保音频分块持续发送，避免大间隔中断

Webhook/回调问题

回调未收到

1. 确保 callback_url 可公开访问（非 localhost）
2. 检查服务器在超时时间内返回 2xx 状态码
3. 确认无防火墙或 WAF 阻止入站请求
4. 建议先通过 webhook.site 等服务进行测试

Webhook 签名验证

Webhook 由 Svix 提供支持。请使用 Svix 官方库进行验证：

import { Webhook } from "svix";
const wh = new Webhook(webhookSecret);
wh.verify(payload, headers);

验证清单

提交转写任务前，请确认以下事项：

• [ ] 使用官方 Gladia SDK（如未使用，请确认有合理原因）
• [ ] API Key 有效且正确传递（通过 SDK 构造函数或 GLADIA_API_KEY 环境变量）
• [ ] 音频文件小于 1000 MB，且在时长限制范围内
• [ ] 音频格式受支持
• [ ] 若启用 code_switching，languages 列表包含 3–5 项
• [ ] 若使用自定义词汇表，强度值设置在 0.4–0.6 之间
• [ ] 实时转写：任务结束时正确调用 stopRecording() / stop_recording()
• [ ] 实时转写：音频格式配置与实际流一致
• [ ] 若配置了回调/ webhook，目标地址可访问
• [ ] 多通道音频为有意为之
• [ ] 错误响应已妥善处理（SDK 抛出类型化错误；原始 API 返回 status、error_message）

进阶阅读

• [认证方式](https://docs.gladia.io/chapters/api/authentication)
• [速率限制与并发控制](https://docs.gladia.io/chapters/limits-and-specifications/rate-limits)
• [支持的格式与限制](https://docs.gladia.io/chapters/limits-and-specifications/supported-formats)
• [Webhook 说明](https://docs.gladia.io/chapters/pre-recorded-stt/webhooks)
• [API 参考（错误码）](https://docs.gladia.io/api-reference)

支持资源

• [Gladia 文档中心](https://docs.gladia.io)
• [支持中心](https://support.gladia.io)
• [API 状态页面](https://status.gladia.io)
• [管理控制台](https://app.gladia.io)