Transformers documentation

Pocket TTS

Transformers

Начало работы

Transformers Установка Быстрый старт

Базовые классы

Модели

Предобработчики

Вывод

API конвейера

Generate API

Оптимизация

Чат с моделями

Развёртывание

Обучение

Начало работы

Настройка

Параметрически эффективная дообучение

Производительность

Распределённое обучение

Аппаратное обеспечение

Квантование

Интеграции с экосистемой

Ресурсы

API

Основные классы

Модели

Текстовые модели

Модели компьютерного зрения

Аудиомодели

Видеомодели

Мультимодальные модели

Модели обучения с подкреплением

Модели временных рядов

Внутренние вспомогательные функции

Справочник

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

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

Эта модель была добавлена в Hugging Face Transformers 2026-10-20.

Pocket TTS

Обзор

Pocket TTS — это модель преобразования текста в речь от Kyutai с 100 млн параметров, являющаяся Continuous Audio Language Model, которая работает быстрее реального времени на CPU. Причинный трансформер генерирует один непрерывный аудиолатентный вектор на кадр (12,5 Гц) через одношаговую flow-головку, а головка определения конца речи принимает решение о моменте остановки.

Процессор содержит аудиотокенизатор Pocket TTS — кодек на основе Mimi, который кодирует голосовые подсказки и декодирует сгенерированные латенты в аудио с частотой 24 кГц. Предопределённые голоса поставляются в виде KV-кэшей (voices/).

Опубликованы два flow heads: Lagrangian self-distillation (flow_type="lsd", по умолчанию) и drifting (flow_type="drifting", english_drifting_26-09). Поддерживается дообучение, см. Обучение.

Эта модель была предоставлена Eustache Le Bihan. Исходный код — kyutai-labs/pocket-tts.

Советы по использованию

Подготовьте входные данные с помощью apply_chat_template() (одно сообщение user на каждый текст, add_generation_prompt=True). Нормализатор токенизатора обрабатывает текст так же, как в оригинале, с настройками языка чекпоинта.
generate возвращает audio_latents и audio_latents_mask; декодируйте их с помощью PocketTTSProcessor.decode().
max_new_tokens по умолчанию устанавливается в соответствии с бюджетом, основанным на длине текста, а генерация останавливается вскоре после того, как логит конца речи превысит eos_threshold.
do_sample=False соответствует исходному при температуре 0. При сэмплировании temperature (по умолчанию 0.3) — это дисперсия начального шума потока.
Разбейте длинный текст с помощью PocketTTSProcessor.split_text(), размещая один диалог в каждом фрагменте.

Использование

Голос

Голос можно задать тремя способами.

1. Клонирование записи: элемент audio в разговоре.

from transformers import AutoModelForTextToWaveform, AutoProcessor

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")

url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/en-Alice_woman.wav"
conversation = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "url": url},
            {"type": "text", "text": "Hello world. I am Kyutai's Pocket TTS."},
        ],
    }
]
inputs = processor.apply_chat_template(
    conversation, tokenize=True, return_dict=True, add_generation_prompt=True
).to(model.device)

outputs = model.generate(**inputs)
audio = processor.decode(outputs.audio_latents, outputs.audio_latents_mask)
processor.save_audio(audio, "cloned.wav")

2. Предвычисленные латенты: пустой элемент audio, при этом латенты передаются в процессор.

from transformers import AutoModelForTextToWaveform, AutoProcessor
from transformers.audio_utils import load_audio

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")

# e.g. a recording encoded once by the processor's audio tokenizer,
# to reuse without re-encoding it
url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/en-Alice_woman.wav"
features = processor.feature_extractor(
    load_audio(url, sampling_rate=24000), sampling_rate=24000
).to(processor.audio_tokenizer.device)
# (num_frames, latent_dim)
voice = processor.audio_tokenizer.encode(**features).latents[0]

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "audio"},
            {"type": "text", "text": "Hello world. I am Kyutai's Pocket TTS."},
        ],
    }
]
inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    return_dict=True,
    add_generation_prompt=True,
    processor_kwargs={"audio_prompt_latents": [voice]},
).to(model.device)

outputs = model.generate(**inputs)
audio = processor.decode(outputs.audio_latents, outputs.audio_latents_mask)
processor.save_audio(audio, "latents.wav")

3. Кэшированный контекст: KV-кэш голосового промпта, передаваемый в качестве past_key_values. В поставленных голосах (voices/) используется именно этот вариант.

from huggingface_hub import hf_hub_download
from safetensors.torch import load_file
from transformers import AutoModelForTextToWaveform, AutoProcessor, DynamicCache

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")

voice = load_file(hf_hub_download(model_id, "voices/alba.safetensors"))
layers = []
for i, layer in enumerate(model.model.layers):
    # each layer's cache on that layer's device
    device = layer.self_attn.k_proj.weight.device
    layers.append(
        (voice[f"layers.{i}.keys"].to(device), voice[f"layers.{i}.values"].to(device))
    )
voice_cache = DynamicCache(layers, config=model.config)

conversation = [
    {
        "role": "user",
        "content": [{"type": "text", "text": "Hello world. I am Kyutai's Pocket TTS."}],
    }
]
inputs = processor.apply_chat_template(
    conversation, tokenize=True, return_dict=True, add_generation_prompt=True
).to(model.device)

outputs = model.generate(**inputs, past_key_values=voice_cache)
audio = processor.decode(outputs.audio_latents, outputs.audio_latents_mask)
processor.save_audio(audio, "cached.wav")

Пакеты и длинный текст

Пакетная обработка нескольких текстов и голосов, при этом длинный текст разбивается на фрагменты:

import torch
from huggingface_hub import hf_hub_download
from safetensors.torch import load_file
from transformers import AutoModelForTextToWaveform, AutoProcessor, DynamicCache

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")


def load_voices(names):
    """The shipped voices, one per conversation, as one cache, left-padded to the
    longest voice, and the mask of their positions.

    `generate` extends the cache: load it for every call.
    """
    voices = [
        load_file(hf_hub_download(model_id, f"voices/{name}.safetensors"))
        for name in names
    ]
    lengths = [voice["layers.0.keys"].shape[2] for voice in voices]
    length = max(lengths)
    layers = []
    for i, layer in enumerate(model.model.layers):
        device = layer.self_attn.k_proj.weight.device
        keys, values = (
            torch.cat(
                [
                    torch.nn.functional.pad(voice[f"layers.{i}.{kind}"], (0, 0, length - n, 0))
                    for voice, n in zip(voices, lengths)
                ]
            ).to(device)
            for kind in ("keys", "values")
        )
        layers.append((keys, values))
    mask = torch.tensor([[0] * (length - n) + [1] * n for n in lengths])
    return DynamicCache(layers, config=model.config), mask


text = (
    "A first sentence that is long enough to be worth splitting. "
    "Then a second one, and a third one for good measure."
)
chunks = processor.split_text(text)
conversations = [
    [{"role": "user", "content": [{"type": "text", "text": chunk}]}]
    for chunk in chunks + ["Hello world"]
]
inputs = processor.apply_chat_template(
    conversations, tokenize=True, return_dict=True, add_generation_prompt=True
).to(model.device)

voice_cache, voice_mask = load_voices(["alba"] * len(chunks) + ["jean"])
# the mask covers the cached voices too
inputs["attention_mask"] = torch.cat(
    [voice_mask.to(inputs["attention_mask"]), inputs["attention_mask"]], dim=-1
)
outputs = model.generate(**inputs, past_key_values=voice_cache)
audio = processor.decode(outputs.audio_latents, outputs.audio_latents_mask)
processor.save_audio(
    [torch.cat(audio[: len(chunks)]), audio[-1]], ["long.wav", "hello.wav"]
)

Дрейф контрольной точки

Тот же способ использования, но с собственными голосами контрольной точки:

from huggingface_hub import hf_hub_download
from safetensors.torch import load_file
from transformers import AutoModelForTextToWaveform, AutoProcessor, DynamicCache

model_id = "eustlb/pocket-tts-english-drifting"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")

voice = load_file(hf_hub_download(model_id, "voices/alba.safetensors"))
layers = []
for i, layer in enumerate(model.model.layers):
    device = layer.self_attn.k_proj.weight.device
    layers.append(
        (voice[f"layers.{i}.keys"].to(device), voice[f"layers.{i}.values"].to(device))
    )

conversation = [
    {
        "role": "user",
        "content": [{"type": "text", "text": "Hello world. I am Kyutai's Pocket TTS."}],
    }
]
inputs = processor.apply_chat_template(
    conversation, tokenize=True, return_dict=True, add_generation_prompt=True
).to(model.device)

outputs = model.generate(
    **inputs, past_key_values=DynamicCache(layers, config=model.config)
)
audio = processor.decode(outputs.audio_latents, outputs.audio_latents_mask)
processor.save_audio(audio, "drifting.wav")

Обучение

Поместите целевой аудио в ход assistant. Процессор возвращает его латенты в качестве labels, а модель возвращает потерю оригинала (потеря потока LSD плюс config.eos_loss_weight, умноженное на потерю конца речи). Голосовой промпт, как правило, является началом того же высказывания.

import torch
from transformers import AutoModelForTextToWaveform, AutoProcessor

model_id = "eustlb/pocket-tts"
processor = AutoProcessor.from_pretrained(model_id, device_map="auto")
model = AutoModelForTextToWaveform.from_pretrained(model_id, device_map="auto")
model.train()

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": voice_prompt},
            {"type": "text", "text": target_text},
        ],
    },
    {"role": "assistant", "content": [{"type": "audio", "audio": target_audio}]},
]
inputs = processor.apply_chat_template(
    conversation, tokenize=True, return_dict=True
).to(model.device)
loss = model(**inputs).loss
loss.backward()

Передавайте голос в виде записи или латентов, а не кэша.
Для classifier-free guidance удалите элемент audio или text из хода user (в оригинале каждый удаляется с вероятностью 0.2).
Предвычисленные латенты передаются в processor_kwargs={"audio_prompt_latents": [...], "labels": [...]}, при этом в качестве заполнителей используются пустые элементы {"type": "audio"}.
Исходный рецепт: AdamW, learning_rate=2e-5 (2e-4 для нового языка), adam_beta2=0.95, weight_decay=0.1, max_grad_norm=1.0, 1000 шагов разгона, затем постоянное значение, EMA весов (затухание 0.999).

Transformers

Pocket TTS

Обзор

Советы по использованию

Использование

Голос

Пакеты и длинный текст

Дрейф контрольной точки

Обучение

PocketTTSConfig

класс transformers.PocketTTSConfig

PocketTTSFlowHeadConfig

класс transformers.PocketTTSFlowHeadConfig

PocketTTSFeatureExtractor

класс transformers.PocketTTSFeatureExtractor

__call__

PocketTTSProcessor

класс transformers.PocketTTSProcessor

__call__

split_text

decode

save_audio

PocketTTSModel

класс transformers.PocketTTSModel

forward

PocketTTSForConditionalGeneration

класс transformers.PocketTTSForConditionalGeneration

forward

generate

sample_latent

denormalize_latents

PocketTTSGenerateOutput

класс transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput

call

call