Transformers documentation
Higgs Audio V2
Эта модель была добавлена в Hugging Face Transformers 19.02.2026.
Higgs Audio V2
Обзор
Higgs Audio V2 — это мощная базовая модель для работы с аудио, разработанная Boson AI. Модель была предварительно обучена на более чем 10 миллионах часов аудиоданных и разнообразном наборе текстовых данных. Несмотря на отсутствие постобучения или дообучения, Higgs Audio v2 демонстрирует выдающиеся результаты в генерации выразительного аудио благодаря глубокому пониманию языка и акустики.
Архитектура модели:
- Мы разработали автоматизированный конвейер аннотации, использующий несколько моделей ASR, модели классификации звуковых событий и нашу собственную модель понимания аудио. С помощью этого конвейера мы очистили и аннотировали 10 миллионов часов аудиоданных, которые мы называем AudioVerse. Модель понимания, разработанная в нашей компании, дообучена на основе Higgs Audio v1 Understanding, которая использует «вариант понимания», показанный на схеме архитектуры.
- Обучили с нуля единый аудио-токенизатор, который захватывает как семантические, так и акустические признаки.
- Предложенная архитектура DualFFN, которая повышает способность LLM моделировать акустические токены с минимальными вычислительными затратами.
Использование
Все приведённые ниже фрагменты кода соответствуют интеграционным тестам в test_higgs_audio.py, что обеспечивает синхронизацию документации с официально поддерживаемыми сценариями использования.
Голосовая система с одним говорящим
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")Умный голос с несколькими спикерами
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")Клонирование голоса в режиме 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")Клонирование голоса нескольких говорящих
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")Пакетный вывод
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"])Обучение
По умолчанию модель не загружает текстовую голову для моделирования языка, чтобы сэкономить память (сокращение примерно на 1,5 ГиБ), так как она не требуется для генерации. Однако при обучении модели текстовая голова необходима для вычисления потерь на текстовых токенах. Чтобы включить её, установите
use_text_head=Trueпри инициализации модели (см. пример ниже).
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()Эта модель была предоставлена Shuai Zheng и Eustache Le Bihan. Исходный код можно найти здесь.
HiggsAudioV2Config
класс 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 )
Параметры
- vocab_size (
int, необязательный, по умолчанию128256) — Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены вinput_ids. - hidden_size (
int, необязательный, по умолчанию3072) — Размерность скрытых представлений. - intermediate_size (
int, необязательный, по умолчанию8192) — Размерность представлений MLP. - num_hidden_layers (
int, необязательный, по умолчанию28) — Количество скрытых слоев в декодере Transformer. - num_attention_heads (
int, необязательный, по умолчанию24) — Количество головок внимания в каждом слое внимания декодера Transformer. - num_key_value_heads (
int, необязательный, по умолчанию8) — Это количество ключевых и value-голов, используемых для реализации Grouped Query Attention. Еслиnum_key_value_heads=num_attention_heads, модель использует Multi Head Attention (MHA); еслиnum_key_value_heads=1— Multi Query Attention (MQA); в остальных случаях применяется GQA. При конвертации мультиголовного чекпоинта в GQA-чекпоинт каждая групповая ключевая и value-голова должна конструироваться путем усреднения (meanpooling) всех исходных голов в этой группе. Дополнительные подробности — в этой статье. Если значение не указано, по умолчанию используетсяnum_attention_heads. - hidden_act (
str, необязательный, по умолчаниюsilu) — Нелинейная функция активации (функция или строка) в декодере. Например,"gelu","relu","silu"и т. д. - max_position_embeddings (
int, необязательный, по умолчанию2048) — Максимальная длина последовательности, с которой может использоваться эта модель. - initializer_range (
float, необязательный, по умолчанию0.02) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов. - rms_norm_eps (
float, необязательный, по умолчанию1e-05) — Значение epsilon, используемое слоями нормализации rms. - use_cache (
bool, необязательный, по умолчаниюTrue) — Указывает, должен ли модель возвращать последние ключи/значения внимания (не используется во всех моделях). Актуально только еслиconfig.is_decoder=Trueили если модель является генеративной моделью только с декодером. - pad_token_id (
int, необязательный, по умолчанию128001) — Идентификатор токена, используемого для выравнивания (padding) в словаре. - bos_token_id (
int, необязательный, по умолчанию1) — Идентификатор токена, используемого для обозначения начала потока в словаре. - eos_token_id (
Union[int, list[int]], необязательный, по умолчанию128009) — Идентификатор токена, используемого для обозначения конца потока в словаре. - pretraining_tp (
int, необязательный, по умолчанию1) — Экспериментальная функция. Ранг тензорного параллелизма, использованный во время предварительного обучения. Подробнее об этом см. в этом документе. Это значение необходимо для обеспечения точной воспроизводимости результатов предварительного обучения. См. также этот вопрос. - 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) — Использовать ли смещение (bias) в слоях проекции query, key, value и output при само-внимании. - attention_dropout (
Union[int, float], необязательный, по умолчанию0.0) — Коэффициент dropout для вероятностей внимания. - mlp_bias (
bool, необязательный, по умолчаниюFalse) — Использовать ли смещение (bias) в слоях up_proj, down_proj и gate_proj внутри MLP-слоёв. - head_dim (
int, необязательный, по умолчанию128) — Размерность головы внимания. Если значение равно None, по умолчанию используется hidden_size // num_attention_heads - num_codebooks (
int, необязательный, по умолчанию8) — Количество параллельных кодовых книг, используемых моделью. - codebook_size (
int, необязательный, по умолчанию1024) — Количество параллельных кодовых книг, используемых моделью. - audio_token_id (
int, необязательный, по умолчанию128016) — Индекс аудио-токена, используемый как плейсхолдер для входного аудио. - audio_bos_token_id (
int, необязательный, по умолчанию 128013) — Идентификатор токена начала последовательности для аудиовыхода. - audio_delay_token_id (
int, необязательный, по умолчанию 128014) — Идентификатор токена, используемый для шаблона задержки аудио при генерации с несколькими кодовыми книгами. - audio_stream_bos_id (
int, необязательный, по умолчанию 1024) — Идентификатор токена начала потока в аудиопоследовательностях. - audio_stream_eos_id (
int, необязательный, по умолчанию 1025) — Идентификатор токена конца потока в аудиопоследовательностях.
Это класс конфигурации для хранения настроек модели HiggsAudioV2ForConditionalGeneration. Он используется для создания модели Higgs Audio V2 в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели bosonai/higgs-audio-v2-generation-3B-base.
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
Пример:
>>> 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
класс 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 )
Параметры
- feature_extractor (
DacFeatureExtractor) — экземпляр DacFeatureExtractor. Экстрактор признаков является обязательным входным параметром. - tokenizer (
AutoTokenizer) — экземпляр AutoTokenizer. Токенизатор является обязательным входным параметром. - audio_tokenizer (
HiggsAudioV2TokenizerModel) — экземпляр HiggsAudioV2TokenizerModel. Токенизатор аудио является обязательным входным параметром. - chat_template (
str, необязательный) — Строка-шаблон для форматирования чата при объединении текстовых и аудиовзаимодействий. - audio_token (
str, необязательный, по умолчанию"<|AUDIO_OUT|>") — Токен, используемый для представления аудиовыхода в текстовой последовательности. - audio_bos_token (
str, необязательный, по умолчанию"<|audio_out_bos|>") — Токен начала последовательности для аудиовыхода. - audio_eos_token (
str, необязательный, по умолчанию"<|audio_eos|>") — Токен конца последовательности для аудиовыхода. - audio_delay_token (
str, необязательный, по умолчанию"<|reserved_special_token_6|>") — Токен, используемый для паттерна задержки аудио при генерации с несколькими кодовыми книгами. - audio_stream_bos_id (
int, необязательный, по умолчанию 1024) — Идентификатор токена начала потока в аудиопоследовательностях. - audio_stream_eos_id (
int, необязательный, по умолчанию 1025) — Идентификатор токена конца потока в аудиопоследовательностях.
Создаёт процессор Higgs Audio, объединяющий DacFeatureExtractor, AutoTokenizer и HiggsAudioV2TokenizerModel в единый процессор. Он наследует функциональность извлечения аудиопризнаков, токенизации и кодирования/декодирования аудио. Подробнее см. call() и decode().
__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
класс transformers.HiggsAudioV2Model
< source >( config: HiggsAudioV2Config )
Параметры
- config (HiggsAudioV2Config) — Класс конфигурации модели, содержащий все параметры модели. Инициализация по файлу конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.
Модель Higgs Audio V2 без дополнительных компонентов, выводящая необработанные скрытые состояния (raw hidden-states) без какого-либо специализированного слоя (head) сверху.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
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
Параметры
- input_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
- audio_input_ids (
torch.LongTensorформы(batch_size, num_audio_frames, num_codebooks), необязательный) — Индексы токенов аудиокниги. Индексы можно получить с помощью HiggsAudioV2TokenizerModel.encode().Индексы можно получить с помощью HiggsAudioV2TokenizerModel.encode().
- attention_mask (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- audio_input_ids_mask (
torch.BoolTensorформы(batch_size, num_audio_frames), необязательный) — Указывает, какие кадры аудио вaudio_input_idsявляются действительными. - position_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, необязательный) — Предвычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно этоpast_key_values, возвращённые моделью на предыдущем этапе декодирования, когдаuse_cache=Trueилиconfig.use_cache=True.В качестве входного параметра допускается только экземпляр Cache, см. наше руководство по кэшу KV. Если
past_key_valuesне переданы, по умолчанию будет инициализирован DynamicCache.Модель будет выводить тот же формат кэша, который был передан на вход.
Если используются
past_key_values, ожидается, что пользователь передаст только необработанныеinput_ids(те, для которых в этой модели ещё не заданы состояния прошлых ключей и значений) формы(batch_size, unprocessed_length), а не всеinput_idsформы(batch_size, sequence_length). - inputs_embeds (
torch.FloatTensorформы(batch_size, sequence_length, hidden_size), необязательный) — При необходимости, вместо передачиinput_idsможно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексыinput_idsпреобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска эмбеддингов модели. - use_cache (
bool, необязательный) — Если установлено вTrue, возвращаются состояния ключей и значенийpast_key_values, которые можно использовать для ускорения декодирования (см.past_key_values).
Возвращает
~models.modeling_outputs.BaseModelOutputWithPast
Обычные выходные данные декодера, в которых позиции-заполнители уже заменены соответствующими аудио-эмбеддингами.
Метод forward модели HiggsAudioV2Model переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
Пример:
>>> 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
класс transformers.HiggsAudioV2ForConditionalGeneration
< source >( config: HiggsAudioV2Configuse_text_head: bool = False )
Параметры
- config (HiggsAudioV2Config) — Класс конфигурации модели, содержащий все параметры модели. Инициализация по файлу конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.
- use_text_head (
bool, необязательный, по умолчанию False) — Указывает, следует ли использовать текстовую голову языковой модели. Такая голова не требуется для генерации, но может использоваться для вычисления текстовой функции потерь при обучении.
Модель Higgs Audio — это авто-регрессивная трансформерная модель, похожая на Llama, с двойным FFN.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
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
Параметры
- input_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
- attention_mask (
torch.BoolTensorформы(batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- audio_input_ids (
torch.LongTensorформы(batch_size, num_audio_frames, num_codebooks), необязательный) — Индексы токенов аудиокниги. Индексы можно получить с помощью HiggsAudioV2TokenizerModel.encode().Индексы можно получить с помощью HiggsAudioV2TokenizerModel.encode().
- audio_input_ids_mask (
torch.BoolTensorформы(batch_size, num_audio_frames), необязательный) — Указывает, какие кадры аудио вaudio_input_idsявляются действительными. - position_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, необязательный) — Предвычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно этоpast_key_values, возвращённые моделью на предыдущем этапе декодирования, когдаuse_cache=Trueилиconfig.use_cache=True.В качестве входного параметра допускается только экземпляр Cache, см. наше руководство по кэшу KV. Если
past_key_valuesне переданы, по умолчанию будет инициализирован DynamicCache.Модель будет выводить тот же формат кэша, который был передан на вход.
Если используются
past_key_values, ожидается, что пользователь передаст только необработанныеinput_ids(те, для которых в этой модели ещё не заданы состояния прошлых ключей и значений) формы(batch_size, unprocessed_length), а не всеinput_idsформы(batch_size, sequence_length). - inputs_embeds (
torch.FloatTensorформы(batch_size, sequence_length, hidden_size), необязательный) — При необходимости, вместо передачиinput_idsможно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексыinput_idsпреобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска эмбеддингов модели. - labels (
torch.LongTensorформы(batch_size, sequence_length), необязательный) — Метки для вычисления потерь маскированного языкового моделирования. Индексы должны находиться в диапазоне[0, ..., config.vocab_size]или быть равны -100 (см. docstringinput_ids). Токены с индексами, установленными в-100, игнорируются (маскируются); потери вычисляются только для токенов с метками в диапазоне[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, необязательный) — Если установлено вTrue, возвращаются состояния ключей и значенийpast_key_values, которые можно использовать для ускорения декодирования (см.past_key_values). - logits_to_keep (
Union[int, torch.Tensor], необязательный, по умолчанию0) — Если передано значение типаint, вычисляет logits для последнихlogits_to_keepтокенов. Если указано0, logits вычисляются для всехinput_ids(особый случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типаtorch.Tensor, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (один размер для batch и длины последовательности).
Возвращает
~models.modeling_outputs.CausalLMOutputWithPast
Объект ~models.modeling_outputs.CausalLMOutputWithPast, содержащий логиты, потерю (если предоставлены метки) и другие выходные данные модели.
Метод forward класса HiggsAudioV2ForConditionalGeneration переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
Пример:
>>> 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
Параметры
- inputs (
torch.Tensorпроизвольной формы в зависимости от модальности, необязательный) — Последовательность, используемая в качестве промпта для генерации или в качестве входных данных для энкодера. ЕслиNone, метод инициализирует её с помощьюbos_token_idи размером батча, равным 1. Для моделей только с декодеромinputsдолжен быть в форматеinput_ids. Для моделей с энкодером-декодером inputs может представлять собойinput_ids,input_values,input_featuresилиpixel_values. - generation_config (GenerationConfig, optional) —
Конфигурация генерации, используемая в качестве базовой параметризации для вызова генерации.
**kwargs, передаваемые в generate и совпадающие с атрибутамиgeneration_config, будут переопределять их. Еслиgeneration_configне указан, будет использован вариант по умолчанию, который имеет следующий приоритет загрузки: 1) из файла моделиgeneration_config.json, если он существует; 2) из конфигурации модели. Обратите внимание, что не указанные параметры наследуют значения по умолчанию GenerationConfig, документация по которым должна быть проверена для параметризации генерации. - logits_processor (
LogitsProcessorList, необязательный) — Пользовательские обработчики logits, дополняющие стандартные обработчики logits, создаваемые на основе аргументов и конфигурации генерации. Если передан обработчик logits, который уже был создан с помощью аргументов или конфигурации генерации, возникает ошибка. Эта функция предназначена для опытных пользователей. - stopping_criteria (
StoppingCriteriaList, необязательный) — Пользовательские критерии остановки, дополняющие критерии остановки по умолчанию, формируемые на основе аргументов и конфигурации генерации. Если передан критерий остановки, который уже был создан с использованием этих аргументов или конфигурации генерации, будет выброшена ошибка. Если ваш критерий остановки зависит от входных данныхscores, убедитесь, что вы передаётеreturn_dict_in_generate=True, output_scores=Trueвgenerate. Эта функция предназначена для опытных пользователей. - prefix_allowed_tokens_fn (
Callable[[int, torch.Tensor], list[int]], необязательный) — Если указан, этот параметр ограничивает поиск лучами (beam search) только разрешёнными токенами на каждом шаге. Если не указан, ограничения не применяются. Функция принимает два аргумента: идентификатор батчаbatch_idиinput_ids. Она должна возвращать список разрешённых токенов для следующего шага генерации, зависящий от идентификатора батчаbatch_idи ранее сгенерированных токеновinputs_ids. Этот аргумент полезен для ограниченной генерации, обусловленной префиксом, как описано в Autoregressive Entity Retrieval. - synced_gpus (
bool, необязательный) — Определяет, следует ли продолжать выполнение цикла while до достижения max_length. Если значение не переопределено, этот флаг будет установлен вTrueпри использованииFullyShardedDataParallelили DeepSpeed ZeRO Stage 3 с несколькими GPU, чтобы избежать блокировки, если один GPU завершает генерацию раньше других. В противном случае по умолчанию устанавливаетсяFalse. - assistant_model (
PreTrainedModel, необязательный) — Модель ассистента, которая может использоваться для ускорения генерации. Модель ассистента должна использовать точно такой же токенизатор. Ускорение достигается, когда прогнозирование кандидатных токенов с помощью модели ассистента выполняется значительно быстрее, чем запуск генерации с моделью, от которой вы вызываете generate. В связи с этим модель ассистента должна быть значительно меньше. - streamer (
BaseStreamer, необязательный) — Объект, который будет использоваться для потоковой передачи сгенерированных последовательностей. Сгенерированные токены передаются черезstreamer.put(token_ids), а streamer отвечает за дальнейшую обработку. - negative_prompt_ids (
torch.LongTensorформы(batch_size, sequence_length), необязательный) — Негативный промпт, необходимый для некоторых процессоров, например CFG. Размер батча должен совпадать с размером входного батча. Это экспериментальная функция, которая может претерпеть несовместимые изменения API в будущих версиях. - negative_prompt_attention_mask (
torch.LongTensorформы(batch_size, sequence_length), необязательный) — Attention_mask дляnegative_prompt_ids. - custom_generate (
strилиCallable, необязательный) — Одно из следующих значений:str(имя репозитория Hugging Face Hub): выполняет пользовательскую функциюgenerate, определённую в файлеcustom_generate/generate.pyэтого репозитория, вместо стандартного методаgenerate. Репозиторий полностью заменяет логику генерации, а тип возвращаемого значения может отличаться.str(путь к локальному репозиторию): то же самое, но из локального пути. Для локальных каталогов также требуетсяtrust_remote_code=True, поскольку выполняется локальныйcustom_generate/generate.py.Callable:generateвыполнит стандартные шаги подготовки входных данных, а затем вызовет переданную callable для запуска цикла декодирования. Подробнее см. документацию.
- kwargs (
dict[str, Any], необязательный) — Служебная параметризацияgeneration_configи/или дополнительные специфичные для модели kwargs, которые будут переданы в функциюforwardмодели. Если модель является моделью с кодировщиком-декодировщиком, kwargs, специфичные для кодировщика, не должны иметь префикса, а kwargs, специфичные для декодера, должны иметь префикс decoder_.
Возвращает
ModelOutput или torch.LongTensor
ModelOutput (если return_dict_in_generate=True
или когда config.return_dict_in_generate=True) или torch.LongTensor.
Если модель не является моделью типа «кодировщик-декодировщик» (model.config.is_encoder_decoder=False), допустимые типы
ModelOutput:
Если модель является моделью с кодировщиком-декодировщиком (model.config.is_encoder_decoder=True), возможные типы
ModelOutput:
Генерирует последовательности идентификаторов токенов для моделей с заголовком языкового моделирования.
Большинство параметров, управляющих генерацией, задаются в
generation_config, который, если не передан явно, принимает значения конфигурации генерации по умолчанию для модели. Вы можете переопределить любые параметрыgeneration_config, передав соответствующие аргументы в generate(), например,.generate(inputs, num_beams=4, do_sample=True).Обзор стратегий генерации и примеры кода приведены в следующем руководстве.