Skip to main content
Version: Next

离线模型下载

适用范围​

本文用于说明宿主 App 如何按 SDK 规则自行下载并放置离线模型包。文档仅覆盖与离线模型包下载、存放和就绪检测相关的内容，不包含 SDK 初始化、鉴权、创建通道、音频采集等完整接入流程。

示例统一使用一对一对话：

  • 语言方向：zh-CN ↔ en-US

  • 模型语言码：zh、en

  • 场景：一对一对话

  • 默认能力：启用 ASR、MT、TTS

下载地址规则​

离线模型包公网下载根地址：

https://resources.timekettle.co/offline-models/v3.1

模型包 URL 按类型拼接：

类型URL 规则示例
ASR{baseUrl}/asr/{lang}.ziphttps://resources.timekettle.co/offline-models/v3.1/asr/zh.zip
MT{baseUrl}/mt/{src}2{dst}.ziphttps://resources.timekettle.co/offline-models/v3.1/mt/zh2en.zip
TTS{baseUrl}/tts/{lang}.ziphttps://resources.timekettle.co/offline-models/v3.1/tts/en.zip
TTS 公共数据{baseUrl}/tts/tmk-tts-data.ziphttps://resources.timekettle.co/offline-models/v3.1/tts/tmk-tts-data.zip

语言码使用主语言标签：

App 语言码模型语言码
zh-CNzh
zh-HKzh
en-USen
en-GBen

宿主生成 URL 时应先把 BCP-47 语言码归一为主语言标签，再拼接下载地址。

一对一对话需要下载哪些包​

以 zh-CN ↔ en-US 一对一对话为例，需要下载以下 7 个包：

包 key下载 URL放置目录说明
asr/zhhttps://resources.timekettle.co/offline-models/v3.1/asr/zh.zip{modelRoot}/asr/zh中文 ASR 模型
asr/enhttps://resources.timekettle.co/offline-models/v3.1/asr/en.zip{modelRoot}/asr/en英文 ASR 模型
mt/zh2enhttps://resources.timekettle.co/offline-models/v3.1/mt/zh2en.zip{modelRoot}/mt/zh2en中文到英文翻译模型
mt/en2zhhttps://resources.timekettle.co/offline-models/v3.1/mt/en2zh.zip{modelRoot}/mt/en2zh英文到中文翻译模型
tts/zhhttps://resources.timekettle.co/offline-models/v3.1/tts/zh.zip{modelRoot}/tts/zh中文 TTS 模型
tts/enhttps://resources.timekettle.co/offline-models/v3.1/tts/en.zip{modelRoot}/tts/en英文 TTS 模型
tts/tmk-tts-datahttps://resources.timekettle.co/offline-models/v3.1/tts/tmk-tts-data.zip{modelRoot}/tts/tmk-tts-dataTTS 公共数据包

