Transformers documentation

Higgs Audio V2

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Model ini disumbangkan ke Hugging Face Transformers pada 2026-02-19.

Higgs Audio V2

Ikhtisar

Higgs Audio V2 adalah model dasar audio yang kuat yang dikembangkan oleh Boson AI. Model ini telah dilatih sebelumnya (pretrained) pada lebih dari 10 juta jam data audio dan kumpulan data teks yang beragam. Meskipun tidak memiliki pelatihan pasca (post-training) atau penyesuaian halus (fine-tuning), Higgs Audio v2 unggul dalam generasi audio yang ekspresif, berkat pemahaman bahasa dan akustiknya yang mendalam.

Arsitektur Model:

Higgs Audio v2 adopts the "generation variant" depicted in the architecture figure above. Its strong performance is driven by three key technical innovations:

Mengembangkan pipeline anotasi otomatis yang memanfaatkan beberapa model ASR, model klasifikasi peristiwa suara, dan model pemahaman audio internal kami. Dengan pipeline ini, kami membersihkan dan mengannotasi 10 juta jam data audio, yang kami sebut sebagai AudioVerse. Model pemahaman internal ini di-finetune di atas Higgs Audio v1 Understanding, yang mengadopsi “understanding variant” yang ditunjukkan pada diagram arsitektur.
Melatih tokenizer audio terpadu dari awal yang menangkap fitur semantik dan akustik.
Arsitektur DualFFN yang diusulkan, yang meningkatkan kemampuan LLM untuk memodelkan token akustik dengan overhead komputasi yang minimal.

Penggunaan

Semua cuplikan di bawah ini mencerminkan pengujian integrasi di test_higgs_audio.py, memastikan dokumentasi tetap selaras dengan alur kerja yang didukung secara resmi.

Suara pintar satu pembicara

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

Suara cerdas multi-pembicara

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

Kloning suara 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")

Kloning suara multi-pembicara

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

Inferensi berbatch

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"])

Pelatihan

Secara default, model tidak memuat kepala pemodelan bahasa teks untuk menghemat memori (pengurangan ~1.5GiB), karena tidak diperlukan untuk generasi. Namun, saat melatih model, Anda membutuhkan kepala teks untuk menghitung loss pada token teks. Untuk mengaktifkannya, atur use_text_head=True saat menginstansiasi model (lihat contoh di bawah).

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

Model ini disumbangkan oleh Shuai Zheng dan Eustache Le Bihan. Kode aslinya dapat ditemukan di sini.

HiggsAudioV2Config

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

Parameter

