Llasa TTS 推論サーバー

Llasa TTSモデルのシンプルな高速推論サーバーです。vLLM、SGLang、またはTransformersを推論バックエンドとして選択できます。

Llasaとは

Llasaは、LLaMAアーキテクチャをベースにしたText-to-Speech (TTS) モデルです。テキストを入力として受け取り、対応するspeech tokenを出力します。これらのspeech tokenは、XCodec2によって音声波形に変換されます。

更新履歴

• 2025-10-25: キャプション対応モデル（Anime-Llasa-3B-Captions）のサポート追加、system_promptパラメータ対応、メタデータ対応UI（gradio_ui_captions.py）追加
• 2025-10-17: 44.1kHz出力対応、XCodec2-44.1kHzモデルのサポート追加、--output-sample-rateオプション追加
• 2024-10-09: SGLang / Transformersバックエンドのサポートを追加、不具合修正など

データフロー

テキスト入力
  ↓
[テキスト正規化]
  ↓
[vLLM/SGLang/Transformers + Llasa] → Speech token生成
  ↓
[XCodec2] → 音声波形デコード
  ↓
WAV音声出力（16kHz または 44.1kHz）

特徴

• 柔軟なバックエンド: vLLM、SGLang、またはTransformersを推論エンジンとして選択可能
• 高速推論: vLLM/SGLangによる最適化されたLLM推論
• 音声クローニング: リファレンス音声による声質制御のサポート
• メタデータ制御: キャプション対応モデル（Anime-Llasa-3B-Captions）では、システムプロンプトで音声の特徴（感情、声質、スタイルなど）を細かく制御可能
• RESTful API: FastAPIベースの使いやすいAPI
• Web UI: Gradio製のブラウザインターフェースを利用可能（通常版とメタデータ対応版の2種類）
• 柔軟な設定: GPU設定、モデルパラメータの細かい調整が可能

インストール

WSL2のUbuntu 24.04、Python 3.12、CUDA 12.9の環境で動作確認済みです。

# XCodec2のインストール（44.1kHz対応版、16kHzモデルとの後方互換性あり）
uv pip install https://huggingface.co/NandemoGHS/Anime-XCodec2-44.1kHz/resolve/main/xcodec2-0.1.6.tar.gz

# 推論バックエンドのインストール（いずれか1つ以上を選択）

# vLLMを使用する場合
uv pip install vllm==0.10.2 --torch-backend=auto
uv pip install -r requirements.txt

# SGLangを使用する場合
uv pip install "sglang[all]==0.5.3" --prerelease=allow
uv pip install -r requirements.txt

# transformersを使用する場合
uv pip install -r requirements.txt
# 環境によってはCUDAのバージョンにあったtorchの再インストールが必要かもしれません
# uv pip install -U torch torchaudio --index-url https://download.pytorch.org/whl/cu***

# 開発環境が必要な場合
uv pip install -r requirements-dev.txt

使い方

推論サーバーの起動

基本的な起動

python run_server.py

サーバーは http://localhost:8000 で起動します。

コマンドライン引数での設定

# SGLangバックエンドを使用
python run_server.py --backend sglang

# Transformersバックエンドを使用
python run_server.py --backend transformers

# FP8モデルを使用
python run_server.py --llasa-model-id NandemoGHS/Anime-Llasa-3B-FP8

# キャプション対応モデルを使用
python run_server.py --llasa-model-id NandemoGHS/Anime-Llasa-3B-Captions

# 44.1kHzモデルを使用（output-sample-rateの設定が必須）
python run_server.py --xcodec2-model-id NandemoGHS/Anime-XCodec2-44.1kHz --output-sample-rate 44100

# カスタムポートで起動
python run_server.py --port 9000

# vLLM/SGLangの設定を調整 (マルチGPUなど)
python run_server.py --backend sglang --gpu-memory-utilization 0.9 --tensor-parallel-size 2

# すべてのオプションを確認
python run_server.py --help

利用可能な引数:

• --backend: 推論バックエンド（選択肢: vllm, sglang, transformers、デフォルト: vllm）
• --llasa-model-id: Llasaモデル ID（デフォルト: NandemoGHS/Anime-Llasa-3B）
• --xcodec2-model-id: XCodec2モデル ID（デフォルト: NandemoGHS/Anime-XCodec2）
• --tensor-parallel-size: vLLM/SGLangのTensor Parallelのサイズ（デフォルト: 1、マルチGPU時に使用）
• --gpu-memory-utilization: GPU メモリ使用率（デフォルト: 0.8）
• --max-model-len: コンテキスト長（デフォルト: 2048）
• --device: 仕様デバイス（デフォルト: cuda）
• --output-sample-rate: 出力音声のサンプリングレート（Hz）（デフォルト: 16000）
  • 重要: 44.1kHzモデル（NandemoGHS/Anime-XCodec2-44.1kHz）を使用する場合は 44100 を指定する必要があります
