# Muse Spark 开放

## 概述

Muse Spark Open 是由 Meta 开发的多模态混合专家（MoE）模型，支持文本、图像、音频和视频作为输入，并生成文本。该模型总参数量为 8160 亿，每个 token 激活 420 亿参数，支持跨所有输入模态共享的上下文窗口，最大可达 1,048,576 个 token。该模型针对智能体编码任务进行了训练，包括多文件代码编辑、调试和工具使用。

语言主干由 62 个 transformer 层组成，每一层将 token 路由到 256 个专家中的 8 个。它采用分组查询注意力（grouped-query attention），并包含查询-键归一化、注意力输出门控与归一化，以及可学习的残差门控。共享的感知编码器用于处理图像和视频帧，而卷积音频编码器则以每秒 12.5 个 token 的速率生成音频表示。Muse Spark Open 与 [Muse Glimmer](./muse_glimmer) 共享其分词器和词表，并对聊天模板进行了扩展以支持多模态输入。检查点提供 BF16 和 [NVFP4 格式](#nvfp4-weights)。

   

## 资源

- [Hugging Face 合集](https://huggingface.co/collections/meta-models/muse-spark-open)
- [Hugging Face 博客](http://hf.co/blog/meta-muse-spark-open)
- [使用 TRL 进行后训练](https://github.com/huggingface/trl/tree/main/examples/sft_muse_spark_open)

```python
import os

from transformers import AutoModelForMultimodalLM, AutoProcessor, DistributedConfig

distributed_config = DistributedConfig(
    tp_size=int(os.environ["WORLD_SIZE"]), # Number of devices across which the dense layers are sharded
    ep_size=int(os.environ["WORLD_SIZE"]), # Number of devices across which the experts are distributed
)

processor = AutoProcessor.from_pretrained("meta-models/Muse-Spark-Open-816B-A42B")
model = AutoModelForMultimodalLM.from_pretrained(
    "meta-models/Muse-Spark-Open-816B-A42B",
    distributed_config=distributed_config,
)

messages = [
    {"role": "user", "content": "Explain in one sentence why the sky is usually blue."},
]
inputs = processor.apply_chat_template(
    messages,
    reasoning_effort="low",  # default: xhigh, options: low/medium/high/xhigh
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device).to(model.dtype)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=512)
print(processor.decode(outputs[0][input_len:], skip_special_tokens=False))
#  to=self<|message|>Explain in one sentence why the sky is usually blue.
# ...
# <|eom|><|start|>assistant to=user<|message|>The sky is usually blue because molecules in Earth's atmosphere scatter shorter-wavelength blue sunlight in all directions much more strongly than longer-wavelength red light.<|eot|>
```

```python
import os

from transformers import AutoModelForMultimodalLM, AutoProcessor, DistributedConfig

distributed_config = DistributedConfig(
    tp_size=int(os.environ["WORLD_SIZE"]),
    ep_size=int(os.environ["WORLD_SIZE"]),
)

processor = AutoProcessor.from_pretrained("meta-models/Muse-Spark-Open-816B-A42B")
model = AutoModelForMultimodalLM.from_pretrained(
    "meta-models/Muse-Spark-Open-816B-A42B",
    distributed_config=distributed_config,
)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
            {"type": "text", "text": "What is shown in this image?"},
        ],
    },
]
inputs = processor.apply_chat_template(
    messages,
    reasoning_effort="medium", # default: xhigh, options: low/medium/high/xhigh
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device).to(model.dtype)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=512)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)
print(response)
#  to=self<|message|>What is shown in this image?
# ...
# <|eom|><|start|>assistant to=user<|message|>The image shows a **Pallas's cat — also known as a manul, *Otocolobus manul*** — walking through snow.
#
# It is a small, stocky wild cat recognizable by:
#
# * **Its extremely dense, long, greyish-brown winter coat** with faint dark stripes and a dusting of snow on its back
# * **Its flat, broad face** with low-set ears, a short muzzle, and dark stripes on the cheeks
# * **Its short legs and thick, plump body** adapted for cold climates
#
# The cat is captured mid-stride on a snow-covered surface, with one front paw lifted. In the background are white birch tree trunks with black markings and a chain-link fence on the left, indicating the animal is in a zoo or wildlife enclosure in winter.<|eot|>
```

```python
import os

from transformers import AutoModelForMultimodalLM, AutoProcessor, DistributedConfig

distributed_config = DistributedConfig(
    tp_size=int(os.environ["WORLD_SIZE"]),
    ep_size=int(os.environ["WORLD_SIZE"]),
)

processor = AutoProcessor.from_pretrained("meta-models/Muse-Spark-Open-816B-A42B")
model = AutoModelForMultimodalLM.from_pretrained(
    "meta-models/Muse-Spark-Open-816B-A42B",
    distributed_config=distributed_config,
)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "video", "url": "https://huggingface.co/datasets/hf-internal-testing/fixtures_videos/resolve/main/tennis.mp4"},
            {"type": "text", "text": "What is happening in this video?"},
        ],
    },
]
inputs = processor.apply_chat_template(
    messages,
    reasoning_effort="medium",  # default: xhigh, options: low/medium/high/xhigh
    processor_kwargs={
        "fps": 2,   # default: 2, number of frames sampled per second
        "num_frames": 8, # default: 94, maximum number of frames sampled from the video
    },
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device).to(model.dtype)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=512)
print(processor.decode(outputs[0][input_len:], skip_special_tokens=False))
#  to=self<|message|>What is happening in this video?
# ...
# <|eom|><|start|>assistant to=user<|message|>In this video two people are playing tennis on an indoor court.
#
# The shot is taken from behind one of the players - a man in a white t-shirt, black shorts and white shoes and socks. He is standing near the baseline on an orange hard court with white lines, in a ready position with his knees bent and his racket held in front of him.
#
# Across the net, on the far side of the court, is his opponent, also dressed in light-colored clothing.
#
# The sequence shows a short rally:
#
# *   The opponent hits the ball over the net.
# *   The man in the foreground shuffles to his left, turns his body, and prepares for a shot.
# *   He executes a two-handed backhand, swinging the racket across his body and following through as he hits the ball back over the net.
#
# The setting is a large indoor tennis hall with a high, arched ceiling with exposed wooden beams and overhead fluorescent lights. The court is surrounded by a grey run-off area, green windscreening on the walls, and netting that separates it from adjacent courts. On the right side you can see an umpire's chair and a few yellow and black benches. An "Adobe Stock" watermark is visible in the center of the frame.<|eot|>
```

```python
import os

from transformers import AutoModelForMultimodalLM, AutoProcessor, DistributedConfig

distributed_config = DistributedConfig(
    tp_size=int(os.environ["WORLD_SIZE"]),
    ep_size=int(os.environ["WORLD_SIZE"]),
)

processor = AutoProcessor.from_pretrained("meta-models/Muse-Spark-Open-816B-A42B")
model = AutoModelForMultimodalLM.from_pretrained(
    "meta-models/Muse-Spark-Open-816B-A42B",
    distributed_config=distributed_config,
)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "url": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/glass_breaking.mp3"},
            {"type": "text", "text": "What is said in this recording?"},
        ],
    },
]
inputs = processor.apply_chat_template(
    messages,
    reasoning_effort="low", # default: xhigh, options: low/medium/high/xhigh
    processor_kwargs={"sampling_rate": 24000},  # sampling rate the model was trained with
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
).to(model.device).to(model.dtype)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=512)
print(processor.decode(outputs[0][input_len:], skip_special_tokens=False))
#  to=self<|message|>We need to respond to user request: "What is said in this recording?"
# ...
# <|eom|><|start|>assistant to=user<|message|>In the recording the person says:
#
# > "Just picked up this glass and the people at the store told me that if I dropped it it wouldn't break."
#
# Then the glass is dropped and shatters.<|eot|>
```

## NVFP4 权重

NVFP4 [量化权重](https://huggingface.co/meta-models/Muse-Spark-Open-816B-A42B-NVFP4) 具有更低的内存需求，可在 hub 上获取。该模型可以在任何支持 NVFP4 的设备上加载，且无需修改代码。量化配置会在加载时自动应用。

> [!IMPORTANT]
> 要支持 NVFP4，必须从[此分支](https://github.com/huggingface/transformers/pull/49015)安装 transformers。
>
> ```bash
> pip install git+https://github.com/huggingface/transformers.git@finegrained-per-scheme-demo
> ```

```python
import os

from transformers import AutoModelForMultimodalLM, AutoProcessor, DistributedConfig

distributed_config = DistributedConfig(
    tp_size=int(os.environ["WORLD_SIZE"]),
    ep_size=int(os.environ["WORLD_SIZE"]),
)

processor = AutoProcessor.from_pretrained("meta-models/Muse-Spark-Open-816B-A42B-NVFP4")
model = AutoModelForMultimodalLM.from_pretrained(
    "meta-models/Muse-Spark-Open-816B-A42B-NVFP4",
    distributed_config=distributed_config,
)

# ...
```

## MuseSparkConfig[[transformers.MuseSparkConfig]]

#### transformers.MuseSparkConfig[[transformers.MuseSparkConfig]]

```python
transformers.MuseSparkConfig(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_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, image_token_id: int = 200092, video_token_id: int = 200091, out_hidden_size: int = 6144, projector_hidden_size: int = 4096, projector_hidden_act: str = 'gelu', audio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, audio_token_id: int = 200038)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/configuration_muse_spark.py#L251)

**参数：**

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：文本骨干网络的配置对象或字典。

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：视觉骨干网络的配置对象或字典。

image_token_id (`int`, *可选*, 默认为 `200092`) : 用作输入图像占位符的图像标记索引。

video_token_id (`int`，*可选*，默认为 `200091`)：用作输入视频占位符的视频 token 索引。

out_hidden_size (`int`，*可选*，默认值为 6144)：视觉编码器在 patch 合并后的输出维度（多模态投影的输入宽度）。

projector_hidden_size (`int`，*可选*，默认为 4096)：多模态投影的中间维度。

projector_hidden_act (`str`，*可选*，默认为 `gelu`)：多模态投影器所使用的激活函数。

audio_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：音频骨干网络的配置对象或字典。

audio_token_id (`int`，*可选*，默认为 `200038`)：用作输入音频占位符的音频 token 索引。

这是用于存储 MuseSparkModel 配置的类。它根据指定的参数实例化 Muse Spark 模型，并定义模型架构。使用默认值实例化配置将生成与 [meta-models/Muse-Spark-Open-816B-A42B](https://huggingface.co/meta-models/Muse-Spark-Open-816B-A42B) 类似的配置。

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

示例：

```python
>>> from transformers import MuseSparkForConditionalGeneration, MuseSparkConfig

>>> # Initializing an MuseSpark style configuration
>>> configuration = MuseSparkConfig()

>>> # Initializing a model from the configuration
>>> model = MuseSparkForConditionalGeneration(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## MuseSparkTextConfig[[transformers.MuseSparkTextConfig]]

#### transformers.MuseSparkTextConfig[[transformers.MuseSparkTextConfig]]

```python
transformers.MuseSparkTextConfig(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 = 202048, hidden_size: int = 8192, intermediate_size: int = 16384, num_hidden_layers: int = 62, num_attention_heads: int = 128, num_key_value_heads: int = 16, head_dim: int = 64, max_position_embeddings: int = 1048576, initializer_range: float = 0.02, rms_norm_eps: float = 1e-05, use_cache: bool = True, pad_token_id: int | None = None, eos_token_id: int | list[int] | None = 200001, bos_token_id: int | None = 200000, tie_word_embeddings: bool = False, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, attention_bias: bool = False, attention_dropout: int | float | None = 0.0, sliding_window: int | None = 2048, layer_types: list[str] | None = None, final_logit_softcapping: float = 20.0, qk_scale_factor: float = 5.4730064863875, output_multiplier: float = 0.1767766952966369, post_norm_eps: float = 1e-08, layer_rope_theta: list[float | int] | None = None, hidden_act: str = 'silu', moe_intermediate_size: int = 4096, num_local_experts: int = 256, num_experts_per_tok: int = 8, routed_scaling_factor: float = 1.0, moe_hidden_size: int = 4096, mlp_layer_types: list[str] | None = None, residual_gate_temperature: float = 0.3, output_router_logits: bool = False)
```

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

**参数：**

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

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

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

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

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

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

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

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

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

rms_norm_eps (`float`，*可选*，默认值为 `1e-05`)：rms 归一化层中使用的 epsilon。

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

pad_token_id (`int`, *可选*) : 词表中用于填充的 Token id。

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

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

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

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

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

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

sliding_window (`int`, *可选*，默认为 `2048`)：滑动窗口注意力机制的窗口大小。如果为 `None`，则不应用滑动窗口。

layer_types (`list[str]`，*可选*)：一个列表，用于显式地将每个层索引与其层类型进行映射。如果未提供，将根据配置值自动生成。

final_logit_softcapping (`float`, *可选*，默认为 `20.0`) : 在计算概率分布之前应用于最终 logits 的软上限值。Logits 会通过 `tanh(logit / cap) * cap` 进行缩放。

qk_scale_factor (`float`, *可选*，默认值为 5.4730064863875)：在应用无缩放 QK-norm 之后，对 Q 施加的乘数，叠加在标准的 `1/sqrt(head_dim)` 注意力缩放之上。

output_multiplier (`float`, *可选*，默认值为 0.1767766952966369) : 在最终 tanh softcap 之前应用于 logits 的缩放系数。对于发布的检查点，其值等于 `1/sqrt(hidden_size / 256)`。

post_norm_eps (`float`, *可选*，默认为 1e-8)：用于注意力后和 FFN 后归一化（位于子层输出与残差之间）的 Epsilon。

layer_rope_theta (`list[float]`, *可选*) : 每层的 RoPE 基础 theta；`0` 表示禁用该层的旋转位置编码（NoPE）。覆盖全局的 `rope_parameters["rope_theta"]`。默认情况下，除从最后一层向前数的每第 4 层外，所有层均使用全局 theta，这些层为 NoPE。

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

moe_intermediate_size (`int`，*可选*，默认为 `4096`)：路由专家 MLP 的中间层大小。

num_local_experts (`int`, *可选*, 默认为 `256`) : 每个设备上的本地专家数量。`num_experts` 应能被 `num_local_experts` 整除。

num_experts_per_tok (`int`，*可选*，默认为 `8`)：每个 token 路由到的专家数量。这是 token 选择路由的 top-k 值。

routed_scaling_factor (`float`，*可选*，默认值为 `1.0`)：缩放因子或路由专家。

moe_hidden_size (`int`，*可选*，默认为 4096)：MoE 块在路由专家之前将 `hidden_size` 池化（pool）到该宽度，并在之后从该宽度反池化（unpool）。专家完全在此宽度下运行。

mlp_layer_types (`list[str]`, *可选*) : 每层 MLP 类型 — `"dense"` 或 `"sparse"`。长度必须等于 `num_hidden_layers`。默认为全部稀疏。

residual_gate_temperature (`float`, *可选*，默认为 0.3) : 在 sigmoid 之前应用于残差门控参数的温度。

output_router_logits (`bool`，*可选*，默认为 `False`)：是否由模型返回路由器 logits。启用此选项后，模型还将输出辅助损失，包括负载均衡损失和路由器 z-loss。

这是用于存储 MuseSparkModel 配置的类。它根据指定的参数实例化 Muse Spark 模型，并定义模型架构。使用默认值实例化配置将生成与 [meta-models/Muse-Spark-Open-816B-A42B](https://huggingface.co/meta-models/Muse-Spark-Open-816B-A42B) 类似的配置。

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

## MuseSparkVisionConfig[[transformers.MuseSparkVisionConfig]]

#### transformers.MuseSparkVisionConfig[[transformers.MuseSparkVisionConfig]]

```python
transformers.MuseSparkVisionConfig(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, patch_size: int = 14, pos_emb_height: int = 32, pos_emb_width: int = 32, num_attention_heads: int = 16, num_hidden_layers: int = 50, hidden_size: int = 1536, intermediate_size: int = 8960, hidden_act: str = 'gelu', rope_parameters: dict | None = None, patch_temporal: int = 2, merge_size: int = 2, max_position_embeddings: int = 1024, layer_norm_eps: float = 1e-05, layer_types: list[str] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/configuration_muse_spark.py#L31)

**参数：**

patch_size (`int`，*可选*，默认为 `14`)：每个 patch 的大小（分辨率）。

pos_emb_height (`int`, *可选*) : 初始位置嵌入高度。

pos_emb_width (`int`, *可选*) : 初始位置嵌入宽度。

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

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

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

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

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

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

patch_temporal (`int`, *可选*) : 用于嵌入输入的时间补丁大小。

merge_size (`tuple[int] | list[int]`，*可选*)：用于合并补丁的核大小。

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

layer_norm_eps (`float`，*可选*，默认为 `1e-05`)：层归一化层所使用的 epsilon。

layer_types (`list[str]`，*可选*)：一个列表，用于显式地将每个层索引与其层类型进行映射。如果未提供，将根据配置值自动生成。

这是用于存储 MuseSparkModel 配置的类。它根据指定的参数实例化 Muse Spark 模型，并定义模型架构。使用默认值实例化配置将生成与 [meta-models/Muse-Spark-Open-816B-A42B](https://huggingface.co/meta-models/Muse-Spark-Open-816B-A42B) 类似的配置。

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

## MuseSparkAudioConfig[[transformers.MuseSparkAudioConfig]]

#### transformers.MuseSparkAudioConfig[[transformers.MuseSparkAudioConfig]]

```python
transformers.MuseSparkAudioConfig(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, patch_sizes: list[int] | tuple[int, ...] = (16, 6, 5, 4), hidden_sizes: list[int] | tuple[int, ...] = (256, 512, 1024, 2048), depths: list[int] | tuple[int, ...] = (2, 2, 2, 2), num_hidden_layers: int = 4, mlp_ratio: float = 4.0, conv_kernel_size: int = 7, hidden_act: str = 'gelu', rms_norm_eps: float = 1e-06, out_hidden_size: int = 8192, initializer_range: float = 0.02)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/configuration_muse_spark.py#L192)

**参数：**

patch_sizes (`list[int] | tuple[int, ...]`，*可选*，默认为 `(16, 6, 5, 4)`)：每个阶段的 patch embedding 所应用的时间下采样因子。它们的乘积表示被合并为一个输出 token 的波形样本数量。

hidden_sizes (`list[int] | tuple[int, ...]`，*可选*，默认为 `(256, 512, 1024, 2048)`)：每个阶段的隐藏层宽度。

depths (`list[int] | tuple[int, ...]`，*可选*，默认为 `(2, 2, 2, 2)`)：每层中卷积块的数量。

num_hidden_layers (`int`, *optional*, 默认为 4) : `MuseSparkAudioLayer` 的数量，即金字塔中的分辨率层数。该参数与 `len(hidden_sizes)` 冗余，并会与其进行校验，因此自定义金字塔时必须同时设置两者。

mlp_ratio (`float`, *可选*, 默认值为 4.0) : 层中 MLP 中间宽度与其隐藏宽度之比。

conv_kernel_size (`int`，*可选*，默认为 7)：深度因果卷积的核大小。

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

rms_norm_eps (`float`，*可选*，默认为 `1e-06`)：rms 归一化层使用的 epsilon。

out_hidden_size (`int`，*可选*，默认为 8192)：最终投影映射到的宽度，即文本模型的隐藏层大小。

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

这是用于存储 MuseSparkModel 配置的类。它根据指定的参数实例化 Muse Spark 模型，并定义模型架构。使用默认值实例化配置将生成与 [meta-models/Muse-Spark-Open-816B-A42B](https://huggingface.co/meta-models/Muse-Spark-Open-816B-A42B) 类似的配置。

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

示例：

```python
>>> from transformers import MuseSparkAudioConfig, MuseSparkAudioModel

>>> configuration = MuseSparkAudioConfig()
>>> model = MuseSparkAudioModel(configuration)
>>> configuration = model.config
```

## MuseSparkFeatureExtractor[[transformers.MuseSparkFeatureExtractor]]

#### transformers.MuseSparkFeatureExtractor[[transformers.MuseSparkFeatureExtractor]]

```python
transformers.MuseSparkFeatureExtractor(feature_size = 1, sampling_rate = 24000, padding_value = 0.0, samples_per_token = 1920, return_attention_mask = True, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/feature_extraction_muse_spark.py#L28)

**参数：**

feature_size (`int`，*可选*，默认为 1)：提取特征的维度。Muse Spark Open 采用单声道音频。

sampling_rate (`int`, *optional*, 默认为 24000) : 音频的预期采样率，单位为赫兹。任何其他采样率的音频在到达此类之前都必须进行重采样。

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

samples_per_token (`int`, *可选*，默认为 1920)：编码器将波形采样折叠为一个嵌入的样本数——即音频配置中 `patch_sizes` 的乘积（16 * 6 * 5 * 4）。批次会被填充到该值的整数倍。

return_attention_mask (`bool`，*可选*，默认为 `True`)：是否让 `__call__()` 返回 `input_values_mask`。音频塔是完全卷积的，不使用该掩码；默认关闭。

构建 Muse Spark Open 特征提取器。

Muse Spark Opens 的音频塔直接处理原始波形——没有频谱图前端——因此它仅执行批处理、填充以及（可选的）截断。它唯一一项不那么直观的任务是将每个批次填充到 `samples_per_token` 的整数倍：编码器会将恰好该数量的样本压缩为一个嵌入，否则将抛出异常。

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

## MuseSparkProcessor[[transformers.MuseSparkProcessor]]

#### transformers.MuseSparkProcessor[[transformers.MuseSparkProcessor]]

```python
transformers.MuseSparkProcessor(image_processor = None, video_processor = None, tokenizer = None, feature_extractor = None, chat_template = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/processing_muse_spark.py#L28)

**参数：**

image_processor (`MuseGlimmerImageProcessor`)：图像处理器是必需的输入。

video_processor (`MuseGlimmerVideoProcessor`)：视频处理器是必需的输入。

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

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

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

构造一个 MuseSparkProcessor，它将图像处理器、视频处理器、分词器和特征提取器封装为单一处理器。

[MuseSparkProcessor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkProcessor) 提供了 [MuseGlimmerImageProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerImageProcessor)、[MuseGlimmerVideoProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerVideoProcessor)、`tokenizer_class` 和 [MuseSparkFeatureExtractor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkFeatureExtractor) 的所有功能。有关更多信息，请参阅 [~MuseGlimmerImageProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerImageProcessor)、[~MuseGlimmerVideoProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerVideoProcessor)、`~tokenizer_class` 和 [~MuseSparkFeatureExtractor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkFeatureExtractor)。

## MuseSparkPreTrainedModel[[transformers.MuseSparkPreTrainedModel]]

#### transformers.MuseSparkPreTrainedModel[[transformers.MuseSparkPreTrainedModel]]

```python
transformers.MuseSparkPreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L494)

**参数：**

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

该模型继承自 [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 文档。

## MuseSparkTextModel[[transformers.MuseSparkTextModel]]

#### transformers.MuseSparkTextModel[[transformers.MuseSparkTextModel]]

```python
transformers.MuseSparkTextModel(config: MuseSparkTextConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L590)

**参数：**

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

未添加任何特定头部的裸 Muse Spark Text Model，直接输出原始隐藏状态。

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = 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/muse_spark/modeling_muse_spark.py#L615)

**参数：**

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)

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

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

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

[MuseSparkTextModel](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkTextModel) 的 forward 方法重写了 `__call__` 特殊方法。

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

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **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 后的注意力权重，用于在自注意力头中计算加权平均值。
- **router_logits** (`tuple(torch.Tensor)`，*可选*，当传入 `output_router_probs=True` 且 `config.add_router_probs=True`，或当 `config.output_router_probs=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, sequence_length, num_experts)`。

  由 MoE 路由器计算的原始路由器 logits（softmax 之后），这些术语用于计算混合专家模型的辅助损失。

## MuseSparkVisionModel[[transformers.MuseSparkVisionModel]]

#### transformers.MuseSparkVisionModel[[transformers.MuseSparkVisionModel]]

```python
transformers.MuseSparkVisionModel(config: MuseSparkVisionConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L948)

**参数：**

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

未添加任何特定头部的裸 Muse Spark 模型，直接输出原始隐藏状态。

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

```python
forward(pixel_values: Tensor, grid_thw: LongTensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L979)

**参数：**

pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`)：与输入图像对应的张量。可以使用 [MuseGlimmerImageProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerImageProcessor) 获取像素值。有关详细信息，请参阅 [MuseGlimmerImageProcessor.__call__()](/docs/transformers/main/zh/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)（[MuseSparkProcessor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkProcessor) 使用 [MuseGlimmerImageProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerImageProcessor) 处理图像）。

grid_thw (`torch.LongTensor`，形状为 `(num_images_or_videos, 3)`)：每个打包图像或视频的时间、高度和宽度补丁网格维度。

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

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

[MuseSparkVisionModel](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkVisionModel) 的 forward 方法会重写 `__call__` 特殊方法。

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

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **pooler_output**（形状为 `(batch_size, hidden_size)` 的 `torch.Tensor`）-- 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后的结果。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重是在预训练期间通过下一句预测（分类）目标训练得到的。
- **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 后的注意力权重，用于在自注意力头中计算加权平均值。

## MuseSparkAudioModel[[transformers.MuseSparkAudioModel]]

#### transformers.MuseSparkAudioModel[[transformers.MuseSparkAudioModel]]

```python
transformers.MuseSparkAudioModel(config: MuseSparkAudioConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L1213)

**参数：**

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

Muse Spark Open 波形音频编码器：一个完全因果的卷积金字塔结构，将原始单声道 24 kHz 音频映射为每 1920 个采样点（80 毫秒，即 12.5 Hz）一个嵌入向量，且其维度已与文本模型的隐藏层大小对齐。该编码器不使用注意力机制，也不使用频谱图前端。

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

```python
forward(input_values: Tensor, padding_cache: transformers.models.muse_spark.modeling_muse_spark.MuseSparkAudioConv1dPaddingCache | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L1228)

**参数：**

input_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`) : 输入原始语音波形的浮点值。可以通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组来获取这些值，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将数组准备为 `input_values`，应使用 [AutoProcessor](/docs/transformers/main/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [MuseSparkProcessor.__call__()](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessorMixin.__call__)。

padding_cache (`MuseSparkAudioConv1dPaddingCache`, *可选*) : 用于卷积层填充的缓存，以在流式块之间保持状态。

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

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

[MuseSparkAudioModel](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkAudioModel) 的 forward 方法重写了 `__call__` 特殊方法。

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

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **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 后的注意力权重，用于在自注意力头中计算加权平均值。

## MuseSparkModel[[transformers.MuseSparkModel]]

#### transformers.MuseSparkModel[[transformers.MuseSparkModel]]

```python
transformers.MuseSparkModel(config: MuseSparkConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L1269)

**参数：**

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

未添加任何特定头部的裸 Muse Spark 模型，直接输出原始隐藏状态。

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = 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, pixel_values: typing.Optional[torch.Tensor] = None, image_grid_thw: typing.Optional[torch.LongTensor] = None, pixel_values_videos: typing.Optional[torch.Tensor] = None, video_grid_thw: typing.Optional[torch.LongTensor] = None, input_values: typing.Optional[torch.Tensor] = None, input_values_mask: typing.Optional[torch.Tensor] = None, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L1362)

**参数：**

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)

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

pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*)：与输入图像对应的张量。可以使用 [MuseGlimmerImageProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerImageProcessor) 获取像素值。有关详细信息，请参阅 [MuseGlimmerImageProcessor.__call__()](/docs/transformers/main/zh/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)（[MuseSparkProcessor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkProcessor) 使用 [MuseGlimmerImageProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerImageProcessor) 处理图像）。

image_grid_thw (`torch.LongTensor`，形状为 `(num_images, 3)`，*可选*)：LLM 中每张图片特征形状的时间、高度和宽度。

pixel_values_videos (`torch.Tensor`，形状为 `(batch_size, num_frames, num_channels, frame_size, frame_size)`，*可选*)：与输入视频对应的张量。可以使用 [MuseGlimmerVideoProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerVideoProcessor) 获取视频的像素值。有关详细信息，请参阅 [MuseGlimmerVideoProcessor.__call__()](/docs/transformers/main/zh/model_doc/molmo2#transformers.Molmo2VideoProcessor.__call__)（[MuseSparkProcessor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkProcessor) 使用 [MuseGlimmerVideoProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerVideoProcessor) 来处理视频）。

video_grid_thw (`torch.LongTensor`，形状为 `(num_videos, 3)`，*可选*)：LLM 中每个视频的特征形状的时间、高度和宽度。

input_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*) : 输入原始语音波形的浮点值。可以通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组来获取这些值，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将该数组准备为 `input_values`，应使用 [AutoProcessor](/docs/transformers/main/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [MuseSparkProcessor.__call__()](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessorMixin.__call__)。

input_values_mask (`torch.Tensor`，形状为 `(batch_size, num_samples)`，*可选*)：指示 `input_values` 中哪些条目是真实音频而非填充，由 [MuseSparkFeatureExtractor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkFeatureExtractor) 生成。当批量处理不同长度的片段时，此项为必需。

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *可选*) : 一个字典，其中键为支持的模态，值为该模态的编码输出。每个编码输出是一个元组，由 (`pooler_output`, *可选*: `last_hidden_states`, *可选*: `hidden_states`, *可选*: `attentions`) 组成，其中 `pooler_output` 的形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)，表示编码器生成的多模态特征序列，并已融合到文本嵌入中。

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

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

[MuseSparkModel](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkModel) 的 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 后的注意力权重，用于在自注意力头中计算加权平均值。
- **image_hidden_states** (`torch.Tensor`，*可选*) -- 大小为 `(batch_size, num_images, sequence_length, hidden_size)` 的 `torch.Tensor`。由视觉编码器生成的模型 image_hidden_states，并在投影最后一个隐藏状态之后得到。
- **router_logits** (`tuple[torch.Tensor]`，*可选*，在传入 `output_router_logits=True` 或 `config.add_router_probs=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, sequence_length, num_experts)`。

  模型的 Router logits，可用于计算混合专家（Mixture of Experts）模型的辅助损失。

示例：

```python
>>> import os

>>> from transformers import AutoProcessor, DistributedConfig, MuseSparkModel

>>> distributed_config = DistributedConfig(
...     tp_size=int(os.environ["WORLD_SIZE"]),
...     ep_size=int(os.environ["WORLD_SIZE"]),
... )

>>> processor = AutoProcessor.from_pretrained("meta-models/Muse-Spark-Open-816B-A42B")
>>> model = MuseSparkModel.from_pretrained(
...     "meta-models/Muse-Spark-Open-816B-A42B",
...     dtype="auto",
...     distributed_config=distributed_config,
... )

>>> messages = [
...     {
...         "role": "user",
...         "content": [
...             {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
...             {"type": "text", "text": "What is shown in this image?"},
...         ],
...     },
... ]

>>> inputs = processor.apply_chat_template(
...     messages,
...     reasoning_effort="medium",
...     add_generation_prompt=True,
...     tokenize=True,
...     return_dict=True,
...     return_tensors="pt",
... ).to(model.device).to(model.dtype)

>>> outputs = model(**inputs)
>>> last_hidden_state = outputs.last_hidden_state
```

## MuseSparkForConditionalGeneration[[transformers.MuseSparkForConditionalGeneration]]

#### transformers.MuseSparkForConditionalGeneration[[transformers.MuseSparkForConditionalGeneration]]

```python
transformers.MuseSparkForConditionalGeneration(config: MuseSparkConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L1552)

**参数：**

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

用于基于其他模态（例如图像-文本到文本生成）进行 token 生成的 Muse Spark 模型。

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, image_grid_thw: typing.Optional[torch.LongTensor] = None, pixel_values_videos: typing.Optional[torch.Tensor] = None, video_grid_thw: typing.Optional[torch.LongTensor] = None, input_values: typing.Optional[torch.Tensor] = None, input_values_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, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/muse_spark/modeling_muse_spark.py#L1590)

**参数：**

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)

pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*)：与输入图像对应的张量。可以使用 [MuseGlimmerImageProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerImageProcessor) 获取像素值。有关详细信息，请参阅 [MuseGlimmerImageProcessor.__call__()](/docs/transformers/main/zh/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)（[MuseSparkProcessor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkProcessor) 使用 [MuseGlimmerImageProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerImageProcessor) 处理图像）。

image_grid_thw (`torch.LongTensor`，形状为 `(num_images, 3)`，*可选*)：LLM 中每张图片特征形状的时间、高度和宽度。

pixel_values_videos (`torch.Tensor`，形状为 `(batch_size, num_frames, num_channels, frame_size, frame_size)`，*可选*)：与输入视频对应的张量。可以使用 [MuseGlimmerVideoProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerVideoProcessor) 获取视频的像素值。有关详细信息，请参阅 [MuseGlimmerVideoProcessor.__call__()](/docs/transformers/main/zh/model_doc/molmo2#transformers.Molmo2VideoProcessor.__call__)（[MuseSparkProcessor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkProcessor) 使用 [MuseGlimmerVideoProcessor](/docs/transformers/main/zh/model_doc/muse_glimmer#transformers.MuseGlimmerVideoProcessor) 来处理视频）。

video_grid_thw (`torch.LongTensor`，形状为 `(num_videos, 3)`，*可选*)：LLM 中每个视频的特征形状的时间、高度和宽度。

input_values (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*) : 输入原始语音波形的浮点值。可以通过将 `.flac` 或 `.wav` 音频文件加载为 `list[float]`、`numpy.ndarray` 或 `torch.Tensor` 类型的数组来获取这些值，*例如* 使用 torchcodec 库（`pip install torchcodec`）或 soundfile 库（`pip install soundfile`）。要将该数组准备为 `input_values`，应使用 [AutoProcessor](/docs/transformers/main/zh/model_doc/auto#transformers.AutoProcessor) 进行填充并转换为 `torch.Tensor` 类型的张量。有关详细信息，请参阅 [MuseSparkProcessor.__call__()](/docs/transformers/main/zh/main_classes/processors#transformers.ProcessorMixin.__call__)。

input_values_mask (`torch.Tensor`，形状为 `(batch_size, num_samples)`，*可选*)：指示 `input_values` 中哪些条目是真实音频而非填充，由 [MuseSparkFeatureExtractor](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkFeatureExtractor) 生成。当批量处理不同长度的片段时，此项为必需。

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` 索引转换为对应的向量，这将非常有用。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于计算掩码语言建模损失的标签。索引值应在 `[0, ..., config.vocab_size]` 范围内，或为 -100（参见 `input_ids` 的文档字符串）。索引值设为 `-100` 的 token 将被忽略（即被掩码），损失仅针对标签在 `[0, ..., config.vocab_size]` 范围内的 token 进行计算。

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

logits_to_keep (`Union[int, torch.Tensor]`，*可选*，默认为 `0`)：如果为 `int`，则计算最后 `logits_to_keep` 个 token 的 logits。如果为 `0`，则计算所有 `input_ids` 的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当可观。如果为 `torch.Tensor`，则必须是一维张量，对应于序列长度维度中需要保留的索引。这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *可选*) : 一个字典，其中键为支持的模态，值为该模态的编码输出。每个编码输出是一个元组，由 (`pooler_output`, *可选*: `last_hidden_states`, *可选*: `hidden_states`, *可选*: `attentions`) 组成，其中 `pooler_output` 的形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)，表示编码器生成的多模态特征序列，并已融合到文本嵌入中。

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

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

[MuseSparkForConditionalGeneration](/docs/transformers/main/zh/model_doc/muse_spark#transformers.MuseSparkForConditionalGeneration) 的 forward 方法重写了 `__call__` 特殊方法。

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 语言建模损失（用于下一个 token 预测）。
- **logits**（形状为 `(batch_size, sequence_length, config.text_config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **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 后的注意力权重，用于在自注意力头中计算加权平均值。
- **image_hidden_states** (`torch.Tensor`，*可选*) -- 大小为 `(batch_size, num_images, sequence_length, hidden_size)` 的 `torch.Tensor`。由视觉编码器生成的模型 image_hidden_states，即投影后的最后一个隐藏状态。
- **router_logits** (`tuple[torch.Tensor]`，*可选*，在传入 `output_router_logits=True` 或 `config.add_router_probs=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, sequence_length, num_experts)`。

  模型的 Router logits，可用于计算混合专家（Mixture of Experts）模型的辅助损失。

示例：

```python
>>> import os

>>> from transformers import AutoProcessor, DistributedConfig, MuseSparkForConditionalGeneration

>>> distributed_config = DistributedConfig(
...     tp_size=int(os.environ["WORLD_SIZE"]),
...     ep_size=int(os.environ["WORLD_SIZE"]),
... )

>>> processor = AutoProcessor.from_pretrained("meta-models/Muse-Spark-Open-816B-A42B")
>>> model = MuseSparkForConditionalGeneration.from_pretrained(
...     "meta-models/Muse-Spark-Open-816B-A42B",
...     dtype="auto",
...     distributed_config=distributed_config,
... )

>>> messages = [
...     {
...         "role": "user",
...         "content": [
...             {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
...             {"type": "text", "text": "What is shown in this image?"},
...         ],
...     },
... ]

>>> inputs = processor.apply_chat_template(
...     messages,
...     reasoning_effort="medium",
...     add_generation_prompt=True,
...     tokenize=True,
...     return_dict=True,
...     return_tensors="pt",
... ).to(model.device).to(model.dtype)
>>> input_len = inputs["input_ids"].shape[-1]

>>> outputs = model.generate(**inputs, max_new_tokens=512)

>>> response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)
>>> print(response)
The image shows a **Pallas's cat — also known as a manul, *Otocolobus manul*** — walking through snow.
...
```