vocab_size (int, opsional, default 128256) — Ukuran kosakata model. Menentukan jumlah token berbeda yang dapat direpresentasikan oleh input_ids.
hidden_size (int, opsional, default 3072) — Dimensi dari representasi tersembunyi.
intermediate_size (int, opsional, default 8192) — Dimensi representasi MLP.
num_hidden_layers (int, opsional, default 28) — Jumlah lapisan tersembunyi dalam decoder Transformer.
num_attention_heads (int, opsional, default 24) — Jumlah attention head untuk setiap lapisan attention di decoder Transformer.
num_key_value_heads (int, opsional, default 8) — Ini adalah jumlah key_value heads yang harus digunakan untuk mengimplementasikan Grouped Query Attention. Jika num_key_value_heads=num_attention_heads, model akan menggunakan Multi Head Attention (MHA), jika num_key_value_heads=1 model akan menggunakan Multi Query Attention (MQA), selain itu GQA yang digunakan. Saat mengkonversi checkpoint multi-head menjadi checkpoint GQA, setiap group key dan value head harus dibangun dengan meanpooling semua head asli di dalam grup tersebut. Untuk detail lebih lanjut, lihat paper ini. Jika tidak ditentukan, akan default ke num_attention_heads.
hidden_act (str, opsional, defaultnya silu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
max_position_embeddings (int, opsional, default 2048) — Panjang maksimum urutan yang mungkin digunakan dengan model ini.
initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
rms_norm_eps (float, opsional, defaultnya 1e-05) — Epsilon yang digunakan oleh lapisan normalisasi rms.
use_cache (bool, opsional, defaultnya True) — Apakah model harus mengembalikan perhatian kunci/nilai terakhir (tidak digunakan oleh semua model). Hanya relevan jika config.is_decoder=True atau ketika model adalah model generatif yang hanya decoder.
pad_token_id (int, opsional, default 128001) — ID token yang digunakan untuk padding dalam kosakata.
bos_token_id (int, opsional, default 1) — ID token yang digunakan untuk awal aliran (beginning-of-stream) dalam kosakata.
eos_token_id (Union[int, list[int]], opsional, default 128009) — ID token yang digunakan untuk end-of-stream dalam kosakata.
pretraining_tp (int, opsional, default 1) — Fitur eksperimental. Rank tensor parallelism yang digunakan selama pretraining. Silakan lihat dokumen ini untuk memahaminya lebih lanjut. Nilai ini diperlukan untuk memastikan reproduktibilitas hasil pretraining secara persis. Silakan lihat isu ini.
tie_word_embeddings (bool, opsional, default False) — Apakah akan mengikat bobot embedding sesuai dengan pemetaan tied_weights_keys model.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opsional) — Kamus yang berisi parameter konfigurasi untuk embedding RoPE. Kamus tersebut harus berisi nilai untuk rope_theta dan secara opsional parameter yang digunakan untuk penskalaan jika Anda ingin menggunakan RoPE dengan max_position_embeddings yang lebih panjang.
attention_bias (bool, opsional, default False) — Apakah akan menggunakan bias pada lapisan proyeksi query, key, value, dan output selama self-attention.
attention_dropout (Union[int, float], opsional, default 0.0) — Rasio dropout untuk probabilitas perhatian.
mlp_bias (bool, opsional, default False) — Apakah akan menggunakan bias pada lapisan up_proj, down_proj, dan gate_proj di dalam lapisan MLP.
head_dim (int, opsional, default 128) — Dimensi head perhatian. Jika None, nilainya akan default ke hidden_size // num_attention_heads
num_codebooks (int, opsional, default 8) — Jumlah codebook paralel yang digunakan oleh model.
codebook_size (int, opsional, defaultnya 1024) — Jumlah codebook paralel yang digunakan oleh model.
audio_token_id (int, opsional, default 128016) — Indeks token audio yang digunakan sebagai placeholder untuk audio input.
audio_bos_token_id (int, opsional, default 128013) — ID token untuk token awal-sekuens (beginning-of-sequence) pada output audio.
audio_delay_token_id (int, opsional, default 128014) — ID token yang digunakan untuk pola penundaan audio dalam generasi multi-codebook.
audio_stream_bos_id (int, opsional, default 1024) — ID untuk token awal-stream dalam urutan audio.
audio_stream_eos_id (int, opsional, default 1025) — ID untuk token end-of-stream dalam urutan audio.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari HiggsAudioV2ForConditionalGeneration. Kelas ini digunakan untuk membuat model Higgs Audio V2 sesuai dengan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari bosonai/higgs-audio-v2-generation-3B-base

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

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

HiggsAudioV2Processor

kelas transformers.HiggsAudioV2Processor

< source >

Parameter