• --host: バインドホスト（デフォルト: 0.0.0.0）
• --port: バインドポート（デフォルト: 8000）
• --reload: 自動リロード有効化

Gradio Web UIの起動

上記の推論サーバを使い、ブラウザから簡単に音声生成ができる簡易的なWeb UIも提供しています。

通常版UI

python gradio_ui.py

Web UIは http://localhost:7860 で起動します。

メタデータ対応UI（キャプション対応モデル用）

キャプション対応モデル（NandemoGHS/Anime-Llasa-3B-Captions）を使用する場合は、メタデータ入力に対応した専用UIを使用できます：

python gradio_ui_captions.py

このUIでは、以下のメタデータを指定して音声の特徴を細かく制御できます：

• caption: 音声の説明（推奨）
• emotion: 感情タグ（angry, sad, happy, seriousなど）
• profile: 話者プロファイル（若い女性声、大人の男性声など）
• mood: ムード（恥ずかしさ、悲しみなど）
• speed: 話速（ゆっくり、速いなど）
• prosody: 抑揚・リズム（震え声、平坦など）
• pitch_timbre: ピッチ・声質（高め、低め、息多めなど）
• style: スタイル（ナレーション風、会話調など）
• notes: 特記事項（距離感、吐息など）

プリセット例も用意されており、簡単に試すことができます。

Web UIのコマンドライン引数

# 推論サーバーのURLを指定
python gradio_ui.py --server-url http://192.168.1.100:8000

# カスタムポートでWeb UIを起動
python gradio_ui.py --port 8080

# 公開リンクを生成（外部アクセス可能）
python gradio_ui.py --share

# 環境変数で推論サーバーのURLを設定
LLASA_SERVER_URL=http://192.168.1.100:8000 python gradio_ui.py

利用可能な引数:

• --server-url: APIサーバーのURL（デフォルト: http://localhost:8000、 環境変数 LLASA_SERVER_URL でも設定可能）
• --host: Web UIのホスト（デフォルト: 0.0.0.0）
• --port: Web UIのポート（デフォルト: 7860）
• --share: Gradio公開リンクを生成

API仕様

POST /tts

テキストから音声を生成します。

パラメータ:

• text (必須): 生成するテキスト
• reference_audio (オプション): リファレンス音声ファイル（WAV形式推奨）
• reference_text (オプション): リファレンス音声のテキスト
• system_prompt (オプション): システムプロンプト（キャプション対応モデル用。メタデータを含む）
• temperature (デフォルト: 0.8): Llasaのtemperature
• top_p (デフォルト: 1.0): Llasaのtop-p
• repetition_penalty (デフォルト: 1.1): Llasaのrepetition penalty
• max_tokens (デフォルト: 2048): 生成する最大トークン数

レスポンス: WAV形式の音声データ（wav、デフォルト16kHz、モノラル）

• サンプリングレートは --output-sample-rate オプションで変更可能

使用例

シンプルな音声合成の例（Python）

import requests

url = "http://localhost:8000/tts"
data = {
    "text": "こんにちは、これはテスト音声です。",
}

response = requests.post(url, data=data)

with open("output.wav", "wb") as f:
    f.write(response.content)

リファレンス音声を使用する例（Python）

import requests

url = "http://localhost:8000/tts"
data = {
    "text": "これは生成したい新しいテキストです。",
    "reference_text": "これはリファレンス音声のテキストです。",
}
files = {
    "reference_audio": open("reference.wav", "rb"),
}

response = requests.post(url, data=data, files=files)

with open("output.wav", "wb") as f:
    f.write(response.content)

キャプション対応モデルでメタデータを使用する例（Python）

import requests

url = "http://localhost:8000/tts"

# システムプロンプトを構築
system_prompt = """emotion: serious
profile: 落ち着いた女性声
mood: シリアス、深刻
speed: 一定
prosody: メリハリがある、断定的
pitch_timbre: 中低音、張りのある声
style: ナレーション風
notes:
caption: 落ち着いた中低音の女性声。シリアスな雰囲気で、張りのある声で断定的に話す。ナレーションのようなスタイル。"""

data = {
    "text": "今思えば、あの時すでに運命の歯車は狂っていたのだろう",
    "system_prompt": system_prompt,
}

response = requests.post(url, data=data)

with open("output.wav", "wb") as f:
    f.write(response.content)

あるいは、utils.pyのbuild_system_prompt()関数を使用してより簡単に構築できます：

import requests
from llasa_server.utils import build_system_prompt

url = "http://localhost:8000/tts"

