# MusicGen Melody

## 概述

MusicGen Melody 模型由 Jade Copet、Felix Kreuk、Itai Gat、Tal Remez、David Kant、Gabriel Synnaeve、Yossi Adi 和 Alexandre Défossez 在 [Simple and Controllable Music Generation](https://huggingface.co/papers/2306.05284) 中提出。

MusicGen Melody 是一个单阶段自回归 Transformer 模型，能够根据文本描述或音频提示生成高质量的音乐样本。文本描述会经过一个冻结的文本编码器模型，以获取一系列隐藏状态表示。随后，MusicGen 在这些隐藏状态的条件约束下，被训练以预测离散音频 token，即*音频编码*。接着，这些音频 token 会通过音频压缩模型（例如 EnCodec）进行解码，从而恢复出音频波形。

通过高效的 token 交错模式，MusicGen 无需对文本/音频提示进行自监督语义表示，从而消除了级联多个模型以预测一组 codebook（例如分层预测或上采样）的需求。相反，它能够在单次前向传播中生成所有 codebook。

该论文的摘要如下：

*我们致力于解决条件音乐生成任务。我们提出了 MusicGen，这是一个在多个压缩离散音乐表示流（即 token）上运行的单一语言模型（LM）。与以往的工作不同，MusicGen 由一个单阶段 Transformer LM 和高效的 token 交错模式组成，从而消除了级联多个模型（例如分层或上采样）的需求。基于这种方法，我们展示了 MusicGen 如何生成高质量样本，同时以文本描述或旋律特征作为条件，从而对生成结果进行更好的控制。我们进行了广泛的实证评估，结合自动评估和人工研究，表明所提出的方法在标准的文本到音乐基准上优于所评估的基线方法。通过消融研究，我们阐明了构成 MusicGen 的各个组件的重要性。*

该模型由 [ylacombe](https://huggingface.co/ylacombe) 贡献。原始代码可在[此处](https://github.com/facebookresearch/audiocraft)找到。预训练检查点可在 [Hugging Face Hub](https://huggingface.co/models?sort=downloads&search=facebook%2Fmusicgen) 上找到。

## 与 [MusicGen](./musicgen) 的区别

与 MusicGen 相比，有两个关键区别：

1. 在此处，音频提示用作生成音频样本的条件信号，而在 [MusicGen](./musicgen) 中，它用于音频续写。
2. 与 MusicGen 不同，条件文本和音频信号被拼接到解码器的隐藏状态中，而不是用作交叉注意力信号。

## 生成

MusicGen Melody 兼容两种生成模式：greedy 和 sampling。在实际使用中，sampling 模式的效果显著优于 greedy 模式，因此我们鼓励在可能的情况下使用 sampling 模式。sampling 模式默认启用，也可以在调用 `MusicgenMelodyForConditionalGeneration.generate()` 时通过设置 `do_sample=True` 来显式指定，或者通过覆盖模型的生成配置（见下文）来实现。

Transformers 支持 MusicGen Melody 的单声道（1 通道）和立体声（2 通道）变体。单声道版本生成一组 codebook。立体声版本生成两组 codebook，分别对应每个通道（左/右），每组 codebook 通过音频压缩模型独立解码。随后，将各通道的音频流合并，得到最终的立体声输出。

### 音频条件生成

该模型可以通过使用 [MusicgenMelodyProcessor](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) 对输入进行预处理，基于文本和音频提示生成音频样本。

在以下示例中，我们使用 🤗 Datasets 库加载音频文件，该库可通过以下命令通过 pip 安装：

```bash
pip install --upgrade pip
pip install datasets[audio]
```

我们即将使用的音频文件加载方式如下：

```python
from datasets import load_dataset

dataset = load_dataset("sanchit-gandhi/gtzan", split="train", streaming=True)
sample = next(iter(dataset))["audio"]
```

音频提示音最好不包含鼓和贝斯等乐器通常产生的低频信号。可以使用 [Demucs](https://github.com/adefossez/demucs/tree/main) 模型将人声及其他信号从鼓和贝斯成分中分离出来。

如果您希望使用 Demucs，请先按照[此处](https://github.com/adefossez/demucs/tree/main?tab=readme-ov-file#for-musicians)的步骤完成安装，然后再使用以下代码片段：

```python
import torch
from demucs import pretrained
from demucs.apply import apply_model
from demucs.audio import convert_audio

wav = torch.tensor(sample["array"]).to(torch.float32)

demucs = pretrained.get_model('htdemucs')

wav = convert_audio(wav[None], sample["sampling_rate"], demucs.samplerate, demucs.audio_channels)
wav = apply_model(demucs, wav[None])
```

然后，您可以使用以下代码片段来生成音乐：

```python
from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration

processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

inputs = processor(
    audio=wav,
    sampling_rate=demucs.samplerate,
    text=["80s blues track with groovy saxophone"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)
```

您也可以不使用 Demucs，直接传入音频信号，但生成质量可能会下降：

```python
from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration

processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

inputs = processor(
    audio=sample["array"],
    sampling_rate=sample["sampling_rate"],
    text=["80s blues track with groovy saxophone"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)
```

音频输出是一个形状为 `(batch_size, num_channels, sequence_length)` 的三维 Torch 张量。要收听生成的音频样本，您可以在 ipynb 笔记本中播放它们：

```python
from IPython.display import Audio

sampling_rate = model.config.audio_encoder.sampling_rate
Audio(audio_values[0].numpy(), rate=sampling_rate)
```

或者使用第三方库（例如 `soundfile`）将它们保存为 `.wav` 文件：

```python
import soundfile as sf

sampling_rate = model.config.audio_encoder.sampling_rate
sf.write("musicgen_out.wav", audio_values[0].T.numpy(), sampling_rate)
```

### 仅文本条件生成

相同的 [MusicgenMelodyProcessor](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) 也可以用于预处理纯文本提示。

```python
from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration

processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

inputs = processor(
    text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)
```

`guidance_scale` 用于无分类器引导（CFG），用于设置条件 logits（由文本提示预测）与无条件 logits（由无条件或“空”提示预测）之间的权重。较高的 guidance scale 会促使模型生成与输入提示更紧密相关的样本，但通常以牺牲音频质量为代价。通过设置 `guidance_scale > 1` 即可启用 CFG。为获得最佳效果，请使用 `guidance_scale=3`（默认值）。

您也可以批量生成：

```python

from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration

processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

# take the first quarter of the audio sample
sample_1 = sample["array"][: len(sample["array"]) // 4]

# take the first half of the audio sample
sample_2 = sample["array"][: len(sample["array"]) // 2]

inputs = processor(
    audio=[sample_1, sample_2],
    sampling_rate=sample["sampling_rate"],
    text=["80s blues track with groovy saxophone", "90s rock song with loud guitars and heavy drums"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)
```

### 无条件生成

无条件（或“空”）生成的输入可以通过方法 [MusicgenMelodyProcessor.get_unconditional_inputs()](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor.get_unconditional_inputs) 获取：

```python
from transformers import MusicgenMelodyForConditionalGeneration, MusicgenMelodyProcessor

model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")
unconditional_inputs = MusicgenMelodyProcessor.from_pretrained("facebook/musicgen-melody").get_unconditional_inputs(num_samples=1)

audio_values = model.generate(**unconditional_inputs, do_sample=True, max_new_tokens=256)
```

### 生成配置

控制生成过程的默认参数，例如采样、引导尺度和生成的 token 数量，可以在模型的生成配置中找到，并按需更新：

```python
from transformers import MusicgenMelodyForConditionalGeneration

model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

# inspect the default generation config
model.generation_config

# increase the guidance scale to 4.0
model.generation_config.guidance_scale = 4.0

# decrease the max length to 256 tokens
model.generation_config.max_length = 256
```

请注意，传递给 generate 方法的任何参数都会**覆盖**生成配置中的对应设置，因此在调用 generate 时设置 `do_sample=False` 将覆盖生成配置中 `model.generation_config.do_sample` 的设置。

## 模型结构

MusicGen 模型可以分解为三个不同的阶段：

1. 文本编码器：将文本输入映射为一系列隐藏状态表示。预训练的 MusicGen 模型使用来自 T5 或 Flan-T5 的冻结文本编码器。
2. MusicGen Melody 解码器：一种语言模型（LM），它基于编码器的隐藏状态表示，自回归地生成音频 token（或代码）。
3. 音频解码器：用于从解码器预测的音频 token 中恢复音频波形。

因此，MusicGen 模型既可以作为独立的解码器模型使用，对应类 [MusicgenMelodyForCausalLM](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyForCausalLM)；也可以作为包含文本编码器和音频编码器的复合模型使用，对应类 [MusicgenMelodyForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyForConditionalGeneration)。如果只需从预训练检查点加载解码器，可以先指定正确的配置进行加载，也可以通过复合模型的 `.decoder` 属性进行访问：

```python
from transformers import AutoConfig, MusicgenMelodyForCausalLM, MusicgenMelodyForConditionalGeneration

# Option 1: get decoder config and pass to `.from_pretrained`
decoder_config = AutoConfig.from_pretrained("facebook/musicgen-melody").decoder
decoder = MusicgenMelodyForCausalLM.from_pretrained("facebook/musicgen-melody", **decoder_config.to_dict(), device_map="auto")

# Option 2: load the entire composite model, but only return the decoder
decoder = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto").decoder
```

由于文本编码器和音频编码器模型在训练过程中保持冻结，MusicGen 解码器 [MusicgenMelodyForCausalLM](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyForCausalLM) 可以基于编码器隐藏状态和音频码数据集进行独立训练。在推理阶段，可将训练好的解码器与冻结的文本编码器和音频编码器组合，以恢复完整的 [MusicgenMelodyForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyForConditionalGeneration) 模型。

## 检查点转换

- 从[此处](https://github.com/facebookresearch/audiocraft/blob/main/docs/MUSICGEN.md#importing--exporting-models)下载原始检查点后，您可以使用位于`src/transformers/models/musicgen_melody/convert_musicgen_melody_transformers.py`的**转换脚本**，通过以下命令进行转换：

```bash
python src/transformers/models/musicgen_melody/convert_musicgen_melody_transformers.py \
    --checkpoint="facebook/musicgen-melody" --pytorch_dump_folder /output/path 
```

提示：

* MusicGen 是在 Encodec 的 32kHz 检查点上训练的。您应确保使用兼容版本的 Encodec 模型。
* 采样模式通常比贪心解码能产生更好的效果 - 您可以在调用 `MusicgenMelodyForConditionalGeneration.generate()` 时通过变量 `do_sample` 来切换采样模式

## MusicgenMelodyDecoderConfig[[transformers.MusicgenMelodyDecoderConfig]]

#### transformers.MusicgenMelodyDecoderConfig[[transformers.MusicgenMelodyDecoderConfig]]

```python
transformers.MusicgenMelodyDecoderConfig(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, vocab_size: int = 2048, max_position_embeddings: int = 2048, num_hidden_layers: int = 24, ffn_dim: int = 4096, num_attention_heads: int = 16, layerdrop: float | int = 0.0, use_cache: bool = True, activation_function: str = 'gelu', hidden_size: int = 1024, dropout: float | int = 0.1, attention_dropout: float | int = 0.0, activation_dropout: float | int = 0.0, initializer_factor: float = 0.02, scale_embedding: bool = False, num_codebooks: int = 4, audio_channels: int = 1, pad_token_id: int | None = 2048, bos_token_id: int | None = 2048, eos_token_id: int | list[int] | None = None, tie_word_embeddings: bool = False, is_decoder: bool = False, add_cross_attention: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/configuration_musicgen_melody.py#L28)

**参数：**

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

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

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

ffn_dim (`int`，*可选*，默认为 `4096`)：MLP 表示的维度。

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

layerdrop (`Union[float, int]`，*可选*，默认为 `0.0`)：LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](see https://huggingface.co/papers/1909.11556)。

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

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

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

dropout (`Union[float, int]`，*可选*，默认为 `0.1`)：所有 dropout 层的比率。

attention_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：注意力概率的 dropout 比率。

activation_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：全连接层内部激活值的 dropout 比率。

initializer_factor (`float`，*可选*，默认为 `0.02`)：用于初始化所有权重矩阵的因子（应保留为 1，内部用于初始化测试）。

scale_embedding (`bool`，*可选*，默认为 `False`)：是否通过将嵌入除以 sqrt(d_model) 来对其进行缩放。

num_codebooks (`int`，*可选*，默认为 `4`)：模型使用的并行码本数量。

audio_channels (`int`，*可选*，默认为 1)：模型使用的音频声道数（单声道或立体声）。立体声模型会为左/右输出声道生成独立的音频流。单声道模型生成单个音频流输出。

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

bos_token_id (`int`，*可选*，默认为 `2048`)：词汇表中用于表示流开始的 Token id。

eos_token_id (`Union[int, list[int]]`，*可选*)：词汇表中用于表示流结束（end-of-stream）的 Token ID。

tie_word_embeddings (`bool`，*可选*，默认为 `False`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

is_decoder (`bool`，*可选*，默认为 `False`)：模型是否用作解码器。如果为 `False`，则模型用作编码器。

add_cross_attention (`bool`，*可选*，默认为 `False`)：是否应在模型中添加交叉注意力层。

这是用于存储 MusicgenMelodyModel 配置的类。它根据指定的参数实例化 Musicgen Melody 模型，并定义模型架构。使用默认值实例化配置将得到与 [facebook/musicgen-melody](https://huggingface.co/facebook/musicgen-melody) 类似的配置。

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

## MusicgenMelodyProcessor[[transformers.MusicgenMelodyProcessor]]

#### transformers.MusicgenMelodyProcessor[[transformers.MusicgenMelodyProcessor]]

```python
transformers.MusicgenMelodyProcessor(feature_extractor, tokenizer)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/processing_musicgen_melody.py#L29)

**参数：**

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

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

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

[MusicgenMelodyProcessor](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) 提供了 [MusicgenMelodyFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) 和 [T5Tokenizer](/docs/transformers/v5.23.0/zh/model_doc/t5#transformers.T5Tokenizer) 的所有功能。有关更多信息，请参阅 [~MusicgenMelodyFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) 和 [~T5Tokenizer](/docs/transformers/v5.23.0/zh/model_doc/t5#transformers.T5Tokenizer)。

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

```python
__call__(*args, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/processing_musicgen_melody.py#L37)

**参数：**

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

#### get_unconditional_inputs[[transformers.MusicgenMelodyProcessor.get_unconditional_inputs]]

```python
get_unconditional_inputs(num_samples = 1, return_tensors = 'pt')
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/processing_musicgen_melody.py#L90)

**参数：**

num_samples (int, *可选*) : 无条件生成的音频采样数量。

辅助函数，用于获取无条件生成所需的空输入，使模型可以在不使用特征提取器或分词器的情况下使用。

示例：
```python
>>> from transformers import MusicgenMelodyForConditionalGeneration, MusicgenMelodyProcessor

>>> model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody")

>>> # get the unconditional (or 'null') inputs for the model
>>> processor = MusicgenMelodyProcessor.from_pretrained("facebook/musicgen-melody")
>>> unconditional_inputs = processor.get_unconditional_inputs(num_samples=1)

>>> audio_samples = model.generate(**unconditional_inputs, max_new_tokens=256)
```

## MusicgenMelodyFeatureExtractor[[transformers.MusicgenMelodyFeatureExtractor]]

#### transformers.MusicgenMelodyFeatureExtractor[[transformers.MusicgenMelodyFeatureExtractor]]

```python
transformers.MusicgenMelodyFeatureExtractor(feature_size = 12, sampling_rate = 32000, hop_length = 4096, chunk_length = 30, n_fft = 16384, num_chroma = 12, padding_value = 0.0, return_attention_mask = False, stem_indices = [3, 2], **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/feature_extraction_musicgen_melody.py#L40)

**参数：**

feature_size (`int`，*可选*，默认为 12)：提取特征的维度。

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

hop_length (`int`，*可选*，默认值为 4096)：用于获取梅尔频率系数的 STFT 的重叠窗口长度。

chunk_length (`int`，*可选*，默认为 30)：用于裁剪和填充较长或较短音频序列时，所使用的最大 `sampling_rate` 样本块数。

n_fft (`int`，*可选*，默认为 16384)：傅里叶变换的大小。

num_chroma (`int`，*可选*，默认为 12)：要使用的色度 bin 数量。

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

return_attention_mask (`bool`，*可选*，默认为 `False`)：是否返回注意力掩码。在调用特征提取器时可以覆盖此设置。[什么是注意力掩码？](../glossary#attention-mask) 对于 Whisper 模型，在进行批量推理时，始终应传入 `attention_mask`，以避免细微的 bug。

stem_indices (`list[int]`，*可选*，默认为 `[3, 2]`)：如果传入 demucs 的输出，则指定要提取的 Stem 通道。

构建 MusicgenMelody 特征提取器。

此特征提取器继承自 [SequenceFeatureExtractor](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)，后者包含了大部分主要方法。有关这些方法的更多信息，请参阅该父类。

此类从经过 [Demucs](https://github.com/adefossez/demucs/tree/main) 处理的音频或直接从原始音频波形中提取色度特征。

## MusicgenMelodyConfig[[transformers.MusicgenMelodyConfig]]

#### transformers.MusicgenMelodyConfig[[transformers.MusicgenMelodyConfig]]

```python
transformers.MusicgenMelodyConfig(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, text_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = None, audio_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = None, decoder: dict | transformers.configuration_utils.PreTrainedConfig | None = None, num_chroma: int = 12, chroma_length: int = 235, initializer_factor: float = 0.02)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/configuration_musicgen_melody.py#L86)

**参数：**

text_encoder (`Union[dict, `PretrainedConfig`]`) : 一个配置对象的实例，用于定义文本编码器的配置。

audio_encoder (`Union[dict, `PretrainedConfig`]`) : 一个配置对象的实例，用于定义音频编码器配置。

decoder (`Union[dict, `PretrainedConfig`]`) : 一个配置对象的实例，用于定义解码器配置。

num_chroma (`int`，*可选*，默认为 12)：要使用的色度 bin 数量。

chroma_length (`int`，*可选*，默认为 235)：当使用音频作为模型条件时，最大色度持续时间。对应于训练期间使用的最大持续时间。

initializer_factor (`float`，*可选*，默认为 `0.02`)：用于初始化所有权重矩阵的因子（应保留为 1，内部用于初始化测试）。

这是用于存储 MusicgenMelodyModel 配置的类。它根据指定的参数实例化 Musicgen Melody 模型，并定义模型架构。使用默认值实例化配置将得到与 [facebook/musicgen-melody](https://huggingface.co/facebook/musicgen-melody) 类似的配置。

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

示例：

```python
>>> from transformers import (
...     MusicgenMelodyConfig,
...     MusicgenMelodyDecoderConfig,
...     T5Config,
...     EncodecConfig,
...     MusicgenMelodyForConditionalGeneration,
... )

>>> # Initializing text encoder, audio encoder, and decoder model configurations
>>> text_encoder_config = T5Config()
>>> audio_encoder_config = EncodecConfig()
>>> decoder_config = MusicgenMelodyDecoderConfig()

>>> configuration = MusicgenMelodyConfig(
...     text_encoder=text_encoder_config, audio_encoder=audio_encoder_config, decoder=decoder_config
... )

>>> # Initializing a MusicgenMelodyForConditionalGeneration (with random weights) from the facebook/musicgen-melody style configuration
>>> model = MusicgenMelodyForConditionalGeneration(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
>>> config_text_encoder = model.config.text_encoder
>>> config_audio_encoder = model.config.audio_encoder
>>> config_decoder = model.config.decoder

>>> # Saving the model, including its configuration
>>> model.save_pretrained("musicgen_melody-model")

>>> # loading model and config from pretrained folder
>>> musicgen_melody_config = MusicgenMelodyConfig.from_pretrained("musicgen_melody-model")
>>> model = MusicgenMelodyForConditionalGeneration.from_pretrained("musicgen_melody-model", config=musicgen_melody_config)
```

## MusicgenMelodyModel[[transformers.MusicgenMelodyModel]]

#### transformers.MusicgenMelodyModel[[transformers.MusicgenMelodyModel]]

```python
transformers.MusicgenMelodyModel(config: MusicgenMelodyDecoderConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L539)

**参数：**

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

未添加任何特定头部的裸 Musicgen Melody 模型，直接输出原始 hidden-states。

该模型继承自 [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.MusicgenMelodyModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_hidden_states: typing.Optional[torch.Tensor] = None, encoder_attention_mask: 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/musicgen_melody/modeling_musicgen_melody.py#L552)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size * num_codebooks, sequence_length)`) : 输入序列标记在词汇表中的索引，对应于音频代码序列。 可以通过使用音频编码器模型（例如 [EncodecModel](/docs/transformers/v5.23.0/zh/model_doc/encodec#transformers.EncodecModel)）对音频提示进行编码以预测音频代码来获取索引。有关详细信息，请参阅 [EncodecModel.encode()](/docs/transformers/v5.23.0/zh/model_doc/encodec#transformers.EncodecModel.encode)。 [什么是输入 ID？](../glossary#input-ids)    在前向传播过程中，`input_ids` 的形状会自动从 `(batch_size * num_codebooks, target_sequence_length)` 转换为 `(batch_size, num_codebooks, target_sequence_length)`。如果您从音频编码模型（例如 [EncodecModel](/docs/transformers/v5.23.0/zh/model_doc/encodec#transformers.EncodecModel)）获取音频代码，请确保帧数等于 1，并在将其作为 `input_ids` 传入之前，将音频代码的形状从 `(frames, batch_size, num_codebooks, target_sequence_length)` 重塑为 `(batch_size * num_codebooks, target_sequence_length)`。

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

encoder_hidden_states (`torch.Tensor`，形状为 `(batch_size, encoder_sequence_length, hidden_size)`，*可选*)：表示文本编码器输出与处理后的音频编码器输出拼接结果的隐藏状态序列。用作条件信号，因此将与投影后的 `decoder_input_ids` 进行拼接。

encoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, encoder_sequence_length)`，*可选*)：用于避免对条件隐藏状态执行注意力机制的掩码。掩码值选自 `[0, 1]`： - 对于**未掩码**的 token，值为 1； - 对于**已掩码**的 token，值为 0。 [什么是注意力掩码？](../glossary#attention-mask)

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`），其包含的元素取决于配置（`None`）和输入。

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

## MusicgenMelodyForCausalLM[[transformers.MusicgenMelodyForCausalLM]]

#### transformers.MusicgenMelodyForCausalLM[[transformers.MusicgenMelodyForCausalLM]]

```python
transformers.MusicgenMelodyForCausalLM(config: MusicgenMelodyDecoderConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L623)

**参数：**

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

带有语言建模头部的 Musicgen Melody 解码器模型。

该模型继承自 [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.MusicgenMelodyForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_hidden_states: typing.Optional[torch.Tensor] = None, encoder_attention_mask: 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, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L651)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size * num_codebooks, sequence_length)`) : 输入序列标记在词汇表中的索引，对应于音频代码序列。 可以通过使用音频编码器模型（例如 [EncodecModel](/docs/transformers/v5.23.0/zh/model_doc/encodec#transformers.EncodecModel)）对音频提示进行编码以预测音频代码来获取索引。有关详细信息，请参阅 [EncodecModel.encode()](/docs/transformers/v5.23.0/zh/model_doc/encodec#transformers.EncodecModel.encode)。 [什么是输入 ID？](../glossary#input-ids)    在前向传播过程中，`input_ids` 的形状会自动从 `(batch_size * num_codebooks, target_sequence_length)` 转换为 `(batch_size, num_codebooks, target_sequence_length)`。如果您从音频编码模型（例如 [EncodecModel](/docs/transformers/v5.23.0/zh/model_doc/encodec#transformers.EncodecModel)）获取音频代码，请确保帧数等于 1，并在将其作为 `input_ids` 传入之前，将音频代码的形状从 `(frames, batch_size, num_codebooks, target_sequence_length)` 重塑为 `(batch_size * num_codebooks, target_sequence_length)`。

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

encoder_hidden_states (`torch.Tensor`，形状为 `(batch_size, encoder_sequence_length, hidden_size)`，*可选*)：表示文本编码器输出与处理后的音频编码器输出拼接结果的隐藏状态序列。用作条件信号，因此将与投影后的 `decoder_input_ids` 进行拼接。

encoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, encoder_sequence_length)`，*可选*)：用于避免对条件隐藏状态执行注意力机制的掩码。掩码值选自 `[0, 1]`： - 对于**未掩码**的 token，值为 1； - 对于**已掩码**的 token，值为 0。 [什么是注意力掩码？](../glossary#attention-mask)

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`）。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length, num_codebooks)`，*可选*) : 用于语言建模的标签。请注意，模型内部会对标签进行**移位**，因此您可以设置 `labels = input_ids`。索引的取值范围为 `[-100, 0, ..., config.vocab_size]`。所有设置为 `-100` 的标签都会被忽略（即被掩码），损失仅针对 `[0, ..., config.vocab_size]` 范围内的标签进行计算。

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

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

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

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 语言建模损失（用于下一个 token 预测）。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **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 后的注意力权重，用于在自注意力头中计算加权平均值。
- **encoder_hidden_states** (`torch.Tensor`，形状为 `(batch_size, encoder_sequence_length, hidden_size)`，*可选*) -- 表示投影后的文本编码器输出与投影后的音频编码器输出拼接而成的条件隐藏状态序列。用作条件信号。

示例：

```python
```

## MusicgenMelodyForConditionalGeneration[[transformers.MusicgenMelodyForConditionalGeneration]]

#### transformers.MusicgenMelodyForConditionalGeneration[[transformers.MusicgenMelodyForConditionalGeneration]]

```python
transformers.MusicgenMelodyForConditionalGeneration(config: MusicgenMelodyConfig = None, text_encoder: transformers.modeling_utils.PreTrainedModel | None = None, audio_encoder: transformers.modeling_utils.PreTrainedModel | None = None, decoder: transformers.models.musicgen_melody.modeling_musicgen_melody.MusicgenMelodyForCausalLM | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L1091)

**参数：**

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

text_encoder (`PreTrainedModel`, *可选*) : 将文本编码为用于条件生成的隐藏状态的文本编码器模型。

audio_encoder (`PreTrainedModel`, *可选*) : 用于将音频编码为隐藏状态以进行条件化的音频编码器模型。

decoder (`MusicgenMelodyForCausalLM`，*可选*)：根据条件信号生成音频标记的解码器模型。

用于基于其他模态（例如图像-文本到文本生成）进行条件控制的 Musicgen Melody 模型的 token 生成。

该模型继承自 [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.MusicgenMelodyForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.BoolTensor] = None, input_features: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, encoder_hidden_states: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L1388)

**参数：**

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)

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

input_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [MusicgenMelodyFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) 获取音频特征。有关详细信息，请参阅 `MusicgenMelodyFeatureExtractor.__call__()`（[MusicgenMelodyProcessor](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) 使用 [MusicgenMelodyFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) 来处理音频）。

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size * num_codebooks, target_sequence_length)`，*可选*) : 解码器输入序列中词元在词汇表中的索引，对应于音频码序列。 可以通过使用音频编码器模型对音频提示进行编码来预测音频码，从而获得这些索引，例如使用 [EncodecModel](/docs/transformers/v5.23.0/zh/model_doc/encodec#transformers.EncodecModel)。有关详细信息，请参阅 [EncodecModel.encode()](/docs/transformers/v5.23.0/zh/model_doc/encodec#transformers.EncodecModel.encode)。 [什么是解码器输入 ID？](../glossary#decoder-input-ids)    在前向传播过程中，`decoder_input_ids` 的形状会自动从 `(batch_size * num_codebooks, target_sequence_length)` 转换为 `(batch_size, num_codebooks, target_sequence_length)`。如果您从音频编码模型（例如 [EncodecModel](/docs/transformers/v5.23.0/zh/model_doc/encodec#transformers.EncodecModel)）获取音频码，请确保帧数等于 1，并在将其作为 `decoder_input_ids` 传入之前，将音频码的形状从 `(frames, batch_size, num_codebooks, target_sequence_length)` 重塑为 `(batch_size * num_codebooks, target_sequence_length)`。

decoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*) : 默认行为：生成一个忽略 `decoder_input_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`。

encoder_hidden_states (`torch.Tensor`，形状为 `(batch_size, encoder_sequence_length, hidden_size)`，*可选*)：表示投影后的文本编码器输出与投影后的音频编码器输出拼接而成的条件隐藏状态序列。它用作条件信号，因此将与投影后的 `decoder_input_ids` 进行拼接。

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

decoder_inputs_embeds (`torch.Tensor`，形状为 `(batch_size, target_sequence_length, hidden_size)`，*可选*)：可选地，您可以选择直接传入嵌入表示，而不是传入 `decoder_input_ids`。如果使用了 `past_key_values`，则只需输入最后一段 `decoder_inputs_embeds`（参见 `past_key_values`）。如果您希望比模型内部的嵌入查找矩阵更精细地控制将 `decoder_input_ids` 索引转换为对应向量的方式，这将非常有用。如果 `decoder_input_ids` 和 `decoder_inputs_embeds` 均未设置，则 `decoder_inputs_embeds` 将取 `inputs_embeds` 的值。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length, num_codebooks)`，*可选*) : 用于语言建模的标签。请注意，模型内部会对标签进行**移位**，因此您可以设置 `labels = input_ids`。索引的取值范围为 `[-100, 0, ..., config.vocab_size]`。所有设置为 `-100` 的标签都会被忽略（即被掩码），损失仅针对 `[0, ..., config.vocab_size]` 范围内的标签进行计算。

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

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

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

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

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 语言建模损失（用于下一个 token 预测）。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **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 后的注意力权重，用于在自注意力头中计算加权平均值。
- **encoder_hidden_states** (`torch.Tensor`，形状为 `(batch_size, encoder_sequence_length, hidden_size)`，*可选*) -- 表示投影后的文本编码器输出与投影后的音频编码器输出拼接而成的条件隐藏状态序列。用作条件信号。

示例：
```python
>>> from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration
>>> import torch

>>> processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
>>> model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody")

>>> inputs = processor(
...     text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
...     padding=True,
...     return_tensors="pt",
... )

>>> pad_token_id = model.generation_config.pad_token_id
>>> decoder_input_ids = (
...     torch.ones((inputs.input_ids.shape[0] * model.decoder.num_codebooks, 1), dtype=torch.long)
...     * pad_token_id
... )

>>> logits = model(**inputs, decoder_input_ids=decoder_input_ids).logits
>>> logits.shape  # (bsz * num_codebooks, encoder_len + tgt_len, vocab_size)
torch.Size([8, 249, 2048])
```