feature_extractor (DacFeatureExtractor) — Instans dari DacFeatureExtractor. Feature extractor adalah input yang wajib.
tokenizer (AutoTokenizer) — Instans dari AutoTokenizer. Tokenizer adalah input yang wajib.
audio_tokenizer (HiggsAudioV2TokenizerModel) — Instans dari HiggsAudioV2TokenizerModel. Audio tokenizer adalah input yang wajib.
chat_template (str, opsional) — String template untuk format chat saat menggabungkan interaksi teks dan audio.
audio_token (str, opsional, default "<|AUDIO_OUT|>") — Token yang digunakan untuk mewakili output audio dalam urutan teks.
audio_bos_token (str, opsional, default "<|audio_out_bos|>") — Token awal-sekuens untuk keluaran audio.
audio_eos_token (str, opsional, defaultnya "<|audio_eos|>") — Token akhir-sekuens untuk keluaran audio.
audio_delay_token (str, opsional, defaultnya "<|reserved_special_token_6|>") — Token yang digunakan untuk pola penundaan audio dalam generasi multi-codebook.
audio_stream_bos_id (int, opsional, default 1024) — ID untuk token awal-stream dalam urutan audio.
audio_stream_eos_id (int, opsional, default 1025) — ID untuk token end-of-stream dalam urutan audio.

Membangun prosesor Higgs Audio yang membungkus DacFeatureExtractor, AutoTokenizer, dan HiggsAudioV2TokenizerModel menjadi satu prosesor. Ia mewarisi fungsionalitas ekstraksi fitur audio, tokenizer, dan encode/decode audio. Lihat call() dan decode() untuk informasi lebih lanjut.

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

decode

< source >

( audio_input_ids )

HiggsAudioV2Model

kelas transformers.HiggsAudioV2Model

< source >

( config: HiggsAudioV2Config )

Parameter

config (HiggsAudioV2Config) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Model Higgs Audio V2 polos yang menghasilkan hidden-states mentah tanpa head spesifik di atasnya.

Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)

Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

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.Tensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ~models.modeling_outputs.BaseModelOutputWithPast

Parameter

input_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks token dari urutan input dalam kosakata. Padding akan diabaikan secara default.
Indeks dapat diperoleh menggunakan AutoTokenizer. Lihat PreTrainedTokenizer.encode() dan PreTrainedTokenizer.call() untuk detailnya.

Apa itu input ID?
audio_input_ids (torch.LongTensor dengan bentuk (batch_size, num_audio_frames, num_codebooks), opsional) — Indeks dari token codebook audio.
Indeks dapat diperoleh menggunakan HiggsAudioV2TokenizerModel.encode().
attention_mask (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Mask untuk menghindari eksekusi attention pada indeks token padding. Nilai mask dipilih dari [0, 1]:
- 1 untuk token yang tidak dimasker,
- 0 untuk token yang dimasker.
Apa itu attention mask?
audio_input_ids_mask (torch.BoolTensor dengan bentuk (batch_size, num_audio_frames), opsional) — Menunjukkan frame audio mana dalam audio_input_ids yang valid.
position_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks posisi token dari setiap urutan input dalam position embeddings. Dipilih dalam rentang [0, config.n_positions - 1].
Apa itu ID posisi?
past_key_values (~cache_utils.Cache, opsional) — Hidden-states yang sudah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan untuk mempercepat decoding berurutan. Ini biasanya terdiri dari past_key_values yang dikembalikan oleh model pada tahap decoding sebelumnya, ketika use_cache=True atau config.use_cache=True.
Hanya instance Cache yang diizinkan sebagai input, lihat panduan kv cache kami. Jika tidak ada past_key_values yang diteruskan, DynamicCache akan diinisialisasi secara default.

Model akan menghasilkan format cache yang sama dengan yang diberikan sebagai input.

Jika past_key_values digunakan, pengguna diharapkan hanya memasukkan input_ids yang belum diproses (yang tidak memiliki state past key value yang diberikan ke model ini) dengan bentuk (batch_size, unprocessed_length) alih-alih semua input_ids dengan bentuk (batch_size, sequence_length).
inputs_embeds (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size), opsional) — Secara opsional, alih-alih meneruskan input_ids, Anda dapat memilih untuk langsung meneruskan representasi tertanam. Hal ini berguna jika Anda ingin memiliki kendali lebih atas cara mengonversi indeks input_ids menjadi vektor terkait, dibandingkan dengan matriks pencarian penanaman internal model.
use_cache (bool, opsional) — Jika diset ke True, state kunci-nilai past_key_values akan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihat past_key_values).

