# Gradium Phonon TTS

## 概述

Gradium Phonon TTS 是 [Gradium](https://gradium.ai) 的端侧文本转语音模型系列，采用 [Pocket TTS](./pocket_tts) 的训练方案：一个因果 Transformer 读取语音提示和文本，然后通过单步流头在每一步以 12.5 Hz 的频率输出一个连续的 32 维音频潜在变量，并由语音结束头决定语句何时结束。这些潜在变量由处理器持有的 [Pocket TTS audio tokenizer](./pocket_tts_audio_tokenizer) 解码为 24 kHz 音频，该处理器即 Pocket TTS 的 [PocketTTSProcessor](/docs/transformers/v5.23.0/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor)。

它与 Pocket TTS 在语音条件化方面有所不同：语音提示由一个独立的说话人编解码器生成的 512 维潜在向量构成，并且一个学习得到的说话人向量会被添加到每个音频潜在向量的位置上。由于该说话人编解码器并未公开，语音以预计算的潜在向量形式提供（包括每个检查点的 `default-voice.safetensors` 以及 [gradium/phonon-voices](https://huggingface.co/gradium/phonon-voices) 中的语音目录），并且音频分词器仅包含解码器：因此无法从录音中克隆语音。

| 检查点 | 参数 | 语言 | 许可证 |
|---|---|---|---|
| [gradium/phonon-31m-en](https://huggingface.co/gradium/phonon-31m-en) | 31M | 英语 | Apache 2.0 |
| [gradium/phonon-40m-en](https://huggingface.co/gradium/phonon-40m-en) | 40M | 英语 | CC BY-NC 4.0 |
| [gradium/phonon-40m-fr](https://huggingface.co/gradium/phonon-40m-fr) | 40M | 法语 | CC BY-NC 4.0 |
| [gradium/phonon-40m-de](https://huggingface.co/gradium/phonon-40m-de) | 40M | 德语 | CC BY-NC 4.0 |
| [gradium/phonon-40m-es](https://huggingface.co/gradium/phonon-40m-es) | 40M | 西班牙语 | CC BY-NC 4.0 |
| [gradium/phonon-40m-pt](https://huggingface.co/gradium/phonon-40m-pt) | 40M | 葡萄牙语 | CC BY-NC 4.0 |
| [gradium/phonon-40m-multilingual](https://huggingface.co/gradium/phonon-40m-multilingual) | 40M | 英语、法语、德语、西班牙语、葡萄牙语 | CC BY-NC 4.0 |

它们的加载方式都相同：切换检查点意味着更改仓库 ID。

该模型由 [Eustache Le Bihan](https://huggingface.co/eustlb) 贡献。原始代码为 [gradium-ai/xn-ptts](https://github.com/gradium-ai/xn-ptts)。

## 使用技巧

- 使用 [apply_chat_template()](/docs/transformers/v5.23.0/zh/main_classes/processors#transformers.ProcessorMixin.apply_chat_template) 准备输入：每段文本对应一条 `user` 消息，在语音所在位置放置一个空的 `{"type": "audio"}` 项，通过 `processor_kwargs={"audio_prompt_latents": [...]}` 传入语音潜变量，并设置 `add_generation_prompt=True`。
- 分词器不会将数字、金额、符号或地址展开拼写，请参阅[文本规范化](#text-normalization)。
- `generate` 会返回 `audio_latents` 和 `audio_latents_mask`；请使用 [PocketTTSProcessor.decode()](/docs/transformers/v5.23.0/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor.decode) 对其进行解码。
- 像 Gradium 的运行时那样生成样本：`temperature` 为 0.3（即流起始噪声的方差），并且在语音结束 logit 超过 `eos_threshold` 后不久停止。`do_sample=False` 表示从零噪声开始流。
- 模型以 bf16 加载，即其权重存储的数据类型；在 CPU 上请传入 `dtype=torch.float32`，以匹配 Gradium 在该环境下的运行时。
- 使用 [PocketTTSProcessor.split_text()](/docs/transformers/v5.23.0/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor.split_text) 拆分长文本，每个分块对应一段对话。

## 用法

### 语音

声音是一个潜变量张量，形状为 `(num_frames, 512)`。每个检查点附带一个默认声音（`default-voice.safetensors`），而 [gradium/phonon-voices](https://huggingface.co/gradium/phonon-voices) 中还有约一百个其他声音，覆盖各种语言，每个声音都有对应的声音 ID（`voices.jsonl` 列出了它们的名称、语言和描述）。任何声音都可以与任何检查点配合使用。

```python
import torch
from huggingface_hub import hf_hub_download
from safetensors.torch import load_file
from transformers import AutoProcessor, GradiumPhononTTSForConditionalGeneration

model_id = "gradium/phonon-31m-en"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = GradiumPhononTTSForConditionalGeneration.from_pretrained(model_id, device_map="auto")

def load_voice(voice_id):
    """A voice of gradium/phonon-voices, as latents of shape (num_frames, 512)."""
    path = hf_hub_download("gradium/phonon-voices", f"voices/{voice_id}.safetensors")
    return load_file(path)["speaker_wavs"][0].T.float()

# Easton (en-us); the checkpoint's own voice: hf_hub_download(model_id, "default-voice.safetensors")
voice = load_voice("LMDIYE0Oa377Qh6Z")
# an empty `audio` item marks the voice
conversation = [
    {"role": "user", "content": [{"type": "audio"}, {"type": "text", "text": "Hello from Phonon."}]}
]
inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    return_dict=True,
    add_generation_prompt=True,
    processor_kwargs={"audio_prompt_latents": [voice]},
).to(model.device)

outputs = model.generate(**inputs)
audio = processor.decode(outputs.audio_latents, outputs.audio_latents_mask)
processor.save_audio(audio, "phonon.wav")
```

### 批处理与长文本

批量处理多段文本，每段文本使用各自的声音，并将长文本拆分为多个片段：

```python
text = (
    "Phonon is a small text-to-speech model that runs on your device. "
    "Long texts are split into sentences, and each chunk is one conversation of the batch."
)
chunks = processor.split_text(text)
texts = chunks + ["And this one is said by another voice."]
voices = [load_voice("LMDIYE0Oa377Qh6Z")] * len(chunks) + [load_voice("NbpkqMVS3CJeq2j8")]
conversations = [
    [{"role": "user", "content": [{"type": "audio"}, {"type": "text", "text": text}]}] for text in texts
]
inputs = processor.apply_chat_template(
    conversations,
    tokenize=True,
    return_dict=True,
    add_generation_prompt=True,
    processor_kwargs={"audio_prompt_latents": voices},
).to(model.device)

outputs = model.generate(**inputs)
audio = processor.decode(outputs.audio_latents, outputs.audio_latents_mask)
processor.save_audio([torch.cat(audio[: len(chunks)]), audio[-1]], ["long.wav", "other.wav"])
```

### 文本规范化

分词器会规范化与语言无关的部分，正如 Gradium 的运行时所做的那样：

| 文本 | 分词器 |
|---|---|
| `“Hello” — it’s here…` | `"Hello" it's here.` |
| `hello (world); see you 🚀` | `Hello, world, see you.` |

它不会拼写出数字、数量、符号或地址，因为这些内容取决于所使用的语言：

| 文本 | 分词器 | Gradium 的运行时 |
|---|---|---|
| `It costs $1,234.56.` | `It costs $1,234.56.` | `It costs 1 thousand 234 dollars and 56 cents.` |
| `Write to jean@gradium.ai` | `Write to jean@gradium.ai.` | `Write to jean at gradium dot A-I.` |
| `It is 21°C` | `It is 21°C.` | `It is 21 degrees Celsius.` |

对于这类情况，请使用 Gradium 运行时的文本规范化功能 [ptts](https://github.com/gradium-ai/xn-ptts)，或者将它们完整拼写出来。

## GradiumPhononTTSConfig[[transformers.GradiumPhononTTSConfig]]

#### transformers.GradiumPhononTTSConfig[[transformers.GradiumPhononTTSConfig]]

```python
transformers.GradiumPhononTTSConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, flow_head_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, vocab_size: int = 4001, hidden_size: int = 768, num_hidden_layers: int = 6, num_attention_heads: int = 12, num_key_value_heads: int | None = None, head_dim: int | None = None, intermediate_size: int = 3072, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-05, attention_bias: bool = False, attention_dropout: float = 0.0, max_position_embeddings: int = 8192, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, latent_dim: int = 32, pad_token_id: int = 3, bos_token_id: int | None = None, eos_token_id: int | None = None, audio_prompt_token_id: int = 5, audio_latent_token_id: int = 6, audio_bos_token_id: int = 4, frame_rate: float = 12.5, initializer_range: float = 0.02, use_cache: bool = True, eos_loss_weight: float = 0.1, flow_loss_num_samples: int = 4, lsd_distill_probability: float = 0.25, lsd_diagonal_weight: float = 0.75, lsd_time_logit_mean: float = 0.4, lsd_time_logit_std: float = 1.0, latent_stats_ema_steps: int = 1000, latent_stats_ema_decay: float = 0.999, audio_prompt_dim: int = 512, num_speakers: int = 1, num_speakers_vocab_size: int = 32, num_speakers_embedding_dim: int = 16, duration_delta: float = 0.0, duration_delta_embedding_dim: int = 128, duration_delta_scale: float = 1000.0, duration_delta_max_period: float = 10000.0)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gradium_phonon_tts/configuration_gradium_phonon_tts.py#L82)

**参数：**

flow_head_config (`Union[GradiumPhononTTSFlowHeadConfig, dict]`, *可选*) : 用于从骨干网络隐藏状态中采样每个潜在变量的 flow head 配置。

vocab_size (`int`，*可选*，默认为 `4001`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。

hidden_size (`int`，*可选*，默认为 `768`)：隐藏表示的维度。

num_hidden_layers (`int`，*可选*，默认为 `6`)：Transformer 解码器中的隐藏层数。

num_attention_heads (`int`，*可选*，默认为 `12`)：Transformer 解码器中每个注意力层的注意力头数量。

num_key_value_heads (`int`, *可选*) : 这是用于实现分组查询注意力（Grouped Query Attention）的键值头数量。如果 `num_key_value_heads=num_attention_heads`，模型将使用多头注意力（MHA）；如果 `num_key_value_heads=1`，模型将使用多查询注意力（MQA）；否则将使用 GQA。在将多头检查点转换为 GQA 检查点时，每个组的键和值头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 [这篇论文](https://huggingface.co/papers/2305.13245)。如果未指定，则默认为 `num_attention_heads`。

head_dim (`int`, *可选*) : 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads

intermediate_size (`int`，*可选*，默认值为 `3072`)：MLP 表示的维度。

hidden_act (`str`，*可选*，默认为 `gelu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

layer_norm_eps (`float`, *可选*，默认为 1e-05)：骨干网络中层归一化的 Epsilon 值。

attention_bias (`bool`，*可选*，默认为 `False`)：在自注意力机制中，是否在查询、键、值和输出投影层中使用偏置。

attention_dropout (`float`, *可选*, 默认为 `0.0`) : 注意力概率的 dropout 比率。

max_position_embeddings (`int`，*可选*，默认为 `8192`)：该模型可能使用的最大序列长度。

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *可选*) : 包含 RoPE 嵌入配置参数的字典。该字典应包含 `rope_theta` 的值，并且如果希望使用更长的 `max_position_embeddings` 配合 RoPE，则可选地包含用于缩放的参数。

latent_dim (`int`，*可选*，默认为 32)：骨干网络接收的音频潜变量（`audio_latents`）的维度；等于 flow head 和音频 tokenizer 的 `latent_dim`。

pad_token_id (`int`，*可选*，默认为 `3`)：词表中用于填充的 Token id。

bos_token_id (`int`, *可选*) : 词表中用于表示流开始的 Token id。

eos_token_id (`int`, *可选*) : 词汇表中用于表示流结束（end-of-stream）的 Token id。

audio_prompt_token_id (`int`，*可选*，默认为 5)：`input_ids` 中语音提示帧的占位符 token id（`<|audio_prompt|>`）。

audio_latent_token_id (`int`, *可选*, 默认为 6) : `input_ids` 中音频潜在位置的占位符 token id (`<|audio_latent|>`)。

audio_bos_token_id (`int`，*可选*，默认为 4)：第一个音频位置的 Token ID，用于关闭提示：它包含学习到的 BOS 潜在向量，首帧即由此生成（`<|audio_bos|>`）。

frame_rate (`float`, *可选*，默认为 12.5)：每秒音频的音频潜在变量数量：`generate` 会基于此推导其默认的帧预算。

initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。

eos_loss_weight (`float`, *可选*，默认为 0.1)：训练损失中语音结束损失的权重。

flow_loss_num_samples (`int`，*可选*，默认为 4)：流损失中每个目标帧的噪声采样次数。

lsd_distill_probability (`float`, *可选*，默认为 0.25)：每个训练步骤中计算 LSD 损失自蒸馏项的概率（经过重新加权以保持期望损失不变）；设为 1 表示在每个步骤都计算该项。

lsd_diagonal_weight (`float`, *可选*，默认为 0.75)：LSD 损失中对角线（瞬时流）项的权重；自蒸馏项负责其余部分。

lsd_time_logit_mean (`float`, *可选*，默认为 0.4) : LSD 损失所采样的流时长的对数正态分布均值。

lsd_time_logit_std (`float`, *可选*，默认为 1.0)：LSD 损失所采样的流时长的 logit-normal 分布的标准差。

latent_stats_ema_steps (`int`, *可选*，默认为 1000)：在最初多少个训练步骤中，`latent_mean` 和 `latent_std` 遵循目标潜变量的指数移动平均；设为 0 则保持它们冻结。

latent_stats_ema_decay (`float`, *可选*，默认为 0.999)：该移动平均数的衰减率。

audio_prompt_dim (`int`，*可选*，默认值为 512)：语音提示潜在变量（`audio_prompt_latents`）的维度，即 Gradium 说话人编解码器（Mimi 编码器，而非音频分词器）的非量化潜在变量，骨干网络会将其投影到 `hidden_size`。

num_speakers (`int`，*可选*，默认为 1)：`num_speakers` 条件的值：其查找表中添加到每个音频潜在位置的一行。

num_speakers_vocab_size (`int`，*可选*，默认为 32)：`num_speakers` 查找表的行数。

num_speakers_embedding_dim (`int`，*可选*，默认为 16)：`num_speakers` 查找表的宽度，投影到 `hidden_size`。

duration_delta (`float`，*可选*，默认值为 0.0)：`duration_delta` 条件的值，以正弦方式嵌入并添加到每个音频潜在位置。

duration_delta_embedding_dim (`int`，*可选*，默认为 128)：`duration_delta` 的正弦嵌入大小，投影到 `hidden_size`。

duration_delta_scale (`float`，*可选*，默认值为 1000.0)：在计算 `duration_delta` 的正弦嵌入之前，应用于该值的系数。

duration_delta_max_period (`float`，*可选*，默认值为 10000.0)：`duration_delta` 的正弦嵌入的最大周期。

这是用于存储 GradiumPhononTTSModel 配置的类。它根据指定的参数实例化 Gradium Phonon Tts 模型，并定义模型架构。使用默认值实例化配置将得到与 [gradium/phonon-31m-en](https://huggingface.co/gradium/phonon-31m-en) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## GradiumPhononTTSFlowHeadConfig[[transformers.GradiumPhononTTSFlowHeadConfig]]

#### transformers.GradiumPhononTTSFlowHeadConfig[[transformers.GradiumPhononTTSFlowHeadConfig]]

```python
transformers.GradiumPhononTTSFlowHeadConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 512, num_hidden_layers: int = 6, latent_dim: int = 32, condition_dim: int = 768, frequency_embedding_size: int = 256, hidden_act: str = 'silu', layer_norm_eps: float = 1e-06, rms_norm_eps: float = 1e-05, max_period: float = 10000.0, flow_type: typing.Literal['lsd', 'drifting'] = 'lsd', loss_weighting_hidden_size: int = 32, loss_weighting_num_layers: int = 3)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gradium_phonon_tts/configuration_gradium_phonon_tts.py#L33)

**参数：**

hidden_size (`int`，*可选*，默认为 `512`)：隐藏表示的维度。

num_hidden_layers (`int`，*可选*，默认为 `6`)：Transformer 解码器中的隐藏层数。

latent_dim (`int`，*可选*，默认为 32)：头部所预测的连续音频潜变量的维度（即音频分词器的潜变量维度）。

condition_dim (`int`，*可选*，默认值为 768)：头所依赖的骨干网络隐藏状态的维度（即骨干网络的 `hidden_size`）。

frequency_embedding_size (`int`，*可选*，默认为 256)：流时间的正弦嵌入大小。

hidden_act (`str`，*可选*，默认为 `silu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

layer_norm_eps (`float`, *可选*，默认为 1e-06)：残差块内部及最终层中层归一化的 Epsilon 值。

rms_norm_eps (`float`, *可选*, 默认值为 1e-05) : 用于关闭时间嵌入的归一化的 Epsilon 值。

max_period (`float`, *可选*，默认为 10000.0)：正弦时间嵌入的最大周期，检查点将其存储为 `freqs`。

flow_type (`str`, *可选*，默认为 `"lsd"`) : 训练该头时使用的目标，它决定了该头的条件设置和采样方式。 `"lsd"`（拉格朗日自蒸馏）：以流步骤的起始时间和结束时间为条件，从高斯噪声中通过欧拉步进行采样。 `"drifting"`：无时间条件，该头在一次调用中将噪声映射到潜在变量。

loss_weighting_hidden_size (`int`，*可选*，默认为 32)：用于从 LSD 损失项的流时间中学习其不确定性权重的 MLP 的宽度（仅用于训练）。

loss_weighting_num_layers (`int`，*可选*，默认为 3)：该 MLP 的隐藏层数。

这是用于存储 GradiumPhononTTSModel 配置的类。它根据指定的参数实例化 Gradium Phonon Tts 模型，并定义模型架构。使用默认值实例化配置将得到与 [gradium/phonon-31m-en](https://huggingface.co/gradium/phonon-31m-en) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## GradiumPhononTTSModel[[transformers.GradiumPhononTTSModel]]

#### transformers.GradiumPhononTTSModel[[transformers.GradiumPhononTTSModel]]

```python
transformers.GradiumPhononTTSModel(config: GradiumPhononTTSConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gradium_phonon_tts/modeling_gradium_phonon_tts.py#L393)

**参数：**

config ([GradiumPhononTTSConfig](/docs/transformers/v5.23.0/zh/model_doc/gradium_phonon_tts#transformers.GradiumPhononTTSConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

Gradium Phonon TTS 骨干网络：一个因果 Transformer，作用于由语音提示（说话人-编解码器潜在变量）、文本标记和音频潜在变量组成的单一数据流，并返回归一化后的隐藏状态。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.GradiumPhononTTSModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, audio_prompt_latents: typing.Optional[torch.Tensor] = None, audio_prompt_latents_mask: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, audio_latents_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gradium_phonon_tts/modeling_gradium_phonon_tts.py#L417)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

audio_prompt_latents (`torch.Tensor`，形状为 `(batch_size, num_prompt_frames, latent_dim)`，*可选*)：音频分词器的语音提示潜在表示（由处理器编码，或来自检查点的 `voices/`），右侧填充至批次中最长的语音，并散布到 `audio_prompt_token_id` 位置。

audio_prompt_latents_mask (`torch.Tensor`，形状为 `(batch_size, num_prompt_frames)`，*可选*)：`audio_prompt_latents` 中语音帧（`1`）与填充（`0`）的掩码。

audio_latents (`torch.Tensor`，形状为 `(batch_size, num_latents, latent_dim)`，*可选*)：归一化的音频潜变量，分散放置在 `audio_latent_token_id` 位置。它们之前的 `audio_bos_token_id` 位置用于结束提示并生成第一帧，始终获得学习到的 BOS 潜变量。

audio_latents_mask (`torch.Tensor`，形状为 `(batch_size, num_latents)`，*可选*) : 当各行包含不同数量的潜在位置（训练时）时，`audio_latents` 中每行潜在值的掩码（`1`）与填充（`0`）。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

**返回：** [BaseModelOutputWithPast](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 或 `tuple(torch.Tensor)`

一个 [BaseModelOutputWithPast](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[GradiumPhononTTSConfig](/docs/transformers/v5.23.0/zh/model_doc/gradium_phonon_tts#transformers.GradiumPhononTTSConfig)）和输入。

[GradiumPhononTTSModel](/docs/transformers/v5.23.0/zh/model_doc/gradium_phonon_tts#transformers.GradiumPhononTTSModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。

  如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列的最后一个隐藏状态。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块中的键和值，以及如果 `config.is_encoder_decoder=True` 则还包括交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

## GradiumPhononTTSForConditionalGeneration[[transformers.GradiumPhononTTSForConditionalGeneration]]

#### transformers.GradiumPhononTTSForConditionalGeneration[[transformers.GradiumPhononTTSForConditionalGeneration]]

```python
transformers.GradiumPhononTTSForConditionalGeneration(config: GradiumPhononTTSConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gradium_phonon_tts/modeling_gradium_phonon_tts.py#L693)

**参数：**

config ([GradiumPhononTTSConfig](/docs/transformers/v5.23.0/zh/model_doc/gradium_phonon_tts#transformers.GradiumPhononTTSConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

Gradium Phonon TTS 文本转语音模型：包括骨干网络、每步采样一个音频潜变量的流头以及语音结束头。它生成音频分词器潜变量，处理器将其解码为 24 kHz 音频。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.GradiumPhononTTSForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, audio_prompt_latents: typing.Optional[torch.Tensor] = None, audio_prompt_latents_mask: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, labels_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gradium_phonon_tts/modeling_gradium_phonon_tts.py#L725)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

audio_prompt_latents (`torch.Tensor`，形状为 `(batch_size, num_prompt_frames, latent_dim)`，*可选*)：音频分词器的语音提示潜在表示，右侧填充，并分散到 `audio_prompt_token_id` 位置。

audio_prompt_latents_mask (`torch.Tensor`，形状为 `(batch_size, num_prompt_frames)`，*可选*)：`audio_prompt_latents` 中语音帧（`1`）与填充（`0`）的掩码。

audio_latents (`torch.Tensor`，形状为 `(batch_size, num_latents, latent_dim)`，*可选*)：归一化的音频潜变量，分散到 `audio_latent_token_id` 位置。

labels (`torch.Tensor`，形状为 `(batch_size, num_frames, latent_dim)`，*可选*) : 音频分词器的目标潜在表示（用于训练），右侧填充。每一行的提示以 `audio_bos_token_id` 位置结尾，随后每个帧对应一个 `audio_latent_token_id` 位置：模型输入归一化后的目标（教师强制），对 BOS 及除最后一帧之外的所有帧的输出应用流损失，这些输出用于预测各帧；并对所有帧应用语音结束损失，其中最后一帧即为语音结束。

labels_mask (`torch.Tensor`，形状为 `(batch_size, num_frames)`，*可选*) : `labels` 中每行目标帧（`1`）与填充（`0`）的掩码。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

**返回：** `GradiumPhononTTSOutputWithPast` 或 `tuple(torch.Tensor)`

`GradiumPhononTTSOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[GradiumPhononTTSConfig](/docs/transformers/v5.23.0/zh/model_doc/gradium_phonon_tts#transformers.GradiumPhononTTSConfig)）和输入。

[GradiumPhononTTSForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/gradium_phonon_tts#transformers.GradiumPhononTTSForConditionalGeneration) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `()`，*可选*，在传入 `labels` 时返回) -- 训练损失：目标潜变量的 LSD 流损失加上 `config.eos_loss_weight` 倍的语音结束损失。
- **logits**（形状为 `(batch_size, sequence_length, 1)` 的 `torch.Tensor`）-- 语音结束 logits，每个位置一个。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。
- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 骨干网络的归一化隐藏状态，用于条件化流头。

示例：

```python
>>> from transformers import AutoProcessor, GradiumPhononTTSForConditionalGeneration

>>> model = GradiumPhononTTSForConditionalGeneration.from_pretrained("gradium/phonon-31m-en")

>>> processor = AutoProcessor.from_pretrained("gradium/phonon-31m-en")
>>> inputs = processor(text="Hello, my dog is cute", return_tensors="pt")

>>> # generate speech
>>> speech = model(inputs["input_ids"])
```

#### generate[[transformers.GradiumPhononTTSForConditionalGeneration.generate]]

```python
generate(inputs: typing.Optional[torch.Tensor] = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/pocket_tts/generation_pocket_tts.py#L122)

**参数：**

inputs (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*) : 由 [PocketTTSProcessor](/docs/transformers/v5.23.0/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor) 准备好的 `input_ids`。也可以作为 `input_ids=` 传入。

kwargs (`dict[str, Any]`, *可选*) : `attention_mask`，语音提示（`audio_prompt_latents` 和 `audio_prompt_latents_mask`，或作为语音前缀缓存的 `past_key_values`，即随附的语音，仅包含文本提示），来自处理器的 `frames_after_eos`，生成参数（`do_sample`、`temperature`、`max_new_tokens` 等），以及 Pocket TTS 特有的 `num_flow_steps`、`eos_threshold` 和 `min_frames_before_eos`，这些参数默认取自生成配置。

**返回值：**

当 `return_dict_in_generate=True`（检查点的生成配置）时，返回 [PocketTTSGenerateOutput](/docs/transformers/v5.23.0/zh/model_doc/pocket_tts#transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput)：包含填充后的 `audio_latents` 及其 `audio_latents_mask`，[PocketTTSProcessor.decode()](/docs/transformers/v5.23.0/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor.decode) 会将它们作为一个批次进行解码。否则，返回生成的潜变量列表，每个样本对应一个 `(num_frames, latent_dim)` 张量，并分别进行解码。

生成语音。此方法重写 [generate()](/docs/transformers/v5.23.0/zh/main_classes/text_generation#transformers.GenerationMixin.generate)，将 `max_new_tokens` 的默认值设为原始运行时的帧预算，即针对批次中最长的文本，取 `ceil((num_text_tokens / 3 + 2) * frame_rate)`。其余部分均通过常规生成钩子处理。

