Transformers documentation

Pocket TTS

Transformers

Başlayın

Transformers Kurulum Hızlı Başlangıç

Taban sınıfları

Modeller

Önişleyiciler

Çıkarım

Pipeline API

Generate API

Optimizasyon

Modellerle sohbet edin

Sunum

Eğitim

Başlayın

Özelleştirme

Parametre verimli ince ayar

Performans

Dağıtık eğitim

Donanım

Kantizasyon

Ekosistem entegrasyonları

Kaynaklar

API

Ana sınıflar

Modeller

Metin modelleri

Görüş modelleri

Ses modelleri

Video modelleri

Çok modlu modeller

Pekiştirmeli öğrenme modelleri

Zaman serisi modelleri

Dahili yardımcılar

Referans

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

Bu model, 2026-10-20 tarihinde Hugging Face Transformers'a katkıda bulunulmuştur.

Pocket TTS

Genel Bakış

Pocket TTS, Kyutai’nin 100M parametreli metinden sese modelidir; CPU üzerinde gerçek zamanlıdan daha hızlı çalışan bir Continuous Audio Language Model’dür. Neden-sonuç (causal) bir transformer, tek adımlı bir akış (flow) başlığı aracılığıyla her kare için (12.5 Hz) bir sürekli ses latent’i üretir ve konuşma sonu (end-of-speech) başlığı ne zaman durulacağına karar verir.

İşleyici, sesli istekleri kodlayıp üretilen latentleri 24 kHz ses olarak çözen, Mimi tabanlı bir codec olan Pocket TTS audio tokenizer bileşenini barındırır. Hazır sesler KV önbellekleri olarak (voices/) dağıtılır.

İki akış başlığı yayınlanmıştır: Lagrangian öz-distilasyon (flow_type="lsd", varsayılan) ve sürüklenen (flow_type="drifting", english_drifting_26-09). İnce ayar (finetuning) desteklenmektedir, bkz. Eğitim.

Bu model Eustache Le Bihan tarafından katkıda bulunmuştur. Orijinal kod kyutai-labs/pocket-tts'tir.

Kullanım ipuçları

Girdileri apply_chat_template() ile hazırlayın (her metin için bir user mesajı, add_generation_prompt=True). Tokenizer'ın normalizer'ı, metni checkpoint'in dil ayarlarıyla orijinalindeki gibi hazırlar.
generate, audio_latents ve audio_latents_mask değerlerini döndürür; bunları PocketTTSProcessor.decode() ile çözümlersiniz.
max_new_tokens, metin uzunluğuna dayalı bir bütçeye göre varsayılan olarak ayarlanır ve üretim, konuşma sonu logiti eos_threshold değerini aştıktan kısa bir süre sonra durur.
do_sample=False, sıcaklık 0'da orijinal ile eşleşir. Örnekleme kullanıldığında, temperature (varsayılan 0.3) akışın başlangıç gürültüsünün varyansıdır.
Uzun metni PocketTTSProcessor.split_text() ile bölün, her parça bir konuşma içersin.

Kullanım

Ses

Ses üç farklı şekilde verilebilir.

1. Bir kaydın kopyalanması: konuşmadaki bir audio öğesi.

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. Ön hesaplanmış latentler: latentler işlemciye geçirilen boş bir audio öğesi.

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. Önbelleğe alınmış bağlam: sesli istemin KV önbelleği, past_key_values olarak geçirilir. Dağıtılan sesler (voices/) bu biçimi kullanır.

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

Partiler ve uzun metin

Birkaç metni ve sesi toplu olarak işleyin, uzun metinleri parçalara ayırın:

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

Sapma kontrol noktası

Aynı kullanım, kontrol noktasının kendi sesleriyle:

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

Eğitim

Hedef ses dosyasını assistant turuna yerleştirin. İşleyici, latentlerini labels olarak döndürür ve model, orijinalin kaybını (LSD akış kaybı ile config.eos_loss_weight çarpısı konuşma sonu kaybı) döndürür. Ses istemi, genellikle aynı ifadenin başlangıcıdır.

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

Sesi bir kayıt veya latents olarak verin, bir önbellek olarak değil.
Sınıfsız yönlendirme (classifier-free guidance) için, user turundaki audio veya text öğesini kaldırın (orijinal uygulama, her birini 0,2 olasılıkla düşürür).
Önceden hesaplanmış latents, processor_kwargs={"audio_prompt_latents": [...], "labels": [...]} içine yerleştirilir; boş {"type": "audio"} öğeleri yer tutucu olarak kullanılır.
Orijinal tarife: AdamW, learning_rate=2e-5 (yeni bir dil için 2e-4), adam_beta2=0.95, weight_decay=0.1, max_grad_norm=1.0, 1000 ısınma adımı ardından sabit, ağırlıkların EMA'sı (sönümleme 0.999).

Transformers

Pocket TTS

Genel Bakış

Kullanım ipuçları

Kullanım

Ses

Partiler ve uzun metin

Sapma kontrol noktası

Eğitim

PocketTTSConfig

sınıf transformers.PocketTTSConfig

PocketTTSFlowHeadConfig

sınıf transformers.PocketTTSFlowHeadConfig

PocketTTSFeatureExtractor

sınıf transformers.PocketTTSFeatureExtractor

__call__

PocketTTSProcessor

sınıf transformers.PocketTTSProcessor

__call__

split_text

decode

save_audio

PocketTTSModel

sınıf transformers.PocketTTSModel

forward

PocketTTSForConditionalGeneration

sınıf transformers.PocketTTSForConditionalGeneration

forward

generate

sample_latent

denormalize_latents

PocketTTSGenerateOutput

sınıf transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput

call

call