Mengembalikan

~models.modeling_outputs.BaseModelOutputWithPast

Output decoder biasa dengan posisi placeholder yang sudah diganti oleh embedding audio yang sesuai.

Metode forward dari HiggsAudioV2Model menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

Contoh:

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

kelas transformers.HiggsAudioV2ForConditionalGeneration

< source >

( config: HiggsAudioV2Configuse_text_head: bool = False )

Parameter

config (HiggsAudioV2Config) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.
use_text_head (bool, opsional, default False) — Apakah akan menggunakan head model bahasa teks. Head semacam ini tidak diperlukan untuk generasi, tetapi dapat digunakan untuk menghitung loss teks saat pelatihan.

Model Higgs Audio, sebuah model transformer auto-regresif mirip Llama dengan dual-FFN.

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.Tensor] = 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

Parameter

input_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks token dari urutan input dalam kosakata. Padding akan diabaikan secara default.
Indeks dapat diperoleh menggunakan AutoTokenizer. Lihat PreTrainedTokenizer.encode() dan PreTrainedTokenizer.call() untuk detailnya.

Apa itu input ID?
attention_mask (torch.BoolTensor dengan bentuk (batch_size, sequence_length), opsional) — Mask untuk menghindari eksekusi attention pada indeks token padding. Nilai mask dipilih dari [0, 1]:
- 1 untuk token yang tidak dimasker,
- 0 untuk token yang dimasker.
Apa itu attention mask?
audio_input_ids (torch.LongTensor dengan bentuk (batch_size, num_audio_frames, num_codebooks), opsional) — Indeks dari token codebook audio.
Indeks dapat diperoleh menggunakan HiggsAudioV2TokenizerModel.encode().
audio_input_ids_mask (torch.BoolTensor dengan bentuk (batch_size, num_audio_frames), opsional) — Menunjukkan frame audio mana dalam audio_input_ids yang valid.
position_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Indeks posisi token dari setiap urutan input dalam position embeddings. Dipilih dalam rentang [0, config.n_positions - 1].
Apa itu ID posisi?
past_key_values (~cache_utils.Cache, opsional) — Hidden-states yang sudah dihitung sebelumnya (key dan values di blok self-attention dan di blok cross-attention) yang dapat digunakan untuk mempercepat decoding berurutan. Ini biasanya terdiri dari past_key_values yang dikembalikan oleh model pada tahap decoding sebelumnya, ketika use_cache=True atau config.use_cache=True.
Hanya instance Cache yang diizinkan sebagai input, lihat panduan kv cache kami. Jika tidak ada past_key_values yang diteruskan, DynamicCache akan diinisialisasi secara default.

Model akan menghasilkan format cache yang sama dengan yang diberikan sebagai input.

