Skip to main content
Version: Next

常见问题

iOS​

为什么在线能力需要先调用 verifyAuth(_:)？​

在线翻译、在线建房与在线建通道都依赖鉴权成功后得到的业务 token。在线语言列表是例外：完成 sdkInit(_:) 后即可请求，不依赖 verifyAuth(_:)。

为什么离线翻译也建议先调用 verifyAuth(_:)？​

离线翻译并不是零前置条件直接可用。SDK 在 verifyAuth(_:) 中会先完成在线鉴权，并在在线鉴权成功后继续尝试离线鉴权，用于确认当前账号是否开通离线翻译能力，并获取离线能力所需的鉴权信息。

为什么离线模型下载成功过，之后又可能不能使用？​

常见原因包括：

  • 当前账号已不具备离线能力

  • 本地模型目录被删除或不完整

  • 模型根目录变更

  • 本次创建通道时所需语言对或场景与已下载模型不匹配

建议在创建离线通道前先调用 isOfflineModelReady(...) 检查。

为什么在线和离线的语言 code 不完全一样？​

在线语言通常使用更完整的 locale 代码，例如 zh-CN、en-US；离线语言通常使用短码，例如 zh、en。接入时请始终使用对应语言列表接口返回的实际 code。

为什么当前建议使用 16000 采样率？​

当前 SDK、Demo 和自动化测试主流程都以 16000 Hz 为准。其他采样率暂未完成完整兼容性验证，正式接入建议优先使用 16000。

为什么离线一对一模式需要双声道输入？​

一对一模式会把左右声道视为两路独立输入：

  • 左声道：一侧说话人

  • 右声道：另一侧说话人

因此一对一模式应设置 pcmChannels = 2，并输入正确的双声道 PCM。

为什么 onRecognized(...) 和 onTranslate(...) 会多次回调？​

这两个回调都支持增量结果：

  • isFinal == false：中间过程结果

  • isFinal == true：本段最终结果

业务方应以 isFinal 或 result.isLast 判断当前结果是否结束。

releaseChannel() 和 destroy() 有什么区别？​

  • releaseChannel()：释放当前翻译会话相关资源，包含当前通道、未完成建房请求、在线房间关闭和离线模型下载管理器等会话状态。下次创建通道前建议先调用。

  • destroy()：释放 SDK 全局资源。调用后若要继续使用，必须重新 sdkInit(_:)，并根据业务重新鉴权。

auto / mix 可以直接用于生产吗？​

当前可以传入，但实际仍会落到在线引擎执行。如果你需要明确行为，建议直接使用 .online 或 .offline。

TmkTranslationMessageTunnel 离线可以用吗？​

不可以。TmkTranslationMessageTunnel 仅在线翻译使用，离线翻译会忽略该配置。

isOfflineTranslationSupported() 返回 false 怎么办？​

说明当前账号或当前鉴权上下文不支持离线翻译。即使 verifyAuth(_:) 已成功，只要离线鉴权未成功，当前接口仍可能返回 false。此时不能创建可用的离线翻译通道。请先确认：

  • 已成功调用 verifyAuth(_:)

  • 当前环境配置正确

  • 账号已开通离线能力

为什么切换新房间或新通道前建议先释放旧资源？​

当前 SDK 使用时建议遵循单房间、单通道模型。创建新的翻译会话前，建议先调用 TmkTranslationSDK.shared.releaseChannel() 释放旧会话，避免旧资源仍占用网络、音频、房间或状态机上下文。

离线 License 解密或解析失败怎么办？​

如果本地 License 因密钥变更、历史版本兼容、设备绑定变化等原因解密或解析失败，SDK 会清理本地离线授权状态并尝试重新请求 License。若当前无网络或后台签发失败，在线 verifyAuth(_:) 仍以在线鉴权结果为准；离线能力会保持不可用，业务侧应提示用户联网后重试离线能力。不要删除 Keychain 中的设备密钥，也不要在 Release 版本调用调试清理接口。

clientSecret 变更后离线 License 还能用吗？​

旧 License 可能无法继续解密。SDK 会自动走重新签发流程，联网成功后即可恢复；离线无网络时无法重新签发，业务侧应提示用户联网重新鉴权。clientSecret 不应写入日志、诊断附件或用户可见错误信息。

Android​

为什么在线能力需要先调用 verifyAuth(callback)？​

在线建房、建通道和 token 获取依赖鉴权结果。未鉴权或鉴权失败时，创建通道可能返回 SDK_NOT_INITIALIZED、AUTHENTICATION_FAILED、ROOM_CREATION_FAILED 或 CHANNEL_CREATION_FAILED。

