Transformers documentation

Pocket TTS

Transformers

はじめに

Transformers インストールクイックスタート

ベースクラス

モデル

プリプロセッサ

推論

Pipeline 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

このモデルは2026年10月20日にHugging Face Transformersに貢献されました。

Pocket TTS

概要

Pocket TTS は Kyutai による 1 億パラメータのテキスト読み上げモデルで、CPU 上でリアルタイムより高速に動作する Continuous Audio Language Model です。因果変換器が 1 ステップフローヘッドを介してフレームごとに 1 つの連続音声潜在変数（12.5 Hz）を出力し、発話終了ヘッドが停止のタイミングを判断します。

プロセッサは、Pocket TTS audio tokenizerを保持しています。これは Mimi ベースのコーデックであり、音声プロンプトをエンコードし、生成された潜在変数を 24 kHz の音声にデコードします。事前定義された音声は KV キャッシュとして同梱されています（voices/）。

2つのフローヘッドがリリースされています:Lagrangian self-distillation(flow_type="lsd"、デフォルト)とdrifting(flow_type="drifting"、english_drifting_26-09)。ファインチューニングに対応しており、Trainingを参照してください。

このモデルは Eustache Le Bihan によって提供されました。元のコードは kyutai-labs/pocket-tts です。

使用のコツ

apply_chat_template() を使用して入力を用意します（テキストごとに user メッセージを1つ、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つの会話にしてください。

使用方法

ボイス

ボイスは3つの方法で指定できます。

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 を行う場合は、user ターン内の audio または text の項目を削除します（元の処理では、それぞれ 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

class transformers.PocketTTSFlowHeadConfig

PocketTTSFeatureExtractor

class transformers.PocketTTSFeatureExtractor

__call__

PocketTTSProcessor

class transformers.PocketTTSProcessor

__call__

split_text

decode

save_audio

PocketTTSModel

class transformers.PocketTTSModel

forward

PocketTTSForConditionalGeneration

クラス transformers.PocketTTSForConditionalGeneration

forward

generate

sample_latent

denormalize_latents

PocketTTSGenerateOutput

クラス transformers.models.pocket_tts.generation_pocket_tts.PocketTTSGenerateOutput

call

call