故障排查

能力服务不可用

确认提供方插件已经安装并加载，然后在 DSH 设置的相应服务页面中选择它。选择禁用会从上下文中移除该服务。

认证失败

确认连接引用了正确的 DSH 凭据，并检查服务器是否要求 Bearer 认证。凭据引用为空时不会发送 API 密钥。

兼容服务器拒绝模型或声音

兼容 OpenAI 并不代表模型和声音目录完全相同。请输入服务器实际支持的标识符。声音发现是可选功能，可能返回空列表。

调用长时间排队

在设置中查看并发状态。一个调用可能同时等待多条规则。检查规则上限、前台保留容量和等待时间最长的调用。取消调用方会从队列移除尚未开始的请求。

流一直占用并发容量

确保使用方读取、取消或丢弃流。maxHoldSeconds 可以作为保护措施释放调度计数，但不能保证远端请求已被取消。

缺少实时转录服务

只有当前 API 提供方实现实时转录时，才会注册 streamingSpeechToText。文件转录仍可能通过 apiSpeechToText 使用，DSH 内置语音转文本提供方也仍是独立选项。

设置更改看似没有生效

确认使用方调用的是所选服务，而不是直接导入厂商实现。能力选择和非启动时字段会实时解析；标记为仅启动时生效的选项需要重启配置档案进程。

对于语言模型，请确认聊天使用了目标 route/model。语言模型路由可以并存，不受单一提供方能力选择器控制。

向量无法正常比较

检查嵌入服务返回的 model 与 dimensions。连接或模型改变后需要重建已保存向量。即使维度碰巧相同，也不要混用不同模型的结果。

兼容端点返回异常数据

这里所说的兼容只描述传输格式，并不保证每个服务器都实现所有端点或字段。请在提供方页面确认准确的方法和路径，在服务器日志中查看保留的 AiError 原始原因，并将响应与文档契约对照。不要在使用方代码中接受缺失索引、无效媒体类型或不完整流事件来绕过异常响应。

区分错误码

错误码	首先检查
not-configured	提供方选择、插件加载状态和引用的连接
invalid-input	空文本、无效数量或范围，以及不匹配的请求结构
unsupported	模型能力与提供方专属选项支持情况
rejected	凭据、配额、策略、模型或声音标识符
unavailable	网络连通性、服务器健康、超时和并发等待
cancelled	调用方生命周期与传递的 AbortSignal

消息和原始原因包含诊断信息，但只有错误码是稳定的分支契约。