为什么离线翻译也建议先调用 verifyAuth(callback)？​

离线能力由账号权限和 License 鉴权共同决定。verifyAuth(callback) 成功后，业务侧需要通过 isOfflineTranslationSupported() 判断当前账号是否开通离线能力，再下载模型或创建离线通道。

为什么离线模型下载成功过，之后又可能不能使用？​

模型资源可能被用户清理、版本需要更新、模型根目录改变，或本地 manifest 与当前下载源不一致。创建离线通道前应重新调用 isOfflineModelReady(...) 或 getOfflineModelPackageInfos(...)。

为什么在线和离线的语言 code 不完全一样？​

在线语言由服务端配置决定，常使用完整 BCP-47 代码。离线引擎使用主语言标签加载模型，SDK 会把 zh-CN、zh-HK 等归一为 zh。离线可用语种由 License scope 与已下载的离线模型共同决定，SDK 层不再做语种白名单拦截：缺少对应模型时在模型资源校验阶段报 OFFLINE_MODEL_NOT_READY，仅当底层引擎运行期判定 locale 非法时才返回 2001113 / INVALID_LANGUAGE_CODE。

为什么当前建议使用 16000 采样率？​

当前在线/离线链路均按 16k PCM 作为推荐输入规格。采样率和声道数与配置不一致会导致识别效果下降、无结果或音频处理错误。

为什么离线一对一模式需要双声道输入？​

离线一对一内部会把左右声道拆分成两条 pipeline：左声道按 sourceLang -> targetLang 处理，右声道按 targetLang -> sourceLang 处理。输入不是双声道交织 PCM 时，声道归属和翻译方向会错误。

为什么 onRecognized(...) 和 onTranslate(...) 会多次回调？​

ASR 和 MT 可能返回中间结果和最终结果。业务侧应通过 isFinal 或 r.isLast 区分是否为最终文本。

stop()、destroy() 和 releaseChannel() 有什么区别？​

stop() 停止当前数据流，适合等待最终结果后再释放。destroy() 只释放单个通道对象。TmkTranslationSDK.releaseChannel() 是会话级释放入口，会释放当前通道、清空当前房间引用，并在在线房间已创建时异步关房，适合页面退出、切换通道或异常恢复。

AUTO / MIX 可以直接用于生产吗？​

当前文档只建议生产接入使用 ONLINE 或 OFFLINE。AUTO / MIX 属于保留能力或内部策略，不建议三方业务直接作为主流程。

isOfflineTranslationSupported() 返回 false 怎么办？​

先确认已完成 sdkInit(context, config) 和 verifyAuth(callback)，并确认账号已开通离线能力。如果仍为 false，不要启动离线模型下载或离线通道，应提示用户检查账号权限或联系后台配置。

为什么切换新房间或新通道前建议先释放旧资源？​

旧通道可能仍持有 RTC/RTM、离线 pipeline、音频播放、房间引用或回调引用。切换前先调用 TmkTranslationSDK.releaseChannel() 可以避免旧异步回调污染新页面状态，并避免在线房间遗留。

离线 License 解密或解析失败怎么办？​

SDK 会尝试清理本地离线授权状态并重新签发 License。重新签发仍失败时，业务侧应提示用户检查网络、账号权限、包名和鉴权配置后重试。

clientSecret 变更后离线 License 还能用吗？​

旧 License 可能无法继续解密。联网时 SDK 会尝试重新签发 License；离线无网络时无法重新签发，业务侧应提示用户联网重新鉴权。

离线模型​

为什么一对一下载了 zh2en 仍然检测不通过？​

一对一需要双向翻译模型。zh-CN ↔ en-US 必须同时包含：

mt/zh2en
mt/en2zh

同时还需要双向 ASR 和双语 TTS。

是否必须下载 tts/tmk-tts-data？​

如果启用 TTS，则必须下载 tts/tmk-tts-data。如果业务明确关闭 TTS，则可以不下载 TTS 语言包和公共数据包。

zip 解压后目录多了一层怎么办？​

宿主应调整最终目录，确保 SDK 看到的路径是：

{modelRoot}/{type}/{name}

例如中文 ASR 必须放在：

{modelRoot}/asr/zh

SDK 检测不通过时先查什么？​

优先检查：

  • 包是否下载完整。

  • zip 是否已解压。

  • 目标目录是否为空。

  • 目录层级是否正确。

  • 语言方向是否完整，尤其是一对一的双向 MT。

  • SDK 检测时传入的 {modelRoot} 是否与宿主下载目录一致。