# Pocket TTS

## 概述

Pocket TTS 是 [Kyutai](https://kyutai.org) 推出的 1 亿参数文本转语音模型，属于一种 [Continuous Audio Language Model](https://huggingface.co/papers/2509.06926)，可在 CPU 上以快于实时的速度运行。该因果 Transformer 通过单步流头（one-step flow head）每帧（12.5 Hz）输出一个连续音频潜在变量，并由语音结束头（end-of-speech head）决定何时停止。

处理器包含 [Pocket TTS 音频分词器](./pocket_tts_audio_tokenizer)，这是一种基于 Mimi 的编解码器，用于对语音提示进行编码，并将生成的潜在变量解码为 24 kHz 音频。预定义的声音以 KV 缓存的形式提供（`voices/`）。

发布了两个 flow heads：Lagrangian 自蒸馏（`flow_type="lsd"`，默认）和 drifting（`flow_type="drifting"`，`english_drifting_26-09`）。支持微调，请参阅 [Training](#training)。

该模型由 [Eustache Le Bihan](https://huggingface.co/eustlb) 贡献。原始代码位于 [kyutai-labs/pocket-tts](https://github.com/kyutai-labs/pocket-tts)。

## 使用技巧

- 使用 [apply_chat_template()](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessorMixin.apply_chat_template) 准备输入（每条文本对应一条 `user` 消息，`add_generation_prompt=True`）。分词器的 normalizer 会按照检查点语言设置，像原始文本一样准备文本。
- `generate` 会返回 `audio_latents` 和 `audio_latents_mask`；请使用 [PocketTTSProcessor.decode()](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor.decode) 对其进行解码。
- `max_new_tokens` 的默认值基于文本长度设定的预算，当语音结束（end-of-speech）的 logit 超过 `eos_threshold` 后不久，生成即停止。
- `do_sample=False` 在温度为 0 时与原始结果一致。在使用采样时，`temperature`（默认值为 0.3）是流起始噪声的方差。
- 使用 [PocketTTSProcessor.split_text()](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor.split_text) 拆分长文本，每个分块对应一段对话。

## 用法

### 语音

语音可以通过三种方式指定。

**1. 克隆录音**：对话中的一个 `audio` 项。

```python
from transformers import AutoModelForTextToWaveform, AutoProcessor

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")

url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/en-Alice_woman.wav"
conversation = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "url": url},
            {"type": "text", "text": "Hello world. I am Kyutai's Pocket TTS."},
        ],
    }
]
inputs = processor.apply_chat_template(
    conversation, tokenize=True, return_dict=True, add_generation_prompt=True
).to(model.device)

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

**2. 预计算潜在变量**：一个空的 `audio` 项，潜在变量通过处理器传入。

```python
from transformers import AutoModelForTextToWaveform, AutoProcessor
from transformers.audio_utils import load_audio

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")

# e.g. a recording encoded once by the processor's audio tokenizer,
# to reuse without re-encoding it
url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/en-Alice_woman.wav"
features = processor.feature_extractor(
    load_audio(url, sampling_rate=24000), sampling_rate=24000
).to(processor.audio_tokenizer.device)
# (num_frames, latent_dim)
voice = processor.audio_tokenizer.encode(**features).latents[0]

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "audio"},
            {"type": "text", "text": "Hello world. I am Kyutai's Pocket TTS."},
        ],
    }
]
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, "latents.wav")
```

**3. 缓存上下文**：语音提示的 KV 缓存，作为 `past_key_values` 传入。附带的语音（`voices/`）使用此形式。

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

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")

voice = load_file(hf_hub_download(model_id, "voices/alba.safetensors"))
layers = []
for i, layer in enumerate(model.model.layers):
    # each layer's cache on that layer's device
    device = layer.self_attn.k_proj.weight.device
    layers.append(
        (voice[f"layers.{i}.keys"].to(device), voice[f"layers.{i}.values"].to(device))
    )
voice_cache = DynamicCache(layers, config=model.config)

conversation = [
    {
        "role": "user",
        "content": [{"type": "text", "text": "Hello world. I am Kyutai's Pocket TTS."}],
    }
]
inputs = processor.apply_chat_template(
    conversation, tokenize=True, return_dict=True, add_generation_prompt=True
).to(model.device)

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

### 批处理与长文本

批量处理多个文本和语音，并将长文本拆分为多个片段：

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

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")

def load_voices(names):
    """The shipped voices, one per conversation, as one cache, left-padded to the
    longest voice, and the mask of their positions.

    `generate` extends the cache: load it for every call.
    """
    voices = [
        load_file(hf_hub_download(model_id, f"voices/{name}.safetensors"))
        for name in names
    ]
    lengths = [voice["layers.0.keys"].shape[2] for voice in voices]
    length = max(lengths)
    layers = []
    for i, layer in enumerate(model.model.layers):
        device = layer.self_attn.k_proj.weight.device
        keys, values = (
            torch.cat(
                [
                    torch.nn.functional.pad(voice[f"layers.{i}.{kind}"], (0, 0, length - n, 0))
                    for voice, n in zip(voices, lengths)
                ]
            ).to(device)
            for kind in ("keys", "values")
        )
        layers.append((keys, values))
    mask = torch.tensor([[0] * (length - n) + [1] * n for n in lengths])
    return DynamicCache(layers, config=model.config), mask

text = (
    "A first sentence that is long enough to be worth splitting. "
    "Then a second one, and a third one for good measure."
)
chunks = processor.split_text(text)
conversations = [
    [{"role": "user", "content": [{"type": "text", "text": chunk}]}]
    for chunk in chunks + ["Hello world"]
]
inputs = processor.apply_chat_template(
    conversations, tokenize=True, return_dict=True, add_generation_prompt=True
).to(model.device)

voice_cache, voice_mask = load_voices(["alba"] * len(chunks) + ["jean"])
# the mask covers the cached voices too
inputs["attention_mask"] = torch.cat(
    [voice_mask.to(inputs["attention_mask"]), inputs["attention_mask"]], dim=-1
)
outputs = model.generate(**inputs, past_key_values=voice_cache)
audio = processor.decode(outputs.audio_latents, outputs.audio_latents_mask)
processor.save_audio(
    [torch.cat(audio[: len(chunks)]), audio[-1]], ["long.wav", "hello.wav"]
)
```

