Transformers documentation

Muse Spark 开放

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

该模型于 2026-10-14 贡献至 Hugging Face Transformers。

FlashAttention SDPA

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 共享其分词器和词表,并对聊天模板进行了扩展以支持多模态输入。检查点提供 BF16 和 NVFP4 格式。

资源

AutoModel
AutoModel 图像
AutoModel 视频
AutoModel Audio
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|>

NVFP4 权重

NVFP4 量化权重 具有更低的内存需求,可在 hub 上获取。该模型可以在任何支持 NVFP4 的设备上加载,且无需修改代码。量化配置会在加载时自动应用。

要支持 NVFP4,必须从此分支安装 transformers。

pip install git+https://github.com/huggingface/transformers.git@finegrained-per-scheme-demo
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

class transformers.MuseSparkConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneimage_token_id: int = 200092video_token_id: int = 200091out_hidden_size: int = 6144projector_hidden_size: int = 4096projector_hidden_act: str = 'gelu'audio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneaudio_token_id: int = 200038 )

参数

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig],可选) — 文本骨干网络的配置对象或字典。
  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig],可选) — 视觉骨干网络的配置对象或字典。
  • image_token_id (int,可选,默认为 200092) — 用作输入图像占位符的图像 token 索引。
  • 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 类似的配置。

配置对象继承自 PreTrainedConfig,可用于控制模型输出。有关更多信息,请参阅 PreTrainedConfig 的文档。

示例:

>>> 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

class transformers.MuseSparkTextConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 202048hidden_size: int = 8192intermediate_size: int = 16384num_hidden_layers: int = 62num_attention_heads: int = 128num_key_value_heads: int = 16head_dim: int = 64max_position_embeddings: int = 1048576initializer_range: float = 0.02rms_norm_eps: float = 1e-05use_cache: bool = Truepad_token_id: int | None = Noneeos_token_id: int | list[int] | None = 200001bos_token_id: int | None = 200000tie_word_embeddings: bool = Falserope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: int | float | None = 0.0sliding_window: int | None = 2048layer_types: list[str] | None = Nonefinal_logit_softcapping: float = 20.0qk_scale_factor: float = 5.4730064863875output_multiplier: float = 0.1767766952966369post_norm_eps: float = 1e-08layer_rope_theta: list[float | int] | None = Nonehidden_act: str = 'silu'moe_intermediate_size: int = 4096num_local_experts: int = 256num_experts_per_tok: int = 8routed_scaling_factor: float = 1.0moe_hidden_size: int = 4096mlp_layer_types: list[str] | None = Noneresidual_gate_temperature: float = 0.3output_router_logits: bool = False )

参数

  • 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,模型将使用 Multi Head Attention (MHA);如果 num_key_value_heads=1,模型将使用 Multi Query Attention (MQA);否则将使用 GQA。在将多头检查点转换为 GQA 检查点时,每个组的 key 和 value 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 这篇论文。如果未指定,则默认为 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 的值,并且如果希望使用 RoPE 处理更长的 max_position_embeddings,则可选地包含用于缩放的参数。
  • attention_bias (bool,可选,默认为 False) — 在自注意力机制中,是否在 query、key、value 和 output 投影层中使用偏置。
  • attention_dropout (Union[int, float],可选,默认为 0.0) — 注意力概率的 dropout 比率。
  • sliding_window (int,可选,默认为 2048) — 滑动窗口注意力的窗口大小。如果为 None,则不应用滑动窗口。
  • layer_types (list[str], 可选) — 一个列表,用于显式地将每个层索引映射到其层类型。如果未提供,将根据 config 值自动生成。
  • final_logit_softcapping (float, 可选,默认为 20.0) — 在计算概率分布之前应用于最终 logits 的软截断值。Logits 会按 tanh(logit / cap) * cap 进行缩放。
  • qk_scale_factor (float,可选,默认值为 5.4730064863875) — 在标准 1/sqrt(head_dim) 注意力缩放的基础上,应用于无缩放 QK-norm 之后 Q 的乘数。
  • 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。默认全部为 sparse。
  • 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 类似的配置。

配置对象继承自 PreTrainedConfig,可用于控制模型输出。有关更多信息,请参阅 PreTrainedConfig 的文档。

MuseSparkVisionConfig

class transformers.MuseSparkVisionConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonepatch_size: int = 14pos_emb_height: int = 32pos_emb_width: int = 32num_attention_heads: int = 16num_hidden_layers: int = 50hidden_size: int = 1536intermediate_size: int = 8960hidden_act: str = 'gelu'rope_parameters: dict | None = Nonepatch_temporal: int = 2merge_size: int = 2max_position_embeddings: int = 1024layer_norm_eps: float = 1e-05layer_types: list[str] | None = None )

