> ## Documentation Index
> Fetch the complete documentation index at: https://docs.echophrase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义模型

> 导入您自己的 ONNX 语音转文字模型

# 自定义模型 <sup>Pro</sup>

Pro 订阅者可以导入自己的语音转文字模型，取代 Echophrase 内置模型库中的模型。
此功能适合高级用户，例如想使用特定微调模型、小众语言模型，或是尚未收录于
内置模型库中的模型。

<Note>
  这是 Pro 功能。方案比较请参阅[测试版页面](/zh-CN/beta)，内置模型（所有方案皆可使用）
  请参阅[模型选择](/zh-CN/config/models)。
</Note>

## 什么是 ONNX 模型？

[ONNX](https://onnx.ai)（Open Neural Network Exchange）是一种开放、可携的机器
学习模型文件格式，让在某个框架训练的模型能在不同的运行环境中运作 - 在此指的
是 ONNX Runtime，也就是 Echophrase 内置模型所使用的运行引擎。

ONNX 格式的语音转文字模型通常包含以下文件：

* **`model.onnx`** - 模型本身（必要）
* **`model.onnx.data`** - 较大模型的外部权重档（选用，仅在模型以此方式导出时
  才会出现）
* **`tokenizer.json`** 与／或 **`config.json`** - 描述如何将模型的原始输出转换
  为文字的文件（选用，但建议提供 - 若缺少，应用程序会退回尽力解码）

您不需要理解此格式的细节即可使用 - Echophrase 会读取您指定的文件，并在缺少
或损坏时提示您。

<Warning>
  Echophrase v1 中的自定义模型必须为 **ONNX** 格式。目前不支持 safetensors 或
  GGUF 等其他格式的自定义模型。
</Warning>

## 从哪里寻找模型

* **[Hugging Face 模型库](https://huggingface.co/models?pipeline_tag=automatic-speech-recognition\&library=onnx)**
  * 已筛选为 ONNX 格式的自动语音识别模型，是最容易浏览的来源。
* **[ONNX Model Zoo](https://github.com/onnx/models)** - 由 ONNX 社区维护的
  预训练 ONNX 模型精选集。

寻找包含 `.onnx` 文件（最好也附有 `tokenizer.json`）且专为自动语音识别设计
的保存库或下载项目。

## 如何导入模型

打开**设置 > 自定义模型**，选择以下其中一种方式导入模型：

<CardGroup cols={2}>
  <Card title="本机文件" icon="folder-open">
    浏览选择磁盘上的 `.onnx` 文件，或直接拖放至设置窗口中。若模型附有
    `.onnx.data` 权重档、`tokenizer.json` 或 `config.json`，请一并加入
    （或直接拖放整个文件夹）。
  </Card>

  <Card title="Hugging Face 保存库" icon="link">
    粘贴保存库网址或 `org/repo` 名称，例如 `openai/whisper-tiny.en`。
    Echophrase 会直接下载该保存库的文件。该保存库必须**恰好包含一个**
    `.onnx` 文件 - 若有多个，请手动下载您想要的文件并改用本机文件方式导入。
  </Card>
</CardGroup>

导入模型后，Echophrase 会实际在 ONNX Runtime 中加载该模型以确认其为有效、
可加载的 ONNX 模型，接着将副本保存于应用程序的本机缓存中。此验证步骤可拦截
损坏的下载文件，以及根本不是 ONNX 模型的文件 - 但不会评估转录质量。

成功导入的模型会**立即成为你的使用中模型** - 不需要额外的选取步骤。你可以
导入**任意数量的模型**并在它们之间切换：每个已导入的模型都会列在导入窗口和
**设置 > 自定义模型**中，各自有「使用」与「移除」，也可以通过 AI 模型清单的
自定义列打开管理。

<Note>
  在 WSL 上，Windows 文件总管无法将文件拖拽进 WSL 窗口，因此导入窗口会显示
  **浏览**按钮，而不是拖放区。
</Note>

<Note>
  自定义模型有 **8 GB** 的大小限制。
</Note>

## 兼容性规范

由于 Echophrase 无法预先得知每个可能模型的架构，因此所有自定义模型都会通过
单一通用推理流程运行。模型若要产生可用的转录结果，必须：

* 接受**原始 16 kHz 单声道波形**作为输入
* 以张量名称 **`audio/input/mel`** 公开该输入
* 产生 Echophrase 可解码为文字的**文字或词元输出**

若模型不符合此规范，Echophrase 仍会加载并运行它 - 不会崩溃 - 但输出可能是
乱码、空白或不合逻辑。这代表该模型与 Echophrase 的推理流程不兼容，并非应用
程序的错误。若遇到此情况，请确认该模型导出时确实是设计给原始波形输入的语音
识别模型，而非在模型外部计算的梅尔频谱或 log-mel 特征。

## 即将推出：转换模型

第二个自定义模型字段 - 供\*\*转换（Transform）\*\*模型使用，用于后制处理转录文字
（语法修正、自定义改写规则等）- 规划于未来版本推出。目前尚不支持自定义转换模型；
内置版本请参阅[转换模型](/zh-CN/config/settings#transform-model-pro)。

## 安全性须知

自定义模型完全在**您的设备上**通过 ONNX Runtime 运行，与 Echophrase 内置模型
使用的引擎相同 - 自定义模型的任何内容都不会上传或发送至 Echophrase 的服务器。

尽管如此，请留意以下几点：

* **仅导入您信任的模型。** `.onnx` 文件本质上是一个运算图，即使 Echophrase
  已验证其能在 ONNX Runtime 中成功加载，恶意或有问题的文件仍可能在运行时
  出现异常行为。
* **验证仅确认格式，不代表质量。** Echophrase 只会检查文件是否为真实、可
  加载的 ONNX 模型 - 无法验证该模型的训练数据、准确度，或其输出是否可信。
* **优先选择可靠来源。** 具有明确作者、说明与下载次数的 Hugging Face 保存库，
  通常比来路不明的链接或文件更值得信赖。