说明：

  • 一对一对话需要双向 ASR、双向 MT、双语 TTS。

  • 如果业务关闭 MT，则不需要下载 mt/* 包。

  • 如果业务关闭 TTS，则不需要下载 tts/{lang} 和 tts/tmk-tts-data。

  • 默认情况下建议完整下载上表 7 个包。

模型根目录结构​

宿主 App 需要准备一个模型根目录，本文用 {modelRoot} 表示。下载并解压完成后，一对一 zh-CN ↔ en-US 的目录结构应为：

{modelRoot}/
  asr/
    zh/
      ...
    en/
      ...
  mt/
    zh2en/
      ...
    en2zh/
      ...
  tts/
    zh/
      ...
    en/
      ...
    tmk-tts-data/
      ...

放置规则：

  • zip 包必须解压后使用，不能只把 zip 文件放到模型目录中。

  • 每个包最终对应一个目录：{modelRoot}/{type}/{name}。

  • asr/zh.zip 解压后的内容放到 {modelRoot}/asr/zh。

  • mt/zh2en.zip 解压后的内容放到 {modelRoot}/mt/zh2en。

  • tts/tmk-tts-data.zip 解压后的内容放到 {modelRoot}/tts/tmk-tts-data。

SDK 就绪检测要求：

  • 需要的包目录必须存在。

  • 需要的包目录不能是空目录。

  • 模型包目录内需要包含有效模型文件。

  • 如果 zip 包内带有同名顶层目录，宿主应确保最终目录仍符合 {modelRoot}/{type}/{name} 这一层级。

宿主下载流程建议​

建议宿主按以下流程处理下载：

  1. 确定业务场景和语言对，例如 zh-CN ↔ en-US 一对一。

  2. 将语言码归一为模型语言码，例如 zh-CN → zh、en-US → en。

  3. 生成需要下载的包列表和 URL。

  4. 检查本地目标目录是否已经存在且可用。

  5. 对缺失或不可用的包发起下载。

  6. 下载 zip 到宿主临时目录。

  7. 下载完成后校验 zip 文件完整性。

  8. 解压到临时解压目录。

  9. 校验解压结果不是空目录，并包含模型文件。

  10. 用解压结果替换目标目录 {modelRoot}/{type}/{name}。

  11. 清理临时 zip 和临时解压目录。

  12. 调用 SDK 模型就绪检测接口。

  13. 检测通过后，再进入后续离线翻译流程。

下载失败处理建议：

  • 网络失败：允许重试或断点续传。

  • 磁盘不足：提示用户清理空间后重试。

  • 解压失败：删除当前包的临时文件和目标目录后重新下载。

  • 单个包失败：只重试失败包，不需要重复下载全部包。

SDK 相关接口​

宿主自下载模型后，需要把同一个模型根目录传给 SDK，并在使用离线能力前检测模型是否准备好。

能力AndroidiOS
设置模型根目录setModelRootDirectory(modelRootDir)setModelRootDirectory(modelRootDirectory)
同步检测模型是否准备好isOfflineModelReady(...)isOfflineModelReady(...)
异步检测模型是否准备好checkOfflineModelReadyAsync(...)checkOfflineModelReadyAsync(...)
查询包状态getOfflineModelPackageInfos(...)getOfflineModelPackageInfos(...)

使用要求：

  • 下载目录、检测目录、SDK 使用目录必须是同一个 {modelRoot}。

  • 一对一对话检测时，场景参数应使用一对一。

  • srcLang、dstLang 应与下载包方向一致。

  • 建议优先使用异步检测接口，避免目录扫描影响 UI。

一对一下载列表生成示例​

以下伪代码只用于说明下载列表如何生成，宿主可按自身下载框架处理。

baseUrl = "https://resources.timekettle.co/offline-models/v3.1"
src = normalize("zh-CN") = "zh"
dst = normalize("en-US") = "en"

packages = [
  "asr/" + src,
  "asr/" + dst,
  "mt/" + src + "2" + dst,
  "mt/" + dst + "2" + src,
  "tts/" + src,
  "tts/" + dst,
  "tts/tmk-tts-data"
]

对应 URL：

https://resources.timekettle.co/offline-models/v3.1/asr/zh.zip
https://resources.timekettle.co/offline-models/v3.1/asr/en.zip
https://resources.timekettle.co/offline-models/v3.1/mt/zh2en.zip
https://resources.timekettle.co/offline-models/v3.1/mt/en2zh.zip
https://resources.timekettle.co/offline-models/v3.1/tts/zh.zip
https://resources.timekettle.co/offline-models/v3.1/tts/en.zip
https://resources.timekettle.co/offline-models/v3.1/tts/tmk-tts-data.zip

对应本地目录：

{modelRoot}/asr/zh
{modelRoot}/asr/en
{modelRoot}/mt/zh2en
{modelRoot}/mt/en2zh
{modelRoot}/tts/zh
{modelRoot}/tts/en
{modelRoot}/tts/tmk-tts-data

交付检查清单​

交付前建议确认：

  • 7 个一对一模型包均已下载。

  • 所有 zip 均已解压。

  • 本地目录结构符合 {modelRoot}/{type}/{name}。

  • 下载目录、检测目录、SDK 使用目录一致。

  • SDK 模型就绪检测返回通过。

  • 下载失败、解压失败、磁盘不足、用户取消等场景都有恢复入口。

常见问题​

离线模型相关的常见问题见 常见问题 · 离线模型。