参数

  • 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 的值,并且如果希望使用 RoPE 处理更长的 max_position_embeddings,则可选地包含用于缩放的参数。
  • patch_temporal (int, 可选) — 用于嵌入输入的时间维度 patch 大小。
  • merge_size (tuple[int] | list[int], 可选) — 用于 patch 合并的 kernel 大小。
  • max_position_embeddings (int,可选,默认为 1024) — 该模型可能使用的最大序列长度。
  • layer_norm_eps (float,可选,默认为 1e-05) — 层归一化层所使用的 epsilon 值。
  • layer_types (list[str], 可选) — 一个列表,用于显式地将每个层索引映射到其层类型。如果未提供,将根据 config 值自动生成。

这是用于存储 MuseSparkModel 配置的类。它根据指定的参数实例化 Muse Spark 模型,并定义模型架构。使用默认值实例化配置,将得到与 meta-models/Muse-Spark-Open-816B-A42B 类似的配置。

配置对象继承自 PreTrainedConfig,可用于控制模型输出。有关更多信息,请参阅 PreTrainedConfig 的文档。

MuseSparkAudioConfig

class transformers.MuseSparkAudioConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonepatch_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 = 4mlp_ratio: float = 4.0conv_kernel_size: int = 7hidden_act: str = 'gelu'rms_norm_eps: float = 1e-06out_hidden_size: int = 8192initializer_range: float = 0.02 )

参数

  • 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,可选,默认为 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 类似的配置。

配置对象继承自 PreTrainedConfig,可用于控制模型输出。有关更多信息,请参阅 PreTrainedConfig 的文档。

示例:

>>> from transformers import MuseSparkAudioConfig, MuseSparkAudioModel

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

MuseSparkFeatureExtractor

class transformers.MuseSparkFeatureExtractor

< >

( feature_size = 1sampling_rate = 24000padding_value = 0.0samples_per_token = 1920return_attention_mask = True**kwargs )

