Transformers documentation
Higgs Audio V2
Este modelo foi contribuído para o Hugging Face Transformers em 19/02/2026.
Higgs Audio V2
Visão geral
Higgs Audio V2 é um poderoso modelo de fundação para áudio desenvolvido pela Boson AI. O modelo foi pré-treinado com mais de 10 milhões de horas de dados de áudio e um conjunto diversificado de dados de texto. Apesar de não ter passado por pós-treinamento ou ajuste fino, o Higgs Audio v2 se destaca na geração de áudio expressivo, graças ao seu profundo entendimento de linguagem e acústica.
Arquitetura do modelo:
- Desenvolvemos um pipeline de anotação automatizado que utiliza múltiplos modelos de ASR, modelos de classificação de eventos sonoros e nosso modelo interno de compreensão de áudio. Com esse pipeline, limparamos e anotamos 10 milhões de horas de dados de áudio, aos quais nos referimos como AudioVerse. O modelo interno de compreensão é finetunado a partir do Higgs Audio v1 Understanding, que adota a “variante de compreensão” mostrada na figura da arquitetura.
- Treinamos um tokenizador de áudio unificado do zero que captura tanto características semânticas quanto acústicas.
- Arquitetura DualFFN proposta, que aprimora a capacidade do LLM de modelar tokens acústicos com sobrecarga computacional mínima.
Uso
Todos os trechos de código abaixo espelham os testes de integração em test_higgs_audio.py, garantindo que a documentação permaneça sincronizada com os fluxos de trabalho oficialmente suportados.
Voz inteligente de um único falante
from transformers import AutoProcessor, HiggsAudioV2ForConditionalGeneration
model_id = "eustlb/higgs-audio-v2-generation-3B-base"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = HiggsAudioV2ForConditionalGeneration.from_pretrained(model_id, device_map="auto")
conversation = [
{
"role": "system",
"content": [
{
"type": "text",
"text": "Generate audio following instruction."
}
],
},
{
"role": "scene",
"content": [
{
"type": "text",
"text": "Audio is recorded from a quiet room."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "The sun rises in the east and sets in the west. This simple fact has been observed by humans for thousands of years."
}
]
}
]
inputs = processor.apply_chat_template(
conversation,
add_generation_prompt=True,
tokenize=True,
return_dict=True,
sampling_rate=24000,
return_tensors="pt"
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=1000, do_sample=False)
decoded = processor.batch_decode(outputs)
processor.save_audio(decoded, "output_single_speaker_smart_voice.wav")Voz inteligente multi-falante
from transformers import AutoProcessor, HiggsAudioV2ForConditionalGeneration
model_id = "eustlb/higgs-audio-v2-generation-3B-base"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = HiggsAudioV2ForConditionalGeneration.from_pretrained(model_id, device_map="auto")
system_message = """You are an AI assistant designed to convert text into speech.
If the user's message includes a [SPEAKER*] tag, do not read out the tag and generate speech for the following text, using the specified voice.
If no speaker tag is present, select a suitable voice on your own."""
user_message = """[SPEAKER0] I can't believe you did that without even asking me first!
[SPEAKER1] Oh, come on! It wasn't a big deal, and I knew you would overreact like this.
[SPEAKER0] Overreact? You made a decision that affects both of us without even considering my opinion!
[SPEAKER1] Because I didn't have time to sit around waiting for you to make up your mind! Someone had to act."""
conversation = [
{
"role": "system",
"content": [
{
"type": "text",
"text": system_message
}
]
},
{
"role": "scene",
"content": [
{
"type": "text",
"text": "Audio is recorded from a quiet room."
},
{
"type": "text",
"text": "SPEAKER0: feminine"
},
{
"type": "text",
"text": "SPEAKER1: masculine"
},
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": user_message
}
]
}
]
inputs = processor.apply_chat_template(
conversation,
add_generation_prompt=True,
tokenize=True,
return_dict=True,
sampling_rate=24000,
return_tensors="pt"
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=50, do_sample=False)
decoded = processor.batch_decode(outputs)
processor.save_audio(decoded, "output_multi_speaker_smart_voice.wav")Clonagem de voz zero-shot
from transformers import AutoProcessor, HiggsAudioV2ForConditionalGeneration
model_id = "eustlb/higgs-audio-v2-generation-3B-base"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = HiggsAudioV2ForConditionalGeneration.from_pretrained(model_id, device_map="auto")
conversation = [
{
"role": "system",
"content": [
{
"type": "text",
"text": "Generate audio following instruction."
}
]
},
{
"role": "scene",
"content": [
{
"type": "text",
"text": "Audio is recorded from a quiet room."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "It was the night before my birthday. Hooray! It's almost here! It may not be a holiday, but it's the best day of the year."
}
]
},
{
"role": "assistant",
"content": [
{
"type": "audio",
"url": "https://huggingface.co/datasets/eustlb/dummy-audio-samples-higgs/resolve/main/belinda.wav"
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "The sun rises in the east and sets in the west. This simple fact has been observed by humans for thousands of years."
}
]
}
]
inputs = processor.apply_chat_template(
conversation,
add_generation_prompt=True,
tokenize=True,
return_dict=True,
sampling_rate=24000,
return_tensors="pt"
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=1000, do_sample=False)
decoded = processor.batch_decode(outputs)
processor.save_audio(decoded, "output_zero_shot_voice_cloning.wav")Clonagem de voz multi-falante
from transformers import AutoProcessor, HiggsAudioV2ForConditionalGeneration
model_id = "eustlb/higgs-audio-v2-generation-3B-base"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = HiggsAudioV2ForConditionalGeneration.from_pretrained(model_id, device_map="auto")
user_message = """[SPEAKER0] I can't believe you did that without even asking me first!
[SPEAKER1] Oh, come on! It wasn't a big deal, and I knew you would overreact like this.
[SPEAKER0] Overreact? You made a decision that affects both of us without even considering my opinion!
[SPEAKER1] Because I didn't have time to sit around waiting for you to make up your mind! Someone had to act."""
conversation = [
{
"role": "system",
"content": [
{
"type": "text",
"text": "Generate audio following instruction."
}
]
},
{
"role": "scene",
"content": [
{
"type": "text",
"text": "Audio is recorded from a quiet room."
},
{
"type": "text",
"text": "SPEAKER0:"
},
{
"type": "audio",
"url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/audio/voice_sample.wav"
},
{
"type": "text",
"text": "SPEAKER1:"
},
{
"type": "audio",
"url": "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/audio/mr_quiller.flac"
},
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": user_message
}
]
},
]
inputs = processor.apply_chat_template(
conversation,
add_generation_prompt=True,
tokenize=True,
return_dict=True,
sampling_rate=24000,
return_tensors="pt"
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=1000, do_sample=False)
decoded = processor.batch_decode(outputs)
processor.save_audio(decoded, "output_multi_speaker_voice_cloning.wav")Inferência em lote
from transformers import AutoProcessor, HiggsAudioV2ForConditionalGeneration
model_id = "eustlb/higgs-audio-v2-generation-3B-base"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = HiggsAudioV2ForConditionalGeneration.from_pretrained(model_id, device_map="auto")
conversation1 = [
{
"role": "system",
"content": [
{
"type": "text",
"text": "Generate audio following instruction."
}
]
},
{
"role": "scene",
"content": [
{
"type": "text",
"text": "Audio is recorded from a quiet room."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "It was the night before my birthday. Hooray! It's almost here! It may not be a holiday, but it's the best day of the year."
}
]
},
{
"role": "assistant",
"content": [
{
"type": "audio",
"url": "https://huggingface.co/datasets/eustlb/dummy-audio-samples-higgs/resolve/main/belinda.wav"
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "The sun rises in the east and sets in the west. This simple fact has been observed by humans for thousands of years."
}
]
}
]
conversation2 = [
{
"role": "system",
"content": [
{
"type": "text",
"text": "Generate audio following instruction."
}
]
},
{
"role": "scene",
"content": [
{
"type": "text",
"text": "Audio is recorded from a quiet room."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": " It's super important to assess fairly the fact that our former model is over. And this is not a question of adjustment. This is not the same world, 2024, 2025. And on top of that, we are making the same mistakes, on top of the key elements I mentioned. We are over-regulating and under-investing. So just if, in the two to three years to come, if we follow our classical agenda, we will be out of the market. I have no doubts."
}
]
},
{
"role": "assistant",
"content": [
{
"type": "audio",
"url": "https://huggingface.co/datasets/eustlb/dummy-audio-samples-higgs/resolve/main/macron.wav"
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hey, here is a clone from the given voice."
}
]
}
]
inputs = processor.apply_chat_template(
[conversation1, conversation2],
add_generation_prompt=True,
tokenize=True,
return_dict=True,
sampling_rate=24000,
return_tensors="pt"
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=1000, do_sample=False)
decoded = processor.batch_decode(outputs)
processor.save_audio(decoded, ["output_batched_1.wav", "output_batched_2.wav"])Treinamento
Por padrão, o modelo não carrega a cabeça de modelagem de linguagem de texto para economizar memória (redução de ~1.5GiB), pois ela não é necessária para a geração. No entanto, ao treinar o modelo, você precisa da cabeça de texto para calcular a perda nos tokens de texto. Para ativá-la, defina
use_text_head=Trueao instanciar o modelo (veja o exemplo abaixo).
from transformers import AutoProcessor, HiggsAudioV2ForConditionalGeneration
model_id = "eustlb/higgs-audio-v2-generation-3B-base"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = HiggsAudioV2ForConditionalGeneration.from_pretrained(model_id, device_map="auto", use_text_head=True)
conversation1 = [
{
"role": "system",
"content": [
{
"type": "text",
"text": "Generate audio following instruction."
}
]
},
{
"role": "scene",
"content": [
{
"type": "text",
"text": "Audio is recorded from a quiet room."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "It was the night before my birthday. Hooray! It's almost here! It may not be a holiday, but it's the best day of the year."
}
]
},
{
"role": "assistant",
"content": [
{
"type": "audio",
"url": "https://huggingface.co/datasets/eustlb/dummy-audio-samples-higgs/resolve/main/belinda.wav"
}
]
}
]
conversation2 = [
{
"role": "system",
"content": [
{
"type": "text",
"text": "Generate audio following instruction."
}
]
},
{
"role": "scene",
"content": [
{
"type": "text",
"text": "Audio is recorded from a quiet room."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": " I would imagine so. A wand with a dragon heartstring core is capable of dazzling magic, and the bond between you and your wand should only grow stronger. Do not be surprised at your new wand's ability to perceive your intentions, particularly in a moment of need"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "audio",
"url": "https://huggingface.co/datasets/eustlb/dummy-audio-samples-higgs/resolve/main/broom_salesman.wav"
}
]
}
]
inputs = processor.apply_chat_template(
[conversation1, conversation2],
tokenize=True,
return_dict=True,
sampling_rate=24000,
return_tensors="pt",
output_labels=True,
).to(model.device)
outputs = model(**inputs)
outputs.loss.backward()Este modelo foi contribuído por Shuai Zheng e Eustache Le Bihan. O código original pode ser encontrado aqui.
HiggsAudioV2Config
classe transformers.HiggsAudioV2Config
< 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 = 128256hidden_size: int = 3072intermediate_size: int = 8192num_hidden_layers: int = 28num_attention_heads: int = 24num_key_value_heads: int = 8hidden_act: str = 'silu'max_position_embeddings: int = 2048initializer_range: float = 0.02rms_norm_eps: float = 1e-05use_cache: bool = Truepad_token_id: int | None = 128001bos_token_id: int | None = 1eos_token_id: int | list[int] | None = 128009pretraining_tp: int | None = 1tie_word_embeddings: bool = Falserope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: int | float | None = 0.0mlp_bias: bool = Falsehead_dim: int | None = 128num_codebooks: int = 8codebook_size: int = 1024audio_token_id: int = 128016audio_bos_token_id: int = 128013audio_delay_token_id: int = 128014audio_stream_bos_id: int = 1024audio_stream_eos_id: int = 1025 )
Parâmetros
- vocab_size (
int, opcional, padrão128256) — Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelosinput_ids. - hidden_size (
int, opcional, padrão3072) — Dimensão das representações ocultas. - intermediate_size (
int, opcional, padrão8192) — Dimensão das representações do MLP. - num_hidden_layers (
int, opcional, padrão28) — Número de camadas ocultas no decodificador do Transformer. - num_attention_heads (
int, opcional, padrão24) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer. - num_key_value_heads (
int, opcional, padrão8) — Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Senum_key_value_heads=num_attention_heads, o modelo usará Multi Head Attention (MHA); senum_key_value_heads=1, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada grupo de cabeças de chave e valor deve ser construído por meio do meanpooling de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte este artigo. Se não for especificado, o valor padrão seránum_attention_heads. - hidden_act (
str, opcional, padrãosilu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo,"gelu","relu","silu", etc. - max_position_embeddings (
int, opcional, padrão2048) — O comprimento máximo de sequência com o qual este modelo pode ser utilizado. - initializer_range (
float, opcional, padrão0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos. - rms_norm_eps (
float, opcional, padrão1e-05) — O epsilon usado pelas camadas de normalização rms. - use_cache (
bool, opcional, padrãoTrue) — Se o modelo deve ou não retornar as últimas chaves/valores de atenção (não usado por todos os modelos). Relevante apenas seconfig.is_decoder=Trueou quando o modelo for um modelo generativo somente decodificador. - pad_token_id (
int, opcional, padrão128001) — ID do token usado para preenchimento no vocabulário. - bos_token_id (
int, opcional, padrão1) — ID do token usado para o início do fluxo no vocabulário. - eos_token_id (
Union[int, list[int]], opcional, padrão128009) — ID do token usado para o fim do fluxo no vocabulário. - pretraining_tp (
int, opcional, padrão1) — Recurso experimental. Rank de paralelismo de tensor usado durante o pré-treinamento. Consulte este documento para entender mais sobre isso. Esse valor é necessário para garantir a reprodutibilidade exata dos resultados do pré-treinamento. Consulte esta issue. - tie_word_embeddings (
bool, opcional, padrãoFalse) — Se deve vincular as embeddings de pesos de acordo com o mapeamentotied_weights_keysdo modelo. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor pararope_thetae, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE commax_position_embeddingsmaiores. - attention_bias (
bool, opcional, padrãoFalse) — Indica se deve ser usado um viés nas camadas de projeção de query, key, value e output durante a autoatenção. - attention_dropout (
Union[int, float], opcional, padrão0.0) — A taxa de dropout para as probabilidades de atenção. - mlp_bias (
bool, opcional, padrãoFalse) — Se deve usar um viés nas camadas up_proj, down_proj e gate_proj das camadas MLP. - head_dim (
int, opcional, padrão128) — A dimensão da cabeça de atenção. Se for None, o valor padrão será hidden_size // num_attention_heads - num_codebooks (
int, opcional, padrão8) — O número de codebooks paralelos usados pelo modelo. - codebook_size (
int, opcional, padrão1024) — O número de codebooks paralelos usados pelo modelo. - audio_token_id (
int, opcional, padrão128016) — O índice do token de áudio usado como marcador de posição para o áudio de entrada. - audio_bos_token_id (
int, opcional, padrão 128013) — O ID do token para o token de início de sequência para saída de áudio. - audio_delay_token_id (
int, opcional, padrão 128014) — O ID do token usado para o padrão de atraso de áudio na geração multi-codebook. - audio_stream_bos_id (
int, opcional, padrão 1024) — O ID do token de início de sequência em sequências de áudio. - audio_stream_eos_id (
int, opcional, padrão 1025) — O ID do token de fim de stream em sequências de áudio.
Esta é a classe de configuração para armazenar a configuração de um HiggsAudioV2ForConditionalGeneration. Ela é usada para instanciar um modelo Higgs Audio V2 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do bosonai/higgs-audio-v2-generation-3B-base
Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.
Exemplo:
>>> from transformers import HiggsAudioV2Model, HiggsAudioV2Config
>>> # Initializing a HiggsAudioV2 style configuration
>>> configuration = HiggsAudioV2Config()
>>> # Initializing a model from the configuration
>>> model = HiggsAudioV2Model(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configHiggsAudioV2Processor
classe transformers.HiggsAudioV2Processor
< source >( feature_extractortokenizeraudio_tokenizerchat_template = Noneaudio_token = '<|AUDIO_OUT|>'audio_bos_token = '<|audio_out_bos|>'audio_eos_token = '<|audio_eos|>'audio_delay_token = '<|reserved_special_token_6|>'audio_stream_bos_id = 1024audio_stream_eos_id = 1025 )
Parâmetros
- feature_extractor (
DacFeatureExtractor) — Uma instância de DacFeatureExtractor. O extrator de recursos é uma entrada obrigatória. - tokenizer (
AutoTokenizer) — Uma instância de AutoTokenizer. O tokenizer é uma entrada obrigatória. - audio_tokenizer (
HiggsAudioV2TokenizerModel) — Uma instância de HiggsAudioV2TokenizerModel. O tokenizer de áudio é uma entrada obrigatória. - chat_template (
str, opcional) — Uma string de modelo para formatação de chat ao combinar interações de texto e áudio. - audio_token (
str, opcional, padrão"<|AUDIO_OUT|>") — O token usado para representar a saída de áudio na sequência de texto. - audio_bos_token (
str, opcional, padrão"<|audio_out_bos|>") — O token de início de sequência para saída de áudio. - audio_eos_token (
str, opcional, padrão"<|audio_eos|>") — O token de fim de sequência para saída de áudio. - audio_delay_token (
str, opcional, padrão"<|reserved_special_token_6|>") — O token usado para o padrão de atraso de áudio na geração multi-codebook. - audio_stream_bos_id (
int, opcional, padrão 1024) — O ID do token de início de sequência em sequências de áudio. - audio_stream_eos_id (
int, opcional, padrão 1025) — O ID do token de fim de stream em sequências de áudio.
Constrói um processador Higgs Audio que encapsula um DacFeatureExtractor, um AutoTokenizer e um HiggsAudioV2TokenizerModel em um único processador. Ele herda as funcionalidades de extração de características de áudio, tokenização e codificação/decodificação de áudio. Consulte call() e decode() para mais informações.
__call__
< source >( text: str | list[str] | list[list[str]] | None = Noneaudio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = Noneoutput_labels: bool | None = False**kwargs: *<class 'transformers.models.higgs_audio_v2.processing_higgs_audio_v2.HiggsAudioV2ProcessorKwargs'> )
HiggsAudioV2Model
classe transformers.HiggsAudioV2Model
< source >( config: HiggsAudioV2Config )
Parâmetros
- config (HiggsAudioV2Config) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.
O modelo Higgs Audio V2 sem modificações, que gera estados ocultos brutos sem nenhum cabeçalho específico no topo.
Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)
Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneaudio_input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.LongTensor] = Noneaudio_input_ids_mask: typing.Optional[torch.BoolTensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ~models.modeling_outputs.BaseModelOutputWithPast
Parâmetros
- input_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.
- audio_input_ids (
torch.LongTensorde forma(batch_size, num_audio_frames, num_codebooks), opcional) — Índices dos tokens do codebook de áudio.Os índices podem ser obtidos usando HiggsAudioV2TokenizerModel.encode().
- attention_mask (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em[0, 1]:- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
- audio_input_ids_mask (
torch.BoolTensorde forma(batch_size, num_audio_frames), opcional) — Indica quais quadros de áudio emaudio_input_idssão válidos. - position_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, opcional) — Estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nopast_key_valuesretornado pelo modelo em uma etapa anterior da decodificação, quandouse_cache=Trueouconfig.use_cache=True.Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum
past_key_valuesfor passado, DynamicCache será inicializado por padrão.O modelo sairá no mesmo formato de cache que é fornecido como entrada.
Se
past_key_valuesforem usados, espera-se que o usuário insira apenas osinput_idsnão processados (aqueles que não têm seus estados de chave e valor passados fornecidos a este modelo) com a forma(batch_size, unprocessed_length), em vez de todos osinput_idscom a forma(batch_size, sequence_length). - inputs_embeds (
torch.FloatTensorde forma(batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, em vez de passarinput_ids, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices deinput_idsnos vetores associados do que a matriz de incorporação interna do modelo. - use_cache (
bool, opcional) — Se definido comoTrue, os estados de chave-valorpast_key_valuessão retornados e podem ser usados para acelerar a decodificação (vejapast_key_values).
Retorna
~models.modeling_outputs.BaseModelOutputWithPast
Saídas usuais do decodificador com as posições de marcador já substituídas pelos correspondentes embeddings de áudio.
O método forward do HiggsAudioV2Model substitui o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
Exemplo:
>>> from transformers import AutoProcessor, HiggsAudioV2Model
>>> import torch
>>> device = "cuda" if torch.cuda.is_available() else "cpu"
>>> processor = AutoProcessor.from_pretrained("eustlb/higgs-audio-v2-generation-3B-base", device_map=device)
>>> model = HiggsAudioV2Model.from_pretrained("eustlb/higgs-audio-v2-generation-3B-base", device_map=device)
>>> conversation = [
... {
... "role": "system",
... "content": [
... {
... "type": "text",
... "text": "Generate audio following instruction."
... }
... ]
... },
... {
... "role": "scene",
... "content": [
... {
... "type": "text",
... "text": "Audio is recorded from a quiet room."
... }
... ]
... },
... {
... "role": "user",
... "content": [
... {
... "type": "text",
... "text": "It was the night before my birthday. Hooray! It's almost here! It may not be a holiday, but it's the best day of the year."
... }
... ]
... },
... {
... "role": "assistant",
... "content": [
... {
... "type": "audio",
... "url": "https://huggingface.co/datasets/eustlb/dummy-audio-samples-higgs/resolve/main/belinda.wav"
... }
... ]
... },
... {
... "role": "user",
... "content": [
... {
... "type": "text",
... "text": "The sun rises in the east and sets in the west. This simple fact has been observed by humans for thousands of years."
... }
... ]
... }
... ]
>>> inputs = processor.apply_chat_template(conversation, return_dict=True, tokenize=True, sampling_rate=24000, return_tensors="pt")
>>> inputs = inputs.to(model.device)
>>> outputs = model(**inputs)HiggsAudioV2ForConditionalGeneration
classe transformers.HiggsAudioV2ForConditionalGeneration
< source >( config: HiggsAudioV2Configuse_text_head: bool = False )
Parâmetros
- config (HiggsAudioV2Config) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.
- use_text_head (
bool, opcional, padrão é False) — Se deve usar uma cabeça de modelo de linguagem de texto. Essa cabeça não é necessária para a geração, mas pode ser usada para calcular a perda de texto durante o treinamento.
O modelo Higgs Audio, um modelo de transformer auto-regressivo semelhante ao Llama com FFN duplo.
Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)
Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.BoolTensor] = Noneaudio_input_ids: typing.Optional[torch.LongTensor] = Noneaudio_input_ids_mask: typing.Optional[torch.LongTensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneaudio_labels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ~models.modeling_outputs.CausalLMOutputWithPast
Parâmetros
- input_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.
- attention_mask (
torch.BoolTensorde forma(batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em[0, 1]:- 1 para tokens que não estão mascarados,
- 0 para tokens que estão mascarados.
- audio_input_ids (
torch.LongTensorde forma(batch_size, num_audio_frames, num_codebooks), opcional) — Índices dos tokens do codebook de áudio.Os índices podem ser obtidos usando HiggsAudioV2TokenizerModel.encode().
- audio_input_ids_mask (
torch.BoolTensorde forma(batch_size, num_audio_frames), opcional) — Indica quais quadros de áudio emaudio_input_idssão válidos. - position_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, opcional) — Estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nopast_key_valuesretornado pelo modelo em uma etapa anterior da decodificação, quandouse_cache=Trueouconfig.use_cache=True.Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum
past_key_valuesfor passado, DynamicCache será inicializado por padrão.O modelo sairá no mesmo formato de cache que é fornecido como entrada.
Se
past_key_valuesforem usados, espera-se que o usuário insira apenas osinput_idsnão processados (aqueles que não têm seus estados de chave e valor passados fornecidos a este modelo) com a forma(batch_size, unprocessed_length), em vez de todos osinput_idscom a forma(batch_size, sequence_length). - inputs_embeds (
torch.FloatTensorde forma(batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, em vez de passarinput_ids, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices deinput_idsnos vetores associados do que a matriz de incorporação interna do modelo. - labels (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Rótulos para o cálculo da perda de modelagem de linguagem mascarada. Os índices devem estar em[0, ..., config.vocab_size]ou ser -100 (veja a docstring deinput_ids). Tokens com índices definidos como-100são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em[0, ..., config.vocab_size]. - audio_labels (
torch.LongTensorof shape(batch_size, num_audio_frames, num_codebooks), optional) — Labels for the audio codebook tokens for computing the masked language modeling loss. Indices should either be in[0, ..., config.codebook_size]. Token with indices set to-100are ignored (masked), the loss is only computed for the tokens with labels in[0, …, config.codebook_size]. Can be obtained usingoutput_labels=True` when calling HiggsAudioV2Processor. - use_cache (
bool, opcional) — Se definido comoTrue, os estados de chave-valorpast_key_valuessão retornados e podem ser usados para acelerar a decodificação (vejapast_key_values). - logits_to_keep (
Union[int, torch.Tensor], opcional, padrão0) — Se for umint, calcula os logits para os últimoslogits_to_keeptokens. Se for0, calcula os logits para todos osinput_ids(caso especial). Apenas os logits do último token são necessários para a geração, e calculá-los apenas para esse token pode economizar memória, o que se torna bastante significativo para sequências longas ou tamanho de vocabulário grande. Se for umtorch.Tensor, deve ser 1D, correspondendo aos índices a serem mantidos na dimensão de comprimento da sequência. Isso é útil ao usar o formato de tensor empacotado (uma única dimensão para lote e comprimento da sequência).
Retorna
~models.modeling_outputs.CausalLMOutputWithPast
Um ~models.modeling_outputs.CausalLMOutputWithPast contendo os logits, a perda (se rótulos forem fornecidos) e outras saídas do modelo.
O método forward de HiggsAudioV2ForConditionalGeneration substitui o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
Exemplo:
>>> from transformers import AutoProcessor, HiggsAudioV2ForConditionalGeneration
>>> model_id = "eustlb/higgs-audio-v2-generation-3B-base"
>>> processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
>>> model = HiggsAudioV2ForConditionalGeneration.from_pretrained(model_id, device_map="auto")
>>> conversation = [
... {
... "role": "system",
... "content": [
... {
... "type": "text",
... "text": "Generate audio following instruction."
... }
... ]
... },
... {
... "role": "scene",
... "content": [
... {
... "type": "text",
... "text": "Audio is recorded from a quiet room."
... }
... ]
... },
... {
... "role": "user",
... "content": [
... {
... "type": "text",
... "text": "It was the night before my birthday. Hooray! It's almost here! It may not be a holiday, but it's the best day of the year."
... }
... ]
... },
... {
... "role": "assistant",
... "content": [
... {
... "type": "audio",
... "url": "https://huggingface.co/datasets/eustlb/dummy-audio-samples-higgs/resolve/main/belinda.wav"
... }
... ]
... },
... {
... "role": "user",
... "content": [
... {
... "type": "text",
... "text": "The sun rises in the east and sets in the west. This simple fact has been observed by humans for thousands of years."
... }
... ]
... }
... ]
>>> inputs = processor.apply_chat_template(conversation, return_dict=True, tokenize=True, sampling_rate=24000, return_tensors="pt")
>>> inputs = inputs.to(model.device)
>>> outputs = model(**inputs)generate
< source >( inputs: typing.Optional[torch.Tensor] = Nonegeneration_config: transformers.generation.configuration_utils.GenerationConfig | None = Nonelogits_processor: transformers.generation.logits_process.LogitsProcessorList | None = Nonestopping_criteria: transformers.generation.stopping_criteria.StoppingCriteriaList | None = Noneprefix_allowed_tokens_fn: collections.abc.Callable[[int, torch.Tensor], list[int]] | None = Nonesynced_gpus: bool | None = Noneassistant_model: typing.Optional[ForwardRef('PreTrainedModel')] = Nonestreamer: typing.Optional[ForwardRef('BaseStreamer')] = Nonenegative_prompt_ids: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonecustom_generate: str | collections.abc.Callable | None = None**kwargs ) → ModelOutput or torch.LongTensor
Parâmetros
- inputs (
torch.Tensorde forma variável dependendo da modalidade, opcional) — A sequência usada como prompt para a geração ou como entrada do modelo para o codificador. SeNone, o método a inicializa combos_token_ide um tamanho de lote de 1. Para modelos apenas de decodificador,inputsdeve estar no formato deinput_ids. Para modelos codificador-decodificador, inputs pode representar qualquer um deinput_ids,input_values,input_featuresoupixel_values. - generation_config (GenerationConfig, opcional) —
A configuração de geração a ser usada como parametrização base para a chamada de geração. Os
**kwargspassados para generate que correspondam aos atributos degeneration_configos sobrescreverão. Segeneration_confignão for fornecido, o padrão será usado, que tem a seguinte prioridade de carregamento: 1) do arquivo de modelogeneration_config.json, se existir; 2) da configuração do modelo. Observe que os parâmetros não especificados herdarão os valores padrão de GenerationConfig, cuja documentação deve ser consultada para parametrizar a geração. - logits_processor (
LogitsProcessorList, opcional) — Processadores de logits personalizados que complementam os processadores de logits padrão criados a partir dos argumentos e da configuração de geração. Se um processador de logits for passado que já foi criado com os argumentos ou com uma configuração de geração, um erro será lançado. Este recurso é destinado a usuários avançados. - stopping_criteria (
StoppingCriteriaList, opcional) — Critérios de parada personalizados que complementam os critérios de parada padrão criados a partir dos argumentos e de uma configuração de geração. Se um critério de parada for passado que já foi criado com os argumentos ou com uma configuração de geração, um erro será lançado. Se o seu critério de parada depende da entradascores, certifique-se de passarreturn_dict_in_generate=True, output_scores=Trueparagenerate. Este recurso é destinado a usuários avançados. - prefix_allowed_tokens_fn (
Callable[[int, torch.Tensor], list[int]], opcional) — Se fornecida, esta função restringe a busca por feixe apenas aos tokens permitidos em cada etapa. Se não for fornecida, nenhuma restrição é aplicada. Esta função recebe 2 argumentos: o ID do lotebatch_ideinput_ids. Ela deve retornar uma lista com os tokens permitidos para a próxima etapa de geração, condicionada ao ID do lotebatch_ide aos tokens gerados anteriormenteinputs_ids. Este argumento é útil para geração condicionada ao prefixo, conforme descrito em Autoregressive Entity Retrieval. - synced_gpus (
bool, opcional) — Se deve continuar executando o loop while até max_length. A menos que seja sobrescrito, este sinalizador será definido comoTrueao usarFullyShardedDataParallelou DeepSpeed ZeRO Stage 3 com múltiplas GPUs para evitar deadlock caso uma GPU termine a geração antes das outras. Caso contrário, o valor padrão éFalse. - assistant_model (
PreTrainedModel, opcional) — Um modelo assistente que pode ser usado para acelerar a geração. O modelo assistente deve ter exatamente o mesmo tokenizer. A aceleração é obtida quando a previsão de tokens candidatos com o modelo assistente é muito mais rápida do que executar a geração com o modelo do qual você está chamando generate. Dessa forma, o modelo assistente deve ser muito menor. - streamer (
BaseStreamer, opcional) — Objeto que será usado para transmitir as sequências geradas. Os tokens gerados são passados porstreamer.put(token_ids)e o streamer é responsável por qualquer processamento adicional. - negative_prompt_ids (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — O prompt negativo necessário para alguns processadores, como o CFG. O tamanho do lote deve corresponder ao tamanho do lote de entrada. Esta é uma funcionalidade experimental, sujeita a alterações na API que podem quebrar a compatibilidade em versões futuras. - negative_prompt_attention_mask (
torch.LongTensorde forma(batch_size, sequence_length), opcional) — Attention_mask paranegative_prompt_ids. - custom_generate (
strouCallable, opcional) — Um dos seguintes:str(nome do repositório no Hugging Face Hub): executa a função personalizadageneratedefinida emcustom_generate/generate.pynesse repositório, em vez do método padrãogenerate. O repositório substitui completamente a lógica de geração, e o tipo de retorno pode ser diferente.str(caminho do repositório local): o mesmo que acima, mas a partir de um caminho local. Diretórios locais também exigemtrust_remote_code=Trueporque ocustom_generate/generate.pylocal é executado.Callable:generateexecutará as etapas habituais de preparação da entrada e, em seguida, chamará a função fornecida para executar o loop de decodificação. Para mais informações, consulte a documentação.
- kwargs (
dict[str, Any], opcional) — Parametrização ad hoc degeneration_confige/ou kwargs específicos do modelo adicionais que serão encaminhados para a funçãoforwarddo modelo. Se o modelo for um modelo encoder-decoder, os kwargs específicos do encoder não devem ter prefixo e os kwargs específicos do decoder devem ter o prefixo decoder_.
Retorna
ModelOutput ou torch.LongTensor
Um ModelOutput (se return_dict_in_generate=True
ou quando config.return_dict_in_generate=True) ou um torch.LongTensor.
Se o modelo não for um modelo encoder-decoder (model.config.is_encoder_decoder=False), os tipos possíveis de
ModelOutput são:
Se o modelo for um modelo encoder-decoder (model.config.is_encoder_decoder=True), os tipos possíveis de
ModelOutput são:
Gera sequências de ids de tokens para modelos com uma cabeça de modelagem de linguagem.
A maioria dos parâmetros de controle de geração é definida em
generation_config, que, se não for fornecida, será definida como a configuração de geração padrão do modelo. Você pode sobrescrever qualquergeneration_configpassando os parâmetros correspondentes para generate(), por exemplo,.generate(inputs, num_beams=4, do_sample=True).Para uma visão geral das estratégias de geração e exemplos de código, consulte o guia a seguir.