### 漂移检查点

用法相同，使用检查点自身的语音：

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

model_id = "eustlb/pocket-tts-english-drifting"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")

voice = load_file(hf_hub_download(model_id, "voices/alba.safetensors"))
layers = []
for i, layer in enumerate(model.model.layers):
    device = layer.self_attn.k_proj.weight.device
    layers.append(
        (voice[f"layers.{i}.keys"].to(device), voice[f"layers.{i}.values"].to(device))
    )

conversation = [
    {
        "role": "user",
        "content": [{"type": "text", "text": "Hello world. I am Kyutai's Pocket TTS."}],
    }
]
inputs = processor.apply_chat_template(
    conversation, tokenize=True, return_dict=True, add_generation_prompt=True
).to(model.device)

outputs = model.generate(
    **inputs, past_key_values=DynamicCache(layers, config=model.config)
)
audio = processor.decode(outputs.audio_latents, outputs.audio_latents_mask)
processor.save_audio(audio, "drifting.wav")
```

## 训练

将目标音频放在 `assistant` 轮次中。处理器将其潜在变量作为 `labels` 返回，模型返回原始损失（LSD 流损失加上 `config.eos_loss_weight` 倍的语音结束损失）。语音提示通常是同一话语的开头部分。

```python
import torch
from transformers import AutoModelForTextToWaveform, AutoProcessor

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")
model.train()

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": voice_prompt},
            {"type": "text", "text": target_text},
        ],
    },
    {"role": "assistant", "content": [{"type": "audio", "audio": target_audio}]},
]
inputs = processor.apply_chat_template(
    conversation, tokenize=True, return_dict=True
).to(model.device)
loss = model(**inputs).loss
loss.backward()
```

- 以录音或潜在表示的形式提供语音，而不是缓存。
- 对于无分类器引导，请删除 `user` 轮次中的 `audio` 或 `text` 项（原始实现以 0.2 的概率分别删除每一项）。
- 预计算的潜在变量应放入 `processor_kwargs={"audio_prompt_latents": [...], "labels": [...]}` 中，并使用空的 `{"type": "audio"}` 项作为占位符。
- 原始配方：AdamW，`learning_rate=2e-5`（新语言为 2e-4），`adam_beta2=0.95`，`weight_decay=0.1`，`max_grad_norm=1.0`，1000 步预热后保持恒定，权重 EMA（衰减系数 0.999）。

## PocketTTSConfig[[transformers.PocketTTSConfig]]

#### transformers.PocketTTSConfig[[transformers.PocketTTSConfig]]

```python
transformers.PocketTTSConfig(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 = 4004, hidden_size: int = 1024, num_hidden_layers: int = 6, num_attention_heads: int = 16, num_key_value_heads: int | None = None, head_dim: int | None = None, intermediate_size: int = 4096, hidden_act: str = 'gelu_pytorch_tanh', 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 = 4000, audio_latent_token_id: int = 4001, audio_prompt_bos_token_id: int = 4002, audio_bos_token_id: int = 4003, 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)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/configuration_pocket_tts.py#L75)