参数

  • feature_size (int,可选,默认为 1) — 提取特征的维度。Muse Spark Open 仅支持单声道音频。
  • sampling_rate (int,可选,默认为 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,其中包含了大部分主要方法。有关这些方法的更多信息,请参阅该父类。

MuseSparkProcessor

class transformers.MuseSparkProcessor

< >

( image_processor = Nonevideo_processor = Nonetokenizer = Nonefeature_extractor = Nonechat_template = None**kwargs )

参数

  • image_processor (MuseGlimmerImageProcessor) — 图像处理器是必需的输入。
  • video_processor (MuseGlimmerVideoProcessor) — 视频处理器是必需的输入。
  • tokenizer (tokenizer_class) — 分词器是必需的输入。
  • feature_extractor (MuseSparkFeatureExtractor) — 特征提取器是必需的输入。
  • chat_template (str) — 一个 Jinja 模板,用于将聊天中的消息列表转换为可分词的字符串。

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

MuseSparkProcessor 提供了 MuseGlimmerImageProcessor、MuseGlimmerVideoProcessor、tokenizer_class 和 MuseSparkFeatureExtractor 的所有功能。有关更多信息,请参阅 ~MuseGlimmerImageProcessor、~MuseGlimmerVideoProcessor、~tokenizer_class 和 ~MuseSparkFeatureExtractor。

MuseSparkPreTrainedModel

类 transformers.MuseSparkPreTrainedModel

< >

( config: PreTrainedConfig*inputs**kwargs )

参数

  • config (PreTrainedConfig) — 模型配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。

MuseSparkTextModel

class transformers.MuseSparkTextModel

< >

( config: MuseSparkTextConfig )

参数

  • config (MuseSparkTextConfig) — 模型配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

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

该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MoeModelOutputWithPast or tuple(torch.Tensor)

参数

  • input_ids (torch.LongTensor 形状为 (batch_size, sequence_length), ,可选) — 输入序列中各 token 在词汇表中的索引。默认情况下,填充(padding)将被忽略。

    可以使用 AutoTokenizer 获取索引。有关详细信息,请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

    什么是输入 ID?

  • attention_mask (torch.Tensor 形状为 (batch_size, sequence_length), ,可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自 [0, 1]:
    • 1 表示未被屏蔽的 token,
    • 对于被掩码的 token,值为 0。

    什么是注意力掩码?

  • position_ids (torch.LongTensor 形状为 (batch_size, sequence_length), 可选) — 输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 [0, config.n_positions - 1].

    什么是位置 ID?

  • past_key_values (~cache_utils.Cache, 可选) — 预计算的隐藏状态(自注意力块和交叉注意力块中的键和值),可用于加速顺序解码。这通常由 past_key_values 在解码的先前阶段返回,当 use_cache=True 或 config.use_cache=True.

    仅允许将 Cache 实例作为输入,请参阅我们的 kv cache 指南。 如果未传入 past_key_values,则默认会初始化 DynamicCache。

    模型将输出与输入相同的缓存格式。

    如果使用了 past_key_values,用户应仅输入未处理的 input_ids(即未向该模型提供其过去键值状态的那些),其形状为 (batch_size, unprocessed_length),而不是形状为 (batch_size, sequence_length) 的全部 input_ids。

  • inputs_embeds(形状为 (batch_size, sequence_length, hidden_size) 的 torch.Tensor,可选) — 可选地,您可以选择直接传入嵌入表示,而不是传入 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)和输入。

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 实例。更多详情,请参阅我们的 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

class transformers.MuseSparkVisionModel

< >

( config: MuseSparkVisionConfig )

参数

  • config (MuseSparkVisionConfig) — 模型配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

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

该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。

forward

< >

( pixel_values: Tensorgrid_thw: LongTensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)

参数

返回值

BaseModelOutputWithPooling 或 tuple(torch.Tensor)

一个 BaseModelOutputWithPooling 或 torch.Tensor 元组(如果传入了 return_dict=False 或 config.return_dict=False),其包含的元素取决于配置(MuseSparkConfig)和输入。

MuseSparkVisionModel 的 forward 方法会重写 __call__ 特殊方法。

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

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

  • pooler_output (torch.Tensor,形状为 (batch_size, hidden_size)) — 序列中第一个 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

class transformers.MuseSparkAudioModel

< >

( config: MuseSparkAudioConfig )

参数

  • config (MuseSparkAudioConfig) — 模型配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

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

该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。

forward

< >

( input_values: Tensorpadding_cache: transformers.models.muse_spark.modeling_muse_spark.MuseSparkAudioConv1dPaddingCache | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutput or tuple(torch.Tensor)

参数

  • 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 进行填充并转换为 torch.Tensor 类型的张量。详情请参见 MuseSparkProcessor.call()。
  • padding_cache (MuseSparkAudioConv1dPaddingCache, 可选) — 用于卷积层填充的缓存,以在流式块之间保持状态。

返回值

BaseModelOutput 或 tuple(torch.Tensor)

一个 BaseModelOutput 或 torch.Tensor 元组(如果传入了 return_dict=False 或 config.return_dict=False),其包含的元素取决于配置(MuseSparkConfig)和输入。

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

class transformers.MuseSparkModel

< >

( config: MuseSparkConfig )

参数

  • config (MuseSparkConfig) — 模型的配置类,包含模型的所有参数。通过配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

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

该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Nonepixel_values: typing.Optional[torch.Tensor] = Noneimage_grid_thw: typing.Optional[torch.LongTensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Nonevideo_grid_thw: typing.Optional[torch.LongTensor] = Noneinput_values: typing.Optional[torch.Tensor] = Noneinput_values_mask: typing.Optional[torch.Tensor] = Nonemm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MuseSparkModelOutputWithPast or tuple(torch.Tensor)

参数

  • input_ids (torch.LongTensor 形状为 (batch_size, sequence_length), ,可选) — 输入序列中各 token 在词汇表中的索引。默认情况下,填充(padding)将被忽略。

    可以使用 AutoTokenizer 获取索引。有关详细信息,请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

    什么是输入 ID?

  • attention_mask (torch.Tensor 形状为 (batch_size, sequence_length), ,可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自 [0, 1]:
    • 1 表示未被屏蔽的 token,
    • 对于被掩码的 token,值为 0。

    什么是注意力掩码?

  • position_ids (torch.LongTensor 形状为 (batch_size, sequence_length), 可选) — 输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 [0, config.n_positions - 1].

    什么是位置 ID?

  • past_key_values (~cache_utils.Cache, 可选) — 预计算的隐藏状态(自注意力块和交叉注意力块中的键和值),可用于加速顺序解码。这通常由 past_key_values 在解码的先前阶段返回,当 use_cache=True 或 config.use_cache=True.

    仅允许将 Cache 实例作为输入,请参阅我们的 kv cache 指南。 如果未传入 past_key_values,则默认会初始化 DynamicCache。

    模型将输出与输入相同的缓存格式。

    如果使用了 past_key_values,用户应仅输入未处理的 input_ids(即未向该模型提供其过去键值状态的那些),其形状为 (batch_size, unprocessed_length),而不是形状为 (batch_size, sequence_length) 的全部 input_ids。

  • inputs_embeds(形状为 (batch_size, sequence_length, hidden_size) 的 torch.Tensor,可选) — 可选地,您可以选择直接传入嵌入表示,而不是传入 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 获取像素值。有关详细信息,请参阅 MuseGlimmerImageProcessor.call()(MuseSparkProcessor 使用 MuseGlimmerImageProcessor 处理图像)。
  • image_grid_thw (torch.LongTensor,形状为 (num_images, 3),可选) — LLM 中每张图片特征形状的时间、高度和宽度。
  • pixel_values_videos(形状为 (batch_size, num_frames, num_channels, frame_size, frame_size) 的 torch.Tensor,可选) — 对应输入视频的张量。可以使用 MuseGlimmerVideoProcessor 获取视频的像素值。有关详细信息,请参阅 MuseGlimmerVideoProcessor.call()(MuseSparkProcessor 使用 MuseGlimmerVideoProcessor 来处理视频)。
  • video_grid_thw(形状为 (num_videos, 3) 的 torch.LongTensor,可选) — 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 进行填充并转换为 torch.Tensor 类型的张量。有关详细信息,请参阅 MuseSparkProcessor.call()。
  • input_values_mask(形状为 (batch_size, num_samples) 的 torch.Tensor,可选) — 指示 input_values 中哪些条目是真实音频而非填充,由 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)和输入。

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 实例。更多详情,请参阅我们的 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)模型的辅助损失。

示例:

>>> 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

class transformers.MuseSparkForConditionalGeneration

< >

( config: MuseSparkConfig )

参数

  • config (MuseSparkConfig) — 模型的配置类,包含模型的所有参数。通过配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

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

该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Noneimage_grid_thw: typing.Optional[torch.LongTensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Nonevideo_grid_thw: typing.Optional[torch.LongTensor] = Noneinput_values: typing.Optional[torch.Tensor] = Noneinput_values_mask: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MuseSparkCausalLMOutputWithPast or tuple(torch.Tensor)

参数

  • input_ids (torch.LongTensor 形状为 (batch_size, sequence_length), ,可选) — 输入序列中各 token 在词汇表中的索引。默认情况下,填充(padding)将被忽略。

    可以使用 AutoTokenizer 获取索引。有关详细信息,请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

    什么是输入 ID?

  • pixel_values (torch.Tensor,形状为 (batch_size, num_channels, image_size, image_size),可选) — 与输入图像对应的张量。可以使用 MuseGlimmerImageProcessor 获取像素值。有关详细信息,请参阅 MuseGlimmerImageProcessor.call()(MuseSparkProcessor 使用 MuseGlimmerImageProcessor 处理图像)。
  • image_grid_thw (torch.LongTensor,形状为 (num_images, 3),可选) — LLM 中每张图片特征形状的时间、高度和宽度。
  • pixel_values_videos(形状为 (batch_size, num_frames, num_channels, frame_size, frame_size) 的 torch.Tensor,可选) — 对应输入视频的张量。可以使用 MuseGlimmerVideoProcessor 获取视频的像素值。有关详细信息,请参阅 MuseGlimmerVideoProcessor.call()(MuseSparkProcessor 使用 MuseGlimmerVideoProcessor 来处理视频)。
  • video_grid_thw(形状为 (num_videos, 3) 的 torch.LongTensor,可选) — 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 进行填充并转换为 torch.Tensor 类型的张量。有关详细信息,请参阅 MuseSparkProcessor.call()。
  • input_values_mask(形状为 (batch_size, num_samples) 的 torch.Tensor,可选) — 指示 input_values 中哪些条目是真实音频而非填充,由 MuseSparkFeatureExtractor 生成。当批量处理长度不同的片段时,此参数为必需项。
  • attention_mask (torch.Tensor 形状为 (batch_size, sequence_length), ,可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自 [0, 1]:
    • 1 表示未被屏蔽的 token,
    • 对于被掩码的 token,值为 0。

    什么是注意力掩码?

  • position_ids (torch.LongTensor 形状为 (batch_size, sequence_length), 可选) — 输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 [0, config.n_positions - 1].

    什么是位置 ID?

  • past_key_values (~cache_utils.Cache, 可选) — 预计算的隐藏状态(自注意力块和交叉注意力块中的键和值),可用于加速顺序解码。这通常由 past_key_values 在解码的先前阶段返回,当 use_cache=True 或 config.use_cache=True.

    仅允许将 Cache 实例作为输入,请参阅我们的 kv cache 指南。 如果未传入 past_key_values,则默认会初始化 DynamicCache。

    模型将输出与输入相同的缓存格式。

    如果使用了 past_key_values,用户应仅输入未处理的 input_ids(即未向该模型提供其过去键值状态的那些),其形状为 (batch_size, unprocessed_length),而不是形状为 (batch_size, sequence_length) 的全部 input_ids。

  • inputs_embeds(形状为 (batch_size, sequence_length, hidden_size) 的 torch.Tensor,可选) — 可选地,您可以选择直接传入嵌入表示,而不是传入 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)和输入。

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 实例。更多详情,请参阅我们的 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)模型的辅助损失。

示例:

>>> 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.
...
Update on GitHub