Transformers documentation
Muse Spark 开放
该模型于 2026-10-14 贡献至 Hugging Face Transformers。
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 格式。

资源
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|>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|>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|>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 量化权重 具有更低的内存需求,可在 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
< source >( 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.configMuseSparkTextConfig
class transformers.MuseSparkTextConfig
< source >( 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
< source >( 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
< source >( 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 的文档。
MuseSparkFeatureExtractor
class transformers.MuseSparkFeatureExtractor
< source >( 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
< source >( image_processor = Nonevideo_processor = Nonetokenizer = Nonefeature_extractor = Nonechat_template = None**kwargs )
构造一个 MuseSparkProcessor,它将图像处理器、视频处理器、分词器和特征提取器封装为单一处理器。
MuseSparkProcessor 提供了 MuseGlimmerImageProcessor、MuseGlimmerVideoProcessor、tokenizer_class 和 MuseSparkFeatureExtractor 的所有功能。有关更多信息,请参阅 ~MuseGlimmerImageProcessor、~MuseGlimmerVideoProcessor、~tokenizer_class 和 ~MuseSparkFeatureExtractor。
MuseSparkPreTrainedModel
类 transformers.MuseSparkPreTrainedModel
< source >( config: PreTrainedConfig*inputs**kwargs )
参数
- config (PreTrainedConfig) — 模型配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。
MuseSparkTextModel
class transformers.MuseSparkTextModel
< source >( config: MuseSparkTextConfig )
参数
- config (MuseSparkTextConfig) — 模型配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
未添加任何特定头部的裸 Muse Spark Text Model,直接输出原始隐藏状态。
该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。
forward
< source >( 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()。
- 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]. - 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
< source >( config: MuseSparkVisionConfig )
参数
- config (MuseSparkVisionConfig) — 模型配置类,包含模型的所有参数。使用配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
未添加任何特定头部的裸 Muse Spark 模型,直接输出原始隐藏状态。
该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。
forward
< source >( pixel_values: Tensorgrid_thw: LongTensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
参数
- pixel_values (
torch.Tensor,形状为(batch_size, num_channels, image_size, image_size)) — 与输入图像对应的张量。可以使用 MuseGlimmerImageProcessor 获取像素值。有关详细信息,请参阅 MuseGlimmerImageProcessor.call()(MuseSparkProcessor 使用 MuseGlimmerImageProcessor 处理图像)。 - grid_thw(形状为
(num_images_or_videos, 3)的torch.LongTensor)— 每个打包图像或视频的时间、高度和宽度补丁网格维度。
返回值
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
< source >( 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
< source >( 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
< source >( config: MuseSparkConfig )
参数
- config (MuseSparkConfig) — 模型的配置类,包含模型的所有参数。通过配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
未添加任何特定头部的裸 Muse Spark 模型,直接输出原始隐藏状态。
该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。
forward
< source >( 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()。
- 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]. - 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_stateMuseSparkForConditionalGeneration
class transformers.MuseSparkForConditionalGeneration
< source >( config: MuseSparkConfig )
参数
- config (MuseSparkConfig) — 模型的配置类,包含模型的所有参数。通过配置文件进行初始化时,不会加载与模型关联的权重,仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
用于基于其他模态(例如图像-文本到文本生成)进行 token 生成的 Muse Spark 模型。
该模型继承自 PreTrainedModel。请查阅父类文档,了解该库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入大小、剪枝头等)。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用,有关通用用法和行为的所有事项,请参阅 PyTorch 文档。
forward
< source >( 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()。
- 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]. - 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.
...