Skip to content

常见问题 ​

为什么不能在 Expo Go 里跑? ​

Expo Go 内置的原生模块集合是固定的,无法加载任意原生代码。本 SDK 依赖 ONNX Runtime,而它是原生的。你需要 Development Build(npx expo run:ios / npx expo run:android)。没有任何配置能让 Expo Go 跑起来。

安装时遇到 401 或 403 ​

你的 npm token 缺失、过期,或未被授权访问 @optimalai scope。按顺序排查:

  1. 你的 npm 用户名已在 sdk-beta-readers 团队中。
  2. 你的 token 是包含 @optimalai scope 的细粒度只读 token。
  3. NPM_TOKEN 已在 shell 中导出,或在 CI / EAS 中配置为 secret。
  4. .npmrc 里是 ${NPM_TOKEN} —— 不是写死的 token,也不是过期的那个。

CLI 报 "base URL not configured" ​

生产模型 CDN 的 URL 由 OptimalAI 在发布时注入,npm 包里不含任何占位域名。在该 URL 上线之前,请显式传入:

bash
npx @optimalai/model-tools@beta add kokoro-82m-v1.1-zh-int8 \
  --base-url https://your-staging-host

或设置 OPTIMALAI_MODELS_BASE_URL。

load() 抛 MODEL_NOT_FOUND ​

这通常是 Metro 或资产解析的问题,而不是模型真的不见了:

  • 你用 withOptimalAI 包裹 Metro 配置了吗?没有它,.onnx、.bin、.txt 不会被注册为资产。
  • 干净 checkout 之后重新跑过模型安装器吗?模型文件是构建产物,不会提交进 Git。
  • 改动原生依赖之后重新构建过 Development Build 吗?
  • 生成的 optimalai-models.ts 在吗,被 import 了吗?

load() 抛 MODEL_CORRUPT ​

资产解析到了,但字节长度或哈希校验失败。磁盘上的文件与 manifest 描述的不一致 —— 下载被截断,或目录被删了一部分。删除模型目录后重装:

bash
npx @optimalai/model-tools@beta add kokoro-82m-v1.1-zh-int8

CLI 是故意不覆盖校验失败的目录的,所以你需要自己先清掉它。

遇到 BUSY ​

那个 client 上已有加载或合成在进行。SDK 一次只允许一个。await 掉进行中的调用, 然后重试。要并行就得用多个 client —— 每个都会独立加载模型并占用各自的内存。

英文文本报 INVALID_TEXT ​

该单词不在内置词典中,而 Beta 版没有 eSpeak 回退。这是刻意设计。请尽早用你的 真实内容去测词典覆盖,并在合成前清洗用户输入。见错误处理。

能在不重载模型的前提下换音色吗? ​

可以。给 synthesizeToFile 传一个不同的 voiceId 即可。ONNX session 保持加载 状态,只有 style embedding 会变。见切换音色与语速。

WAV 存到哪里?谁来删? ​

默认落在应用的缓存目录下,文件名自动生成。如果想指定位置,传 outputPath。 无论哪种方式,文件都属于你 —— SDK 从不删除它。如果会反复合成,请自行清理 目录。

传入已存在的 outputPath 会怎样? ​

合成会以 OUTPUT_EXISTS 失败。请先删除文件,或让 SDK 生成新名字。同一个路径传 两次不会静默覆盖。

有流式接口吗? ​

没有。本 Beta 没有,近期路线图里也没有。

能用在裸 React Native(不用 Expo)上吗? ​

不能。本 Beta 明确针对 Expo SDK 57。裸 React Native 支持不在本次发布范围内。

怎么反馈问题? ​

请附上错误 code、TtsError.details 内容、设备与系统版本、以及 model id。 这些信息通常足以复现。