Jika past_key_values digunakan, pengguna diharapkan hanya memasukkan input_ids yang belum diproses (yang tidak memiliki state past key value yang diberikan ke model ini) dengan bentuk (batch_size, unprocessed_length) alih-alih semua input_ids dengan bentuk (batch_size, sequence_length).
inputs_embeds (torch.Tensor dengan bentuk (batch_size, sequence_length, hidden_size), opsional) — Secara opsional, alih-alih meneruskan input_ids, Anda dapat memilih untuk langsung meneruskan representasi tertanam. Hal ini berguna jika Anda ingin memiliki kendali lebih atas cara mengonversi indeks input_ids menjadi vektor terkait, dibandingkan dengan matriks pencarian penanaman internal model.
labels (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Label untuk menghitung kerugian pemodelan bahasa yang disamarkan (masked language modeling). Indeks harus berada dalam [0, ..., config.vocab_size] atau -100 (lihat docstring input_ids). Token dengan indeks yang disetel ke -100 diabaikan (disamarkan), kerugian hanya dihitung untuk token dengan label dalam [0, ..., config.vocab_size].
audio_labels (torch.LongTensor of 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 using output_labels=True` when calling HiggsAudioV2Processor.
use_cache (bool, opsional) — Jika diset ke True, state kunci-nilai past_key_values akan dikembalikan dan dapat digunakan untuk mempercepat decoding (lihat past_key_values).
logits_to_keep (Union[int, torch.Tensor], opsional, default 0) — Jika berupa int, hitung logits untuk logits_to_keep token terakhir. Jika 0, hitung logits untuk semua input_ids (kasus khusus). Hanya logits token terakhir yang diperlukan untuk generasi, dan menghitungnya hanya untuk token tersebut dapat menghemat memori, yang menjadi cukup signifikan untuk urutan panjang atau ukuran kosakata besar. Jika berupa torch.Tensor, harus 1D yang sesuai dengan indeks yang akan dipertahankan pada dimensi panjang urutan. Ini berguna saat menggunakan format tensor terpadu (satu dimensi untuk batch dan panjang urutan).

Mengembalikan

~models.modeling_outputs.CausalLMOutputWithPast

~models.modeling_outputs.CausalLMOutputWithPast yang berisi logits, loss (jika label disediakan), dan output lain dari model.

Metode forward dari HiggsAudioV2ForConditionalGeneration menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

Contoh:

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

Parameter

inputs (torch.Tensor dengan bentuk yang bervariasi tergantung pada modalitas, opsional) — Urutan yang digunakan sebagai prompt untuk generasi atau sebagai input model ke encoder. Jika None, metode ini menginisialisasinya dengan bos_token_id dan ukuran batch 1. Untuk model decoder-only, inputs harus dalam format input_ids. Untuk model encoder-decoder, inputs dapat mewakili salah satu dari input_ids, input_values, input_features, atau pixel_values.
generation_config (GenerationConfig, opsional) — Konfigurasi generasi yang akan digunakan sebagai parametrisasi dasar untuk panggilan generasi. **kwargs yang diteruskan ke generate dan cocok dengan atribut dari generation_config akan menimpanya. Jika generation_config tidak disediakan, nilai default akan digunakan, yang memiliki prioritas pemuatan sebagai berikut: 1) dari file model generation_config.json, jika ada; 2) dari konfigurasi model. Perhatikan bahwa parameter yang tidak ditentukan akan mewarisi nilai default dari GenerationConfig, yang dokumentasinya harus diperiksa untuk memparametrisasi generasi.
logits_processor (LogitsProcessorList, opsional) — Prosesor logits kustom yang melengkapi prosesornya logits default yang dibangun dari argumen dan konfigurasi generasi. Jika prosesornya logits yang sudah dibuat dengan argumen atau konfigurasi generasi dilewatkan, sebuah error akan dilempar. Fitur ini ditujukan untuk pengguna tingkat lanjut.
stopping_criteria (StoppingCriteriaList, opsional) — Kriteria penghentian kustom yang melengkapi kriteria penghentian default yang dibangun dari argumen dan konfigurasi generasi. Jika kriteria penghentian yang di-pass sudah dibuat dengan argumen atau konfigurasi generasi, sebuah error akan dilempar. Jika kriteria penghentian Anda bergantung pada input scores, pastikan Anda meng-pass return_dict_in_generate=True, output_scores=True ke generate. Fitur ini ditujukan untuk pengguna tingkat lanjut.
prefix_allowed_tokens_fn (Callable[[int, torch.Tensor], list[int]], opsional) — Jika disediakan, fungsi ini membatasi pencarian beam hanya pada token yang diizinkan di setiap langkah. Jika tidak disediakan, tidak ada batasan yang diterapkan. Fungsi ini mengambil 2 argumen: ID batch batch_id dan input_ids. Fungsi ini harus mengembalikan daftar token yang diizinkan untuk langkah generasi berikutnya yang dikondisikan pada ID batch batch_id dan token yang sebelumnya dihasilkan inputs_ids. Argumen ini berguna untuk generasi yang dibatasi berdasarkan prefiks, seperti yang dijelaskan dalam Autoregressive Entity Retrieval.
synced_gpus (bool, opsional) — Apakah akan terus menjalankan loop while hingga max_length. Kecuali di-override, flag ini akan diset ke True jika menggunakan FullyShardedDataParallel atau DeepSpeed ZeRO Stage 3 dengan beberapa GPU untuk menghindari deadlock jika satu GPU selesai menghasilkan sebelum GPU lainnya. Jika tidak, defaultnya adalah False.
assistant_model (PreTrainedModel, opsional) — Model asisten yang dapat digunakan untuk mempercepat generasi. Model asisten harus memiliki tokenizer yang persis sama. Percepatan tercapai ketika memprediksi token kandidat dengan model asisten jauh lebih cepat daripada menjalankan generasi dengan model yang Anda panggil generate dari. Oleh karena itu, model asisten harus jauh lebih kecil.
streamer (BaseStreamer, opsional) — Objek yang akan digunakan untuk streaming urutan yang dihasilkan. Token yang dihasilkan diteruskan melalui streamer.put(token_ids) dan objek tersebut bertanggung jawab untuk pemrosesan lebih lanjut.
negative_prompt_ids (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Prompt negatif yang diperlukan oleh beberapa prosesor seperti CFG. Ukuran batch harus sesuai dengan ukuran batch input. Ini adalah fitur eksperimental, yang dapat mengalami perubahan API yang merusak (breaking changes) pada versi mendatang.
negative_prompt_attention_mask (torch.LongTensor dengan bentuk (batch_size, sequence_length), opsional) — Attention_mask untuk negative_prompt_ids.
custom_generate (str atau Callable, opsional) — Salah satu dari berikut ini:
- str (nama repositori Hugging Face Hub): menjalankan fungsi generate kustom yang didefinisikan di custom_generate/generate.py pada repositori tersebut, bukan metode generate standar. Repositori ini sepenuhnya menggantikan logika generasi, dan tipe pengembaliannya dapat berbeda.
- str (jalur repositori lokal): sama seperti di atas tetapi dari jalur lokal. Direktori lokal juga memerlukan trust_remote_code=True karena custom_generate/generate.py lokal dieksekusi.
- Callable: generate akan melakukan langkah-langkah persiapan input yang biasa, lalu memanggil callable yang diberikan untuk menjalankan loop decoding. Untuk informasi lebih lanjut, lihat dokumentasinya.
kwargs (dict[str, Any], opsional) — Parametrisasi ad hoc untuk generation_config dan/atau kwargs spesifik model tambahan yang akan diteruskan ke fungsi forward dari model. Jika model tersebut adalah model encoder-decoder, kwargs spesifik encoder tidak boleh diberi awalan dan kwargs spesifik decoder harus diberi awalan decoder_.

Mengembalikan

ModelOutput atau torch.LongTensor

Sebuah ModelOutput (jika return_dict_in_generate=True atau ketika config.return_dict_in_generate=True) atau sebuah torch.LongTensor.

Jika model bukan model encoder-decoder (model.config.is_encoder_decoder=False), tipe ModelOutput yang mungkin adalah:

Jika model adalah model encoder-decoder (model.config.is_encoder_decoder=True), tipe ModelOutput yang mungkin adalah:

Membuat rangkaian id token untuk model dengan kepala pemodelan bahasa.

Sebagian besar parameter pengendali generasi diatur di generation_config yang, jika tidak diteruskan, akan disetel ke konfigurasi generasi default model. Anda dapat menimpa generation_config mana pun dengan meneruskan parameter yang sesuai ke generate(), misalnya .generate(inputs, num_beams=4, do_sample=True).

Untuk ringkasan strategi generasi dan contoh kode, lihat panduan berikut.

Update on GitHub

←GraniteSpeechPlus Tokenizer Higgs Audio V2→