**参数：**

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

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

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

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

num_attention_heads (`int`，*可选*，默认为 `16`)：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`，*可选*，默认为 `4096`)：MLP 表示的维度。

hidden_act (`str`，*可选*，默认为 `gelu_pytorch_tanh`)：解码器中的非线性激活函数（函数或字符串）。例如，`"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_prompt_latents`、`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`，*可选*，默认值为 4000)：`input_ids` 中语音提示帧的占位符 token id。

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

audio_prompt_bos_token_id (`int`，*可选*，默认值为 4002)：放置在语音提示之前的 Token ID；其嵌入向量是原始模型在语音前添加的学习向量。

audio_bos_token_id (`int`，*可选*，默认值为 4003)：第一个音频位置的 Token ID，用于关闭提示：它保存了学习到的 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)：该移动平均数的衰减率。

这是用于存储 PocketTTSModel 配置的类。它根据指定的参数实例化 Pocket Tts 模型，并定义模型架构。使用默认值实例化配置将生成与 [eustlb/pocket-tts](https://huggingface.co/eustlb/pocket-tts) 类似的配置。

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

## PocketTTSFlowHeadConfig[[transformers.PocketTTSFlowHeadConfig]]

#### transformers.PocketTTSFlowHeadConfig[[transformers.PocketTTSFlowHeadConfig]]

```python
transformers.PocketTTSFlowHeadConfig(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 = 1024, 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/main/src/transformers/models/pocket_tts/configuration_pocket_tts.py#L27)

**参数：**

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

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

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

condition_dim (`int`，*可选*，默认为 1024)：头所依赖的骨干网络隐藏状态的维度（即骨干网络的 `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 的隐藏层数。

这是用于存储 PocketTTSModel 配置的类。它根据指定的参数实例化 Pocket Tts 模型，并定义模型架构。使用默认值实例化配置将生成与 [eustlb/pocket-tts](https://huggingface.co/eustlb/pocket-tts) 类似的配置。

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

## PocketTTSFeatureExtractor[[transformers.PocketTTSFeatureExtractor]]

#### transformers.PocketTTSFeatureExtractor[[transformers.PocketTTSFeatureExtractor]]

```python
transformers.PocketTTSFeatureExtractor(feature_size = 1, sampling_rate = 24000, padding_value = 0.0, frame_size = 1920, pad_to_multiple_of = 1920, end_on_pause = True, pause_duration = 0.08, fade_out_duration = 0.02, silence_floor_db = 35.0, analysis_frame_duration = 0.02, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/feature_extraction_pocket_tts.py#L29)

**参数：**

feature_size (`int`，*可选*，默认为 1)：通道数。

sampling_rate (`int`, *可选*，默认为 24000)：音频波形应被数字化采样的采样率，以赫兹（Hz）为单位。

padding_value (`float`, *可选*, 默认值为 0.0) : 用于填充的值。

frame_size (`int`，*可选*，默认为 1920)：音频分词器每个潜在帧中的音频采样数（即其 `frame_size`）。

pad_to_multiple_of (`int`，*可选*，默认值为 1920)：将音频填充为该值的整数倍；填充为 `frame_size` 的整数倍可确保每个潜在帧完整。

end_on_pause (`bool`，*可选*，默认为 `True`)：是否使每个波形恰好以 `pause_duration` 秒的静音结尾：将截断尾部静音（比最响帧高出 `analysis_frame_duration` 秒且低于 `silence_floor_db` 的帧），对剩余部分的最后 `fade_out_duration` 秒进行淡出处理，并追加 `pause_duration` 秒的零值。

pause_duration (`float`, *可选*，默认为 0.08)：`end_on_pause` 所添加的静音时长，单位为秒。

fade_out_duration (`float`, *可选*，默认为 0.02)：`end_on_pause` 在暂停前应用的淡出持续时间，以秒为单位。

silence_floor_db (`float`, *可选*，默认值为 35.0)：低于最响分析帧的 dB 值，低于此值时 `end_on_pause` 会将尾部帧视为静音。

analysis_frame_duration (`float`, *可选*，默认为 0.02)：`end_on_pause` 所测量的帧持续时长，单位为秒。

构建 Pocket TTS 特征提取器，用于为音频分词器的编码器准备语音提示波形。

每个波形可选地以一段短暂停顿结尾（即原始的`end_on_pause`：训练提示词结束于两个单词之间的停顿内，在语音处停止的提示词会使模型继续生成，而在较长静音处结束的提示词则会延迟起始），随后该批次会在右侧填充至分词器帧大小的整数倍。

#### __调用__[[transformers.PocketTTSFeatureExtractor.__call__]]

```python
__call__(audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']], sampling_rate: int | None = None, end_on_pause: bool | None = None, padding: bool | str | transformers.utils.generic.PaddingStrategy | None = True, pad_to_multiple_of: int | None = None, max_length: int | None = None, return_attention_mask: bool | None = True, return_tensors: str | None = 'pt', **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/feature_extraction_pocket_tts.py#L106)

**参数：**

audio (`np.ndarray`、`torch.Tensor`、`list[np.ndarray]`、`list[torch.Tensor]`)：语音提示的单个单声道波形或单声道波形批次。

sampling_rate (`int`, *可选*) : `audio` 输入的采样率。强烈建议在 forward 调用时传入 `sampling_rate`，以避免静默错误。

end_on_pause (`bool`, *可选*) : 是否在每个波形的末尾添加一个短暂的停顿，请参阅类的文档字符串。默认值为 `self.end_on_pause`。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/main/zh/internal/file_utils#transformers.utils.PaddingStrategy)，*可选*，默认为 `True`)：批次的填充策略，参见 [pad()](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor.pad)。

pad_to_multiple_of (`int`, *可选*) : 将批次填充为该值的倍数。默认值为 `self.pad_to_multiple_of`。

## PocketTTSProcessor[[transformers.PocketTTSProcessor]]

#### transformers.PocketTTSProcessor[[transformers.PocketTTSProcessor]]

```python
transformers.PocketTTSProcessor(feature_extractor, tokenizer, audio_tokenizer = None, chat_template = None, short_text_max_words: int = 4, frames_after_eos_short_text: int = 4, frames_after_eos: int = 2, fade_in_duration: float = 0.005)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/processing_pocket_tts.py#L51)

**参数：**

feature_extractor (`PocketTTSFeatureExtractor`)：特征提取器是必需的输入。

tokenizer (`TokenizersBackend`)：分词器是必需的输入。

audio_tokenizer (`PocketTTSAudioTokenizerModel`，*可选*)：编解码器：它将音频编码为潜在表示，并将生成的潜在表示解码为音频。

chat_template (`str`) : 一个 Jinja 模板，用于将聊天中的消息列表转换为可分词的字符串。

short_text_max_words (`int`，*可选*，默认为 4)：长度不超过该词数的文本，在语音结束帧之后会追加 `frames_after_eos_short_text` 帧。

frames_after_eos_short_text (`int`，*可选*，默认为 4)：对于短文本，在语音结束帧之后生成的帧数。

frames_after_eos (`int`，*可选*，默认为 2)：在语音结束帧之后生成的帧数，用于处理较长的文本。

fade_in_duration (`float`, *可选*，默认为 0.005)：应用于每个解码波形开头的线性淡入持续时间（以秒为单位）：新的解码器状态会以一个小步长开始，听起来像是一个咔哒声。

构建一个 PocketTTSProcessor，它将特征提取器和分词器封装为单个处理器。

[PocketTTSProcessor](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor) 提供了 [PocketTTSFeatureExtractor](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSFeatureExtractor) 和 [TokenizersBackend](/docs/transformers/main/zh/main_classes/tokenizer#transformers.TokenizersBackend) 的所有功能。有关更多信息，请参阅 [~PocketTTSFeatureExtractor](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSFeatureExtractor) 和 [~TokenizersBackend](/docs/transformers/main/zh/main_classes/tokenizer#transformers.TokenizersBackend)。

#### __调用__[[transformers.PocketTTSProcessor.__call__]]

```python
__call__(text: str | list[str] | None = None, audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None, audio_prompt_latents: list[torch.Tensor] | None = None, labels: list[torch.Tensor] | None = None, **kwargs: *<class 'transformers.models.pocket_tts.processing_pocket_tts.PocketTTSProcessorKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/processing_pocket_tts.py#L109)

**参数：**

text (`str` 或 `list[str]`) : 由 [apply_chat_template()](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessorMixin.apply_chat_template) 渲染的提示词。

audio (`np.ndarray`、`torch.Tensor` 或它们的列表，*可选*)：对话的波形，单声道，采样率为 24 kHz，按对话顺序排列：每个语音，以及在训练中的每个目标。

audio_prompt_latents (`list[torch.Tensor]`, *可选*) : 预计算的语音，每个语音占位符对应一个 `(num_frames, latent_dim)` 张量，而非波形。

labels (`list[torch.Tensor]`, *可选*) : 预计算的目标（训练），每个目标占位符对应一个 `(num_frames, latent_dim)` 张量，而非波形。

end_on_pause (`bool`, *kwargs*, *可选*) : 是否在每个语音提示波形的末尾添加一个短暂的停顿，就像原始实现在克隆语音之前所做的那样。默认值为特征提取器的 `end_on_pause`。

return_tensors (`str` 或 [TensorType](/docs/transformers/main/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

- ****kwargs** ([ProcessingKwargs](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessingKwargs), *可选*) : 针对每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

**返回值：**

包含 `input_ids`、`attention_mask`、`audio_prompt_latents` 和 `audio_prompt_latents_mask` 的 [BatchFeature](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.BatchFeature)；用于生成的 `frames_after_eos`（在语音结束帧之后生成的帧数，按文本长度计算），以及用于训练的 `labels` 和 `labels_mask`。

#### split_text[[transformers.PocketTTSProcessor.split_text]]

```python
split_text(text: str, max_tokens: int = 50)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/processing_pocket_tts.py#L285)

**参数：**

text (`str`) : 要拆分的文本。

max_tokens (`int`，*可选*，默认为 50)：每个块的最大 token 数。

将 `text` 拆分为最多包含 `max_tokens` 个 token 的按句子对齐的块，与原始的 `split_into_best_sentences` 行为一致：预处理后的文本在句子末尾处截断（而非在小数点处截断），对于在子句末尾处仍超过 `max_tokens` 的句子进行截断，然后贪心地对这些片段进行分组。每个块旨在作为批次中的一个对话。

#### decode[[transformers.PocketTTSProcessor.decode]]

```python
decode(audio_latents: torch.Tensor, audio_latents_mask: torch.Tensor | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/processing_pocket_tts.py#L343)

**参数：**

audio_latents （形状为 `(batch_size, num_frames, latent_dim)` 或 `(num_frames, latent_dim)` 的 `torch.Tensor`）：`generate` 返回的潜变量（`PocketTTSGenerateOutput.audio_latents`），解码为一个批次，或单个样本的潜变量。

audio_latents_mask (`torch.Tensor`，形状为 `(batch_size, num_frames)`，*可选*)：每个样本帧的掩码（`PocketTTSGenerateOutput.audio_latents_mask`）。若未提供，则每行均以完整长度进行解码。

**返回值：**

`list[torch.Tensor]`，包含位于 CPU 上的 1D 波形，每行一个，或对应单个样本潜变量的一个波形。

使用音频分词器将生成的潜在变量解码为波形，并像原始实现一样，对每个波形的开头 `fade_in_duration` 秒进行淡入处理。

#### save_audio[[transformers.PocketTTSProcessor.save_audio]]

```python
save_audio(audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']], saving_path: str | pathlib.Path | list[str | pathlib.Path], sampling_rate: int | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/processing_pocket_tts.py#L392)

将生成的波形写入 WAV 文件。

audio (`torch.Tensor`、`np.ndarray` 或它们的列表)：波形，即 [decode()](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor.decode) 的返回值。saving_path (`str`、`Path` 或它们的列表)：每个波形对应一个路径。sampling_rate (`int`，*可选*)：波形的采样率，默认为特征提取器（即音频分词器）的采样率。

## PocketTTSModel[[transformers.PocketTTSModel]]

#### transformers.PocketTTSModel[[transformers.PocketTTSModel]]

```python
transformers.PocketTTSModel(config: PocketTTSConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/modeling_pocket_tts.py#L498)

**参数：**

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

Pocket TTS 骨干网络：一个因果 Transformer，作用于由语音提示、文本 token 和音频潜在变量组成的单一序列，并返回归一化后的隐藏状态。语音提示和音频潜在变量均为音频分词器的潜在变量，由处理器持有。

该模型继承自 [PreTrainedModel](/docs/transformers/main/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.PocketTTSModel.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/main/src/transformers/models/pocket_tts/modeling_pocket_tts.py#L518)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/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/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/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/main/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 或 `tuple(torch.Tensor)`

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

[PocketTTSModel](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSModel) 的 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/main/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 后的注意力权重，用于在自注意力头中计算加权平均值。

## PocketTTSForConditionalGeneration[[transformers.PocketTTSForConditionalGeneration]]

#### transformers.PocketTTSForConditionalGeneration[[transformers.PocketTTSForConditionalGeneration]]

```python
transformers.PocketTTSForConditionalGeneration(config: PocketTTSConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/modeling_pocket_tts.py#L672)

**参数：**

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

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

该模型继承自 [PreTrainedModel](/docs/transformers/main/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.PocketTTSForConditionalGeneration.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/main/src/transformers/models/pocket_tts/modeling_pocket_tts.py#L702)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/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/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/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`）。

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

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

[PocketTTSForConditionalGeneration](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSForConditionalGeneration) 的 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/main/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, PocketTTSForConditionalGeneration

>>> model = PocketTTSForConditionalGeneration.from_pretrained("eustlb/pocket-tts")

>>> processor = AutoProcessor.from_pretrained("eustlb/pocket-tts")
>>> inputs = processor(text="Hello, my dog is cute", return_tensors="pt")

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

#### generate[[transformers.PocketTTSForConditionalGeneration.generate]]

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

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

**参数：**

inputs (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*) : 由 [PocketTTSProcessor](/docs/transformers/main/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/main/zh/model_doc/pocket_tts#transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput)：包含填充后的 `audio_latents` 及其 `audio_latents_mask`，[PocketTTSProcessor.decode()](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor.decode) 会将它们作为一个批次进行解码。否则，返回生成的潜变量列表，每个样本对应一个 `(num_frames, latent_dim)` 张量，并分别进行解码。

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

#### sample_latent[[transformers.PocketTTSForConditionalGeneration.sample_latent]]

```python
sample_latent(condition: Tensor, noise: Tensor, num_flow_steps: int)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/modeling_pocket_tts.py#L807)

**参数：**

condition (`torch.Tensor`，形状为 `(batch_size, hidden_size)`)：正在生成的位置的 Backbone 隐藏状态。

noise (`torch.Tensor`，形状为 `(batch_size, latent_dim)`)：按 `sqrt(temperature)` 缩放的 Gaussian 噪声，或零。

num_flow_steps (`int`) : LSD 采样器的欧拉步数（drifting head 会忽略此参数，因为它只调用一次）。

**返回：** 形状为 `(batch_size, latent_dim)` 的 `torch.Tensor`

在归一化空间中的采样潜在变量。

使用 flow head 从 `noise` 中采样下一个潜在变量。

#### denormalize_latents[[transformers.PocketTTSForConditionalGeneration.denormalize_latents]]

```python
denormalize_latents(audio_latents: Tensor)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/pocket_tts/modeling_pocket_tts.py#L854)

将流头归一化空间中的潜在变量映射到音频分词器的空间。

## PocketTTSGenerateOutput[[transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput]]

#### transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput[[transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput]]

```python
transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput(sequences: LongTensor, scores: tuple[torch.Tensor] | None = None, logits: tuple[torch.Tensor] | None = None, attentions: tuple[tuple[torch.Tensor]] | None = None, hidden_states: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, audio_latents: typing.Optional[torch.Tensor] = None, audio_latents_mask: typing.Optional[torch.LongTensor] = None)
```

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

**参数：**

sequences (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`)：提示词 token id，后接每个生成帧对应的一个 `audio_latent_token_id`。音频本身位于 `audio_latents` 中。

scores (`tuple(torch.Tensor)` *可选*，当 `output_scores=True` 时返回) : 每个生成帧的语音结束 logit，每帧一个形状为 `(batch_size,)` 的张量。

logits (`tuple(torch.Tensor)` *可选*，当 `output_logits=True` 时返回) : 与 `scores` 相同：Pocket TTS 没有词汇表，因此两者之间没有需要处理的内容。

attentions (`tuple(tuple(torch.Tensor))`，*可选*，当 `output_attentions=True` 时返回)：一个元组（每个生成的帧对应一个元素），其中每个元素又是一个元组（每一层对应一个元素），包含形状为 `(batch_size, num_heads, generated_length, sequence_length)` 的 `torch.Tensor`。

hidden_states (`tuple(tuple(torch.Tensor))`，*可选*，当 `output_hidden_states=True` 时返回)：一个元组（每个生成的帧对应一个元素），其中每个元素又是一个元组（每一层对应一个元素），包含形状为 `(batch_size, generated_length, hidden_size)` 的 `torch.Tensor`。

past_key_values (`Cache`，*可选*，当 `use_cache=True` 时返回)：生成结束时骨干网络的键/值缓存。

audio_latents （形状为 `(batch_size, num_frames, latent_dim)` 的 `torch.Tensor`）：生成的潜在变量，位于音频分词器的潜在空间中，在每个样本自身的帧之后用零进行右填充。[PocketTTSProcessor.decode()](/docs/transformers/main/zh/model_doc/pocket_tts#transformers.PocketTTSProcessor.decode) 会将它们转换为波形。

audio_latents_mask (`torch.LongTensor`，形状为 `(batch_size, num_frames)`)：每个样本帧的掩码（`1`），包含语音结束帧及其后的帧，与填充（`0`）相对。

`PocketTTSForConditionalGeneration.generate` 的输出。