Transformers documentation

Pocket TTS

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

이 모델은 2026-10-20에 Hugging Face Transformers에 기여되었습니다.

Pocket TTS

개요

Pocket TTS는 Kyutai의 1억 파라미터 텍스트-음성 변환 모델로, CPU에서 실시간보다 빠르게 동작하는 Continuous Audio Language Model입니다. Causal transformer가 one-step flow head를 통해 프레임당(12.5 Hz) 하나의 연속 오디오 latent를 출력하고, end-of-speech head가 언제 생성을 중단할지 결정합니다.

프로세서에는 Pocket TTS 오디오 토크나이저가 포함되어 있습니다. 이는 Mimi 기반 코덱으로, 음성 프롬프트를 인코딩하고 생성된 잠긴 변수(latents)를 24 kHz 오디오로 디코딩합니다. 사전 정의된 목소리는 KV 캐시(voices/)로 제공됩니다.

두 가지 flow head가 공개되었습니다: Lagrangian self-distillation(flow_type="lsd", 기본값)과 drifting(flow_type="drifting", english_drifting_26-09). Fine-tuning을 지원하며, Training을 참고하세요.

이 모델은 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는 텍스트 길이에 기반한 예산이 기본값이며, end-of-speech logit이 eos_threshold를 초과한 직후 생성이 중단됩니다.
do_sample=False는 temperature 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. 사전 계산된 latents: latents가 프로세서에 전달되는 빈 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"]
)

Drifting checkpoint

같은 사용법이며, 체크포인트 자체의 목소리를 사용합니다:

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 턴에 대상 오디오를 배치합니다. 프로세서가 그 latents를 labels로 반환하고, 모델은 원래의 loss(LSD flow loss에 config.eos_loss_weight를 곱한 end-of-speech loss를 더한 값)를 반환합니다. 음성 프롬프트는 일반적으로 동일한 발화의 시작 부분입니다.

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

음성을 캐시가 아닌 녹음이나 latents로 제공하세요.
Classifier-free guidance를 사용하려면 user 턴의 audio 또는 text 항목을 제거합니다(원본에서는 각각 0.2의 확률로 제거합니다).
사전 계산된 latents는 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 warmup steps 후 일정, 가중치의 EMA (decay 0.999).

Transformers

Pocket TTS

개요

사용 팁

사용

음성

배치와 긴 텍스트

Drifting checkpoint

학습

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

class transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput

call

call