# メタデータからシステムプロンプトを構築
system_prompt = build_system_prompt(
    caption="落ち着いた中低音の女性声。シリアスな雰囲気で、張りのある声で断定的に話す。ナレーションのようなスタイル。",
    emotion="serious",
    profile="落ち着いた女性声",
    mood="シリアス、深刻",
    speed="一定",
    prosody="メリハリがある、断定的",
    pitch_timbre="中低音、張りのある声",
    style="ナレーション風",
)

data = {
    "text": "今思えば、あの時すでに運命の歯車は狂っていたのだろう",
    "system_prompt": system_prompt,
}

response = requests.post(url, data=data)

with open("output.wav", "wb") as f:
    f.write(response.content)

cURLでの使用例

# シンプルなTTS
curl -X POST "http://localhost:8000/tts" \
  -F "text=こんにちは、これはテスト音声です。" \
  -o output.wav

# リファレンス音声付き
curl -X POST "http://localhost:8000/tts" \
  -F "text=これは生成したい新しいテキストです。" \
  -F "reference_text=これはリファレンス音声のテキストです。" \
  -F "reference_audio=@reference.wav;type=audio/wav" \
  -o output.wav

Web UIでの使用

通常版UIの使用

1. APIサーバーを起動:

   python run_server.py
   

2. 別のターミナルでWeb UIを起動:

   python gradio_ui.py
   

3. ブラウザで http://localhost:7860 にアクセス

4. UIで以下を設定:

   • APIサーバーURL: 必要に応じて変更（デフォルト: http://localhost:8000）
   • リファレンス音声: オプションで音声ファイルをアップロード
   • リファレンステキスト: リファレンス音声を使用する場合は必須
   • 生成するテキスト: 生成したいテキストを入力
   • パラメータ: Temperature、Top-p、Repetition Penaltyを調整

5. 「音声を生成」ボタンをクリック

メタデータ対応UIの使用（キャプション対応モデル）

1. キャプション対応モデルでAPIサーバーを起動:

   python run_server.py --llasa-model-id NandemoGHS/Anime-Llasa-3B-Captions
   

2. 別のターミナルでメタデータ対応UIを起動:

   python gradio_ui_captions.py
   

3. ブラウザで http://localhost:7860 にアクセス

4. UIで以下を設定:

   • APIサーバーURL: 必要に応じて変更（デフォルト: http://localhost:8000）
   • リファレンス音声: オプションで音声ファイルをアップロード
   • リファレンステキスト: リファレンス音声を使用する場合は必須
   • 生成するテキスト: 生成したいテキストを入力
   • メタデータ: caption（推奨）および他のメタデータフィールドを入力
     • captionは短い日本語で音声の特徴を記述（例：「落ち着いた女性声、シリアスな雰囲気」）
     • その他のフィールドはオプション（emotion, profile, mood, speed, prosody, pitch_timbre, style, notes）
   • パラメータ: Temperature、Top-p、Repetition Penaltyを調整

5. 「音声を生成」ボタンをクリック

Examplesタブでプリセット例を選択して、すぐに試すこともできます。

ヘルスチェック

curl http://localhost:8000/health

アーキテクチャ

コンポーネント

• vLLM / SGLang / Transformers: Llasa LLMモデル（NandemoGHS/Anime-Llasa-3B）の推論
• XCodec2: Speech tokenから音声波形への変換（NandemoGHS/Anime-XCodec2）
• FastAPI: REST APIサーバー
• Gradio: Web UIフロントエンド

ディレクトリ構成

llasa-server/
├── llasa_server/
│   ├── __init__.py
│   ├── api.py                  # FastAPI エンドポイント
│   ├── codec.py                # XCodec2 ラッパー
│   ├── config.py               # サーバー設定管理
│   ├── engine_vllm.py               # vLLM エンジン
│   ├── engine_base.py          # エンジン抽象基底クラス
│   ├── engine_sglang.py        # SGLang エンジン
│   ├── engine_transformers.py  # Transformers エンジン
│   ├── server.py               # メインサーバークラス
│   └── utils.py                # ユーティリティ類（メタデータ構築関数含む）
├── run_server.py        # APIサーバー起動スクリプト
├── gradio_ui.py         # Gradio Web UI（通常版）
├── gradio_ui_captions.py # Gradio Web UI（メタデータ対応版）
├── example_client.py    # 推論のサンプルスクリプト
├── requirements.txt     # 必要ライブラリ
├── requirements-dev.txt # 開発用ライブラリ
└── README.md            # このドキュメント

ライセンス

このリポジトリのコードはMITライセンスの下で提供されています。

利用しているモデルのライセンスについては、各モデルの提供元を確認してください。デフォルトで使われているAnime-Llasa-3BおよびAnime-XCodec2はCC BY-NC 4.0ライセンスです。